threers_physics/lib.rs
1//! Rigid-body physics for [`threers`](https://docs.rs/threers).
2//!
3//! Gravity, collisions, joints, scene queries and inverse kinematics — pure
4//! Rust, no dependencies beyond `threers` itself, and wasm-ready.
5//!
6//! ```
7//! use threers_physics::prelude::*;
8//!
9//! let mut world = World::new(); // gravity is -9.81 Y
10//! world.add_body(RigidBody::fixed().shape(Shape::ground()));
11//!
12//! let ball = world.add_body(
13//! RigidBody::dynamic()
14//! .shape(Shape::ball(0.5))
15//! .translation(Vector3::new(0.0, 10.0, 0.0))
16//! .restitution(0.7),
17//! );
18//!
19//! for _ in 0..600 {
20//! world.step(1.0 / 60.0); // once per frame
21//! }
22//!
23//! // It fell, bounced itself out, and came to rest on the ground — then went
24//! // to sleep, so it costs nothing from here on.
25//! let body = world.body(ball).unwrap();
26//! assert!((body.translation().y - 0.5).abs() < 0.05);
27//! assert!(body.is_sleeping());
28//! ```
29//!
30//! # Where things live
31//!
32//! | Module | Role |
33//! |---|---|
34//! | [`world`] | [`World`](world::World) — the object you actually talk to |
35//! | [`body`] | [`RigidBody`](body::RigidBody), its builder, and the arena |
36//! | [`shape`] | Collision shapes and analytic mass properties |
37//! | [`collider`] | A shape plus where it sits on a body |
38//! | [`joint`] | Fixed, spherical, revolute, prismatic, distance, spring |
39//! | [`query`] | Raycasts, shape casts, overlap and point queries |
40//! | [`ik`] | FABRIK and CCD chains with joint limits |
41//! | [`character`] | Kinematic move-and-slide controller |
42//! | [`material`] | Friction, restitution and collision filtering |
43//!
44//! The stages of a step — [`broadphase`], [`narrowphase`], [`contact`],
45//! [`solver`] — are public too, so a custom pipeline can reuse the pieces.
46//! [`gjk`] and [`hull`] are the geometry kernels underneath.
47//!
48//! # Conventions worth knowing up front
49//!
50//! - **Sizes are half-extents**, because that is what the solver works in. Every
51//! such constructor has a `*_from_size` sibling taking the full dimensions a
52//! `*Geometry` would: [`Shape::cuboid`](shape::Shape::cuboid) versus
53//! [`Shape::cuboid_from_size`](shape::Shape::cuboid_from_size).
54//! - **Capsules, cylinders and cones are Y-aligned**, matching three.js.
55//! - **Contact normals point from `b` toward `a`**: translating `a` along the
56//! normal separates the pair. This holds throughout [`narrowphase`],
57//! [`contact`] and [`gjk`].
58//! - **Restitution combines with `Max`, friction with `Average`** — see
59//! [`PhysicsMaterial`](material::PhysicsMaterial) for why.
60//! - **Jointed bodies do not collide with each other** unless you ask; see
61//! [`Joint::collide_connected`](joint::Joint::collide_connected).
62//!
63//! # Determinism
64//!
65//! The same scene stepped the same way produces the same result, run to run and
66//! regardless of whether `parallel` is enabled. Constraint solve order and
67//! reported collision events are sorted rather than left to hash-map iteration
68//! order, which is what replays and lockstep networking need.
69//!
70//! # Feature flags
71//!
72//! | Flag | Effect |
73//! |---|---|
74//! | `parallel` | Multi-threaded narrow phase via rayon. Native only. |
75//! | `gpu` | Broad phase on a wgpu compute shader. Native **and** wasm32/WebGPU. |
76//! | `async` | Pulls in a tokio runtime for async callers. Native only. |
77//!
78//! rayon needs OS threads, so on `wasm32` `parallel` is deliberately a no-op
79//! rather than a build error. [`gpu`] is the browser's route to parallelism —
80//! read its module docs before reaching for it, since a dispatch and readback
81//! costs more than the CPU sweep-and-prune below a few thousand bodies.
82
83#[cfg(feature = "assembly")]
84pub mod assembly;
85pub mod body;
86pub mod broadphase;
87pub mod bvh;
88pub mod character;
89pub mod collider;
90pub mod contact;
91pub mod debug;
92pub mod decompose;
93pub mod diagnostics;
94pub mod forces;
95pub mod gjk;
96#[cfg(feature = "gpu")]
97pub mod gpu;
98pub mod heightfield;
99pub mod hull;
100pub mod ik;
101pub mod island;
102pub mod joint;
103pub mod material;
104pub mod math;
105#[cfg(all(feature = "assembly", feature = "openscad"))]
106pub mod mechanism;
107pub mod narrowphase;
108pub mod query;
109#[cfg(feature = "openscad")]
110pub mod scad;
111pub mod shape;
112pub mod snapshot;
113pub mod solver;
114pub mod tendon;
115pub mod trimesh;
116pub mod vehicle;
117#[cfg(all(feature = "assembly", feature = "openscad"))]
118pub mod verify;
119pub mod world;
120
121/// Everything you normally need, in one import.
122///
123/// ```
124/// use threers_physics::prelude::*;
125/// ```
126///
127/// Re-exports `Vector3`, `Quaternion` and `Ray` from `threers` too, so simple
128/// programs need only this one `use`.
129pub mod prelude {
130 #[cfg(feature = "assembly")]
131 pub use crate::assembly::{
132 Assembly, AssemblyError, AssemblyReport, Axis, Easing, Feature, FeatureKind, Interference,
133 Mate, MateId, MateKind, Part, PartId, PartPhysics, Sweep,
134 };
135 pub use crate::body::{BodyId, BodySet, BodyType, LockedAxes, RigidBody, RigidBodyBuilder};
136 pub use crate::character::{CharacterController, CharacterMove};
137 pub use crate::collider::Collider;
138 pub use crate::contact::{CollisionEvent, ContactManifold, ContactPoint, ContactSet};
139 pub use crate::decompose::{decompose, decompose_to_shape, DecompositionConfig};
140 pub use crate::gjk::{closest_points, Proximity, ShapeProxy, SupportMap};
141 pub use crate::hull::{ConvexHull, HullFace};
142 pub use crate::ik::{IkChain, IkConstraint, IkJoint, IkResult};
143 #[cfg(feature = "mechanism")]
144 pub use crate::joint::{AxialKind, JointState, Servo};
145 pub use crate::joint::{
146 Dof, DofMotion, Joint, JointId, JointKind, JointLimits, JointSet, JointSpring, Motor,
147 Softness,
148 };
149 pub use crate::material::{CombineRule, InteractionGroups, PhysicsMaterial};
150 pub use crate::math::{Aabb, Isometry, Mat3};
151 pub use crate::query::{PointProjection, QueryFilter, RayHit, ShapeHit};
152 pub use crate::shape::{ColliderFit, MassProperties, Shape};
153 pub use crate::solver::{SimulationQuality, SolverConfig};
154 pub use crate::tendon::{
155 ResolvedPath, Tendon, TendonArc, TendonId, TendonKind, TendonNode, TendonObstacle,
156 TendonPoint, TendonSet,
157 };
158 pub use crate::trimesh::TriMesh;
159 pub use crate::vehicle::{Vehicle, Wheel, WheelConfig};
160 pub use crate::world::{GravityModel, SleepConfig, World};
161 pub use threers::math::{Quaternion, Ray, Vector3};
162}