Skip to main content

Crate threers_physics

Crate threers_physics 

Source
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

ModuleRole
worldWorld — the object you actually talk to
bodyRigidBody, its builder, and the arena
shapeCollision shapes and analytic mass properties
colliderA shape plus where it sits on a body
jointFixed, spherical, revolute, prismatic, distance, spring
queryRaycasts, shape casts, overlap and point queries
ikFABRIK and CCD chains with joint limits
characterKinematic move-and-slide controller
materialFriction, 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_size sibling taking the full dimensions a *Geometry would: Shape::cuboid versus Shape::cuboid_from_size.
  • Capsules, cylinders and cones are Y-aligned, matching three.js.
  • Contact normals point from b toward a: translating a along the normal separates the pair. This holds throughout narrowphase, contact and gjk.
  • Restitution combines with Max, friction with Average — see PhysicsMaterial for 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

FlagEffect
parallelMulti-threaded narrow phase via rayon. Native only.
gpuBroad phase on a wgpu compute shader. Native and wasm32/WebGPU.
asyncPulls 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 threers vector 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 threers mesh BVH.
vehicle
A raycast vehicle: one rigid body, four rays, and tyre forces.
world
World — the object you actually talk to.