rigid_body_creation_and_insertion

A rigid-body is created by a RigidBodyBuilder that is based on the builder pattern: each of its methods returns a new builder with the corresponding property set, so they can be chained. The builder is obtained from one of the static methods of the RigidBody class. Then it needs to be inserted into the physics world with PhysicsWorld.add_body (or directly into its RigidBodySet with world.rigid_bodies.insert), which returns the RigidBodyHandle identifying the new rigid-body.

info

The following example shows several setters that can be called to customize the rigid-body being built. The input values are just random so using this example as-is will not lead to a useful result.

import rapier3d as rp

# The world that will contain our rigid-bodies.
world = rp.PhysicsWorld()

# Builder for a fixed rigid-body.
_ = rp.RigidBody.fixed()
# Builder for a dynamic rigid-body.
_ = rp.RigidBody.dynamic()
# Builder for a kinematic rigid-body controlled at the velocity level.
_ = rp.RigidBody.kinematic_velocity_based()
# Builder for a kinematic rigid-body controlled at the position level.
_ = rp.RigidBody.kinematic_position_based()
# The properties of the builder can also be given as keyword arguments.
_ = rp.RigidBody.dynamic(translation=(0.0, 5.0, 1.0), gravity_scale=0.5)
# Builder for a body with a status specified by an enum.
rigid_body = (
    rp.RigidBody.new_body(rp.RigidBodyType.DYNAMIC)
    # The rigid body translation.
    # Default: zero vector.
    .translation((0.0, 5.0, 1.0))
    # The rigid body rotation, as a scaled rotation axis.
    # Default: no rotation.
    .rotation((0.0, 0.0, 5.0))
    # The rigid body position. Will override `.translation(...)` and `.rotation(...)`.
    # Default: the identity isometry.
    .position(rp.Isometry3((1.0, 3.0, 2.0), rp.Rotation3.from_scaled_axis((0.0, 0.0, 0.4))))
    # The linear velocity of this body.
    # Default: zero velocity.
    .linvel((1.0, 3.0, 4.0))
    # The angular velocity of this body.
    # Default: zero velocity.
    .angvel((3.0, 0.0, 1.0))
    # The scaling factor applied to the gravity affecting the rigid-body.
    # Default: 1.0
    .gravity_scale(0.5)
    # Whether or not this body can sleep.
    # Default: True
    .can_sleep(True)
    # Whether or not CCD is enabled for this rigid-body.
    # Default: False
    .ccd_enabled(False)
    # All done, actually build the rigid-body.
    .build()
)
# Insert the rigid-body into the world.
rigid_body_handle = world.add_body(rigid_body)

All the properties are optional. The only calls that are required are RigidBody.fixed(), RigidBody.dynamic(), RigidBody.kinematic_velocity_based(), RigidBody.kinematic_position_based(), or RigidBody.new_body(body_type), to initialize the builder. Each of them also accepts the builder properties as keyword arguments. Calling .build() to actually build the RigidBody is optional: PhysicsWorld.add_body accepts the builder as well, and its optional colliders argument attaches a list of colliders to the new rigid-body in the same call.

Once inserted, the rigid-body is accessed with world.rigid_bodies[handle]. The returned RigidBody is a view of the rigid-body stored in the world: modifying its properties (e.g. rigid_body.linvel = (1.0, 0.0, 0.0)) modifies the simulated rigid-body directly, and a RigidBody built but not inserted yet is copied by the insertion (so modifying it afterwards has no effect on the world). The rigid-body is removed from the world, together with its colliders and the joints attached to it, with PhysicsWorld.remove_body.

info

Typically, the inertia and center of mass are automatically set to the inertia and center of mass resulting from the shapes of the colliders attached to the rigid-body. But they can also be set manually.