performance

name	performance
description	Keep a Three.js game at a smooth framerate as it grows — instancing, level-of-detail, object pooling, culling, draw-call and allocation discipline, and profiling with vitexec. Use when a game stutters or drops frames, or proactively when a scene has many objects, enemies, particles, or lights.

Performance

A scene that runs fine with a few objects stutters once it has crowds, particles, and a big map. The framerate is set by three budgets — draw calls, GPU work, and per-frame CPU/allocations — and the levers below each target one. Measure first, then fix the actual bottleneck.

Measure first

Don't guess. Profile the running game with vitexec --performance-trace (and --cpu-profile for hot functions). Read the verdict from where the frame time goes: long scripting/JS time per frame and a busy main thread mean CPU-bound (apply "less per-frame CPU"); a cheap main thread but high GPU/render time, many draw calls, or large overdraw mean GPU-bound (apply "less GPU work" / "fewer draw calls"). Fix the budget the trace actually points to, not the one you assumed.

Fewer draw calls

Each distinct mesh is roughly one draw call; thousands of them stall the CPU submitting work.

• Instancing: render many copies of the same geometry (trees, rocks, grass, bullets, identical enemies) as one InstancedMesh. Position each copy with mesh.setMatrixAt(i, matrix) and then set mesh.instanceMatrix.needsUpdate = true — omit that flag and instances never move.
• Merge static geometry: combine non-moving meshes that share a material into one buffer geometry. The tradeoff: a merged mesh is culled all-or-nothing, so don't merge geometry spread across a large area that benefits from per-object frustum culling.
• Share materials/textures: reuse material and texture instances; an atlas lets different props share one draw call.

Less GPU work

• Cull: leave frustumCulled = true (the default) so off-screen objects are skipped; for huge worlds, also cull by distance.
• LOD: swap distant objects for cheaper versions (THREE.LOD), or hide small distant detail entirely.
• Overdraw: cap large transparent/additive particles and full-screen effects; bound shadow-map size and the number of shadow-casting lights.

Less per-frame CPU

• Pool, don't allocate: reuse objects, and reuse scratch Vector3/Quaternion/Matrix4 instances instead of new-ing them inside the update loop — per-frame allocation causes GC hitches.
• Cap dynamic counts: bound the number of live enemies, particles, and projectiles; recycle from a pool rather than creating/destroying.
• Don't trigger recompiles: changing the light count or a material's defines at runtime recompiles shaders (see the lights skill). Keep them fixed.
• Spread work: amortize expensive systems (pathfinding, AI re-planning) across frames instead of doing all of it every frame.