Skip to main content

Getting started

Setting up Rapier with Cargo​

rapier relies on the official Rust package manager Cargo for dependency resolution and compilation. Therefore, making rapier ready to use in your project is simply a matter of adding a new dependency to your Cargo.toml file. You can either use the rapier2d crate for 2D physics simulation or the rapier3d crate for 3D physics simulation. For high-precision simulation using 64-bits floats, use the rapier2d-f64 crate or the rapier3d-f64 crate.

Until rapier reaches 1.0, it is strongly recommended to always use its latest published version, though you may encounter breaking changes from time to time.

To get the best of rapier multiple features can be enabled optionally:

  • parallel: enables parallelism of the physics pipeline with the rayon crate.
  • serde-serialize: enables serialization of the physics components with serde.
  • enhanced-determinism: enables cross-platform determinism (assuming the rest of your code is also deterministic) across all 32-bit and 64-bit platforms that implements the IEEE 754-2008 standard strictly. This includes most modern processors as well as WASM targets.
  • wasm-bindgen: enables usage of rapier as a dependency of a WASM crate that is compiled with wasm-bindgen.

SIMD optimizations (based on the wide crate) are always enabled: the solver processes 4 contact manifolds per instruction, and falls back to scalar code on targets without SIMD support.

warning

Enabling parallelism is only useful if the scene being simulated has a high number of moving rigid-bodies, colliders, and/or joints. If the simulation isn't sufficiently complex, the parallelism may actually make the simulation slower because of the parallelism overhead.

Currently, the enhanced-determinism feature cannot be enabled at the same time as the simd8 feature, which changes the SIMD lane width and is therefore its own determinism domain.

Cargo example​

[package]
name    = "example-using-rapier"
version = "0.0.0"
authors = [ "You" ]

[dependencies]
# TODO: Replace the * by the latest version number.
rapier2d = { version = "*" }

[[bin]]
name = "example"
path = "./example.rs"

Basic simulation example​

Here is a basic example of main.rs file. This creates a ball bouncing on a fixed ground. Details about the elements used in this examples are given in subsequent pages of this guide.

<load path='/2d/rust/examples/rs_basic_sim2.rs' marker='basic_sim' />