Threejs Impl Physics

threejs-impl-physics

Quick Reference

Engine Selection Decision Tree

Rule: ALWAYS use Rapier for production applications requiring determinism, CCD, or > 100 bodies. Use cannon-es for prototyping and simple scenes.

Critical Warnings

NEVER forget to call world.step() in the animation loop — physics bodies will NOT move without it.

NEVER use mesh.position.copy(body.position) with Rapier — Rapier returns plain {x, y, z} objects, NOT CANNON.Vec3. ALWAYS use mesh.position.set(pos.x, pos.y, pos.z).

NEVER use Rapier APIs before await RAPIER.init() completes — ALL Rapier classes are undefined until WASM loads.

NEVER use Trimesh / trimesh colliders on dynamic bodies — triangle meshes are STATIC only in both engines. Use ConvexPolyhedron / convexHull for dynamic concave geometry.

NEVER create physics bodies without corresponding Three.js meshes unless intentionally creating invisible colliders — orphaned bodies waste simulation budget.

---

cannon-es

World Setup

import * as CANNON from 'cannon-es';

const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);
world.broadphase = new CANNON.SAPBroadphase(world);
world.solver.iterations = 10;
world.allowSleep = true;

ALWAYS set world.allowSleep = true — sleeping bodies skip simulation and dramatically improve performance.

ALWAYS use SAPBroadphase for scenes with > 20 bodies. NaiveBroadphase is O(n^2).

Body Types

const body = new CANNON.Body({
  mass: 5,
  position: new CANNON.Vec3(0, 10, 0),
  shape: new CANNON.Box(new CANNON.Vec3(1, 1, 1)), // half-extents
  linearDamping: 0.01,
  angularDamping: 0.01,
});
world.addBody(body);

Shape Types

Materials and Contacts

const groundMat = new CANNON.Material('ground');
const ballMat = new CANNON.Material('ball');
const contact = new CANNON.ContactMaterial(groundMat, ballMat, {
  friction: 0.4,
  restitution: 0.6,
});
world.addContactMaterial(contact);

// Assign materials to bodies
groundBody.material = groundMat;
ballBody.material = ballMat;

ALWAYS assign materials to bodies after creating ContactMaterial — without assignment, the ContactMaterial has NO effect.

Constraints

const hinge = new CANNON.HingeConstraint(bodyA, bodyB, {
  pivotA: new CANNON.Vec3(0, 0, 0),
  axisA: new CANNON.Vec3(0, 1, 0),
  pivotB: new CANNON.Vec3(-2, 0, 0),
  axisB: new CANNON.Vec3(0, 1, 0),
});
world.addConstraint(hinge);

Events

body.addEventListener('collide', (event) => {
  const { contact } = event;
  // contact.ni = contact normal
  // contact.ri = contact point relative to bodyA
  // contact.rj = contact point relative to bodyB
});
body.addEventListener('sleep', () => { /* body went to sleep */ });
body.addEventListener('wakeup', () => { /* body woke up */ });

Stepping

// ALWAYS use three-argument step for deterministic simulation
const fixedTimeStep = 1 / 60;
const maxSubSteps = 3;

function animate() {
  const delta = clock.getDelta();
  world.step(fixedTimeStep, delta, maxSubSteps);
}

---

Rapier

WASM Initialization

import RAPIER from '@dimforge/rapier3d-compat';

await RAPIER.init(); // MUST await — ALL APIs undefined before this resolves

const gravity = { x: 0.0, y: -9.81, z: 0.0 };
const world = new RAPIER.World(gravity);

ALWAYS wrap Rapier usage in an async function or top-level await. Calling ANY Rapier constructor before init() resolves throws a runtime error.

RigidBody Creation (Builder Pattern)

// Dynamic body
const bodyDesc = RAPIER.RigidBodyDesc.dynamic()
  .setTranslation(0, 10, 0)
  .setLinvel(0, 0, 0)
  .setAngvel({ x: 0, y: 0, z: 0 })
  .setLinearDamping(0.01)
  .setAngularDamping(0.01)
  .setCcdEnabled(true);
const rigidBody = world.createRigidBody(bodyDesc);

// Static body
const staticDesc = RAPIER.RigidBodyDesc.fixed().setTranslation(0, 0, 0);
const staticBody = world.createRigidBody(staticDesc);

// Kinematic (position-based)
const kinDesc = RAPIER.RigidBodyDesc.kinematicPositionBased();
const kinBody = world.createRigidBody(kinDesc);

// Kinematic (velocity-based)
const kinVelDesc = RAPIER.RigidBodyDesc.kinematicVelocityBased();

Collider Shapes

const colliderDesc = RAPIER.ColliderDesc.cuboid(1, 1, 1)
  .setRestitution(0.5)
  .setFriction(0.7);
world.createCollider(colliderDesc, rigidBody);

Ray Casting

const ray = new RAPIER.Ray({ x: 0, y: 10, z: 0 }, { x: 0, y: -1, z: 0 });
const hit = world.castRay(ray, 100, true);
if (hit) {
  const hitPoint = ray.pointAt(hit.timeOfImpact);
  const hitCollider = world.getCollider(hit.colliderHandle);
}

CCD (Continuous Collision Detection)

ALWAYS enable CCD on fast-moving bodies to prevent tunneling through thin geometry:

const desc = RAPIER.RigidBodyDesc.dynamic().setCcdEnabled(true);

Collision Events

const eventQueue = new RAPIER.EventQueue(true);
world.step(eventQueue);

eventQueue.drainCollisionEvents((handle1, handle2, started) => {
  // started === true: collision began
  // started === false: collision ended
});

eventQueue.drainContactForceEvents((event) => {
  const force = event.totalForceMagnitude();
});

Debug Rendering

const { vertices, colors } = world.debugRender();
const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3));
geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 4));
const material = new THREE.LineBasicMaterial({ vertexColors: true });
const lines = new THREE.LineSegments(geometry, material);
scene.add(lines);

---

Three.js Sync Pattern

cannon-es Sync

// Store body-mesh pairs
const pairs = [];

function addPhysicsObject(mesh, body) {
  scene.add(mesh);
  world.addBody(body);
  pairs.push({ mesh, body });
}

function updatePhysics(delta) {
  world.step(1 / 60, delta, 3);
  for (const { mesh, body } of pairs) {
    mesh.position.copy(body.position);       // Vec3 → Vector3 (compatible)
    mesh.quaternion.copy(body.quaternion);    // Quaternion → Quaternion (compatible)
  }
}

cannon-es Vec3 and Quaternion are directly compatible with Three.js .copy().

Rapier Sync

const pairs = [];

function addPhysicsObject(mesh, rigidBody) {
  scene.add(mesh);
  pairs.push({ mesh, rigidBody });
}

function updatePhysics() {
  world.step();
  for (const { mesh, rigidBody } of pairs) {
    const pos = rigidBody.translation();   // returns {x, y, z}
    const rot = rigidBody.rotation();      // returns {x, y, z, w}
    mesh.position.set(pos.x, pos.y, pos.z);
    mesh.quaternion.set(rot.x, rot.y, rot.z, rot.w);
  }
}

NEVER use .copy() with Rapier return values — they are plain objects, NOT Three.js types.

---

React Three Fiber Integration

@react-three/rapier

import { Physics, RigidBody } from '@react-three/rapier';

function Scene() {
  return (
    <Physics gravity={[0, -9.81, 0]}>
      <RigidBody type="fixed">
        <mesh position={[0, -1, 0]}>
          <boxGeometry args={[20, 1, 20]} />
          <meshStandardMaterial />
        </mesh>
      </RigidBody>
      <RigidBody>
        <mesh position={[0, 5, 0]}>
          <sphereGeometry args={[1]} />
          <meshStandardMaterial />
        </mesh>
      </RigidBody>
    </Physics>
  );
}

@react-three/cannon

import { Physics, useBox, useSphere } from '@react-three/cannon';

function Floor() {
  const [ref] = useBox(() => ({ mass: 0, args: [20, 1, 20], position: [0, -1, 0] }));
  return (
    <mesh ref={ref}>
      <boxGeometry args={[20, 1, 20]} />
      <meshStandardMaterial />
    </mesh>
  );
}

---

Performance Comparison

---

Reference Links

• references/methods.md — API signatures for cannon-es and Rapier
• references/examples.md — Working integration examples
• references/anti-patterns.md — Common physics mistakes and fixes

Official Sources

• https://pmndrs.github.io/cannon-es/docs/
• https://rapier.rs/docs/user_guides/javascript/getting_started
• https://github.com/pmndrs/react-three-rapier
• https://github.com/pmndrs/use-cannon

threejs-impl-physics — Anti-Patterns

Anti-Pattern 1: Forgetting world.step() in the Animation Loop

Wrong:

function animate() {
  requestAnimationFrame(animate);
  // world.step() is missing!
  mesh.position.copy(body.position);
  mesh.quaternion.copy(body.quaternion);
  renderer.render(scene, camera);
}

Why it fails: Without calling world.step(), the physics simulation NEVER advances. Bodies remain frozen at their initial positions regardless of gravity or applied forces.

Correct:

function animate() {
  requestAnimationFrame(animate);
  const delta = clock.getDelta();
  world.step(1 / 60, delta, 3); // ALWAYS step the world
  mesh.position.copy(body.position);
  mesh.quaternion.copy(body.quaternion);
  renderer.render(scene, camera);
}

---

Anti-Pattern 2: Using .copy() with Rapier Return Values

Wrong:

// Rapier sync
const pos = rigidBody.translation();
mesh.position.copy(pos); // FAILS — pos is {x, y, z}, not a Vector3

Why it fails: Rapier translation() and rotation() return plain JavaScript objects {x, y, z} and {x, y, z, w}. Three.js .copy() expects objects with a .copy() method or matching class instances. This may silently fail or throw errors depending on the Three.js version.

Correct:

const pos = rigidBody.translation();
const rot = rigidBody.rotation();
mesh.position.set(pos.x, pos.y, pos.z);
mesh.quaternion.set(rot.x, rot.y, rot.z, rot.w);

Note: cannon-es Vec3 and Quaternion ARE compatible with Three.js .copy() — this anti-pattern applies ONLY to Rapier.

---

Anti-Pattern 3: Using Rapier APIs Before await RAPIER.init()

Wrong:

import RAPIER from '@dimforge/rapier3d-compat';

// Calling immediately without init
const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 }); // THROWS: WASM not loaded

Why it fails: Rapier is a Rust library compiled to WASM. The WASM binary MUST be loaded and initialized before ANY Rapier class is available. Accessing constructors before init() resolves causes runtime errors.

Correct:

import RAPIER from '@dimforge/rapier3d-compat';

async function main() {
  await RAPIER.init(); // MUST await first
  const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
  // Now safe to use all Rapier APIs
}
main();

---

Anti-Pattern 4: Using Trimesh on Dynamic Bodies

Wrong:

// cannon-es
const body = new CANNON.Body({
  mass: 5, // dynamic
  shape: new CANNON.Trimesh(vertices, indices), // BROKEN — Trimesh is static only
});

// Rapier
const desc = RAPIER.RigidBodyDesc.dynamic();
const body = world.createRigidBody(desc);
world.createCollider(RAPIER.ColliderDesc.trimesh(vertices, indices), body); // BROKEN

Why it fails: Triangle mesh collision detection in both cannon-es and Rapier is designed ONLY for static geometry. Dynamic trimesh colliders produce incorrect collision responses, tunneling, and undefined behavior. The engines do NOT support mesh-mesh dynamic collision.

Correct:

// Use convex hull for dynamic bodies
// cannon-es
const body = new CANNON.Body({
  mass: 5,
  shape: new CANNON.ConvexPolyhedron({ vertices: convexVerts, faces: convexFaces }),
});

// Rapier
const desc = RAPIER.ColliderDesc.convexHull(new Float32Array(flatVertices));

ALWAYS decompose concave dynamic geometry into convex parts using libraries like v-hacd or manual decomposition.

---

Anti-Pattern 5: Wrong Half-Extents for Box Shapes

Wrong:

// Three.js box is 2x2x2 (full size)
const mesh = new THREE.Mesh(new THREE.BoxGeometry(2, 2, 2));

// cannon-es — passing full size instead of half-extents
const shape = new CANNON.Box(new CANNON.Vec3(2, 2, 2)); // WRONG — this creates a 4x4x4 box

// Rapier — same mistake
const collider = RAPIER.ColliderDesc.cuboid(2, 2, 2); // WRONG — 4x4x4

Why it fails: Both cannon-es Box and Rapier cuboid use HALF-EXTENTS, not full dimensions. A BoxGeometry(2, 2, 2) has half-extents of (1, 1, 1). Passing full sizes doubles the physics collider, causing objects to collide in empty space.

Correct:

const width = 2, height = 2, depth = 2;
const mesh = new THREE.Mesh(new THREE.BoxGeometry(width, height, depth));

// cannon-es — half-extents
const shape = new CANNON.Box(new CANNON.Vec3(width / 2, height / 2, depth / 2));

// Rapier — half-extents
const collider = RAPIER.ColliderDesc.cuboid(width / 2, height / 2, depth / 2);

---

Anti-Pattern 6: Variable Timestep Physics

Wrong:

function animate() {
  const delta = clock.getDelta();
  world.step(delta); // WRONG — variable timestep causes non-deterministic simulation
}

Why it fails: Using delta directly as the timestep produces different simulation results at different frame rates. Objects may tunnel through walls at low FPS or behave differently on fast vs slow machines.

Correct (cannon-es):

function animate() {
  const delta = clock.getDelta();
  world.step(1 / 60, delta, 3); // fixed step with interpolation
}

Correct (Rapier):

// Rapier uses a fixed internal timestep by default (1/60)
world.step(); // ALWAYS call without arguments for consistent behavior

ALWAYS use a fixed timestep. cannon-es achieves this via the three-argument world.step(). Rapier uses a fixed timestep internally by default.

---

Anti-Pattern 7: Not Assigning Materials to Bodies

Wrong:

const groundMat = new CANNON.Material('ground');
const ballMat = new CANNON.Material('ball');
const contact = new CANNON.ContactMaterial(groundMat, ballMat, {
  friction: 0.4,
  restitution: 0.6,
});
world.addContactMaterial(contact);

// Materials never assigned to bodies — ContactMaterial has NO effect
const ground = new CANNON.Body({ mass: 0, shape: new CANNON.Plane() });
const ball = new CANNON.Body({ mass: 1, shape: new CANNON.Sphere(1) });

Why it fails: Creating a ContactMaterial only defines rules for interactions between two Material instances. Unless the Material is explicitly assigned to each Body via the .material property, the engine uses default material settings and the ContactMaterial is ignored.

Correct:

ground.material = groundMat;
ball.material = ballMat;

---

Anti-Pattern 8: Not Disposing Rapier WASM Resources

Wrong:

// Switching scenes, removing physics
function cleanupPhysics() {
  // Just setting world to null — WASM memory leaks
  world = null;
}

Why it fails: Rapier objects live in WASM linear memory, which is NOT managed by JavaScript's garbage collector. Failing to call .free() on the world and event queue causes permanent memory leaks that persist until page reload.

Correct:

function cleanupPhysics() {
  if (eventQueue) {
    eventQueue.free();
    eventQueue = null;
  }
  if (world) {
    world.free();
    world = null;
  }
}

ALWAYS call .free() on Rapier World and EventQueue objects when they are no longer needed.

---

Anti-Pattern 9: Ignoring Sleep for Static Scenes

Wrong:

const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);
// allowSleep defaults to false — ALL bodies simulated every frame

Why it fails: Without sleep, every body in the world is simulated every physics step, even if it has come to rest. In a scene with hundreds of stacked boxes that have settled, this wastes the majority of the physics budget on bodies that are not moving.

Correct:

const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);
world.allowSleep = true; // bodies at rest stop being simulated

ALWAYS enable sleep in cannon-es. Rapier enables sleep by default.

---

Anti-Pattern 10: Creating Physics Ground with Wrong Orientation

Wrong (cannon-es):

const ground = new CANNON.Body({
  mass: 0,
  shape: new CANNON.Plane(),
  // No rotation — Plane faces +Z by default, not +Y
});
world.addBody(ground);

Why it fails: CANNON.Plane faces the local +Z axis by default. Without rotating it, the ground plane is vertical (like a wall), and objects fall through the intended ground position.

Correct:

const ground = new CANNON.Body({
  mass: 0,
  shape: new CANNON.Plane(),
});
ground.quaternion.setFromEuler(-Math.PI / 2, 0, 0); // rotate to face +Y (up)
world.addBody(ground);

ALWAYS rotate CANNON.Plane by -Math.PI / 2 around X to create a horizontal ground.

threejs-impl-physics — Examples

Example 1: cannon-es — Falling Boxes Scene

Complete scene with a static ground plane and dynamic falling boxes.

import * as THREE from 'three';
import * as CANNON from 'cannon-es';

// Three.js setup
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 100);
camera.position.set(0, 10, 20);
camera.lookAt(0, 0, 0);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.shadowMap.enabled = true;
document.body.appendChild(renderer.domElement);

// Lighting
const dirLight = new THREE.DirectionalLight(0xffffff, 1);
dirLight.position.set(5, 10, 7.5);
dirLight.castShadow = true;
scene.add(dirLight);
scene.add(new THREE.AmbientLight(0x404040, 0.5));

// Physics world
const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);
world.broadphase = new CANNON.SAPBroadphase(world);
world.allowSleep = true;

// Contact material
const defaultMat = new CANNON.Material('default');
const defaultContact = new CANNON.ContactMaterial(defaultMat, defaultMat, {
  friction: 0.3,
  restitution: 0.4,
});
world.addContactMaterial(defaultContact);

// Ground
const groundBody = new CANNON.Body({
  mass: 0, // static
  shape: new CANNON.Plane(),
  material: defaultMat,
});
groundBody.quaternion.setFromEuler(-Math.PI / 2, 0, 0);
world.addBody(groundBody);

const groundMesh = new THREE.Mesh(
  new THREE.PlaneGeometry(50, 50),
  new THREE.MeshStandardMaterial({ color: 0x808080 }),
);
groundMesh.rotation.x = -Math.PI / 2;
groundMesh.receiveShadow = true;
scene.add(groundMesh);

// Dynamic boxes
const pairs = [];
for (let i = 0; i < 20; i++) {
  const size = 0.5 + Math.random() * 0.5;
  const halfSize = size / 2;

  const body = new CANNON.Body({
    mass: 1,
    position: new CANNON.Vec3(
      (Math.random() - 0.5) * 4,
      5 + i * 2,
      (Math.random() - 0.5) * 4,
    ),
    shape: new CANNON.Box(new CANNON.Vec3(halfSize, halfSize, halfSize)),
    material: defaultMat,
  });
  world.addBody(body);

  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(size, size, size),
    new THREE.MeshStandardMaterial({ color: Math.random() * 0xffffff }),
  );
  mesh.castShadow = true;
  scene.add(mesh);

  pairs.push({ mesh, body });
}

// Animation loop
const clock = new THREE.Clock();
function animate() {
  requestAnimationFrame(animate);
  const delta = clock.getDelta();

  world.step(1 / 60, delta, 3);
  for (const { mesh, body } of pairs) {
    mesh.position.copy(body.position);
    mesh.quaternion.copy(body.quaternion);
  }

  renderer.render(scene, camera);
}
animate();

---

Example 2: Rapier — Sphere Drop with Ray Casting

Complete scene using Rapier WASM with ray-based ground detection.

import * as THREE from 'three';
import RAPIER from '@dimforge/rapier3d-compat';

async function main() {
  await RAPIER.init();

  // Three.js setup
  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 100);
  camera.position.set(0, 8, 15);
  camera.lookAt(0, 0, 0);
  const renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(window.innerWidth, window.innerHeight);
  document.body.appendChild(renderer.domElement);
  scene.add(new THREE.DirectionalLight(0xffffff, 1));
  scene.add(new THREE.AmbientLight(0x404040, 0.5));

  // Physics world
  const gravity = { x: 0.0, y: -9.81, z: 0.0 };
  const world = new RAPIER.World(gravity);

  // Ground (fixed body)
  const groundDesc = RAPIER.RigidBodyDesc.fixed().setTranslation(0, -0.5, 0);
  const groundBody = world.createRigidBody(groundDesc);
  const groundCollider = RAPIER.ColliderDesc.cuboid(25, 0.5, 25)
    .setRestitution(0.3)
    .setFriction(0.8);
  world.createCollider(groundCollider, groundBody);

  const groundMesh = new THREE.Mesh(
    new THREE.BoxGeometry(50, 1, 50),
    new THREE.MeshStandardMaterial({ color: 0x808080 }),
  );
  groundMesh.position.set(0, -0.5, 0);
  scene.add(groundMesh);

  // Spheres
  const pairs = [];
  for (let i = 0; i < 50; i++) {
    const radius = 0.3 + Math.random() * 0.3;
    const bodyDesc = RAPIER.RigidBodyDesc.dynamic()
      .setTranslation(
        (Math.random() - 0.5) * 6,
        5 + i * 1.5,
        (Math.random() - 0.5) * 6,
      )
      .setCcdEnabled(true);
    const rigidBody = world.createRigidBody(bodyDesc);
    const colliderDesc = RAPIER.ColliderDesc.ball(radius)
      .setRestitution(0.7)
      .setFriction(0.5);
    world.createCollider(colliderDesc, rigidBody);

    const mesh = new THREE.Mesh(
      new THREE.SphereGeometry(radius, 16, 16),
      new THREE.MeshStandardMaterial({ color: Math.random() * 0xffffff }),
    );
    scene.add(mesh);
    pairs.push({ mesh, rigidBody });
  }

  // Raycaster marker
  const markerGeo = new THREE.SphereGeometry(0.1, 8, 8);
  const markerMat = new THREE.MeshBasicMaterial({ color: 0xff0000 });
  const marker = new THREE.Mesh(markerGeo, markerMat);
  scene.add(marker);

  // Ray cast on click
  window.addEventListener('click', () => {
    const ray = new RAPIER.Ray({ x: 0, y: 20, z: 0 }, { x: 0, y: -1, z: 0 });
    const hit = world.castRay(ray, 50, true);
    if (hit) {
      const point = ray.pointAt(hit.timeOfImpact);
      marker.position.set(point.x, point.y, point.z);
    }
  });

  // Animation loop
  function animate() {
    requestAnimationFrame(animate);
    world.step();
    for (const { mesh, rigidBody } of pairs) {
      const pos = rigidBody.translation();
      const rot = rigidBody.rotation();
      mesh.position.set(pos.x, pos.y, pos.z);
      mesh.quaternion.set(rot.x, rot.y, rot.z, rot.w);
    }
    renderer.render(scene, camera);
  }
  animate();
}
main();

---

Example 3: cannon-es — Hinge Constraint (Door)

A door attached to a frame with a hinge constraint.

import * as THREE from 'three';
import * as CANNON from 'cannon-es';

const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);
world.broadphase = new CANNON.SAPBroadphase(world);

// Frame (static)
const frameBody = new CANNON.Body({ mass: 0 });
frameBody.addShape(new CANNON.Box(new CANNON.Vec3(0.1, 1.5, 0.1)));
frameBody.position.set(-1, 1.5, 0);
world.addBody(frameBody);

// Door (dynamic)
const doorBody = new CANNON.Body({
  mass: 5,
  shape: new CANNON.Box(new CANNON.Vec3(1, 1.5, 0.05)),
  position: new CANNON.Vec3(0, 1.5, 0),
});
world.addBody(doorBody);

// Hinge constraint
const hinge = new CANNON.HingeConstraint(frameBody, doorBody, {
  pivotA: new CANNON.Vec3(0.1, 0, 0),
  axisA: new CANNON.Vec3(0, 1, 0),
  pivotB: new CANNON.Vec3(-1, 0, 0),
  axisB: new CANNON.Vec3(0, 1, 0),
});
world.addConstraint(hinge);

// Three.js meshes (create scene, camera, renderer as in Example 1)
const doorMesh = new THREE.Mesh(
  new THREE.BoxGeometry(2, 3, 0.1),
  new THREE.MeshStandardMaterial({ color: 0x8b4513 }),
);
scene.add(doorMesh);

// Apply force to open door
doorBody.applyImpulse(new CANNON.Vec3(0, 0, 10), new CANNON.Vec3(1, 0, 0));

// Sync in animation loop
function updatePhysics(delta) {
  world.step(1 / 60, delta, 3);
  doorMesh.position.copy(doorBody.position);
  doorMesh.quaternion.copy(doorBody.quaternion);
}

---

Example 4: Rapier — Debug Rendering

Visualize Rapier collision shapes as wireframe overlays.

import * as THREE from 'three';
import RAPIER from '@dimforge/rapier3d-compat';

async function main() {
  await RAPIER.init();
  const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });

  // ... create bodies and colliders ...

  // Debug line mesh
  let debugMesh = null;

  function updateDebugRender() {
    const { vertices, colors } = world.debugRender();

    if (debugMesh) {
      scene.remove(debugMesh);
      debugMesh.geometry.dispose();
      debugMesh.material.dispose();
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3));
    geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 4));
    const material = new THREE.LineBasicMaterial({ vertexColors: true, depthTest: false });
    debugMesh = new THREE.LineSegments(geometry, material);
    debugMesh.renderOrder = 999;
    scene.add(debugMesh);
  }

  function animate() {
    requestAnimationFrame(animate);
    world.step();
    updateDebugRender();
    renderer.render(scene, camera);
  }
  animate();
}
main();

---

Example 5: React Three Fiber with @react-three/rapier

Declarative physics with R3F.

import { Canvas } from '@react-three/fiber';
import { Physics, RigidBody, CuboidCollider } from '@react-three/rapier';

function Ground() {
  return (
    <RigidBody type="fixed">
      <CuboidCollider args={[25, 0.5, 25]} position={[0, -0.5, 0]} />
      <mesh position={[0, -0.5, 0]}>
        <boxGeometry args={[50, 1, 50]} />
        <meshStandardMaterial color="#808080" />
      </mesh>
    </RigidBody>
  );
}

function FallingBox({ position }) {
  return (
    <RigidBody restitution={0.5} friction={0.7}>
      <mesh position={position} castShadow>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="orange" />
      </mesh>
    </RigidBody>
  );
}

export default function App() {
  return (
    <Canvas shadows camera={{ position: [0, 10, 20], fov: 75 }}>
      <ambientLight intensity={0.5} />
      <directionalLight position={[5, 10, 5]} castShadow />
      <Physics gravity={[0, -9.81, 0]} debug>
        <Ground />
        {Array.from({ length: 10 }, (_, i) => (
          <FallingBox key={i} position={[(Math.random() - 0.5) * 4, 5 + i * 2, 0]} />
        ))}
      </Physics>
    </Canvas>
  );
}

threejs-impl-physics — Methods Reference

cannon-es API

CANNON.World

CANNON.Body

CANNON.Vec3

CANNON Shape Constructors

CANNON.Material and CANNON.ContactMaterial

CANNON Constraint Constructors

CANNON Broadphase Types

---

Rapier API

RAPIER Module

RAPIER.World

RAPIER.RigidBodyDesc (Builder)

RAPIER.RigidBody

RAPIER.ColliderDesc (Builder)

RAPIER.Ray

RAPIER.EventQueue