Skip to main content

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:

R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
R2RigidBodyHandle rigid_body_handle = r2InsertRigidBody(world, &rigid_body);
// The default density is 1.0, we are setting 2.0 for this example.
R2ColliderDesc collider = r2BallColliderDesc(1.0);
collider.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.
r2InsertCollider(rigid_body_handle, &collider);

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. */
R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
rigid_body.additionalMass = 0.5;
// Sets both the mass and angular inertia at once (this overrides `additionalMass`).
rigid_body.useAdditionalMassProperties = 1;
rigid_body.additionalMassProperties = (R2MassProperties){
    .local_com = r2Vector(0.0, 1.0),
    .mass = 0.5,
    .principal_inertia = 0.3,
};
/* Set the mass-properties after the rigid-body creation. */
R2MassProperties mass_properties = {
    .local_com = r2Vector(0.0, 1.0),
    .mass = 0.5,
    .principal_inertia = 0.3,
};
// The last `1` argument makes sure the rigid-body is awake.
r2RigidBody_SetAdditionalMassProperties(rigid_body_handle, mass_properties, 1);

The additionalMass field of R3RigidBodyDesc only adds a mass (the angular inertia being scaled accordingly, based on the shapes of the colliders), whereas the additionalMassProperties field (taken into account only if useAdditionalMassProperties is set to 1) specifies the full mass-properties (mass, center-of-mass, and principal angular inertia) of type R3MassProperties. After the creation of the rigid-body, they are modified with r3RigidBody_SetAdditionalMass and r3RigidBody_SetAdditionalMassProperties respectively.

The resulting mass-properties (including the colliders' contributions) can be read with r3RigidBody_Mass, r3RigidBody_LocalCenterOfMass (in the local-space of the rigid-body), and r3RigidBody_CenterOfMass (in world-space). 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 r3RigidBody_RecomputeMassPropertiesFromColliders.