Getting started

warning

This documentation is still work-in-progress. It may contain some incomplete or outdated information.

Setting up Rapier with Cargo#

rapier relies on the official Rust package manager Cargo for dependency resolution and compilation. Therefore, making rapier ready to be used by 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. You will also need the nalgebra crate as well because it defines algebraic entities (vectors, points, transformation matrices): it is automatically re-exported as rapier2d::na and rapier3d::na.

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

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

  • simd-stable: enables explicit SIMD optimizations using the wide crate. Has limited cross-platform support but can be used with a stable version of the Rust compiler.
  • simd-nightly: enables explicit SIMD optimizations using the packed_simd crate. Has a great cross-platform support but requires a nightly version of the Rust compiler.
  • 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 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.

Currently, the enhanced-determinism feature cannot be enabled at the same time as the parallel or simd-{stable,nightly} features.

Cargo example#

[package]
name = "example-using-rapier"
version = "0.0.0"
authors = [ "You" ]
[dependencies]
# TODO: Replace the * by the latest version number.
rapier2d = { version = "*", features = [ "simd-nightly", "parallel" ] }
[[bin]]
name = "example"
path = "./example.rs"