avian3d/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](solver::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//! | [`IntegratorPlugin`] | Handles motion caused by velocity, and applies external forces and gravity. |
27//! | [`SolverPlugin`] | Solves constraints (contacts and joints). |
28//! | [`CcdPlugin`] | Performs sweep-based [Continuous Collision Detection](dynamics::ccd) for bodies with the [`SweptCcd`] component to prevent tunneling. |
29//! | [`SleepingPlugin`] | Manages sleeping and waking for bodies, automatically deactivating them to save computational resources. |
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 rigid_body;
67pub mod sleeping;
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::{
73 components::GlobalAngularInertia, ComputeMassProperties, MassProperties,
74 };
75 pub use super::{
76 ccd::{CcdPlugin, SpeculativeMargin, SweepMode, SweptCcd},
77 integrator::{Gravity, IntegratorPlugin},
78 rigid_body::{
79 mass_properties::{
80 bevy_heavy::{
81 AngularInertiaTensor, AngularInertiaTensorError, ComputeMassProperties2d,
82 ComputeMassProperties3d, MassProperties2d, MassProperties3d,
83 },
84 components::{
85 AngularInertia, CenterOfMass, ColliderDensity, ColliderMassProperties,
86 ComputedAngularInertia, ComputedCenterOfMass, ComputedMass, Mass,
87 MassPropertiesBundle, NoAutoAngularInertia, NoAutoCenterOfMass, NoAutoMass,
88 },
89 MassPropertiesExt, MassPropertyHelper, MassPropertyPlugin,
90 },
91 *,
92 },
93 sleeping::{DeactivationTime, SleepingPlugin, SleepingThreshold, WakeUpBody},
94 solver::{
95 joints::*,
96 schedule::{SolverSchedulePlugin, SolverSet, SubstepCount, SubstepSchedule},
97 PhysicsLengthUnit, SolverPlugin,
98 },
99 };
100}
101
102// For intra-doc links
103#[allow(unused_imports)]
104use crate::prelude::*;