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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
//! 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](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 |
//! | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
//! | [`SolverPlugins`] | A plugin group for the physics solver's plugins. See the plugin group's documentation for more information. |
//! | [`JointPlugin`] | A plugin for managing and initializing [joints]. Does *not* include the actual joint solver. |
//! | [`MassPropertyPlugin`] | Manages mass properties of dynamic [rigid bodies](RigidBody). |
//! | [`ForcePlugin`] | Manages and applies external forces, torques, and acceleration for rigid bodies. See the [module-level documentation](rigid_body::forces). |
//!
//! # 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
/// Re-exports common types related to the rigid body dynamics functionality.
// For intra-doc links
use crate*;