rigid_body_mass_properties

The mass properties of a rigid-body is composed of three parts:

• The mass which determines the resistance of the rigid-body wrt. linear movements. A high mass implies that larger forces are needed to make the rigid-body translate.
• The angular inertia determines the resistance of the rigid-body wrt. the angular movements. A high angular inertia implies that larger torques are needed to make the rigid-body rotate.
• The center-of-mass determines relative to what points torques are applied to the rigid-body.

note

Zero is a special value for masses and angular inertia. A mass equal to zero is interpreted as an infinite mass. An angular inertia equal to zero is interpreted as an infinite angular inertia. Therefore, a rigid-body with a mass equal to zero will not be affected by any force, and a rigid-body with an angular inertia equal to zero will not be affected by any torque.

Computing the mass and angular-inertia can often be difficult because they depend on the geometric shape of the object being simulated. This is why they are automatically computed by Rapier when a collider is attached to the rigid-body: the collider add its own mass and angular-inertia contribution (computed based on the collider's shape and density) to the rigid-body it is attached to:

rigid_body_handle = world.add_body(rp.RigidBody.dynamic())
# The default density is 1.0, we are setting 2.0 for this example.
collider = rp.Collider.ball(1.0).density(2.0)
# When the collider is attached, the rigid-body's mass and angular
# inertia is automatically updated to take the collider into account.
world.add_collider(collider, parent=rigid_body_handle)

Alternatively, it is possible to set the mass properties of a rigid-body when it is created. Keep in mind that this won't prevent the colliders' contributions to be added to these values. So make sure to set the attached colliders' densities to zero if you want your explicit values to be the final mass-properties values.

# Set the mass-properties when the rigid-body is created.
rigid_body = (
    rp.RigidBody.dynamic()
    .additional_mass(0.5)
    # Sets both the mass and angular inertia at once.
    .additional_mass_properties(
        rp.MassProperties(local_com=(0.0, 1.0, 0.0), mass=0.5, principal_inertia=(0.3, 0.2, 0.1))
    )
    .build()
)

# Set the mass-properties after the rigid-body creation.
rigid_body = world.rigid_bodies[rigid_body_handle]
# The rigid-body is woken up, unless `wake_up=False` is given.
rigid_body.set_additional_mass_properties(
    rp.MassProperties(local_com=(0.0, 1.0, 0.0), mass=0.5, principal_inertia=(0.3, 0.2, 0.1))
)

The RigidBodyBuilder.additional_mass method only adds a mass (the angular inertia being scaled accordingly, based on the shapes of the colliders), whereas RigidBodyBuilder.additional_mass_properties specifies the full mass-properties (mass, center-of-mass, and principal angular inertia) given as a MassProperties. After the creation of the rigid-body, they are modified with RigidBody.set_additional_mass and RigidBody.set_additional_mass_properties respectively.

The resulting mass-properties (including the colliders' contributions) can be read with the mass, local_center_of_mass (in the local-space of the rigid-body), center_of_mass (in world-space), and mass_properties properties of the RigidBody. They are updated automatically by the physics engine but, if you need them right after modifying the colliders or the additional mass-properties of a rigid-body (without waiting for the next timestep), they can be updated manually with rigid_body.recompute_mass_properties_from_colliders(world.colliders).