Mass Properties V2

[Jondolf]

Mass properties in Avian are currently inefficient and unergonomic.

• Overriding mass properties is not straightforward. This is a very common pain point for users.
• The different mass properties of colliders cannot be set individually. Only the density is configurable.
• Mass property components have confusing relationships and duplicate APIs. Mass and InverseMass as well as Inertia and InverseInertia are stored separately, even though they are tightly coupled.
• Kinematic bodies, static bodies, and standalone colliders have mass properties, even though they don't need them.
• ColliderMassProperties looks like a component that can be configured, even though it is automatically updated and intended as read-only.
• In 3D, the world-space angular inertia tensor is recomputed multiple times per substep. This is expensive.

This is a proposal for overhauling how mass properties are handled in Avian.

At a high level, my proposal consists of the following:

• Remove InverseMass and InverseInertia. Store the inverses in Mass and AngularInertia directly, but expose an ergonomic API that abstracts away the complexity.
• Remove the Component derive from Mass, AngularInertia, and CenterOfMass. Add wrappers like ReadOnlyMass, ReadOnlyAngularInertia, and ReadOnlyCenterOfMass to make it clear that they should not be set directly.
• Rename ColliderMassProperties to ReadOnlyColliderMassProperties, and make the fields only accessible through getters.
• Add CustomMass, CustomAngularInertia, and CustomCenterOfMass components for explicitly setting mass properties for rigid bodies or colliders, also making editor workflows like Blenvy nicer.
• Make mass properties optional for kinematic bodies, static bodies, and standalone colliders. The mass property components should only be inserted automatically for dynamic bodies and colliders attached to them.
• In 3D, cache the world-space angular inertia tensor in a read-only GlobalAngularInertia component, and only update it when the Rotation is changed.

I will go into a bit more detail in the following sections, along with actual code examples. Keep in mind that this is just a draft, and details may change. My plan is to implement this over multiple PRs.

Remove InverseMass and InverseInertia in favor of Mass and AngularInertia

Currently, the inverses of Mass and Inertia (poor name, since mass is also inertia) are cached in the InverseMass and InverseInertia components. They are updated automatically.

These relationships are confusing and add complexity. The physics engine primarily just needs the inverse mass properties, while Mass and Inertia are mainly a user-facing API. In addition, when the Mass or Inertia are changed, their inverses will be out of sync until the systems responsible for updating them run.

I propose storing the inverses in Mass and AngularInertia directly. This is abstracted away through constructors and getters, so you don't need to deal with the inverse unless you want to.

#[derive(Component)]
pub struct Mass {
    inverse: Scalar,
}

let mut mass = Mass::new(5.0);
assert_eq!(mass.value(), 5.0);

mass.set(Mass::from_inverse(0.5));
assert_eq!(mass.value(), 2.0);
assert_eq!(mass.inverse(), 0.5);

2D:

#[derive(Component)]
pub struct AngularInertia {
    inverse: Scalar,
}

let mut angular_inertia = AngularInertia::new(5.0);
assert_eq!(angular_inertia.value(), 5.0);

angular_inertia.set(AngularInertia::from_inverse(0.5));
assert_eq!(angular_inertia.value(), 2.0);
assert_eq!(angular_inertia.inverse(), 0.5);

3D:

#[derive(Component)]
pub struct AngularInertia {
    inverse: Matrix,
}

let mut angular_inertia = AngularInertia::new(Matrix::from_diagonal(Vector::splat(2.0)));
assert_eq!(angular_inertia.tensor().diagonal(), Vector::splat(2.0));

Store Mass, AngularInertia, and CenterOfMass in Read-Only Components

In the previous section, Mass, AngularInertia, and CenterOfMass were still components. However, they are automatically updated by the physics engine, and are generally not intended to be modified directly. You can modify them manually, but the mass properties of colliders are always added on top. This adds a lot of complexity and has led to lots of confusion.

In addition, they're not used just as components, as they are also stored in e.g. ColliderMassProperties.

I propose removing the Component derive from Mass, AngularInertia, and CenterOfMass, and adding read-only wrappers ReadOnlyMass, ReadOnlyAngularInertia, and ReadOnlyCenterOfMass. The physics engine uses these internally, and manages them in the background.

// These could be grouped for queries with `MassPropertiesQuery`

#[derive(Component, Deref)]
pub struct ReadOnlyMass(Mass);

#[derive(Component, Deref)]
pub struct ReadOnlyAngularInertia(AngularInertia);

#[derive(Component, Deref)]
pub struct ReadOnlyCenterOfMass(CenterOfMass);

ColliderMassProperties should also be renamed to ReadOnlyColliderMassProperties and properly made read-only to avoid misuse.

With Mass, AngularInertia, and CenterOfMass being their own types that don't assume ECS usage, we could even have them in a general 3rd party mass property computation crate. In fact, I have that already: bevy_heavy! We can start by having the types in Avian directly though.

Now, if the mass properties are read-only, how do you configure them? See the next section!

Add CustomMass, CustomAngularInertia, and CustomCenterOfMass

Edit Aug 25: This originally had MassMode, AngularInertiaMode, and CenterOfMassMode components with Auto and Custom variants, but the Auto variant was kind of redundant since it's the default behavior, so I simplified the types here.

Currently, the only way to explicitly set the mass properties for an object is to set the ColliderDensity of each of its colliders to zero and to then set the Mass, Inertia, and (optionally) CenterOfMass manually. You can also add more mass by modifying Mass directly, but the collider's mass properties are still added on top. This is confusing, not very flexible, and likely has bugs and weird edge cases.

In the previous sections, we also made the mass properties read-only. Additionally, the internal representation (multiplicative inverse) isn't very user-friendly, which makes working with editors, inspectors, and scene workflows like Blenvy painful.

I propose fixing all of the above issues by adding CustomMass, CustomAngularInertia, and CustomCenterOfMass components. They can be used to explicitly specify mass properties. If the components don't exist, the corresponding mass properties are automatically derived from colliders by default.

#[derive(Component)]
pub enum CustomMass {
    Mass(Scalar),
    Density(Scalar),
}

impl Default for CustomMass {
    fn default() -> Self {
        Self::Density(1.0)
    }
}

#[cfg(feature = "2d")]
#[derive(Component, Deref, DerefMut)]
pub struct CustomAngularInertia(pub Scalar);

#[cfg(feature = "3d")]
#[derive(Component, Deref, DerefMut)]
pub struct CustomAngularInertia {
    // Note: We could also store a 3x3 tensor, but it'd be more difficult and error-prone
    //       to manually specify and edit in inspectors. There will be constructors for tensors as well.
    pub principal_inertia: Vector,
    pub orientation: Quaternion,
}

#[derive(Component, Deref, DerefMut)]
pub struct CustomCenterOfMass(pub Vector);

On a RigidBody entity, the components affect the entire body's mass property computation. Otherwise, each attached collider can specify its own mass properties.

Make Mass Properties For Non-Dynamic Objects and Standalone Colliders Optional

Currently, mass property components are inserted automatically for all rigid bodies and colliders. However, only dynamic rigid bodies and colliders attached to them really need mass.

Mass properties should only be inserted for dynamic rigid bodies and colliders attached to them. However, if other physics entities have mass property components anyway (e.g. added manually by the user), they should probably still get updated automatically.

This will require changes to the solver to make mass optional. Eventually, we should have one-body constraints (e.g. specialized dynamic-static constraints) for optimization purposes as well, but for now, we can probably just assume default mass properties when the components are missing.

Cache World-Space Angular Inertia in GlobalAngularInertia (3D)

In 3D, angular inertia depends on the orientation of the object. The local angular inertia tensor is stored in ReadOnlyAngularInertia, and the world-space version is currently computed multiple times per substep. This is expensive.

The world-space angular inertia only needs to be recomputed when the local angular inertia or rotation changes. The rotation is only changed once per substep, during position/rotation integration. The world-space angular inertia should be cached in its own read-only component.

#[derive(Component, Deref)]
pub struct GlobalAngularInertia(AngularInertia);

Alternatively, we could store it in ReadOnlyAngularInertia directly, and design the API such that the world-space version is always updated whenever the local version is changed.

Extra: EffectiveMass and EffectiveAngularInertia

Most of the physics engine actually uses the effective mass and effective angular inertia, which take the LockedAxes component into account. We could cache these as well, either in their own components, or in ReadOnlyMass and ReadOnlyAngularInertia directly.

The effective versions are quite cheap to compute though, so it isn't immediately clear if caching would be worth it. This needs benchmarking.

Extra: Make Mass Properties Optional Conditionally

There are some special scenarios where we could technically omit mass property components.

• If all translational axes are locked, we could omit ReadOnlyMass.
  • Note: Angular inertia still requires mass, but it doesn't need to be stored in a component.
• If all rotational axes locked, we could omit ReadOnlyAngularInertia.
• If the center of mass is Vector::ZERO, we could omit ReadOnlyCenterOfMass.

However, I don't think it's really worth it to special-case these scenarios. It adds complexity for minimal performance gains (if any) and may be unexpected for users.

[Hellzbellz123]

just some thoughts ive been having while working on my simulation project related too mass properties

one of the things thats pretty common when working with physics engines is tuning parameters like mass/velocity trying too get stable/ 'good' feeling physics.
a common workflow i use is eyeballing in code then using something like bevy_inspector_egui too tune the parameter visually until it feels correct.

im not sure how the CustomAngularInertia component might react too changes of CustomMass or CustomCenterOfMass

[Jondolf]

By default, all the mass properties are automatically derived from the attached colliders. If you add a CustomMass, it will override the automatically computed mass, and scale the angular inertia accordingly (since it depends on the mass). And if you add a CustomAngularInertia, it will override the automatically computed angular inertia, ignoring the mass and center of mass of the object.

This is similar to existing game engines like Godot and Unity. By default, angular inertia and the center of mass are computed automatically, but you can decide to override them with custom values.

---

As an aside, I realized that CustomAngularInertia in 3D should probably store the principal inertia as a Vec3, along with an orientation for the local inertial frame, since directly modifying the 3x3 tensor in inspectors and editors may be a bit error prone and confusing (it must be symmetric and positive definite). I'll update the proposal to use this representation. The type will still have constructors for using a tensor if desired.

[janhohenheim]

Finally got around to reading this! This all sounds really well thought out and actionable. Some thoughts:

• The idea of directly storing the inverse and exposing a method that silently calculates the inverse of the inverse is brilliant, I love it.
• We may even want to completely disallow Mass on static rigid bodies, or document explicitly that having a Mass on it won't have an effect. I know the engine currently supports moving static rigid bodies around, but this mass rework could a first step towards limiting this.
• I personally prefer the prefix Override over Custom, as Custom sounds to me a bit like a custom collider - i.e. a way of completely changing how something works. Instead, we simply force a certain value.
• Agreed that omitting mass property components is probably not worth it.

I have two open questions:

• What happens when OverrideMass (going by my name suggestion, hehe) is removed? Does the mass go back to how it would be calculated if there was no override? At least for me, this would be useful for avian_pickup, as I temporarily reduce the mass while holding an object but want to restore it to normal once I let it go
• If an entity has an OverrideMass, can I read it? If so, I have two ways of reading the same value, which is a bit meh. Maybe OverrideMass should only have a set and no get?

[Jondolf]

Thanks for going over this!

I personally prefer the prefix Override over Custom, as Custom sounds to me a bit like a custom collider - i.e. a way of completely changing how something works. Instead, we simply force a certain value.

I went with Custom here because of Godot's naming:

and because it feels pretty clear to me in this context that it customizes how the value is computed, not how mass inherently works (what would a completely custom interpretation of mass even mean?). I'm definitely open to changing this if there's a better alternative though.

I'm not sure if OverrideFoo is better, since it doesn't seem like an immediately obvious name that I'd look for, and I don't recall any type in Bevy using it, whereas some types do use Custom in a similar context, like bevy_sprite::Anchor::Custom.

One option I was thinking about: This is closer to an earlier iteration of my proposal, but instead of CustomMass, CustomAngularInertia, and CustomCenterOfMass, we could just have Mass, AngularInertia, and CenterOfMass enums:

#[derive(Component)]
pub enum Mass {
    Density(Scalar),
    Custom(Scalar),
}

impl Default for Mass {
    fn default() -> Self {
        Self::Density(1.0)
    }
}

#[cfg(feature = "2d")]
#[derive(Component, Default)]
pub enum AngularInertia {
    #[default]
    Auto,
    Custom(Scalar)
}

#[cfg(feature = "3d")]
#[derive(Component, Default)]
pub enum AngularInertia {
    #[default]
    Auto,
    Custom {
        principal_angular_inertia: Vector,
        orientation: Quaternion,
    }
}

#[derive(Component, Default)]
pub enum CenterOfMass {
    #[default]
    Auto,
    Custom(Vector),
}

This has a few benefits:

• The user-facing API, naming, and semantics are more obvious.
• The "automatic" variant is made explicit. It's a bit strange to compute mass properties automatically without any component clearly indicating that behavior. This ties to Reduce implicit defaults by requiring more components #504, and with Bevy 0.15, we could technically even require these components, defaulting to automatic computation.
• Changing between automatic and custom values at runtime is easier, since you can just change the variant instead of needing to add or remove components.
• Editor workflows will likely be nicer with these enums and more obvious names.

This does perhaps make the names ReadOnlyMass, ReadOnlyAngularInertia, and ReadOnlyCenterOfMass in this proposal a bit weird, as they just sound like read-only versions of Mass, AngularInertia, and CenterOfMass, and it's less clear what components the simulation actually uses.

One idea I had is that we could also rename them to ComputedMass, ComputedAngularInertia, and ComputedCenterOfMass. This would make it even more obvious that the components are automatically computed while reducing confusion with what values the simulation uses.

Let me know if you have any thoughts on this! I keep changing my mind on these APIs and still haven't locked in a final design, so it's all up for discussion.

What happens when OverrideMass (going by my name suggestion, hehe) is removed? Does the mass go back to how it would be calculated if there was no override? At least for me, this would be useful for avian_pickup, as I temporarily reduce the mass while holding an object but want to restore it to normal once I let it go

With my proposal above, you'd probably set it to Auto/Density instead of removing the component. If you did remove the component, I'm not sure... If we choose that Mass etc. are truly required, it'd probably disable mass computation for that entity and not do anything, but we could also choose that the lack of Mass is treated as Auto.

If we go with the CustomMass/OverrideMass approach, I imagine it should return back to the automatically computed value. Again the semantics are less clear here since the automatic behavior isn't explicitly specified by anything, unlike with my proposed Mass enum.

If an entity has an OverrideMass, can I read it? If so, I have two ways of reading the same value, which is a bit meh. Maybe OverrideMass should only have a set and no get?

You can, yes. CustomMass/OverrideMass only exists for entities with a custom value though, while ReadOnlyMass/ComputedMass/WhateverMass is the actual computed value that exists on all rigid bodies, and is what you should probably read. But I don't think being able to read the custom mass is necessarily harmful, so I'm not sure if there's much value in making it write-only.

Also worth noting that the internal representation isn't the exact same, especially for 3D angular inertia.

[mbrea-c]

I really like this.

In particular I'm very happy about the Custom* components being applicable to both rigid bodies and individual colliders, this was a big pain point for me.

This is not something I'd expect a physics engine to support really (too much complexity for limited gain), but one question I'd have is whether you've given any thought for being able to override the mass for a "subtree" of a collider hierarchy for a particular rigid body. I found it pretty common to have deep collider hierarchies when working with a benvy-like workflow (multiple blenvy-created scenes with colliders as children for a particular rigid body) and sometimes I'd have wished I could override the mass for some of these scenes separately. Kind of similar to overriding rigid body mass properties, but only for some part of the collider hierarchy.

[Jondolf]

So there have been a lot of ideas for the API, both here and on Discord, as well as many open questions: should we separate computed mass and "custom mass", should we support "additional mass", what does all of that look like, should we use enums or many smaller components, what components should be required...

A lot of these designs ultimately have quite a bit of complexity and somewhat confusing semantics. I took a step back to consider simpler options, and to try and reduce the API to a minimum:

Just have Mass, AngularInertia, and CenterOfMass. No separate components for additional mass or overrides. It'd work like the following:

• No Mass specified -> compute Mass from colliders, taking into account their densities.
• Mass specified -> use that for the initial value.
• By default, if colliders are added after the body's initial creation, their mass is added to the body's mass.
• By default, if colliders are transformed or their densities are changed after the body's initial creation, the body's mass properties are updated accordingly.
• Automatic mass property updates can be disabled for individual entities with the NoAutoMass, NoAutoAngularInertia, and NoAutoCenterOfMass marker components.
• Automatic mass property updates can be disabled globally by just disabling the MassPropertyPlugin.

Additionally, there would be a MassHelper system parameter (like TransformHelper) that lets you manually recompute mass properties based on attached colliders at any time, or do any other updates you might want. Maybe it could even handle overriding mass properties for "subtrees" of collider hierarchies, like @mbrea-c described?

Compared to previous proposals, this would have benefits like:

• Reduced API surface. There's a single source of truth, no separate "custom mass" and "computed mass" or similar. Also less memory usage.
• More flexibility. You can choose to opt out of automatic mass computation completely and modify things as much as you want. Even build your own abstractions for things lïke additional mass!
• Sensible defaults. If you do nothing, mass is automatically computed from colliders. If you specify it manually, that value is used. If you add more colliders later, mass takes that into account, unless you choose to opt out.
• More ECS-friendly. The marker components just act as filters for disabling automatic mass computation. No need to check enum variants or check for optional components.
• No confusing semantics in terms of what components are required and what components are purely configuration.
• Easy overrides at runtime. Just set Mass!

This is also quite similar to Box2D, where mass properties are computed automatically when shapes are added, but you can manually set or adjust it at runtime, and use b2Body_ApplyMassFromShapes to revert it to the mass determined by shapes. Or Godot, where an angular inertia of zero means that it'll be computed from colliders, but you can also specify a custom value.

[Jondolf]

Might actually make more sense to make the "Mass specified on spawn" case work such that mass properties of child colliders are still added on top unless NoAutoMass exists. Otherwise, you would get negative mass if you e.g. set the Mass of a rigid body to 10.0, and then removed a child collider with a mass of 20.0.

[Jondolf]

I'm back working on this, and have yet another revised proposal to throw on the table.

My previous proposal looks pretty good on paper, but I've realized that there are still several issues with it:

• Mass means different things on a rigid body (total mass) vs. on a child collider (mass override for the collider).
• Since the Mass can be modified at any time, and it is also the value used for the total mass, it is easy to produce nonsensical states without any indication of the override (e.g. a component). For example, you can just set the mass of a rigid body to 5.0, even though it has a child collider with a mass of 10.0. If you then remove the collider, you could get negative mass!
• How do we detect if Mass was added explicitly, meaning it should override the initial value, or if it was added as a required component, meaning the collider's mass should be used?
• The data representations for Mass and AngularInertia aren't very user-friendly, editor-friendly, or BSN-friendly.

Documenting and implementing the behavior properly was very difficult the more I played around with it.

To simplify behavior and provide a nicer and more consistent API with fewer special cases, I think we do ultimately want to maintain a separation between "total mass computed for a dynamic body" and "mass contribution specified for this entity".

Separate Mass and ComputedMass

Similarly to my first proposal, we could have read-only ComputedMass, ComputedAngularInertia, and ComputedCenterOfMass components, storing the total mass properties of a dynamic rigid body, possibly taking locked axes into account. These would be required for rigid bodies, and can use the efficient representations needed by physics, storing the inverse mass and inverse angular inertia.

#[derive(Component)]
pub struct ComputedMass {
    inverse: f32,
}

// Assuming 3D here
#[derive(Component)]
pub struct ComputedAngularInertia {
    inverse: Mat3,
}

#[derive(Component)]
pub struct ComputedCenterOfMass(Vec3);

Mass, AngularInertia, and CenterOfMass on the other hand are optional, and they represent how much a single entity contributes to the total mass properties stored in the computed versions. The computed mass is the sum of the masses of all descendants and the rigid body entity itself. These components can have user-friendly representations instead of the inverses, which also makes specifying them in editors and BSN nicer.

#[derive(Component)]
pub struct Mass(pub f32);

#[derive(Component)]
pub struct AngularInertia {
    pub principal: Vec3,
    pub local_frame: Quat,
}

#[derive(Component)]
pub struct CenterOfMass(pub Vec3);

Like in the earlier proposal, if you don't want the masses of attached colliders to affect the computed mass, you can add the NoAutoMass (or NoInheritedMass, or OverrideMass?) marker component to the rigid body. This gives you full control over the mass, for cases where that is desired. This would work similarly for angular inertia and the center of mass.

Some advantages over the previous proposal are:

• There is a clear and logical separation between computed values and user-specified values.
• Mass has a clear single purpose, and represents the same thing regardless of whether it's on a rigid body or collider.
• User-specified values are never unexpectedly modified by the engine, and no information is lost when changes are made elsewhere. Mass properties can always be trivially recomputed from attached colliders, and mass overrides are explicit at the component-level.
• The data representations for the user-facing types are friendlier for both users and editors.

Some examples of how this would behave:

- `RigidBody`, `Collider`

ComputedMass is equal to the mass computed for the collider (in ColliderMassProperties), defaulting to a density of 1.0.

- `RigidBody`, `Collider`, `Mass(5.0)`

ComputedMass is equal to 5.0. ComputedAngularInertia is the collider's angular inertia, scaled to match the ComputedMass.

- `RigidBody`, `Collider`, `Mass(5.0)`
	- `Collider`

ComputedMass is equal to 5.0 plus the child collider's mass. ComputedAngularInertia is the total angular inertia given by the colliders, scaled to match the ComputedMass.

- `RigidBody`, `Collider`, `Mass(5.0)`
	- `Collider`, `Mass(10.0)`

ComputedMass is equal to 5.0 + 10.0 == 15.0. ComputedAngularInertia is the total angular inertia given by the colliders, scaled to match the ComputedMass.

- `RigidBody`, `Collider`, `Mass(5.0)`, `NoAutoMass`
	- `Collider`, `Mass(10.0)`

ComputedMass is equal to 5.0. The masses of child colliders are ignored due to NoAutoMass. ComputedAngularInertia is the total angular inertia given by the colliders, scaled to match the ComputedMass.

The rules work similarly for AngularInertia and CenterOfMass.

I'm currently quite confident in this approach, and am in the process of trying to implement it. We'll see if I discover more problems and need to go back to the drawing board for the tenth time :P

[Jondolf]

Done in #500, #532, and #574.