Cannon-es: architecture of a physics engine

1. Why Cannon-es

Cannon-es is a maintained TypeScript fork of the original cannon.js library by Stefan Hedman. It's a pure-JS (no WASM) rigid-body physics engine designed to run comfortably inside a browser tab alongside a Three.js renderer. It trades some raw performance and feature completeness against engines like Rapier or Ammo.js (Bullet compiled to WASM) for a much smaller footprint and a simple, readable object model — which is exactly why it shows up so often in educational and small-scale interactive simulations.

Understanding its architecture matters even if you never read the source: every rigid-body engine — Cannon-es, Rapier, Bullet, Havok — is built from the same handful of building blocks. Learn them once here and the same mental model transfers everywhere.

2. The World object

Everything in Cannon-es lives inside a single World instance. It's the top-level container that owns the list of bodies, the gravity vector, the broadphase implementation, the solver, and the list of active constraints and contact materials.

Calling world.step(dt) once per animation frame advances every body: it runs the broadphase, narrow-phase contact generation, the constraint solver, and finally integrates positions and velocities forward by dt.

3. Body and Shape

A Body is a rigid object with mass, position, quaternion orientation, linear and angular velocity, damping, and a material. A body owns one or more Shape instances (box, sphere, cylinder, plane, convex polyhedron, trimesh, or a compound of several shapes) that define its collision geometry — deliberately kept separate from any visual mesh, so the same invisible collision box can drive a much more detailed Three.js model.

A mass of 0 marks a body as static — infinite effective inertia, never moved by forces or collisions (the ground plane, a wall). Every dynamic body computes its own inertia tensor from its shapes so that torques produce the correct angular acceleration.

4. Broadphase

With N bodies, testing every pair for collision is O(N²) — fine for a dozen bodies, ruinous for a thousand. The broadphase's job is to cheaply discard pairs that obviously cannot be touching (their bounding boxes don't overlap) before the expensive narrow-phase math ever runs. Cannon-es ships three broadphase strategies:

For the full picture on how sweep-and-prune, grids and BVH trees actually work — and how narrow-phase SAT/GJK/EPA algorithms take over from there — see Broad-phase and narrow-phase collision detection.

5. Solver

Once contact pairs are known, Cannon-es generates equations — one per contact point, plus friction equations, plus one per active constraint. The default GSSolver (Gauss-Seidel) is an iterative solver: it walks the equation list repeatedly, adjusting each body's velocity a little at a time so that all constraints are satisfied simultaneously, rather than solving one giant linear system exactly.

More iterations mean stiffer, more accurate stacks and joints at a higher CPU cost per frame — a direct dial between quality and performance exposed as world.solver.iterations.

6. Constraints

Beyond contacts, Cannon-es exposes explicit joint types that bolt two bodies together with restricted relative motion:

• PointToPointConstraint — ball-and-socket, pins one local point on each body together (rope segments, ragdoll hips).
• HingeConstraint — one rotational degree of freedom (doors, wheels, gears — see the Mechanisms simulation).
• DistanceConstraint — keeps two bodies a fixed distance apart, cheaper than a full point-to-point pin.
• ConeTwistConstraint — a hinge with a limited swing cone, used for shoulder/hip-like ragdoll joints.
• LockConstraint — fuses two bodies rigidly, useful for temporarily merging fragments (see the fracture pipeline below).

Each constraint is turned into one or more equations for the same GSSolver described above — architecturally, a joint is just a contact that never breaks.

7. The step() loop

Every call to world.step(dt) runs the same five phases in order:

// Simplified Cannon-es world.step() pipeline
function step(dt) {
  applyForces(bodies);           // gravity, user forces, springs
  const pairs = broadphase.collisionPairs(world);
  const contacts = narrowphase(pairs);   // exact contact points + normals
  solver.solve(dt, contacts, constraints); // Gauss-Seidel iterations
  integrate(bodies, dt);         // semi-implicit (symplectic) Euler
}

The final integration step uses semi-implicit Euler: velocity is updated from the (now solved) forces first, then position is updated using the new velocity. It's first-order accurate but symplectic — it doesn't leak energy the way explicit Euler does. See Verlet, Leapfrog and RK4 for why that distinction matters for long-running simulations.

8. Sleeping bodies

Simulating a body that hasn't moved in twenty frames wastes CPU. Cannon-es tracks each body's kinetic energy over a short window; if it stays below sleepSpeedLimit for longer than sleepTimeLimit, the body is marked SLEEPING and skipped entirely by integration and the solver — until a moving body touches it again, which wakes it up. This is essential for scenes with dozens of resting crates, rubble piles, or fracture debris that eventually come to rest.

9. Common pitfalls