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, or after its creation by modifying its ColliderMassProperties component:

Example 2D

// 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);

Example 3D

// 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: Vec3::new(0.0, 1.0, 2.0),
    mass: 0.5,
    principal_inertia_local_frame: Quat::IDENTITY,
    principal_inertia: Vec3::new(0.3, 0.4, 0.5),
});
// 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.