meshfx // COLLISION // THREEJS

How to add collision to a mesh in three.js

three.js has no physics, so collision is up to you: load a separate low-poly collision mesh with your GLB, hide it, and test against it with the Octree and Capsule addons that ship with three.js, or give a physics library simple boxes, spheres and convex shapes. Testing against the detailed render mesh works but slows down quickly.

pyrofx effects work today, and new accounts start with $5 of usage.

MODULE // meshfx AVAILABLE

meshfx measures faults, checks repairs and makes LODs for a triangle budget. meshfx runs on the hosted API: try it in the Playground.

  • No built-in physics
  • Addons: Octree and Capsule
  • Ship the collision mesh in the GLB

01 // IN THE FILE

Ship the collision mesh inside the GLB

  1. In your 3D editor, model a low-poly shell over the level or prop, with flat floors, plain walls, ramps, and boxes around small detail.
  2. Name it clearly, for example collision_level, and export it in the same GLB as the visible model.
  3. After loading, find the collision mesh by name and hide it, keeping it for physics.
  4. Build the collision structure from it once at load time, not every frame.

02 // CODE

Walk a player capsule against the collision mesh

The addons in three.js include an Octree that indexes a mesh's triangles and a Capsule that stands in for the player, which is enough for a first-person or third-person walker.

collision.js
import * as THREE from 'three';
import { Octree } from 'three/addons/math/Octree.js';
import { Capsule } from 'three/addons/math/Capsule.js';

const collider = gltf.scene.getObjectByName('collision_level');
collider.visible = false;
const world = new Octree().fromGraphNode(collider);

const player = new Capsule(new THREE.Vector3(0, 0.35, 0), new THREE.Vector3(0, 1.45, 0), 0.35);

function resolveCollisions() {
  const hit = world.capsuleIntersect(player);
  if (hit) player.translate(hit.normal.multiplyScalar(hit.depth));
}

Call resolveCollisions() each frame after you move the capsule, then place the camera at the top of the capsule.

03 // PHYSICS LIBRARIES

When objects need to tumble and bounce

For crates that fall, roll and stack, run a physics library alongside three.js and give each object a simple shape: a box, sphere or capsule where it fits, or a convex hull (a shape that wraps the mesh with no dents) for irregular props. Keep triangle-mesh shapes for static ground and walls, because physics libraries handle moving bodies best with convex shapes.

After every physics step, copy each body's position and rotation to its three.js mesh.

04 // meshfx

meshfx for collision in three.js

meshfx measures faults, checks repairs and makes LODs. Build physics shapes in your engine or editor. Hosted meshfx runs are available in the Playground.

06 // FAQ

three.js collision questions

All questions →

README.COLLISION_MESH_THREEJS
How do I do mesh collision in three.js?

three.js has no built in physics. Use the Octree and Capsule addons against a light collision mesh for walking players or a physics library for moving objects.

What is a collision mesh in three.js?

A collision mesh is a simpler invisible shape that physics tests against instead of the detailed model, either hidden in your GLB or built as physics shapes.

Why should a three.js collision mesh be separate from the render mesh?

Physics tests every triangle it receives, so a detailed render mesh slows checks and snags players. A separate light shell is faster and smoother to walk on.

How simple should a three.js collision mesh be?

Keep it as simple as players can feel, with flat floors, straight walls, ramps over stairs and boxes around clutter. A few thousand triangles fits a level.

Explore meshfx outputs

Inspect compiled meshfx outputs and their reports. Hosted meshfx runs are available in the Playground.

All effects, guides and explainers →