Skip to main content

Getting started

Installing Rapier with pip​

The Python bindings of rapier are available as the rapier3d package, which wraps the 3D physics engine with 32-bits floats. There is no 2D version of the Python bindings yet, so only the 3D examples of this guide are shown. The package requires Python 3.9 or later, and can be installed with pip:

pip install rapier3d

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.

Some functions (e.g. the ones reading or writing many particle positions at once) accept and return NumPy arrays. NumPy is installed along with the numpy extra: pip install rapier3d[numpy].

Building from source​

The bindings can also be built from the python folder of the Rapier repository, e.g., to use a version of Rapier that isn't published yet. This requires a Rust toolchain and maturin. From the root of the repository, and with your virtual environment activated:

pip install maturin
maturin develop --release -m bindings/python/rapier-py-3d/Cargo.toml

This installs the package into your virtual environment in editable mode. Replacing maturin develop by maturin build produces a wheel instead. The following cargo features can be given to maturin with -F:

  • 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.

The engine is always built with parallelism enabled: each physics world uses its own pool of threads, and the GIL is released while it is being stepped.

Basic simulation example​

Here is a basic example of a Python script. 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.

import rapier3d as rp

# The world owns every structure needed by the simulation.
world = rp.PhysicsWorld(gravity=(0.0, -9.81, 0.0))

# Create the ground.
world.colliders.insert(rp.Collider.cuboid(100.0, 0.1, 100.0).build())

# Create the bouncing ball.
ball_body_handle = world.add_body(
    rp.RigidBody.dynamic(translation=(0.0, 10.0, 0.0)),
    colliders=[rp.Collider.ball(0.5).restitution(0.7)],
)

# Run the game loop, stepping the simulation once per frame.
for _ in range(200):
    world.step()

    ball_body = world.rigid_bodies[ball_body_handle]
    print("Ball altitude:", ball_body.translation.y)
info

This example lets the PhysicsWorld own every structure of the simulation. Its add_body method inserts a rigid-body together with its colliders.

API reference​

Every class and method of the Python bindings is documented by its docstring, and listed in the API reference of the Python bindings. The package also ships type stubs, so that your editor can show them and check your code.