Crate bevy_heavy

source
Expand description

bevy_heavy is a crate for computing mass properties (mass, angular inertia, and center of mass) for the geometric primitives in the Bevy game engine. This is typically required for things like physics simulations.

§Usage

Mass properties can be computed individually for shapes using the mass, angular_inertia, and center_of_mass methods:

use bevy_heavy::{ComputeMassProperties2d, MassProperties2d};
use bevy_math::{primitives::Rectangle, Vec2};

let rectangle = Rectangle::new(2.0, 1.0);
let density = 2.0;

let mass = rectangle.mass(density);
let angular_inertia = rectangle.angular_inertia(mass);
let center_of_mass = rectangle.center_of_mass();

You can also compute all mass properties at once, returning MassProperties2d for 2D shapes, or MassProperties3d for 3D shapes. This can be more efficient when more than one property is needed.

let mass_props = rectangle.mass_properties(density);

The mass property types have several helper methods for various transformations and operations:

let shifted_inertia = mass_props.shifted_angular_inertia(Vec2::new(-3.5, 1.0));
let global_center_of_mass = mass_props.global_center_of_mass(Vec2::new(5.0, 7.5));

You can also add and subtract mass properties:

let mass_props_2 = MassProperties2d::new(mass, angular_inertia, Vec2::new(0.0, 1.0));
let sum = mass_props + mass_props_2;
approx::assert_relative_eq!(sum - mass_props_2, mass_props);

To support mass property computation for custom shapes, implement ComputeMassProperties2d or ComputeMassProperties3d for them.

§Terminology

§Mass

Mass is a scalar value representing resistance to linear acceleration when a force is applied.

Mass is commonly measured in kilograms (kg).

§Angular Inertia

Angular inertia, also known as the moment of inertia or rotational inertia, is the rotational analog of mass. It represents resistance to angular acceleration when a torque is applied.

An object’s angular inertia depends on its mass, shape, and how the mass is distributed relative to a rotational axis. It increases with mass and distance from the axis.

In 2D, angular inertia can be treated as a scalar value, as it is only defined relative to the Z axis.

In 3D, angular inertia can be represented with a symmetric, positive-semidefinite 3x3 tensor (AngularInertiaTensor) that describes the moment of inertia for rotations about the X, Y, and Z axes. By diagonalizing this matrix, it is possible to extract the principal axes of inertia (a Vec3) and a local inertial frame (a Quat) that defines the XYZ axes.

The latter diagonalized representation is more compact and often easier to work with, but the full tensor can be more efficient for computations using the angular inertia.

Angular inertia is commonly measured in kilograms times meters squared (kg⋅m²).

§Center of Mass

The center of mass is the average position of mass in an object. Applying a force at the center of mass causes linear acceleration without angular acceleration.

If an object has uniform density, mass is evenly distributed, and the center of mass is at the geometric center, also known as the centroid.

The center of mass is commonly measured in meters (m).

Structs§

Enums§

Traits§