Mass Property Rework (#574)

# Objective

Closes #443.
Implements the rest of #499, continuing the work done in #500 and #532.

The current mass property functionality is very limited, confusing, and footgunny.

- `Mass`, `AngularInertia`, and `CenterOfMass` can be added to a rigid body to specify its initial mass properties. However, the mass properties of colliders and descendants are *always* added on top, to the same components. From the user's perspective, the initial mass information is lost, and *there is no way to fully override mass properties on spawn*.
- If you manually set `Mass` to a lower value at runtime, and then remove a collider, you could end up with *negative* mass.
- Angular inertia is not scaled when mass is changed at runtime.
- Specifying the center of mass at spawn does nothing, *except* if an initial mass is specified. This is because when mass properties from colliders are added/removed, the new center of mass is computed as the weighted average, and the initial mass for the rigid body is zero.
- `Mass`, `AngularInertia`, and `CenterOfMass` do *nothing* on child colliders.
- After #500, mass and angular inertia store inverses, and 3D angular inertia in particular stores a 3x3 matrix. These representations aren't very user-friendly, and may not be ideal for scene and editor workflows.
- The internal implementation is confusing and has a decent amount of overhead, relying on observers and storing previous collider transforms for mass property updates.

We need a mass property system that is simple, understandable, and lightweight, while being flexible enough to support more advanced use cases. Some high-level goals here are:

- Unless overridden, colliders and child colliders should contribute to the total mass properties.
- It must be straightforward to override the total mass properties and disable automatic mass computation.
- It should also be possible to override mass properties for indidual child colliders, using the same components as for rigid bodies.
- User-specified mass properties should not be lost, and it should not be possible to get negative mass unless explicitly overridden.
- Behavior should be intuitive.

## Solution

### `Mass` and `ComputedMass`

Using the same component for the *user-specified* mass and the *total* mass (that takes all attached colliders into account) was problematic.

The *total mass properties* of rigid bodies are now stored in the new `ComputedMass`, `ComputedAngularInertia`, and `ComputedCenterOfMass` components. By default, these are updated automatically when mass properties are changed, or when colliders are added or removed. Computed mass properties are required components for `RigidBody`.

`Mass`, `AngularInertia`, and `CenterOfMass` now instead represent the mass properties associated with a *specific* entity. These are optional and never modified by Avian directly. If a rigid body entity has `Mass(10.0)`, and its child collider has `Mass(5.0)`, their mass properties will be combined as `ComputedMass(15.0)`.

```rust
// Total mass for rigid body: 10 + 5 = 15
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(10.0),
))
.with_child((Collider::circle(1.0), Mass(5.0)));
```

If `Mass`, `AngularInertia`, or `CenterOfMass` are not set for an entity, the mass properties of its collider will be used instead, if present. Overridding mass with `Mass` also scales angular inertia accordingly, unless it is also overriden with `AngularInertia`.

Sometimes, you might not want child entities or colliders to contribute to the total mass properties. This can be done by adding the `NoAutoMass`, `NoAutoAngularInertia`, and `NoAutoCenterOfMass` marker components, giving you full manual control.

```rust
// 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::circle(1.0),
    Mass(5.0),
    Transform::from_translation(Vec3::new(0.0, 4.0, 0.0)),
));
```

That's pretty much it! To recap, the core API has been distilled into:

1. By default, mass properties are computed from attached colliders and `ColliderDensity`.
2. Mass properties can be overridden for individual entities with `Mass`, `AngularInertia`, and `CenterOfMass`.
3. If the rigid body has descendants (child colliders), their mass properties will be combined for the total `ComputedMass`, `ComputedAngularInertia`, and `ComputedCenterOfMass`.
4. To prevent child entities from contributing to the total mass properties, use the `NoAutoMass`, `NoAutoAngularInertia`, and `NoAutoCenterOfMass` marker components.

This is *much* more predictable and flexible than the old system.

This isn't all that has changed though. I have implemented *many* more improvements here.

## API Improvements

### Representation

Unlike the computed mass property components, `Mass`, `AngularInertia`, and `CenterOfMass` have user-friendly representations with public fields. 3D `AngularInertia` differs the most, as it now stores a principal angular inertia (`Vec3`) and the orientation of the local inertial frame (`Quat`) instead of an inertia tensor (`Mat3`). This is more memory efficient and more intuitive to tune by hand.

```rust
// Irrelevant derives and docs stripped for readability.

#[derive(Component, Default, Deref, DerefMut)]
pub struct Mass(pub f32);

#[cfg(feature = "2d")]
#[derive(Component, Default, Deref, DerefMut)]
pub struct AngularInertia(pub f32);

#[cfg(feature = "3d")]
#[derive(Component)]
pub struct AngularInertia {
    /// The principal angular inertia, representing resistance to angular acceleration
    /// about the local coordinate axes defined by the `local_frame`.
    pub principal: Vec3,
    /// The orientation of the local inertial frame.
    pub local_frame: Quat,
}

#[cfg(feature = "2d")]
#[derive(Component, Default, Deref, DerefMut)]
pub struct CenterOfMass(pub Vec2);

#[cfg(feature = "3d")]
#[derive(Component, Default, Deref, DerefMut)]
pub struct CenterOfMass(pub Vec3);
```

### Helpers and Constructors

There are now a *ton* more helpers and constructors, especially for 3D `AngularInertia`. It has methods like:

- `new`, `try_new`
- `new_with_local_frame`, `try_with_local_frame`
- `from_tensor`
- `tensor`
	- This returns an `AngularInertiaTensor`, which has further methods and operations. More on that in the next section!

`ComputedMass`, `ComputedAngularInertia`, and `ComputedCenterOfMass` have even more methods in order to help work with the inverse representation efficiently.

### `bevy_heavy` Integration

[`bevy_heavy`](https://github.com/Jondolf/bevy_heavy) is my new mass property crate for Bevy. It provides `MassProperty2d` and `MassProperty3d` types, and traits for computing mass properties for *all* of Bevy's primitive shapes. Avian now takes advantage of this in a few ways.

`Collider` now implements the `ComputeMassProperties2d`/`ComputeMassProperties3d` trait for mass property computation. The `mass_properties` method returns `MassProperty2d`/`MassProperty3d` instead of `ColliderMassProperties`, and you can also compute mass, angular inertia, and the center of mass individually:

```rust
// Compute all 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 (2D here)
let mass = capsule.mass(2.0);
let angular_inertia = capsule.angular_inertia(mass);
let center_of_mass = capsule.center_of_mass();
```

`Mass`, `AngularInertia`, `CenterOfMass`, and `MassPropertiesBundle` now also have a `from_shape` method that takes a type implementing `ComputeMassProperties2d`/`ComputeMassProperties3d` and a density. The nice part here is that you can also use Bevy's primitive shapes:

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

> [!NOTE]
> For now, mass properties for actual colliders still use Parry's mass computation methods, which are less flexible. If we eventually manage to replace Parry with an alternative using Bevy's geometric primitives though, we could transition to only using `bevy_heavy` here.

Working with 3D angular inertia and converting between different representations can be somewhat complex. `bevy_heavy` has an eigensolver for diagonalizing angular inertia tensors, and provides an `AngularInertiaTensor` type to wrap this in a nice API. This is used a bit internally, and also returned by methods like `AngularInertia::tensor`.

As you might have noticed earlier, `Mass`, `AngularInertia`, `CenterOfMass`, and `ColliderDensity` now only use `f32` types. This is partially to integrate better with `bevy_heavy`, but also because I believe `f64` precision just isn't needed for these user-facing mass property types. The total computed mass properties still support `f64` however.

### `MassPropertyHelper`

Sometimes, it might be useful to compute or update mass properties for individual entities or hierarchies manually. There is now a new `MassPropertyHelper` system parameter for this, with the following methods:

- `update_mass_properties`
- `total_mass_properties` (descendants + local)
- `descendants_mass_properties`
- `local_mass_properties`

The old internal logic for mass property updates relied on storing previous and current collider transforms, subtracting old mass properties if present, and adding the new mass properties. This was very error-prone, probably buggy, had bookkeeping overhead, and was somewhat expensive, since it used observers to trigger recomputation.

Now, mass properties are always just recomputed "from scratch" with `update_mass_properties`, which recomputes the total mass properties, taking into account descendants, colliders, and the `NoAutoMass`, `NoAutoAngularInertia`, and `NoAutoCenterOfMass` components. Mass properties are combined using `Iterator::sum`, which is more efficient than the old approach of adding every collider's mass properties individually. Updates are triggered by adding the `RecomputeMassProperties` sparse-set component when mass properties are detected to have changed, avoiding duplicate computation and using standard query iteration instead of observer triggers. I expect this to have much less overhead, and it at least reduces a lot of internal complexity.

I expect the `MassPropertyHelper` to get more user-facing utilities in the future as we identify usage patterns and common tasks users need to perform.

### Other Changes

- Zero mass and angular inertia is now treated as valid, and interpreted as infinite mass (like in most engines). It no longer emits warnings, and collider density is not clamped in any way.
- `ColliderMassProperties` stores `MassProperties2d`/`MassProperties3d` instead of separate properties. This simplifies a lot of internals and provides a richer API.
- `ColliderMassProperties` is now properly read-only, excluding setting the component directly or reinserting it.
- Added a *ton* of documentation and polish for mass properties.
- Added lots of tests to verify behavior is as expected.
- Added `MassPropertiesSystems` system sets for mass properties, and decoupled the `ColliderBackendPlugin` further from `MassPropertyPlugin`.
- Fixed some scheduling issues.
- Reworked the module structure a bit to organize things better.

## Future Work

- Make computed mass properties only required for dynamic bodies. We could distinguish between different types of rigid bodies at the component-level, e.g. `DynamicBody`, `KinematicBody`, and `StaticBody` (there are many approaches we could take here).
- Only compute `ColliderMassProperties` automatically for colliders that are attached to a (dynamic) rigid body.

---

## Migration Guide

### Behavior Changes

- `Mass`, `AngularInertia`, and `CenterOfMass` are now optional, and can be used to override the mass properties of an entity if present, ignoring the entity's collider. Mass properties that are not set are still computed from the entity's `Collider` and `ColliderDensity`.
- Mass properties of child entities still contribute to the total mass properties of rigid bodies by default, but the total values are stored in `ComputedMass`, `ComputedAngularInertia`, and `ComputedCenterOfMass` instead of `Mass`, `AngularInertia`, and `CenterOfMass`. The latter components are now never modified by Avian directly.
- To prevent colliders or descendants from contributing to the total mass properties, add the `NoAutoMass`, `NoAutoAngularInertia`, and `NoAutoCenterOfMass` marker components to the rigid body, giving you full manual control.
- Previously, changing `Mass` at runtime did not affect angular inertia. Now, it is scaled accordingly, unless `NoAutoAngularInertia` is present.
- Previously, specifying the `CenterOfMass` at spawn did nothing *unless* an initial `Mass` was specified, even if the entity had a collider that would give it mass. This has been fixed.
- Previously, `Mass`, `AngularInertia`, and `CenterOfMass` did *nothing* on child colliders. Now, they effectively override `ColliderMassProperties` when computing the total mass properties for the rigid body.
- Previously, zero mass and angular inertia were treated as invalid. It emitted warnings, which was especially problematic and spammy for runtime collider constructors. Now, they are treated as acceptable values, and interpreted as infinite mass, like in most other engines.

### API Changes

- `Mass`, `AngularInertia`, `CenterOfMass`, `ColliderDensity`, and `ColliderMassProperties` now always use `f32` types, even with the `f64` feature. Total mass properties stored in `ComputedMass`, `ComputedAngularInertia`, and `ComputedCenterOfMass` still support `f64`.
- In 3D, `AngularInertia` now stores a principal angular inertia (`Vec3`) and the orientation of the local inertial frame (`Quat`) instead of an inertia tensor (`Mat3`). However, several different constructors are provided, including `from_tensor`.
- `MassPropertiesBundle::new_computed` and `ColliderMassProperties::from_collider` have been renamed to `from_shape`.
- `ColliderMassProperties` now stores a `MassProperties2d`/`MassProperties3d` instead of separate properties.
- Types implementing `AnyCollider` must now also implement the `ComputeMassProperties2d`/`ComputeMassProperties3d` trait instead of the `mass_properties` method.

Author: Jondolf

README.md

@@ -121,7 +121,7 @@ fn setup(
         Collider::cuboid(1.0, 1.0, 1.0),
         AngularVelocity(Vec3::new(2.5, 3.5, 1.5)),
         PbrBundle {
-            mesh: meshes.add(Cuboid::new(1.0, 1.0, 1.0)),
+            mesh: meshes.add(Cuboid::from_length(1.0)),
             material: materials.add(Color::srgb_u8(124, 144, 255)),
             transform: Transform::from_xyz(0.0, 4.0, 0.0),
             ..default()

crates/avian2d/Cargo.toml

@@ -33,6 +33,7 @@ enhanced-determinism = [
     "parry2d?/enhanced-determinism",
     "parry2d-f64?/enhanced-determinism",
     "bevy_math/libm",
+    "bevy_heavy/libm",
 ]
 
 default-collider = ["dep:nalgebra"]
@@ -61,6 +62,7 @@ bench = false
 avian_derive = { path = "../avian_derive", version = "0.1" }
 bevy = { version = "0.15", default-features = false }
 bevy_math = { version = "0.15" }
+bevy_heavy = { version = "0.1" }
 libm = { version = "0.2", optional = true }
 parry2d = { version = "0.17", optional = true }
 parry2d-f64 = { version = "0.17", optional = true }
@@ -76,6 +78,7 @@ bitflags = "2.5.0"
 examples_common_2d = { path = "../examples_common_2d" }
 benches_common_2d = { path = "../benches_common_2d" }
 bevy_math = { version = "0.15", features = ["approx"] }
+bevy_heavy = { version = "0.1", features = ["approx"] }
 glam = { version = "0.29", features = ["bytemuck"] }
 approx = "0.5"
 bytemuck = "1.19"

crates/avian2d/examples/chain_2d.rs

@@ -49,7 +49,7 @@ fn setup(
         let current_particle = commands
             .spawn((
                 RigidBody::Dynamic,
-                MassPropertiesBundle::new_computed(&Collider::circle(particle_radius), 1.0),
+                MassPropertiesBundle::from_shape(&Circle::new(particle_radius as f32), 1.0),
                 Mesh2d(particle_mesh.clone()),
                 MeshMaterial2d(particle_material.clone()),
                 Transform::from_xyz(0.0, -i as f32 * (particle_radius as f32 * 2.0 + 1.0), 0.0),

crates/avian2d/examples/custom_collider.rs

@@ -1,5 +1,7 @@
 //! An example demonstrating how to make a custom collider and use it for collision detection.
 
+#![allow(clippy::unnecessary_cast)]
+
 use avian2d::{math::*, prelude::*};
 use bevy::prelude::*;
 use examples_common_2d::ExampleCommonPlugin;
@@ -55,21 +57,8 @@ impl AnyCollider for CircleCollider {
         ColliderAabb::new(position, Vector::splat(self.radius))
     }
 
-    fn mass_properties(&self, density: Scalar) -> ColliderMassProperties {
-        // In 2D, the Z length is assumed to be 1.0, so volume = area
-        let volume = PI * self.radius.powi(2);
-        let mass = density * volume;
-        let angular_inertia = mass * self.radius.powi(2) / 2.0;
-
-        ColliderMassProperties {
-            mass,
-            angular_inertia,
-            center_of_mass: default(),
-        }
-    }
-
     // This is the actual collision detection part.
-    // It compute all contacts between two colliders at the given positions.
+    // It computes all contacts between two colliders at the given positions.
     fn contact_manifolds(
         &self,
         other: &Self,
@@ -122,6 +111,25 @@ impl AnyCollider for CircleCollider {
     }
 }
 
+// Implement mass computation for the collider shape.
+// This is needed for physics to behave correctly.
+impl ComputeMassProperties2d for CircleCollider {
+    fn mass(&self, density: f32) -> f32 {
+        // In 2D, the Z length is assumed to be `1.0`, so volume == area.
+        let volume = std::f32::consts::PI * self.radius.powi(2) as f32;
+        density * volume
+    }
+
+    fn unit_angular_inertia(&self) -> f32 {
+        // Angular inertia for a circle, assuming a mass of `1.0`.
+        self.radius.powi(2) as f32 / 2.0
+    }
+
+    fn center_of_mass(&self) -> Vec2 {
+        Vec2::ZERO
+    }
+}
+
 // Note: This circle collider only supports uniform scaling.
 impl ScalableCollider for CircleCollider {
     fn scale(&self) -> Vector {

crates/avian2d/examples/distance_joint_2d.rs

@@ -34,7 +34,7 @@ fn setup(mut commands: Commands) {
             square_sprite,
             Transform::from_xyz(100.0, 0.0, 0.0),
             RigidBody::Dynamic,
-            MassPropertiesBundle::new_computed(&Collider::rectangle(50.0, 50.0), 1.0),
+            MassPropertiesBundle::from_shape(&Rectangle::from_length(50.0), 1.0),
         ))
         .id();
 

crates/avian2d/examples/fixed_joint_2d.rs

@@ -38,7 +38,7 @@ fn setup(mut commands: Commands) {
             square_sprite,
             Transform::from_xyz(100.0, 0.0, 0.0),
             RigidBody::Dynamic,
-            MassPropertiesBundle::new_computed(&Collider::rectangle(50.0, 50.0), 1.0),
+            MassPropertiesBundle::from_shape(&Rectangle::from_length(50.0), 1.0),
         ))
         .id();
 

crates/avian2d/examples/prismatic_joint_2d.rs

@@ -38,7 +38,7 @@ fn setup(mut commands: Commands) {
             square_sprite,
             Transform::from_xyz(100.0, 0.0, 0.0),
             RigidBody::Dynamic,
-            MassPropertiesBundle::new_computed(&Collider::rectangle(50.0, 50.0), 1.0),
+            MassPropertiesBundle::from_shape(&Rectangle::from_length(50.0), 1.0),
         ))
         .id();
 

crates/avian2d/examples/revolute_joint_2d.rs

@@ -38,7 +38,7 @@ fn setup(mut commands: Commands) {
             square_sprite,
             Transform::from_xyz(0.0, -100.0, 0.0),
             RigidBody::Dynamic,
-            MassPropertiesBundle::new_computed(&Collider::rectangle(50.0, 50.0), 1.0),
+            MassPropertiesBundle::from_shape(&Rectangle::from_length(50.0), 1.0),
         ))
         .id();
 

crates/avian3d/Cargo.toml

@@ -34,6 +34,7 @@ enhanced-determinism = [
     "parry3d?/enhanced-determinism",
     "parry3d-f64?/enhanced-determinism",
     "bevy_math/libm",
+    "bevy_heavy/libm",
 ]
 
 default-collider = ["dep:nalgebra"]
@@ -48,6 +49,7 @@ bevy_picking = ["bevy/bevy_picking"]
 serialize = [
     "dep:serde",
     "bevy/serialize",
+    "bevy_heavy/serialize",
     "parry3d?/serde-serialize",
     "parry3d-f64?/serde-serialize",
     "bitflags/serde",
@@ -63,6 +65,7 @@ bench = false
 avian_derive = { path = "../avian_derive", version = "0.1" }
 bevy = { version = "0.15", default-features = false }
 bevy_math = { version = "0.15" }
+bevy_heavy = { version = "0.1" }
 libm = { version = "0.2", optional = true }
 parry3d = { version = "0.17", optional = true }
 parry3d-f64 = { version = "0.17", optional = true }
@@ -75,13 +78,14 @@ itertools = "0.13"
 bitflags = "2.5.0"
 
 [dev-dependencies]
+examples_common_3d = { path = "../examples_common_3d" }
+benches_common_3d = { path = "../benches_common_3d" }
 bevy = { version = "0.15", default-features = false, features = [
     "bevy_gltf",
     "animation",
 ] }
-examples_common_3d = { path = "../examples_common_3d" }
-benches_common_3d = { path = "../benches_common_3d" }
 bevy_math = { version = "0.15", features = ["approx"] }
+bevy_heavy = { version = "0.1", features = ["approx"] }
 approx = "0.5"
 criterion = { version = "0.5", features = ["html_reports"] }
 bevy_mod_debugdump = { git = "https://github.com/jakobhellermann/bevy_mod_debugdump" }

crates/avian3d/examples/chain_3d.rs

@@ -56,7 +56,7 @@ fn setup(
         let current_particle = commands
             .spawn((
                 RigidBody::Dynamic,
-                MassPropertiesBundle::new_computed(&Collider::sphere(particle_radius), 1.0),
+                MassPropertiesBundle::from_shape(&Sphere::new(particle_radius as f32), 1.0),
                 Mesh3d(particle_mesh.clone()),
                 MeshMaterial3d(particle_material.clone()),
                 Transform::from_xyz(0.0, -i as f32 * particle_radius as f32 * 2.2, 0.0),