Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 39 ยท Performance and Frameworks

Instancing, Merging, BatchedMesh and LOD

Draw thousands of objects fast in Three.js: InstancedMesh with per-instance color and matrices, merged geometry, BatchedMesh for mixed shapes, and LOD for distance-based detail.

A forest, a crowd, a field of grass, a starfield, a city of boxes: scenes full of repeated objects are where naive Three.js code hits a wall. As the previous lesson showed, every Mesh is a draw call, and a thousand separate trees will cap your frame rate long before the GPU gets tired. The solutions all do the same thing in different ways: tell the GPU to draw many things in a single call.

This lesson covers the four tools you need: InstancedMesh (many copies of one shape), merged geometry (many static shapes fused into one), BatchedMesh (many different shapes in one call), and LOD (swap detailed models for simpler ones when far away).

InstancedMesh: one shape, many copies

InstancedMesh stores one geometry and one material plus a transform matrix (and optionally a color) per instance. The GPU draws all instances in one call.

JavaScript
const count = 10000;
const mesh = new THREE.InstancedMesh(geometry, material, count);
const dummy = new THREE.Object3D();            // a scratch object for building matrices

for (let i = 0; i < count; i++) {
  dummy.position.set(x, y, z);
  dummy.rotation.set(rx, ry, rz);
  dummy.scale.setScalar(s);
  dummy.updateMatrix();
  mesh.setMatrixAt(i, dummy.matrix);
  mesh.setColorAt(i, color);                   // optional, creates mesh.instanceColor
}
mesh.instanceMatrix.needsUpdate = true;        // tell Three.js the data changed
if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
scene.add(mesh);

To animate instances, update their matrices in the loop and set instanceMatrix.needsUpdate = true; for tens of thousands of moving instances, do the motion in a vertex shader instead (see vertex shaders). Set mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage) if you update it every frame.

Two details that trip people up: the frustum culling of an InstancedMesh uses one bounding sphere for all instances, so call mesh.computeBoundingSphere() after placing them (or set frustumCulled = false), and raycasting returns instanceId so you know which instance was hit.

10,000 cubes in one draw call

Ten thousand separate meshes would be ten thousand draw calls. Here it is one, and the CPU cost is only the loop that writes matrices.

Merging geometry: static scenery

If objects never move relative to each other (the buildings of a level, the bricks of a wall), you can bake them into one BufferGeometry with mergeGeometries. The result is a single mesh with a single draw call and no per-object CPU cost. The price: you cannot move, hide or recolor parts independently, and all parts must share a material (use vertex colors for variety).

JavaScript
import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';

const parts = [];
for (...) {
  const g = new THREE.BoxGeometry(1, h, 1);
  g.applyMatrix4(matrixForThisBox);          // bake the transform into the vertices
  parts.push(g);
}
const merged = mergeGeometries(parts);       // all parts need the same attributes
parts.forEach((g) => g.dispose());
scene.add(new THREE.Mesh(merged, material));

mergeGeometries returns null (and logs an error) if the geometries have different attribute sets or are a mix of indexed and non-indexed. BoxGeometry and friends all have position, normal and uv plus an index, so primitives merge happily.

BatchedMesh: many different shapes, one call

InstancedMesh repeats one geometry. BatchedMesh holds several different geometries in one big buffer and lets you add instances of each, with individual transforms, colors and visibility. It also supports per-instance frustum culling and sorting, which makes it a good fit for scenes such as a city made of a few building types, or a mixed crowd.

JavaScript
const batch = new THREE.BatchedMesh(maxInstances, maxVertices, maxIndices, material);
const boxId  = batch.addGeometry(new THREE.BoxGeometry(1, 1, 1));
const coneId = batch.addGeometry(new THREE.ConeGeometry(0.6, 1.4, 12));
const id = batch.addInstance(boxId);
batch.setMatrixAt(id, matrix);
batch.setColorAt(id, color);
batch.setVisibleAt(id, false);   // hide one instance without removing it

You must declare the maximum vertex and index counts up front; getGeometryRangeAt and optimize() help when you remove and add geometries over time.

Merged geometry vs BatchedMesh

The renderer reports 2 draw calls for 350 visible objects: one for the merged skyline, one for the batch. Contrast that with the 400 calls in the previous lesson.

Which tool for which job?

InstancedMesh Many copies of one shape
mergeGeometries Static scenery, one material
BatchedMesh Several shapes, per-instance control
LOD Simpler models far away

They combine: LOD levels can themselves be instanced.

1 / 2

LOD: level of detail

Distant objects cover only a few pixels, so drawing 50,000 triangles for them is a waste. THREE.LOD holds several versions of an object and shows the right one depending on the distance to the camera. Add levels with lod.addLevel(object, distance); the object with the greatest distance not exceeded is used. LOD needs update(camera), which the renderer calls for you when the LOD is in the scene.

JavaScript
const lod = new THREE.LOD();
lod.addLevel(highDetailMesh, 0);     // from distance 0
lod.addLevel(mediumDetailMesh, 15);  // beyond 15 units
lod.addLevel(lowDetailMesh, 40);     // beyond 40 units
lod.addLevel(new THREE.Object3D(), 120);  // beyond 120: draw nothing

The lower levels can be simpler geometry (fewer segments), cheaper materials, or even a flat billboard. Artists produce LODs in modeling tools; glTF pipelines (gltf-transform simplify) can create them automatically. A hysteresis setting on addLevel prevents flickering when the camera sits on a boundary.

LOD switching with distance

Flat shading makes the difference between levels obvious: the near rock is smooth, the far rock is a crude low-poly shape that nobody notices at that distance. Watch the console numbers, and the faceted look change as the camera moves.

Other bigger levers

  • Impostors / billboards: for the farthest trees, draw a flat sprite; render the 3D model into a texture once.
  • Frustum and occlusion culling: Three.js culls by frustum automatically; occlusion culling (hiding objects behind walls) you do yourself, e.g. with a portal system.
  • Texture atlases and shared materials let more objects batch together.
  • Web workers and OffscreenCanvas can move rendering off the main thread so the page stays responsive.
  • Geometry compression (Draco, Meshopt) helps download time, not frame rate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an InstancedMesh with 10,000 instances cost in draw calls?

    All instances share one geometry and material and are drawn with a single instanced draw call.
  2. 2. After changing instance matrices in the animation loop, what must you set?

    The instance matrices live in a buffer attribute that must be flagged so it is uploaded to the GPU again.
  3. 3. When is mergeGeometries a poor choice?

    Merging bakes everything into one mesh, so individual parts can no longer be moved or recolored (other than by editing vertex data).
  4. 4. What does LOD do?

    LOD holds several detail levels and selects one by the distance to the camera, saving triangles on far objects.

Summary

  • Many objects mean many draw calls; the fixes draw many things per call.
  • InstancedMesh repeats one shape with per-instance matrices and colors; flag instanceMatrix.needsUpdate after changes.
  • mergeGeometries fuses static pieces into one mesh; use vertex colors for variety.
  • BatchedMesh combines several shapes with per-instance control in one call.
  • LOD swaps in simpler models at a distance; check renderer.info.render.calls to confirm savings.

Next: React Three Fiber and Other Frameworks