avian3d::dynamics::rigid_body

Module mass_properties

source
Expand description

Mass property functionality for rigid bodies and colliders.

§Overview

Every dynamic rigid body has mass, angular inertia, and a center of mass. These mass properties determine how the rigid body responds to forces and torques.

  • Mass: Represents resistance to linear acceleration. A higher mass requires more force for the same acceleration.
  • Angular Inertia: Represents resistance to angular acceleration. A higher angular inertia requires more torque for the same angular acceleration.
  • Center of Mass: The average position of mass in the body. Applying forces at this point produces no torque.

Static and kinematic rigid bodies have infinite mass and angular inertia, and do not respond to forces or torques. Zero mass for a dynamic body is also treated as a special case, and corresponds to infinite mass.

Mass properties can be set for individual entities using the Mass, AngularInertia, and CenterOfMass components. If they are not present, mass properties are instead computed automatically from attached colliders based on their shape and ColliderDensity.

If a rigid body has child entities, their mass properties are combined to compute the total mass properties of the rigid body. These are stored in the ComputedMass, ComputedAngularInertia, and ComputedCenterOfMass components, which are updated automatically when mass properties are changed, or when colliders are added or removed.

To prevent mass properties of child entities from contributing to the total mass properties, you can use the NoAutoMass, NoAutoAngularInertia, and NoAutoCenterOfMass marker components. This can be useful when full control over mass properties is desired.

§Example

If no mass properties are set, they are computed automatically from attached colliders based on their shape and density.

// Note: `ColliderDensity` is optional, and defaults to `1.0` if not present.
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    ColliderDensity(2.0),
));

If mass properties are set with the Mass, AngularInertia, and CenterOfMass components, they override the values computed from colliders.

// Override mass and the center of mass, but use the collider's angular inertia.
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(5.0),
    CenterOfMass::new(0.0, -0.5, 0.0),
));

If the rigid body has child colliders, their mass properties will be combined for the total ComputedMass, ComputedAngularInertia, and ComputedCenterOfMass.

// Total mass: 10.0 + 5.0 = 15.0
// Total center of mass: (10.0 * [0.0, -0.5, 0.0] + 5.0 * [0.0, 4.0, 0.0]) / (10.0 + 5.0) = [0.0, 1.0, 0.0]
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(10.0),
    CenterOfMass::new(0.0, -0.5, 0.0),
    Transform::default(),
))
.with_child((
    Collider::sphere(1.0),
    Mass(5.0),
    Transform::from_xyz(0.0, 4.0, 0.0),
));

To prevent child entities from contributing to the total mass properties, use the NoAutoMass, NoAutoAngularInertia, and NoAutoCenterOfMass marker components.

// Total mass: 10.0
// Total center of mass: [0.0, -0.5, 0.0]
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(10.0),
    CenterOfMass::new(0.0, -0.5, 0.0),
    NoAutoMass,
    NoAutoCenterOfMass,
    Transform::default(),
))
.with_child((
    Collider::sphere(1.0),
    Mass(5.0),
    Transform::from_xyz(0.0, 4.0, 0.0),
));

§Computing Mass Properties for Shapes

Mass properties of colliders and Bevy’s primitive shapes can be computed using methods provided by the ComputeMassProperties2d and ComputeMassProperties3d traits.

// Compute mass properties for a capsule collider with a density of `2.0`.
let capsule = Collider::capsule(0.5, 1.5);
let mass_properties = capsule.mass_properties(2.0);

// Compute individual mass properties for a `Circle`.
let circle = Circle::new(1.0);
let mass = circle.mass(2.0);
let angular_inertia = circle.angular_inertia(mass);
let center_of_mass = circle.center_of_mass();

Similarly, shapes can be used to construct the Mass, AngularInertia, and CenterOfMass components, or the MassPropertiesBundle.

// Construct individual mass properties from a collider.
let shape = Collider::sphere(0.5);
commands.spawn((
    RigidBody::Dynamic,
    Mass::from_shape(&shape, 2.0),
    AngularInertia::from_shape(&shape, 1.5),
    CenterOfMass::from_shape(&shape),
));

// Construct a `MassPropertiesBundle` from a primitive shape.
let shape = Sphere::new(0.5);
commands.spawn((RigidBody::Dynamic, MassPropertiesBundle::from_shape(&shape, 2.0)));

This mass property computation functionality is provided by the bevy_heavy crate.

§Mass Property Helper

MassPropertyHelper is a SystemParam that provides convenient helper methods that can be used to modify or compute mass properties for individual entities and hierarchies at runtime.

For example, MassPropertyHelper::total_mass_properties computes the total mass properties of an entity, taking into account the mass properties of descendants and colliders.

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§