Cannon-es API Quick Reference

🌍 World

CANNON.World is the top-level container: gravity, broadphase, solver, and the list of bodies/constraints/contact materials all live on it. Call world.step(dt) once per animation frame to advance the simulation.

import * as CANNON from 'cannon-es';

const world = new CANNON.World({
  gravity: new CANNON.Vec3(0, -9.82, 0),
});
world.broadphase = new CANNON.SAPBroadphase(world);
world.solver.iterations = 10;

// Fixed-timestep step call in the render loop
const fixedTimeStep = 1 / 60;
function animate() {
  requestAnimationFrame(animate);
  world.step(fixedTimeStep);
  renderer.render(scene, camera);
}

📦 Body

CANNON.Body represents a single rigid body: mass, position, quaternion (orientation), velocity, angular velocity, and one or more attached shapes. A body with mass: 0 is static — infinite mass, never moves, but participates in collisions.

const body = new CANNON.Body({
  mass: 1,
  position: new CANNON.Vec3(0, 5, 0),
  shape: new CANNON.Sphere(0.5),
  linearDamping: 0.01,
});
body.applyForce(new CANNON.Vec3(0, 0, 50), body.position);
body.applyImpulse(new CANNON.Vec3(5, 0, 0), body.position);
world.addBody(body);

🔷 Shapes

A Body can carry multiple shapes (compound bodies), each with an optional local offset and orientation via body.addShape(shape, offset, quaternion).

🧪 Materials & ContactMaterial

A Material is just a named tag on a shape/body; the actual friction and restitution numbers live on a ContactMaterial that pairs two materials together.

const ice = new CANNON.Material('ice');
const rubber = new CANNON.Material('rubber');

const iceRubberContact = new CANNON.ContactMaterial(ice, rubber, {
  friction: 0.02,      // low — slides freely
  restitution: 0.3,    // 0 = no bounce, 1 = perfectly elastic
  contactEquationStiffness: 1e8,
  contactEquationRelaxation: 3,
});
world.addContactMaterial(iceRubberContact);

const puck = new CANNON.Body({ mass: 1, material: rubber, shape: new CANNON.Cylinder(0.4,0.4,0.1,16) });
const rink = new CANNON.Body({ mass: 0, material: ice, shape: new CANNON.Plane() });

🔗 Constraints

Constraints (joints) restrict the relative motion of two bodies. All constraints are added to the world with world.addConstraint(c).

// Pendulum: hinge a box to a fixed anchor point
const anchor = new CANNON.Body({ mass: 0 });
anchor.position.set(0, 5, 0);
world.addBody(anchor);

const hinge = new CANNON.HingeConstraint(anchor, bobBody, {
  pivotA: new CANNON.Vec3(0, 0, 0),
  pivotB: new CANNON.Vec3(0, 1.5, 0),
  axisA:  new CANNON.Vec3(0, 0, 1),
  axisB:  new CANNON.Vec3(0, 0, 1),
});
world.addConstraint(hinge);

🎯 Collision Groups & Masks

Every shape carries a collisionFilterGroup (which group it belongs to) and collisionFilterMask (which groups it should test against) — both bitmasks. Two shapes collide only if (A.group & B.mask) and (B.group & A.mask) are both non-zero.

const GROUP_PLAYER  = 1;   // 0b0001
const GROUP_ENEMY   = 2;   // 0b0010
const GROUP_TERRAIN = 4;   // 0b0100
const GROUP_TRIGGER = 8;   // 0b1000 — no physical response, events only

playerBody.collisionFilterGroup = GROUP_PLAYER;
playerBody.collisionFilterMask  = GROUP_ENEMY | GROUP_TERRAIN | GROUP_TRIGGER;

// Enemies collide with terrain but pass through each other
enemyBody.collisionFilterGroup = GROUP_ENEMY;
enemyBody.collisionFilterMask  = GROUP_PLAYER | GROUP_TERRAIN;

📡 Events

playerBody.addEventListener('collide', (e) => {
  const impactSpeed = e.contact.getImpactVelocityAlongNormal();
  if (impactSpeed > 5) playLandingSound(impactSpeed);
});

⚙️ Cannon-es ↔ Three.js Sync

Cannon-es has no rendering concept of its own — every frame, copy each body's position and quaternion directly into the matching Three.js mesh. Both libraries use the same axis convention and quaternion layout, so no conversion is needed.

const bodies = []; // { body: CANNON.Body, mesh: THREE.Mesh }

function addBox(size, mass, position) {
  const shape = new CANNON.Box(new CANNON.Vec3(size.x/2, size.y/2, size.z/2));
  const body  = new CANNON.Body({ mass, shape, position: new CANNON.Vec3(...position) });
  world.addBody(body);

  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(size.x, size.y, size.z),
    new THREE.MeshStandardMaterial({ color: 0x60a5fa }),
  );
  scene.add(mesh);

  bodies.push({ body, mesh });
  return body;
}

function animate() {
  requestAnimationFrame(animate);
  world.step(1/60);

  // Sync every mesh to its body's physics state
  for (const { body, mesh } of bodies) {
    mesh.position.copy(body.position);
    mesh.quaternion.copy(body.quaternion);
  }

  renderer.render(scene, camera);
}

⚠️ Common Pitfalls

• Adding a Trimesh/Heightfield to a dynamic body: concave shapes silently behave incorrectly (or fail to collide) unless the body has mass: 0.
• Forgetting to reset forces: forces applied via applyForce accumulate and are cleared automatically each world.step() — but manual integration loops that skip step() will leak force indefinitely.
• Thin fast-moving bodies tunneling through walls: increase world.solver.iterations, enable ccdSpeedThreshold/ccdSweptSphereRadius, or substep the simulation (see the physics engine tutorial).
• Jittery stacks: raise solver iterations (15–20), enable world.allowSleep, and check that contactEquationStiffness isn't set too high for your timestep — extremely stiff contacts can overshoot and oscillate.
• Scaling a Three.js mesh but not the Cannon shape: cannon-es shapes have no scale property — bake the scale into the shape's dimensions when you create it (e.g. multiply Box half-extents), not via the mesh transform.