1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

//! Rigid body dynamics, handling the motion and physical interactions of non-deformable objects.
//!
//! A [`RigidBody`] is the core component of a physics simulation.
//! It describes a rigid, non-deformable physics object that can be either dynamic,
//! kinematic, or static.
//!
//! Rigid body dynamics includes:
//!
//! - Motion of rigid bodies based on their [`LinearVelocity`] and [`AngularVelocity`].
//! - Acceleration caused by external forces and [`Gravity`].
//! - Collision response, preventing objects from overlapping each other,
//!   considering properties such as [`Friction`] and [`Restitution`].
//! - [Joints](solver::joints) connecting rigid bodies to each other.
//! - Everything else related to the physical behavior and properties of rigid bodies.
//!
//! Rigid body dynamics does *not* include:
//!
//! - Simulation of fluids (liquids and gasses)
//! - Elasticity (soft bodies)
//! - Plasticity (permanent deformation)
//!
//! ## Plugins
//!
//! | Plugin               | Description                                                                                                                           |
//! | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
//! | [`IntegratorPlugin`] | Handles motion caused by velocity, and applies external forces and gravity.                                                           |
//! | [`SolverPlugin`]     | Solves constraints (contacts and joints).                                                                                             |
//! | [`CcdPlugin`]        | Performs sweep-based [Continuous Collision Detection](dynamics::ccd) for bodies with the [`SweptCcd`] component to prevent tunneling. |
//! | [`SleepingPlugin`]   | Manages sleeping and waking for bodies, automatically deactivating them to save computational resources.                              |
//!
//! ## Accuracy
//!
//! The engine uses iterative algorithms to approximate the simulation.
//! Thus, results may not be perfectly accurate:
//!
//! - Constraints (contacts and joints) are not perfectly rigid.
//!   - Objects can overlap, especially in extreme stacking scenarios.
//!   - Contacts can be slightly bouncy even when the [`Restitution`] is zero.
//!   - Joint chains can stretch and in extreme cases have jittery behavior.
//!   - High mass ratios, such as when a very heavy object rests on top of a lighter one,
//!     can be difficult for the engine to deal with.
//! - [`Friction`] and [`Restitution`] may not be perfectly accurate.
//! - Objects moving at high speeds can pass through thin and small geometry due to discrete time steps,
//!   a phenomenon known as *tunneling*. This can be mitigated with [Continuous Collision Detection](ccd).
//!
//! These caveats are very common for physics engines intended for real-time applications,
//! not something specific to this engine. Approximations are required for several reasons:
//!
//! - Performance.
//!   - Exact results are simply not possible, especially at the frame rates
//!     expected from games and other real-time applications.
//! - Some differential equations do not have known exact solutions.
//!   - [Semi-implicit Euler] integration is used to approximate them.
//! - Some constraints cannot be solved uniquely.
//!   - An iterative [Gauss-Seidel] solver is used to solve them approximately.
//!
//! In practice, the results should be accurate enough for most real-time applications.
//! Perfect accuracy is very rarely necessary, if ever, and most of the more visible issues
//! can typically be worked around.
//!
//! [Gauss-Seidel]: https://en.wikipedia.org/wiki/Gauss%E2%80%93Seidel_method
//! [Semi-implicit Euler]: https://en.wikipedia.org/wiki/Semi-implicit_Euler_method

pub mod ccd;
pub mod integrator;
pub mod rigid_body;
pub mod sleeping;
pub mod solver;

/// Re-exports common types related to the rigid body dynamics functionality.
pub mod prelude {
    pub use super::{
        ccd::{CcdPlugin, SpeculativeMargin, SweepMode, SweptCcd},
        integrator::{Gravity, IntegratorPlugin},
        rigid_body::*,
        sleeping::{DeactivationTime, SleepingPlugin, SleepingThreshold},
        solver::{joints::*, PhysicsLengthUnit, SolverPlugin, SolverSet},
    };
}

// For intra-doc links
#[allow(unused_imports)]
use crate::prelude::*;