Atlaslog
Atlaslog / three.js / API reference / InstancedMesh
three.js · API reference

InstancedMesh

Quick answer

InstancedMesh draws one geometry and material many times while storing a per-instance matrix, collapsing thousands of repeated objects into a single draw call. Write every slot with setMatrixAt(), optionally add per-instance tint with setColorAt(), and call computeBoundingSphere() for culling. Use it for building clusters, trees, and repeated markers.

Last verified 2026-11-03 · three.js 0.160.0 · Cite this page
new THREE.InstancedMesh ( geometry , material , count )
Key points
Example
const geometry = new THREE.BoxGeometry(8, 1, 8);
const material = new THREE.MeshStandardMaterial({ color: 0xaeb8c2 });

const count = buildings.length;
const mesh = new THREE.InstancedMesh(geometry, material, count);

const matrix = new THREE.Matrix4();
const color = new THREE.Color();

buildings.forEach(function (b, i) {
  matrix.compose(
    new THREE.Vector3(b.x, b.height / 2, b.z),
    new THREE.Quaternion(),
    new THREE.Vector3(1, b.height, 1)
  );
  mesh.setMatrixAt(i, matrix);

  color.setHSL(0.58, 0.18, 0.55 + (b.height % 10) * 0.01);
  mesh.setColorAt(i, color);
});

mesh.instanceMatrix.needsUpdate = true;
if (mesh.instanceColor) {
  mesh.instanceColor.needsUpdate = true;
}
mesh.castShadow = true;
mesh.receiveShadow = true;
mesh.computeBoundingSphere();
scene.add(mesh);
Notes
Runnable examplesChinese originalAll API references
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Cite this page

Atlaslog (2026). InstancedMesh. https://www.jingweizhi.com/en/three/api/instanced-mesh.html (accessed 2026-11-03).