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, with ColliderBuilder::density, ColliderBuilder::mass, or ColliderBuilder::mass_properties: The mass-properties of a collider can be set when the collider is created, or after its creation by modifying its ColliderMassProperties component: The mass-properties of a collider can be set when the collider is created, with ColliderDesc.setDensity, ColliderDesc.setMass, or ColliderDesc.setMassProperties: 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: The mass-properties of a collider can be set when the collider is created, with ColliderBuilder.density, ColliderBuilder.mass, or ColliderBuilder.mass_properties: 
let rigid_body = RigidBodyBuilder::dynamic().build();
let rigid_body_handle = world.insert_body(rigid_body);
// First option: by setting the density of the collider (or we could just leave
//               its default value 1.0).
let collider = ColliderBuilder::cuboid(1.0, 2.0).density(2.0).build();
// Second option: by setting the mass of the collider.
let collider = ColliderBuilder::cuboid(1.0, 2.0).mass(0.8).build();
// Third option: by setting the mass-properties explicitly.
let collider = ColliderBuilder::cuboid(1.0, 2.0)
    .mass_properties(MassProperties::new(Vector::new(0.0, 1.0), 0.5, 0.3))
    .build();
// When the collider is attached, the rigid-body's mass and angular
// inertia is automatically updated to take the collider into account.
world.insert_collider(collider, Some(rigid_body_handle));

They can also be modified after the creation of the collider with Collider::set_density, Collider::set_mass, or Collider::set_mass_properties. Each of these methods (as well as the builder methods above) replaces the mass-properties previously set by any of the others: for example, calling Collider::set_mass on a collider built with ColliderBuilder::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 RigidBody::recompute_mass_properties_from_colliders).

 
// First option: by setting the density of the collider (or we could just leave
//               its default value 1.0).
let collider_mprops = ColliderMassProperties::Density(2.0);
// Second option: by setting the mass of the collider.
let collider_mprops = ColliderMassProperties::Mass(0.8);
// Third option: by setting the mass-properties explicitly.
let collider_mprops = ColliderMassProperties::MassProperties(MassProperties {
    local_center_of_mass: Vec2::new(0.0, 1.0),
    mass: 0.5,
    principal_inertia: 0.3,
});

// When the collider is attached, the rigid-body's mass and angular
// inertia will be automatically updated to take the collider into account.
commands
    .spawn(RigidBody::Dynamic)
    .insert(Collider::ball(0.5))
    .insert(collider_mprops);

The resulting volume, density, mass, and local mass-properties of a collider can be read from its ReadColliderMassProperties component, inserted automatically with the Collider component. This component is updated whenever the collider or its ColliderMassProperties change, and modifying it has no effect on the simulation.

 
let rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic();
let rigidBody = world.createRigidBody(rigidBodyDesc);
// First option: by setting the density of the collider (or we could just leave
//               its default value 1.0).
let colliderDesc = RAPIER.ColliderDesc.cuboid(1.0, 2.0)
    .setDensity(2.0);
// Second option: by setting the mass of the collider.
let colliderDesc2 = RAPIER.ColliderDesc.cuboid(1.0, 2.0)
    .setMass(0.8);
// Third option: by setting the mass-properties explicitly.
let colliderDesc3 = RAPIER.ColliderDesc.cuboid(1.0, 2.0)
    .setMassProperties(0.5, { x: 0.0, y: 1.0 }, 0.3);
// When the collider is attached, the rigid-body's mass and angular
// inertia is automatically updated to take the collider into account.
let collider = world.createCollider(colliderDesc, rigidBody);

They can also be modified after the creation of the collider with Collider.setDensity, Collider.setMass, or Collider.setMassProperties. Each of these methods (as well as the ColliderDesc methods above) replaces the mass-properties previously set by any of the others: for example, calling Collider.setMass on a collider created with ColliderDesc.setDensity 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 RigidBody.recomputeMassPropertiesFromColliders).

 
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.

 
rigid_body_handle = world.add_body(rp.RigidBody.dynamic())
# First option: by setting the density of the collider (or we could just leave
#               its default value 1.0).
collider = rp.Collider.cuboid(1.0, 2.0, 3.0).density(2.0).build()
# Second option: by setting the mass of the collider.
collider = rp.Collider.cuboid(1.0, 2.0, 3.0).mass(0.8).build()
# Third option: by setting the mass-properties explicitly.
collider = (
    rp.Collider.cuboid(1.0, 2.0, 3.0)
    .mass_properties(
        rp.MassProperties(
            local_com=(0.0, 1.0, 0.0),
            mass=0.5,
            principal_inertia=(0.3, 0.2, 0.1),
        )
    )
    .build()
)
# 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)

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

They can also be modified after the creation of the collider by assigning its density, mass, or mass_properties property. Each of these properties (as well as the builder methods above) replaces the mass-properties previously set by any of the others: for example, assigning the mass of a collider built with ColliderBuilder.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 RigidBody.recompute_mass_properties_from_colliders(world.colliders)). The resulting volume, density, mass, and local mass-properties of a collider can be read from its volume, density, mass, and mass_properties properties.