Skip to main content

collider_mass_properties

The mass properties of a rigid-body is computed as the sum of the mass-properties manually set by the user for the rigid-body, plus the mass-properties of the colliders attached to it. There are two ways to define the mass-properties of a collider:

  1. The easiest, automatic, way: by giving the collider a non-zero density (the default density is 1.0) or a non-zero mass. This will make sure the other mass-properties like the angular inertia tensor are computed automatically from the collider's shape.
  2. The manual way: by giving an explicit mass and angular inertia to the collider.

It is recommended to use the density-based or mass-based approaches as it will ensure the automatically-computed mass-properties are coherent with the geometric shape. Wrong mass-properties (especially the angular inertia part and center-of-mass location) may lead to odd behaviors. The manual approach is usually useful when modeling real-world objects for which you already know the real-world mass, center-of-mass, and angular inertia tensor.

The mass-properties of a collider can be set when the collider is created, by setting the massMode of its description to R3_MASS_DENSITY (the default), R3_MASS_TOTAL, or R3_MASS_PROPERTIES, and the corresponding density, mass, or massProperties field:

R2RigidBodyDesc rigid_body = r2DynamicRigidBodyDesc();
R2RigidBodyHandle rigid_body_handle = r2InsertRigidBody(world, &rigid_body);
// First option: by setting the density of the collider (or we could just leave
//               its default value 1.0).
R2ColliderDesc collider = r2CuboidColliderDesc(r2Vector(1.0, 2.0));
collider.density = 2.0;
// Second option: by setting the mass of the collider.
collider = r2CuboidColliderDesc(r2Vector(1.0, 2.0));
collider.massMode = R2_MASS_TOTAL;
collider.mass = 0.8;
// Third option: by setting the mass-properties explicitly.
collider = r2CuboidColliderDesc(r2Vector(1.0, 2.0));
collider.massMode = R2_MASS_PROPERTIES;
collider.massProperties = (R2MassProperties){
    .local_com = r2Vector(0.0, 1.0),
    .mass = 0.5,
    .principal_inertia = 0.3,
};
// 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);

The explicit mass-properties are given by a R3MassProperties: the center-of-mass local_com in the collider's local space, the mass, and the principal_inertia (a scalar in 2D, or the three principal angular inertia in 3D, along the axes given by the principal_inertia_local_frame rotation).

They can also be modified after the creation of the collider with r3Collider_SetDensity, r3Collider_SetMass, or r3Collider_SetMassProperties. Each of these functions (as well as the massMode of the description) replaces the mass-properties previously set by any of the others: for example, calling r3Collider_SetMass on a collider created with a density makes its density be ignored. The mass-properties of the rigid-body the collider is attached to are then updated automatically at the next simulation step (or immediately with r3RigidBody_RecomputeMassPropertiesFromColliders). The resulting volume, density, mass, and local mass-properties of a collider can be read with r3Collider_Volume, r3Collider_Density, r3Collider_Mass, and r3Collider_MassProperties.