Struct Mass

pub struct Mass(pub f32);

The mass of an entity, representing resistance to linear acceleration. A higher mass requires more force for the same acceleration.

If Mass is not present, but the entity has a Collider, its ColliderMassProperties computed based on the shape and ColliderDensity will be used instead.

The Mass component does not take into account the masses of child entities, and it is never modified by the engine. The total mass of a dynamic rigid body that does consider child entities and colliders is stored in the ComputedMass component. It is updated automatically when mass properties are changed, or when colliders are added or removed.

A total mass of zero is a special case, and is interpreted as infinite mass, meaning the rigid body will not be affected by any forces.

Usage

The Mass component can be used to define the mass of a rigid body entity or its descendants:

commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(5.0),
));

If no Mass is present, the ComputedMass will be computed from the collider based on its shape and ColliderDensity.

// 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 the rigid body has child colliders, their masses will be added to the total ComputedMass.

// Total mass: 10.0 + 5.0 = 15.0
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(10.0),
))
.with_child((Collider::sphere(1.0), Mass(5.0)));

To prevent masses of child entities from contributing to the total ComputedMass, add the NoAutoMass component. This can be useful when full control over mass is desired.

// Total mass: 10.0
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    Mass(10.0),
    NoAutoMass,
))
.with_child((Collider::sphere(1.0), Mass(5.0)));

Mass Updates

The Mass component is never modified by the engine, so you can safely update it at any time.

The total ComputedMass is updated automatically whenever the mass properties of a rigid body or its descendants change, or when colliders are added or removed. This update is triggered by adding the RecomputeMassProperties component, which is removed after the update is performed in MassPropertySystems::UpdateComputedMassProperties.

To immediately perform a manual update of the total mass properties for a specific rigid body entity, you can call MassPropertyHelper::update_mass_properties in a system.

Related Types

• ComputedMass stores the total mass of a dynamic rigid body that considers child entities and colliders.
• NoAutoMass disables masses of child entities being taken into account for the ComputedMass.
• AngularInertia is the rotational equivalent of mass, representing resistance to angular acceleration.
• CenterOfMass is the local point where the mass is concentrated. Applying forces at this point produces no torque.
• MassPropertiesBundle is a bundle containing mass properties.
• MassPropertyHelper is a SystemParam with utilities for computing and updating mass properties.

Tuple Fields

0: f32

Implementations

impl Mass

pub const ZERO: Self = _

A mass of 0.0.

pub fn from_shape<T: ComputeMassProperties>(shape: &T, density: f32) -> Self

Computes the Mass of the given shape using the given density.

// Compute the mass from a collider with a density of `2.0`.
let mass = Mass::from_shape(&Collider::sphere(1.0), 2.0);

// Bevy's primitive shapes can also be used.
let mass = Mass::from_shape(&Sphere::new(1.0), 2.0);

Methods from Deref<Target = f32>

pub const RADIX: u32 = 2u32

pub const MANTISSA_DIGITS: u32 = 24u32

pub const DIGITS: u32 = 6u32

pub const EPSILON: f32 = 1.1920929E-7f32

pub const MIN: f32 = -3.40282347E+38f32

pub const MIN_POSITIVE: f32 = 1.17549435E-38f32

pub const MAX: f32 = 3.40282347E+38f32

pub const MIN_EXP: i32 = -125i32

pub const MAX_EXP: i32 = 128i32

pub const MIN_10_EXP: i32 = -37i32

pub const MAX_10_EXP: i32 = 38i32

pub const NAN: f32 = NaN_f32

pub const INFINITY: f32 = +Inf_f32

pub const NEG_INFINITY: f32 = -Inf_f32

pub fn total_cmp(&self, other: &f32) -> Ordering

Returns the ordering between self and other.

Unlike the standard partial comparison between floating point numbers, this comparison always produces an ordering in accordance to the totalOrder predicate as defined in the IEEE 754 (2008 revision) floating point standard. The values are ordered in the following sequence:

• negative quiet NaN
• negative signaling NaN
• negative infinity
• negative numbers
• negative subnormal numbers
• negative zero
• positive zero
• positive subnormal numbers
• positive numbers
• positive infinity
• positive signaling NaN
• positive quiet NaN.

The ordering established by this function does not always agree with the PartialOrd and PartialEq implementations of f32. For example, they consider negative and positive zero equal, while total_cmp doesn’t.

The interpretation of the signaling NaN bit follows the definition in the IEEE 754 standard, which may not match the interpretation by some of the older, non-conformant (e.g. MIPS) hardware implementations.

Example

struct GoodBoy {
    name: String,
    weight: f32,
}

let mut bois = vec![
    GoodBoy { name: "Pucci".to_owned(), weight: 0.1 },
    GoodBoy { name: "Woofer".to_owned(), weight: 99.0 },
    GoodBoy { name: "Yapper".to_owned(), weight: 10.0 },
    GoodBoy { name: "Chonk".to_owned(), weight: f32::INFINITY },
    GoodBoy { name: "Abs. Unit".to_owned(), weight: f32::NAN },
    GoodBoy { name: "Floaty".to_owned(), weight: -5.0 },
];

bois.sort_by(|a, b| a.weight.total_cmp(&b.weight));

// `f32::NAN` could be positive or negative, which will affect the sort order.
if f32::NAN.is_sign_negative() {
    assert!(bois.into_iter().map(|b| b.weight)
        .zip([f32::NAN, -5.0, 0.1, 10.0, 99.0, f32::INFINITY].iter())
        .all(|(a, b)| a.to_bits() == b.to_bits()))
} else {
    assert!(bois.into_iter().map(|b| b.weight)
        .zip([-5.0, 0.1, 10.0, 99.0, f32::INFINITY, f32::NAN].iter())
        .all(|(a, b)| a.to_bits() == b.to_bits()))
}

Trait Implementations

impl Clone for Mass

fn clone(&self) -> Mass

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for Mass

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_required_components( requiree: ComponentId, components: &mut Components, storages: &mut Storages, required_components: &mut RequiredComponents, inheritance_depth: u16, )

Registers required components.

fn register_component_hooks(hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl Debug for Mass

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Mass

fn default() -> Mass

Returns the “default value” for a type.

impl Deref for Mass

type Target = f32

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Mass

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<ComputedMass> for Mass

fn from(mass: ComputedMass) -> Self

Converts to this type from the input type.

impl From<Mass> for ComputedMass

fn from(mass: Mass) -> Self

Converts to this type from the input type.

impl From<f32> for Mass

fn from(value: f32) -> Self

Converts to this type from the input type.

impl FromReflect for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl PartialEq for Mass

fn eq(&self, other: &Mass) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialReflect for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn clone_value(&self) -> Box<dyn PartialReflect>

Clones the value as a Reflect trait object.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result

Debug formatter for the value.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl TupleStruct for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, index: usize) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn field_len(&self) -> usize

Returns the number of fields in the tuple struct.

fn iter_fields(&self) -> TupleStructFieldIter<'_>

Returns an iterator over the values of the tuple struct’s fields.

fn clone_dynamic(&self) -> DynamicTupleStruct

Clones the struct into a DynamicTupleStruct.

fn get_represented_tuple_struct_info(&self) -> Option<&'static TupleStructInfo>

Will return None if TypeInfo is not available.

impl TypePath for Mass

where Mass: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for Mass

where Mass: Any + Send + Sync, f32: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for Mass

impl StructuralPartialEq for Mass