The obvious way to build that in three.js is one THREE.Mesh per tile and one per letter. It works. It also means hundreds of draw calls every frame, and on the school Chromebooks many students play on, that’s where the frame budget goes.

Today every tile and every letter goes through four BatchedMesh objects: one for opaque tiles, one for transparent ones, one for water ripples and one for text.

This post is how that works, and the handful of things that surprised us along the way.

Why hundreds of meshes hurt

A draw call isn’t expensive because the GPU minds drawing a small mesh. It’s expensive because of everything the CPU does around it. Every Object3D in the scene gets its world matrix recomputed, gets frustum-culled, gets sorted and pushed into a render list, and then three.js binds its program, uploads its uniforms and binds its buffers before issuing the draw. Multiply that by several hundred and you’ve spent a good chunk of your 16 milliseconds on bookkeeping before the GPU has done anything interesting.

The fix for “lots of the same object” in three.js has long been InstancedMesh. That’s not quite our situation, though.

BatchedMesh, not InstancedMesh

InstancedMesh draws one geometry many times. That’s perfect for a forest of identical trees. Our tiles are a stone, then a log, then a wall, then spikes: different shapes, in no particular pattern.

BatchedMesh, added to three.js at the end of 2023, is built for exactly that. You give it several geometries, it packs them into one shared vertex and index buffer, and each instance says which of those geometries it is. It’s all drawn with a single material.

The API is small. You size the buffers up front, add each geometry once, then add as many instances as you like:

const batch = new THREE.BatchedMesh(maxInstances, maxVertices, maxIndices, material);

const stone = batch.addGeometry(stoneGeometry);
const log = batch.addGeometry(logGeometry);

const id = batch.addInstance(stone);
batch.setMatrixAt(id, matrix);
batch.setColorAt(id, color);

Where the browser supports WEBGL_multi_draw, three.js renders the whole batch in one multi-draw call. Where it doesn’t, it falls back to looping over the instances, which is still a big win: there’s one object in the scene graph, one program bind and one set of buffers, instead of hundreds.

Two things we added on top made it pleasant to work with:

• A geometry registry. Each tile factory registers its meshes once, by name, and gets back the geometry id. Registering the same name twice returns the existing id instead of adding a duplicate.
• Instances as tiny wrappers. A tile doesn’t own a Mesh or even an Object3D. It owns an instance id, and moving it means one setMatrixAt. No scene graph node, no matrix-world propagation.

addGeometry also takes optional reserved vertex and index counts. We reserve a bit of headroom for letters, so a glyph can be swapped for its outlined version in place with setGeometryAt instead of reallocating anything.

One material, every tile type

Batching only works if everything in the batch shares a material, but our tiles don’t look alike. Traps flash, fragile tiles crack, water-side tiles get a waterline, and so on.

So there’s one MeshStandardMaterial for all the opaque tiles, extended through onBeforeCompile. Each tile factory contributes its own chunk of GLSL, and the shared shader branches on a per-instance tile type ID. That means one shader program for every tile variant, which also keeps the shader warm-up story simple. Roll It takes the same idea further and draws its ink outlines in the material too, with no extra pass.

The type ID has to come from somewhere per instance, and this is the trick that makes the rest of the post possible. setColorAt doesn’t write into a vertex attribute. It writes into a floating-point RGBA texture with one texel per instance, which the vertex shader reads with the instance’s index. So an instance’s “color” is really four floats of per-instance data, and you’re free to use them for things that aren’t color at all.

Posing a treadmill on the GPU

The treadmill is where this paid off most. It’s a mini-game tile: a moving belt the character has to run along, built from step boards, chain sections and couplers that loop around the machine. Each slot on the belt is about 15 instances, and a default treadmill has around 257 of them.

Animating that the straightforward way means computing a matrix for every piece on the CPU and calling setMatrixAt about 257 times a frame, per treadmill, and then re-uploading the matrix texture.

Instead, every piece knows where it sits on the loop. Its loop position goes in the instance color’s green channel and the index of the machine it belongs to goes in blue. Both are written once, when the treadmill is built. The vertex shader reads them, reads that machine’s state from a small uniform array, and works out the piece’s position and rotation itself.

The per-frame cost of a whole treadmill is now writing one vec4 into that uniform array. However long you make the machine, it adds no draw calls, no material and no per-frame matrix writes.

What breaks when the shader moves things

Moving an instance in the vertex shader works immediately for the color pass. Then three other systems turn out to still believe the instance is sitting at its batching matrix, which for a GPU-posed piece is only its anchor.

Shadows. Shadow maps are rendered with a separate depth material, which doesn’t include your custom vertex code, so every belt piece casts its shadow from its anchor. The fix is a customDepthMaterial on the batch, built from the same injected vertex chunks as the main material, so shadows come from the posed position.

Lighting. If the shader rotates a piece but not its normal, it’s lit as if it had never turned. Rotate the normal in the same place, by injecting into the beginnormal_vertex chunk. The depth pass never compiles that chunk, which is fine, since shadows don’t need normals.

Culling. BatchedMesh culls each instance against its bounding sphere, positioned by its matrix. A piece whose matrix says “anchor” but whose shader says “far end of the belt” gets culled whenever the anchor leaves the screen. We pad each track geometry’s bounds to cover everywhere the shader can move it.

The costs

It isn’t free.

Fixed ceilings. A BatchedMesh is sized when you create it. Our opaque batch reserves room for 10,000 instances, and that number quietly becomes an authoring limit: the treadmill’s maximum length is a budget calculated against it. Allocate too much and you waste GPU memory; too little and level construction fails.

CPU-posed pieces need care too. A few instances still have to move on the CPU, like the boards of a fragile tile falling away. If your wrapper exposes position, rotation and scale setters, each one can trigger its own setMatrixAt. Compose the matrix once from reusable scratch objects and write it with a single call.

Off-screen work. A mini-game far down the runway doesn’t need to animate at all. The mini-game tiles check whether they’re near the character first, and skip their update entirely when they aren’t.

Manual cleanup. Instances aren’t scene graph objects, so nothing tears them down for you. When a level ends, each tile’s reference to its instance has to be cleared by hand.

Shader glue. A stock material is easy to reason about. An onBeforeCompile material with contributions from a dozen tile factories, a depth variant and generated GLSL for the treadmill is not. We keep a written note in the codebase explaining where each injection point is and why.

When I’d reach for it

• Many objects, a few different shapes, one material: BatchedMesh.
• Many copies of exactly one shape: InstancedMesh is simpler.
• A few hundred things moving every frame: pose them in the vertex shader from a small uniform, and put their static per-instance data in the instance color.
• And if you do: fix shadows, normals and culling bounds at the same time, before you forget which of them you already did.

The frame rate stopped depending on how long the level is, and level designers stopped having to think about it. Both of those were the point.

That shape, a single long frame the first time something appears, is almost always a WebGL program being linked. The fix is well known: warm your shaders up before the level starts. What’s less well known is that the obvious warm-up can do all of its work and still leave every stutter exactly where it was.

What’s actually blocking

three.js creates a GPU program for a material the first time that material is rendered. It compiles the vertex and fragment shaders, then calls gl.linkProgram().

That call usually doesn’t block. Browsers and drivers generally link in the background, so linkProgram() returns straight away and your frame carries on. The wait happens later, when three.js asks the program for its uniform locations. In three.js that lookup is deferred until the program’s first use, which is the first draw call that uses it. At that point the driver has to finish the link before it can answer, and your frame sits there until it does.

So the stall isn’t at material creation, and it isn’t at new THREE.Mesh(). It lands on whichever frame first draws with that program. For an effect that only appears mid-level, that’s mid-level.

Why you can’t reproduce it

Chrome caches linked program binaries on disk, keyed by the shader source and the driver. The first visit pays the full link; a reload usually doesn’t. That’s why the hitch shows up for players and vanishes the moment you go looking for it.

Test on a fresh browser profile, and again after any shader change, because an edited shader is a new cache entry.

The fix: link everything before the level starts

three.js has renderer.compile(scene, camera) for exactly this. It walks the scene, works out which program every material will need, and creates them all up front. Do it once the level is built, behind a loading screen or a transition, and the links land before anyone is playing.

// after every mesh, light and environment map is in place
renderer.compile(scene, camera);

Two details make this more useful than it looks. compile() walks the scene with a plain traverse, so objects with visible = false are included; a hidden hammer or a parked enemy gets warmed along with everything else. And programs are shared by signature, so several materials that differ only in their colors end up on one program. Whichever of them draws first pays for the link, which is a good argument for warming the whole scene rather than guessing which feature to pre-warm.

It needs to run late, though. Lighting and scene.environment feed into the program too, so if you compile before they’re final, you warm programs your frames will never ask for.

The catch: the color-space variant

This is the part that cost me the most time.

A three.js program’s cache key includes its output color space, and that value depends on where you’re drawing. With no render target bound, three.js uses renderer.outputColorSpace, which is sRGB, because the result is going to the screen. With a render target bound, it uses the linear working color space, because something downstream (your post-processing) will do the final conversion.

If you render through an effect composer, your scene never draws straight to the canvas. Every material draws into the composer’s render target, so every program your frames use is the linear variant.

Now look at the warm-up. Call renderer.compile() with nothing bound and three.js dutifully links the sRGB variant of every material. Nothing ever draws with those. Then the first real frame asks for the linear variant, doesn’t find it, and links it right there, mid-level, exactly as before.

The warm-up did real work, doubled your program count, and moved the stutter precisely nowhere. It also fails silently, which is the dangerous part: a warm-up that links the wrong variant looks identical to one that works.

The fix is to bind the target your frames actually draw into while you compile:

function warmUpShaderPrograms(renderer, scene, camera, target) {
  const previous = renderer.getRenderTarget();
  renderer.setRenderTarget(target); // the composer's input buffer
  renderer.compile(scene, camera);
  renderer.setRenderTarget(previous);
}

In Voyage the target is the buffer the first render pass draws into. Any render target works, since the key only cares whether one is bound, but using the real one keeps the intent obvious.

Programs that come and go

The warm-up fixed the first-time stutters, but a few effects still hitched every single time, not just the first.

These were effects that build a fresh material per event (a respawn burst, a water splash, a mine blast) and dispose it when the effect ends. three.js reference-counts programs, and when the last material using a program is disposed, the program is destroyed. So every mine blast created its material, linked its program, drew, disposed, and threw the program away again. Chrome’s binary cache makes those repeat links cheaper, but the first draw still waits.

compile() can’t help either, because it only sees what’s in the scene when you call it, and these materials don’t exist yet.

The fix was a keep-alive: one hidden instance of each effect, parked in the scene for the whole level and never drawn. It holds the program’s reference count above zero, so the program is never destroyed, and because compile() ignores visible, the warm-up links it at load along with everything else. For it to work, the parked copy has to produce the same program key as a real one. That meant passing things like a waterline height as a uniform rather than baking it into the shader source, and pinning an explicit customProgramCacheKey on the one material that had its own.

One thing that doesn’t work: creating the material in a constructor and throwing it away. A material only acquires a program by being rendered or compiled as part of a scene. An orphaned material warms nothing.

Checking it without a profiler

You don’t need a performance trace to see whether this worked. renderer.info.programs lists every program three.js currently holds, and its length makes a very honest counter. Put it on a debug overlay and watch it through a level; three-kit’s three-meter HUD keeps draw calls, hitches and frame time on screen beside it.

const linked = renderer.info.programs?.length ?? 0;

It should climb during loading, settle, and then not move again. Every time it goes up during play, a program just linked mid-game; if it goes up and then back down, something is creating and destroying the same program per event. In Voyage it settled at 38 and blipped to 39 on every respawn, fragile tile and mine hit, until the keep-alives went in.

It also catches the color-space mistake. Compare the settled count against a build without the warm-up: it should be about the same total, just reached earlier. If it’s roughly double, both variants are being linked and the render-target bind has gone missing.

compile or compileAsync?

three.js also has renderer.compileAsync(), which uses the KHR_parallel_shader_compile extension and resolves when every program reports it’s ready. It’s the right choice when something has to wait on the result, like holding a loading screen until shaders are done.

I used the synchronous compile(). Nothing in Voyage needed to know when the links finished, since the level reveal already runs for most of a second, which is plenty of time for them to land. compileAsync() also works by polling every material’s program on a 10ms timer, and if you tear the scene down mid-poll (say, the player skips straight to the next lesson) the poll can find a disposed material with no program and throw from inside a timer callback, leaving the promise hanging. If you use it, make sure teardown can’t race it.

What a warm-up doesn’t cover

compile() warms the materials in your scene graph and nothing else.

• Shadow depth materials aren’t prepared, so a new shadow caster can still link its depth program at first draw. In Voyage every shadow caster is on screen from the first frame, so it never mattered.
• Post-processing passes have their own materials outside the scene. If you enable a pass mid-game, it links when it first runs.
• Lights are only collected if they’re visible, and the light setup is part of the program key. Add or toggle lights after the warm-up and you can invalidate what you warmed.

What I’d do on any three.js project

• Call renderer.compile(scene, camera) once the scene is fully built, with lighting and environment final.
• Bind the render target your frames draw into while you do it.
• Keep one parked instance of anything that creates materials per event.
• Watch renderer.info.programs.length through a real play session, on a fresh browser profile.

The frame rate was never the problem. The problem was a handful of single frames, each one paying for a link at the worst possible moment. Move those links behind the loading screen, make sure they’re the variants your frames actually use, and the level plays the way it did in your head.