Three.js Performance

Profiling First

import Stats from "three/addons/libs/stats.module.js";

const stats = new Stats();
stats.showPanel(0); // 0=fps, 1=ms, 2=mb
document.body.appendChild(stats.dom);

function animate() {
  stats.begin();
  // ... render
  stats.end();
}

Open Chrome DevTools → Performance or install Spector.js for GPU frame capture.

renderer.info exposes draw call counts:

console.log(renderer.info.render); // { calls, triangles, points, lines }
console.log(renderer.info.memory); // { geometries, textures }

Instancing (biggest win)

// One draw call for N meshes — critical for particles, trees, buildings
const count = 10000;
const geo = new THREE.SphereGeometry(0.1, 8, 4); // low-poly
const mat = new THREE.MeshStandardMaterial({ color: 0xff8800 });
const mesh = new THREE.InstancedMesh(geo, mat, count);
mesh.castShadow = true;
scene.add(mesh);

const dummy = new THREE.Object3D();
for (let i = 0; i < count; i++) {
  dummy.position.set(
    (Math.random() - 0.5) * 20,
    Math.random() * 5,
    (Math.random() - 0.5) * 20,
  );
  dummy.rotation.set(Math.random() * Math.PI, Math.random() * Math.PI, 0);
  dummy.scale.setScalar(0.5 + Math.random());
  dummy.updateMatrix();
  mesh.setMatrixAt(i, dummy.matrix);
}
mesh.instanceMatrix.needsUpdate = true;

// Per-instance color
mesh.setColorAt(i, new THREE.Color(Math.random(), 0.5, 0.5));
mesh.instanceColor.needsUpdate = true;

// Animate instances
function animate() {
  // Update specific instances
  mesh.getMatrixAt(i, dummy.matrix);
  dummy.matrix.decompose(dummy.position, dummy.quaternion, dummy.scale);
  dummy.rotation.y += delta;
  dummy.updateMatrix();
  mesh.setMatrixAt(i, dummy.matrix);
  mesh.instanceMatrix.needsUpdate = true;
}

Geometry Merging (static scenes)

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

const geos = objects.map((obj) => {
  const g = obj.geometry.clone();
  g.applyMatrix4(obj.matrixWorld); // bake transform into geometry
  return g;
});
const merged = mergeGeometries(geos, true); // true = use groups for multi-material
const mesh = new THREE.Mesh(merged, materials);
scene.add(mesh);
// Replaces N draw calls with 1

LOD (Level of Detail)

const lod = new THREE.LOD();

const highGeo = new THREE.SphereGeometry(1, 64, 32);
const midGeo = new THREE.SphereGeometry(1, 16, 8);
const lowGeo = new THREE.SphereGeometry(1, 6, 3);
const mat = new THREE.MeshStandardMaterial();

lod.addLevel(new THREE.Mesh(highGeo, mat), 0); // within 0 units
lod.addLevel(new THREE.Mesh(midGeo, mat), 15); // within 15 units
lod.addLevel(new THREE.Mesh(lowGeo, mat), 50); // within 50 units

scene.add(lod);

// Must call in render loop:
function animate() {
  lod.update(camera);
  renderer.render(scene, camera);
}

Frustum Culling

Three.js does frustum culling automatically. Make sure:

mesh.frustumCulled = true; // default true — don't set to false unless needed
geo.computeBoundingSphere(); // required for culling — called automatically on most geo
geo.computeBoundingBox();

For InstancedMesh, culling applies to the whole mesh. Use custom culling per-instance for large sparse sets.

Texture Optimization

// Reduce resolution — don't use 4096x4096 unless necessary
// Use 512x512 or 1024x1024 for most objects

// Compress textures (KTX2 / Basis Universal)
import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";
const ktx2Loader = new KTX2Loader()
  .setTranscoderPath("/basis/")
  .detectSupport(renderer);
// Use .ktx2 textures for GPU-native compression (no CPU decompression)

// Mipmaps — auto-generated, ensure power-of-2 dimensions
texture.generateMipmaps = true;
texture.minFilter = THREE.LinearMipmapLinearFilter;
texture.anisotropy = renderer.capabilities.getMaxAnisotropy();

// Dispose textures no longer needed
texture.dispose();

Material & Draw Call Tips

// Share materials across meshes
const sharedMat = new THREE.MeshStandardMaterial({ color: 0xff0000 });
mesh1.material = sharedMat;
mesh2.material = sharedMat; // same material = same draw call batch (sometimes)

// Avoid per-frame material changes — they break batching

// Use MeshBasicMaterial for UI/billboards that don't need lighting
const uiMat = new THREE.MeshBasicMaterial({ map: texture, transparent: true });

// Avoid transparent objects when possible — they break render order optimization
// Use alphaTest instead of transparent when possible
mat.alphaTest = 0.5;
mat.transparent = false; // faster than transparent: true

Renderer Settings for Performance

// Disable shadows for mobile / low-end
renderer.shadowMap.enabled = false;

// Reduce pixel ratio on high-DPI
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5)); // instead of 2

// Disable antialias if not needed
// new THREE.WebGLRenderer({ antialias: false })

// Use half-precision for render targets when possible
// renderTarget = new THREE.WebGLRenderTarget(w, h, { type: THREE.HalfFloatType })

// Dispose everything when tearing down
renderer.dispose();
renderer.forceContextLoss();

Common Gotchas

• Each unique material = one shader program = overhead at first render
• mesh.visible = false still costs a draw call check — use scene.remove(mesh) for long-lived invisible objects
• Avoid updating instanceMatrix every frame if only some instances change
• Skinned meshes (with bones) can't be instanced with standard InstancedMesh — use custom approach
• renderer.info.render.calls resets each frame — read it after render, not before