avian2d/dynamics/
mod.rs

1//! Rigid body dynamics, handling the motion and physical interactions of non-deformable objects.
2//!
3//! A [`RigidBody`] is the core component of a physics simulation.
4//! It describes a rigid, non-deformable physics object that can be either dynamic,
5//! kinematic, or static.
6//!
7//! Rigid body dynamics includes:
8//!
9//! - Motion of rigid bodies based on their [`LinearVelocity`] and [`AngularVelocity`].
10//! - Acceleration caused by external forces and [`Gravity`].
11//! - Collision response, preventing objects from overlapping each other,
12//!   considering properties such as [`Friction`] and [`Restitution`].
13//! - [Joints](joints) connecting rigid bodies to each other.
14//! - Everything else related to the physical behavior and properties of rigid bodies.
15//!
16//! Rigid body dynamics does *not* include:
17//!
18//! - Simulation of fluids (liquids and gasses)
19//! - Elasticity (soft bodies)
20//! - Plasticity (permanent deformation)
21//!
22//! # Plugins
23//!
24//! | Plugin                 | Description                                                                                                                                |
25//! | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
26//! | [`SolverPlugins`]      | A plugin group for the physics solver's plugins. See the plugin group's documentation for more information.                                |
27//! | [`JointPlugin`]        | A plugin for managing and initializing [joints]. Does *not* include the actual joint solver.                                               |
28//! | [`MassPropertyPlugin`] | Manages mass properties of dynamic [rigid bodies](RigidBody).                                                                              |
29//! | [`ForcePlugin`]        | Manages and applies external forces, torques, and acceleration for rigid bodies. See the [module-level documentation](rigid_body::forces). |
30//!
31//! # Accuracy
32//!
33//! The engine uses iterative algorithms to approximate the simulation.
34//! Thus, results may not be perfectly accurate:
35//!
36//! - Constraints (contacts and joints) are not perfectly rigid.
37//!   - Objects can overlap, especially in extreme stacking scenarios.
38//!   - Contacts can be slightly bouncy even when the [`Restitution`] is zero.
39//!   - Joint chains can stretch and in extreme cases have jittery behavior.
40//!   - High mass ratios, such as when a very heavy object rests on top of a lighter one,
41//!     can be difficult for the engine to deal with.
42//! - [`Friction`] and [`Restitution`] may not be perfectly accurate.
43//! - Objects moving at high speeds can pass through thin and small geometry due to discrete time steps,
44//!   a phenomenon known as *tunneling*. This can be mitigated with [Continuous Collision Detection](ccd).
45//!
46//! These caveats are very common for physics engines intended for real-time applications,
47//! not something specific to this engine. Approximations are required for several reasons:
48//!
49//! - Performance.
50//!   - Exact results are simply not possible, especially at the frame rates
51//!     expected from games and other real-time applications.
52//! - Some differential equations do not have known exact solutions.
53//!   - [Semi-implicit Euler] integration is used to approximate them.
54//! - Some constraints cannot be solved uniquely.
55//!   - An iterative [Gauss-Seidel] solver is used to solve them approximately.
56//!
57//! In practice, the results should be accurate enough for most real-time applications.
58//! Perfect accuracy is very rarely necessary, if ever, and most of the more visible issues
59//! can typically be worked around.
60//!
61//! [Gauss-Seidel]: https://en.wikipedia.org/wiki/Gauss%E2%80%93Seidel_method
62//! [Semi-implicit Euler]: https://en.wikipedia.org/wiki/Semi-implicit_Euler_method
63
64pub mod ccd;
65pub mod integrator;
66pub mod joints;
67pub mod rigid_body;
68pub mod solver;
69
70/// Re-exports common types related to the rigid body dynamics functionality.
71pub mod prelude {
72    pub(crate) use super::rigid_body::mass_properties::{ComputeMassProperties, MassProperties};
73    #[cfg(feature = "xpbd_joints")]
74    pub use super::solver::xpbd::XpbdSolverPlugin;
75    #[expect(deprecated)]
76    pub use super::{
77        ccd::{CcdPlugin, SpeculativeMargin, SweepMode, SweptCcd},
78        integrator::{Gravity, IntegratorPlugin},
79        joints::{
80            AngleLimit, DistanceJoint, DistanceLimit, FixedJoint, JointAnchor, JointBasis,
81            JointCollisionDisabled, JointDamping, JointDisabled, JointForces, JointFrame,
82            JointPlugin, PrismaticJoint, RevoluteJoint,
83        },
84        rigid_body::{
85            forces::{
86                ConstantAngularAcceleration, ConstantForce, ConstantLinearAcceleration,
87                ConstantLocalForce, ConstantLocalLinearAcceleration, ConstantTorque, ForcePlugin,
88                ForceSystems, Forces, RigidBodyForces,
89            },
90            mass_properties::{
91                MassPropertiesExt, MassPropertyHelper, MassPropertyPlugin,
92                bevy_heavy::{
93                    AngularInertiaTensor, AngularInertiaTensorError, ComputeMassProperties2d,
94                    ComputeMassProperties3d, MassProperties2d, MassProperties3d,
95                },
96                components::{
97                    AngularInertia, CenterOfMass, ColliderDensity, ColliderMassProperties,
98                    ComputedAngularInertia, ComputedCenterOfMass, ComputedMass, Mass,
99                    MassPropertiesBundle, NoAutoAngularInertia, NoAutoCenterOfMass, NoAutoMass,
100                },
101            },
102            sleeping::{
103                DeactivationTime, SleepThreshold, SleepTimer, Sleeping, SleepingDisabled,
104                SleepingThreshold, TimeSleeping, TimeToSleep,
105            },
106            *,
107        },
108        solver::{
109            PhysicsLengthUnit, SolverPlugin, SolverPlugins,
110            islands::{
111                IslandPlugin, IslandSleepingPlugin, SleepBody, SleepIslands, WakeBody, WakeIslands,
112                WakeUpBody,
113            },
114            schedule::{
115                SolverSchedulePlugin, SolverSet, SolverSystems, SubstepCount, SubstepSchedule,
116            },
117            solver_body::SolverBodyPlugin,
118        },
119    };
120    #[cfg(feature = "3d")]
121    pub use super::{
122        joints::SphericalJoint,
123        rigid_body::forces::{ConstantLocalAngularAcceleration, ConstantLocalTorque},
124    };
125}
126
127// For intra-doc links
128#[allow(unused_imports)]
129use crate::prelude::*;
avian2d/dynamics/mod.rs

avian2d/dynamics/
mod.rs
