Expand description
Rigid-body physics for threers.
Gravity, collisions, joints, scene queries and inverse kinematics — pure
Rust, no dependencies beyond threers itself, and wasm-ready.
use threers_physics::prelude::*;
let mut world = World::new(); // gravity is -9.81 Y
world.add_body(RigidBody::fixed().shape(Shape::ground()));
let ball = world.add_body(
RigidBody::dynamic()
.shape(Shape::ball(0.5))
.translation(Vector3::new(0.0, 10.0, 0.0))
.restitution(0.7),
);
for _ in 0..600 {
world.step(1.0 / 60.0); // once per frame
}
// It fell, bounced itself out, and came to rest on the ground — then went
// to sleep, so it costs nothing from here on.
let body = world.body(ball).unwrap();
assert!((body.translation().y - 0.5).abs() < 0.05);
assert!(body.is_sleeping());§Where things live
| Module | Role |
|---|---|
world | World — the object you actually talk to |
body | RigidBody, its builder, and the arena |
shape | Collision shapes and analytic mass properties |
collider | A shape plus where it sits on a body |
joint | Fixed, spherical, revolute, prismatic, distance, spring |
query | Raycasts, shape casts, overlap and point queries |
ik | FABRIK and CCD chains with joint limits |
character | Kinematic move-and-slide controller |
material | Friction, restitution and collision filtering |
The stages of a step — broadphase, narrowphase, contact,
solver — are public too, so a custom pipeline can reuse the pieces.
gjk and hull are the geometry kernels underneath.
§Conventions worth knowing up front
- Sizes are half-extents, because that is what the solver works in. Every
such constructor has a
*_from_sizesibling taking the full dimensions a*Geometrywould:Shape::cuboidversusShape::cuboid_from_size. - Capsules, cylinders and cones are Y-aligned, matching three.js.
- Contact normals point from
btowarda: translatingaalong the normal separates the pair. This holds throughoutnarrowphase,contactandgjk. - Restitution combines with
Max, friction withAverage— seePhysicsMaterialfor why. - Jointed bodies do not collide with each other unless you ask; see
Joint::collide_connected.
§Determinism
The same scene stepped the same way produces the same result, run to run and
regardless of whether parallel is enabled. Constraint solve order and
reported collision events are sorted rather than left to hash-map iteration
order, which is what replays and lockstep networking need.
§Feature flags
| Flag | Effect |
|---|---|
parallel | Multi-threaded narrow phase via rayon. Native only. |
gpu | Broad phase on a wgpu compute shader. Native and wasm32/WebGPU. |
async | Pulls in a tokio runtime for async callers. Native only. |
rayon needs OS threads, so on wasm32 parallel is deliberately a no-op
rather than a build error. [gpu] is the browser’s route to parallelism —
read its module docs before reaching for it, since a dispatch and readback
costs more than the CPU sweep-and-prune below a few thousand bodies.
Modules§
- body
- Rigid bodies and the arena that stores them.
- broadphase
- Broad phase: cheap rejection of pairs that cannot possibly touch.
- bvh
- Dynamic bounding-volume hierarchy.
- character
- A kinematic character controller: move-and-slide against the world.
- collider
- Colliders — a shape, where it sits on its body, and how it behaves on contact.
- contact
- Persistent contact manifolds.
- debug
- Seeing what the solver sees.
- decompose
- Turning a concave mesh into a handful of convex pieces.
- diagnostics
- What the engine noticed while it was running.
- forces
- Force fields: drag, buoyancy, wind and explosions.
- gjk
- GJK distance and EPA penetration depth for convex shapes.
- heightfield
- Heightfields: terrain as a grid of heights rather than a triangle soup.
- hull
- Convex hulls: quickhull construction plus the volume integrals the mass properties need.
- ik
- Inverse kinematics: pose a chain so its tip reaches a target.
- island
- Connected components of the constraint graph.
- joint
- Joints — constraints that tie two bodies together.
- material
- Surface properties and collision filtering.
- math
- Rigid-transform and inertia-tensor math built on the
threersvector types. - narrowphase
- Contact generation: from a pair of positioned shapes to a contact manifold.
- prelude
- Everything you normally need, in one import.
- query
- Scene queries: rays, shape casts, overlap tests and point lookups.
- shape
- Collision shapes and their mass properties.
- snapshot
- Capturing and restoring simulation state.
- solver
- Constraint solver: sequential impulses with warm starting.
- tendon
- Tendons — a cable routed through a chain of points, constrained by its total length.
- trimesh
- Triangle-mesh colliders, accelerated by the
threersmesh BVH. - vehicle
- A raycast vehicle: one rigid body, four rays, and tyre forces.
- world
World— the object you actually talk to.