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:

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.