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.
new THREE.InstancedMesh ( geometry , material , count )
Key points
- count is fixed at construction and cannot be changed later; allocate the maximum up front.
- instanceMatrix holds 16 floats per instance and defaults to DynamicDrawUsage.
- setColorAt() creates instanceColor on first call and requires material support.
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
- Unwritten instance slots keep identity matrices and render stacked at the origin.
- Instancing saves draw calls, not memory; a million instances still consumes large matrix buffers.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). InstancedMesh. https://www.jingweizhi.com/en/three/api/instanced-mesh.html (accessed 2026-11-03).