Struct AngularInertia

pub struct AngularInertia {
    pub principal: Vec3,
    pub local_frame: Quat,
}

The local angular inertia of an entity, representing resistance to angular acceleration. A higher angular inertia requires more torque for the same acceleration.

If AngularInertia is not present, but the entity has a Collider, its ColliderMassProperties computed based on the shape and mass will be used instead. Angular inertia scales with mass, so a higher Mass or ColliderDensity will result in higher inertia.

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

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

See the module-level documentation for more general information on angular inertia.

Usage

AngularInertia is defined by the moment of inertia along the principal axes (a Vec3) defined by the local inertial frame (a Quat). Most entities will have a local inertial frame of Quat::IDENTITY, which means that the principal axes are aligned with the entity’s local axes.

// Principal angular inertia: `2.0` for the local X and Z axes, and `5.0` for the Y axis.
let inertia1 = AngularInertia::new(Vec3::new(2.0, 5.0, 2.0));

// A local inertial frame rotated by 90 degrees about the X axis.
let inertia2 = AngularInertia::new_with_local_frame(Vec3::new(2.0, 5.0, 2.0), Quat::from_rotation_x(PI / 2.0));

AngularInertia can also be created from a symmetric 3x3 matrix known as the angular inertia tensor. It summarizes all moments of inertia of an object in a single matrix, and can be used to perform computations with angular inertia, but is often not constructed manually.

// For simplicity, we use the same principal angular inertia as before, with an identity local frame.
let inertia1 = AngularInertia::from_tensor(Mat3::from_diagonal(Vec3::new(2.0, 5.0, 2.0)));

// The angular inertia tensor can be retrieved back from the principal angular inertia.
let tensor = inertia1.tensor();

The AngularInertia component can be used to define the angular inertia of a rigid body entity or its descendants:

commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    AngularInertia::new(Vec3::new(2.0, 5.0, 2.0)),
));

If no AngularInertia is present, the ComputedAngularInertia will be computed from the collider based on its mass and shape.

// 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 angular inertia will be added to the total ComputedAngularInertia. Here both entities are at the origin, but offsets relative to the center of mass would also impact the total inertia.

// Total angular inertia: [2.0, 5.0, 2.0] + [1.0, 2.0, 1.0] = [3.0, 7.0, 3.0]
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    AngularInertia::new(Vec3::new(2.0, 5.0, 2.0)),
))
.with_child((Collider::sphere(1.0), AngularInertia::new(Vec3::new(1.0, 2.0, 1.0))));

To prevent angular inertia of child entities from contributing to the total ComputedAngularInertia, add the NoAutoAngularInertia component. This can be useful when full control over inertia is desired.

// Total angular inertia: [2.0, 5.0, 2.0]
commands.spawn((
    RigidBody::Dynamic,
    Collider::capsule(0.5, 1.5),
    AngularInertia::new(Vec3::new(2.0, 5.0, 2.0)),
    NoAutoAngularInertia,
))
.with_child((Collider::sphere(1.0), AngularInertia::new(Vec3::new(1.0, 2.0, 1.0))));

Angular Inertia Updates

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

The total ComputedAngularInertia 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

• ComputedAngularInertia stores the total angular inertia of a dynamic rigid body that considers child entities and colliders.
• NoAutoAngularInertia disables the mass properties of child entities being taken into account for the ComputedAngularInertia.
• AngularInertiaTensor is the symmetric 3x3 matrix representation of angular inertia.
• Mass is the linear equivalent of angular inertia, representing resistance to linear 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.

Fields

principal: Vec3

The principal angular inertia, representing resistance to angular acceleration about the local coordinate axes defined by the local_frame.

local_frame: Quat

The orientation of the local inertial frame.

Implementations

impl AngularInertia

pub const ZERO: Self = _

An angular inertia of 0.0 for all axes, with an identity local frame.

pub fn new(principal_angular_inertia: Vec3) -> Self

Creates a new AngularInertia from the given principal angular inertia.

The principal angular inertia represents resistance to angular acceleration about the local coordinate axes.

To specify the orientation of the local inertial frame, consider using AngularInertia::new_with_local_frame.

Panics

Panics if any component of the principal angular inertia is negative or NaN when debug_assertions are enabled.

pub fn try_new( principal_angular_inertia: Vec3, ) -> Result<Self, AngularInertiaError>

Tries to create a new AngularInertia from the given principal angular inertia.

The principal angular inertia represents resistance to angular acceleration about the local coordinate axes. To specify the orientation of the local inertial frame, consider using AngularInertia::try_new_with_local_frame.

Errors

Returns Err(AngularInertiaError) if any component of the principal angular inertia is negative or NaN.

pub fn new_with_local_frame( principal_angular_inertia: Vec3, local_frame: Quat, ) -> Self

Creates a new AngularInertia from the given principal angular inertia and the orientation of the local inertial frame.

The principal angular inertia represents resistance to angular acceleration about the local coordinate axes defined by the given local_frame.

Panics

Panics if any component of the principal angular inertia is negative or NaN when debug_assertions are enabled.

pub fn try_new_with_local_frame( principal_angular_inertia: Vec3, local_frame: Quat, ) -> Result<Self, AngularInertiaError>

Tries to create a new AngularInertia from the given principal angular inertia and the orientation of the local inertial frame.

The principal angular inertia represents resistance to angular acceleration about the local coordinate axes defined by the given local_frame.

Errors

Returns Err(AngularInertiaError) if any component of the principal angular inertia is negative or NaN.

pub fn from_tensor(tensor: impl Into<AngularInertiaTensor>) -> Self

Creates a new AngularInertia from the given angular inertia tensor.

The tensor should be symmetric and positive definite.

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

Computes the AngularInertia of the given shape using the given mass.

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

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

pub fn tensor(self) -> AngularInertiaTensor

Returns the AngularInertiaTensor represented by this principal AngularInertia and local inertial frame.

pub fn is_finite(self) -> bool

Returns true if the principal angular inertia and inertial local frame are neither infinite nor NaN.

pub fn is_nan(self) -> bool

Returns true if the principal angular inertia or inertial local frame is NaN.

Trait Implementations

impl Clone for AngularInertia

fn clone(&self) -> AngularInertia

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Component for AngularInertia

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 AngularInertia

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

Formats the value using the given formatter.

impl Default for AngularInertia

fn default() -> AngularInertia

Returns the “default value” for a type.

impl From<AngularInertia> for AngularInertiaTensor

fn from(inertia: AngularInertia) -> Self

Converts to this type from the input type.

impl From<AngularInertia> for ComputedAngularInertia

fn from(inertia: AngularInertia) -> Self

Converts to this type from the input type.

impl From<AngularInertiaTensor> for AngularInertia

fn from(tensor: AngularInertiaTensor) -> Self

Converts to this type from the input type.

impl From<ComputedAngularInertia> for AngularInertia

fn from(inertia: ComputedAngularInertia) -> Self

Converts to this type from the input type.

impl From<Mat3> for AngularInertia

fn from(tensor: Mat3) -> Self

Converts to this type from the input type.

impl FromReflect for AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: 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 AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: 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 AngularInertia

fn eq(&self, other: &AngularInertia) -> 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 AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: 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 AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: 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 Struct for AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, name: &str) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

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

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

fn field_at_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 PartialReflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

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

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if TypeInfo is not available.

impl TypePath for AngularInertia

where AngularInertia: 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 AngularInertia

where AngularInertia: Any + Send + Sync, Vec3: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Quat: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for AngularInertia

impl StructuralPartialEq for AngularInertia