Renderer: shader and pipeline compilation stalls the first frames of a 3D scene

[obiot]

On the first load of a 3D scene the background renders immediately and the geometry appears up to a second later, often in waves rather than all at once. It scales with the number of distinct program / pipeline variants a scene uses, not with its triangle count, so the larger the scene the longer the wait.

The cost is shader and pipeline construction, done lazily on first use, on the render thread.

To be precise about which programs are lazy: on WebGL the base programs are already built during await app.init() — batchers are constructed in WebGLRenderer.init and GLShader's constructor compiles and links — and both lit batchers deliberately call _bindLightBlock() from their own init() (lit_mesh_batcher.js:80, lit_quad_batcher.js:201) so the default program's block index is resolved at birth. What is lazy is the shaderVariant() permutations: mesh|fog, instanced|0..N, shadow, shadow|fog. That matches the profile below, where every slow query is against a newly linked program.

Where it lands

WebGPU — video/webgpu/pipeline/cache.js:506 calls device.createRenderPipeline, the synchronous form, on a cache miss, mid-frame. The cache key (cache.js:469) is ```${shaderKey}|${topology}|${blend}|${pma}|${stencilMode}|${format}|${sampleCount}`` plus |mesh:cull:front, `|dw0` and `|fog`. `shaderKey` is the dominant multiplier — the shader family, `mesh` vs the lit tier vs `instanced|N` vs each registered custom module — and it is also the only axis derivable from a renderable, which matters below. A scene mints one pipeline per combination it encounters, each paying its compile the first frame it appears. `video/webgpu/texture/store.js:325` does the same for the mipmap pipeline. Nothing in the engine uses `createRenderPipelineAsync`.

WebGL — compilation and linking are already asynchronous inside the driver; both compileShader and linkProgram return in ~0 ms. The stall lands wherever the engine first queries the result, which forces the driver to finish:

• video/webgl/utils/program.js:10 — getShaderParameter(shader, COMPILE_STATUS)
• video/webgl/utils/program.js:39 — getProgramParameter(program, LINK_STATUS); on most drivers linking is the expensive half
• video/webgl/buffer/uniformblock.js:89 — getUniformBlockIndex(program, …), reached through bindTo from lit_mesh_batcher.js:101 and lit_quad_batcher.js:269

Measured

CPU profile of the forest example, headless software rasterizer:

	share	self time
bindTo (→ getUniformBlockIndex), mesh tier	41.9%	2091 ms
compileShader (→ COMPILE_STATUS)	9.2%	457 ms

Of 17 getUniformBlockIndex calls only three are slow — 2053 ms, 1845 ms, 1772 ms — and each is the first query against a newly linked program. _bindLightBlock already guards against re-binding the same program, so the call count is not the problem; the wait is. The blocking-task timeline shows the same shape: a 436 ms block, then a ~2000 ms block, with geometry arriving after each.

Two caveats. The numbers come from a software rasterizer, so the absolute values are far larger than on a GPU — the structure is what matters. And the WebGPU half is from reading the code: the local harness has no navigator.gpu, so that path is not measured.

Why switching to the async call is not, by itself, the fix

createRenderPipelineAsync moves the compile off the calling frame, but with nowhere to wait for it the result is a frame that renders without the geometry instead of a frame that stalls. The cost has to move earlier, to a point where the game is already waiting.

Proposal

A public warm-up, e.g. renderer.warmUp(container) (name open): walk the renderables a container will draw, resolve the pipeline / program key each one would need, and build them ahead of the first frame.

Called automatically from level.load(), so the common path gets it for free. level.load() is the right hook because it is not TMX-only — safeLoadLevel branches on targetLevel.format, and anything that is not "tmx" goes through the generic addTo(container, options), which is how glTF/GLB scenes load (me.level.load("diorama", { scale: 50 }) is in its own JSDoc). So one hook covers tilemaps and 3D scenes alike.

The window is already the right one. level.load() calls state.stop() when the loop was running and defers the real work, so the loop is stopped across the whole load. The insertion point is in safeLoadLevel (level/level.js), after the container is populated and before the loop resumes:

// TMX loader, or targetLevel.addTo(...) — container is now populated
<-- warm up here: the world contents are known and the loop is stopped
emit(LEVEL_LOADED, levelId);
options.onLoaded(levelId);
if (restart) state.restart();

A synchronous warm-up is enough, and needs no API change. The loop is stopped at that point, so building the pipelines costs the same total time but spends it while the game is already waiting instead of on the first rendered frame — which is the entire goal. The asynchronous pipeline-creation path buys one extra thing on top: it keeps the main thread responsive during the warm-up, which on a loading screen is the least valuable place to have it. #1646 would provide a completion point to await at if we want that later; it is a possible refinement, not a prerequisite.

What is still undecided

Two of these block implementation.

1. The pipeline key cannot be derived from a renderable alone. Half of it can: batcher choice (mesh.lit), instanced family (mesh.instanceLayout → instancedFamilyFor(layout), which registers module and vertex layout and is callable outside a pass), cullMode / frontFace (mesh.cullBackFaces, mesh.rightHanded), custom shader family, topology. The other half needs draw-time context a container walk does not have:

• renderer._fog3d is set only by camera.draw(). At warm-up time no camera is drawing, and options.container may not even be the container a current camera draws — a glTF scene can be loaded into a detached container for an inactive stage.
• Transparent routing keys off packedTint >>> 24 !== 0xff, where the alpha is the accumulated product of every ancestor's opacity. Replicating that per renderable means replicating the whole ancestor accumulation.
• retained (whether a Camera3d draws it on a backend with supportsRetainedMesh) flips frontFace.
• renderer.stencilMode is mask state at draw time.

So the ticket has to pick one of:

• (a) dry-run the draw path with recording suppressed, reusing every derivation for free and staying correct as axes are added. Needs new "derive but do not record" plumbing in both backends.
• (b) explicit key-derivation methods per batcher taking (renderable, context). Cheaper, but creates a second implementation of the key that must be kept in step with the first.

2. Minting the program is not the expensive part. The profile says bindTo is 41.9% and compilation 9.2%. bindTo is reached only from _bindLightBlock(), which runs on a program switch during a draw. A warm-up that only calls shaderVariant() / pipelineCache.get() moves the 9% and leaves the 42% exactly where it was. The warm-up must also perform the binding query that forces the driver to resolve each newly minted program. This is the difference between fixing the reported stall and not.

3. Context loss would undo it, mid-game. Neither backend's cache survives a restore: WebGL rebuilds shaderVariants from scratch in init(), and WebGPU replaces pipelineCache outright on device.lost. After a restore the exact stall returns, now during play rather than on a loading screen — worse than the case being fixed. Does warmUp re-run on ONCONTEXT_RESTORED, and who holds the container reference?

4. The API is unspecified beyond its name. Return type (void, a count, a promise — the "synchronous is enough" argument implies void, which is a signature decision, not a detail); behaviour on Canvas or a renderer with no 3D content (Renderer.drawMesh is an empty base at video/renderer.js:806, so a no-op override is the obvious precedent); recursion, idempotency, detached containers, null. And scope: is it pipelines only, or everything a first draw allocates? The mipmap pipeline cited above is minted during a texture upload, which a pipeline-key walk never reaches, and retained geometry uploads on first draw. Relatedly, a tilemap's first-frame cost is texture upload and atlas setup rather than mesh pipelines — so it is not yet clear the level.load() hook helps the TMX case used to justify it.

5. KHR_parallel_shader_compile is not used anywhere. It is the WebGL counterpart to asynchronous pipeline creation and the only way to make the WebGL half non-blocking. Worth an explicit decision rather than silence.

6. Existing tests constrain this. No test calls level.load() at all, so the hook has no coverage to extend and needs a new spec. And webgl_mesh_fog.spec.js:249 asserts shaderVariants.has("mesh|fog") === false — an eager warm-up contradicts it directly. webgpu_pipeline.spec.js and webgpu_post_effect.spec.js assert exact pipeline counts and family keys, and family keys are registration-order dependent (key = \effect:${registeredModules.size}``), so warming ahead of first draw renumbers them.

Scope notes

• The warm-up can only resolve keys for what is in the container when it runs. An object spawned later that introduces a new blend mode still compiles on first use. The lazy path stays as the fallback; this removes the bulk case.
• Scenes not built through level.load() — a world assembled procedurally, or meshes added by hand — need the explicit call, which is why the public method is worth having on its own.
• The engine's preloader registers levels from its parsers (loader/parsers/tmx.js:33 and loader/parsers/gltf.js:1123 both call level.add()) but never instantiates one — nothing in loader.js or loadingscreen.js calls level.load(). Assets first, level after.
• Outside the level module there are exactly two callers of level.load(), both in renderable/trigger.js (lines 202 and 228). Inside it, reload(), next() and previous() all delegate to load(). The reveal effect in the trigger is chained off onLoaded, which runs before state.restart() — so a warm-up inserted ahead of onLoaded makes the fade-in start once the pipelines are warm, with no extra sequencing.
• feat(loader): "shader" asset type — preloaded, precompiled ShaderEffects + clone() #1534 established the "resolve GPU resources before the frame that needs them" pattern for shader effects. This is the same idea one tier down, for the mesh and lit pipelines.
• Distance fog added |fog as a pipeline / define axis this release, and the transparent pass (Mesh/Sprite3d: blended (alpha) pass for soft-transparent 3D sprites #1516) added another per mesh — a blended draw takes depthWrite: false plus the mesh's own blendMode as the blend axis. Both multiply the variant count. Note fog is renderer-global per camera pass, not per mesh (mesh.fog === false opts out at the uniform level only and does not change the key), so the doubling materialises when fogged and unfogged passes coexist — a Camera2d pass, a minimap, fog toggled at runtime — rather than within one fogged pass. The lazy-compile behaviour predates both.
• Worth measuring on a real GPU before sizing the work — the software-rasterizer numbers above establish the shape, not the budget.

[obiot]

(Superseded: the body above now incorporates this. Kept for the discussion record.)

Originally proposed calling the warm-up from level.load() rather than leaving it a manual-only entry point, on the grounds that safeLoadLevel branches on targetLevel.format — so the same hook covers glTF/GLB scenes as well as TMX — and that the loop is already stopped across the load, making it the natural window.

Both points are now in the issue body, along with the exact insertion point and the finding that a synchronous warm-up is sufficient there, so no API change is required.

[obiot]

Making level.load() awaitable

Worth doing, and the engine has already settled the shape once.

The house pattern is "same function, returns a Promise, callback still fires." That is what loader.preload() does since #1512 — its own JSDoc shows both forms side by side:

me.loader.preload(game.assets, () => this.loaded());   // callback form
await me.loader.preload(game.assets);                  // ...or await it

level.load() should match that rather than gain a separate async sibling. The xxxAsync convention seen in some asset-loading APIs exists to work around a load() whose return type is effectively frozen — typically one that takes several callbacks and returns void across a large subclass hierarchy, where changing the return would touch every implementation. Nothing here is in that position, and adding a second entry point would leave the engine with two different answers to the same question.

It is a safe change. load() returns true today, and a Promise is truthy, so if (me.level.load("x")) keeps working. The only form that breaks is an explicit === true, and there is none in the engine: the only internal callers are the two in renderable/trigger.js (lines 202 and 228), both of which ignore the return value entirely. reload(), next() and previous() all return this.load(...), so they come along for free — four @returns {boolean} JSDoc tags to update.

options.onLoaded stays exactly as it is, the same way preload kept its onloadcb.

Why it matters here. load() already defers the real work through a setTimeout when the loop was running, so the load finishes after the call returns and there is currently no way to observe completion except the callback. Returning a promise closes that, and it is what lets the warm-up above be genuinely asynchronous: safeLoadLevel can await the pipeline build (the async pipeline-creation path on WebGPU) before LEVEL_LOADED / onLoaded / state.restart(), instead of being forced to block. A scene can then do

await level.load("myLevel");   // resolves with the world built AND its pipelines warm

and know the first rendered frame will not compile anything.

Two things to be careful about:

• An unawaited rejected promise becomes an unhandled rejection. preload() already carries that exposure and shipped with it, so this is consistent rather than new — but the failure path should reject rather than throw synchronously.
• load() currently returns true before the level exists (the setTimeout path). Anything that today treats the return as "loaded" is already wrong; the promise makes the correct thing possible without changing what the callback does.

[obiot]

Correction on the previous comment

I claimed returning a Promise from level.load() was safe because a Promise is truthy. That is right at runtime and wrong overall: it ignores the shipped types.

build/level/level.d.ts declares function load(levelId: string, options?: {…}): boolean;. A TypeScript game doing

const ok: boolean = me.level.load("myLevel");

stops compiling the moment that becomes Promise<boolean>. Same for reload(), next() and previous(), which delegate to it. No await needs to be added for the game to run — but the build breaks, and that is a break, on a package that ships its own types.

Is a separate async entry point normal?

There is no single convention, and the split is historical rather than principled. Asset-loading APIs that started callback-first — load(url, onLoad, onProgress, onError) returning void across a large subclass hierarchy — add a Promise-returning sibling, because changing the original return type would break every consumer and every subclass. APIs designed Promise-first simply return the promise from load() and have no sibling.

melonJS sits in both camps already: loader.preload() returns a Promise (Promise-first), while level.load() returns boolean (the older shape). So level.loadAsync() is the precedented answer for this specific function, and the small inconsistency with preload() is the price of not breaking typed consumers.

But the warm-up does not depend on this

Worth separating, because it would be a shame to let the warm-up force an API decision.

A synchronous warm-up inside safeLoadLevel already solves the reported problem. The loop is stopped there, so building the pipelines costs the same total time but spends it while the game is already waiting, instead of on the first rendered frame. That is the entire goal, and it needs no API change at all.

The asynchronous pipeline-creation path buys one extra thing on top: it keeps the main thread responsive during the warm-up. On a loading screen that is the least valuable place to have it.

So the suggested order is:

1. Warm-up, synchronous, called from safeLoadLevel before LEVEL_LOADED / onLoaded / state.restart(). No API change, no break, fixes the stall.
2. Awaitable level loading judged separately on its own merits — level.loadAsync() if it lands in a minor, or load() returning a promise if it lands in a major.

[obiot]

The setTimeout in level.load() is legacy, not a design choice

Traced it: the deferral and its comment go back to 2011-07-08 (v0.9.0), where it read "pause the game loop to avoid some silly side effects". Promises are ES2015 and were not practical until around 2016; queueMicrotask arrived in 2018. So setTimeout was not chosen over a microtask — it was the only deferral primitive available at the time. There is no macrotask semantic to preserve here.

The deferral itself is still needed. renderable/trigger.js:228 calls level.load() from a trigger handler — inside the game loop, potentially mid-iteration over the very container safeLoadLevel then calls .reset() on and destroys. state.stop() sets a flag but does not unwind the current frame; the deferral is what moves the world mutation to between frames. Only the mechanism is historical.

Swapping it is an internal change with no API surface:

state.stop();
queueMicrotask(() => safeLoadLevel(levelId, options, true));

A microtask drains when the JS stack empties — the end of the rAF callback containing update and draw — so it unwinds the frame exactly as the timer does.

It also fixes a latent issue: setTimeout is clamped to ≥1000 ms in background tabs in every major browser, so a level load queued as the tab hides sits behind that clamp. A microtask has no clamp. The one thing a macrotask buys — yielding to the browser to paint once before the heavy work — is worth nothing here, since state.stop() has already halted the loop and level.load() does not switch to the loading state.

And it is the seam the rest of this needs. Once the deferral is promise-shaped internally:

function scheduleLoad(levelId, options, restart) {
	return Promise.resolve().then(() => safeLoadLevel(levelId, options, restart));
}

load() keeps return true, so no type breaks — and a later loadAsync() simply returns that internal promise instead of discarding it, while the warm-up gets a real completion point to be awaited at.

Suggested order, smallest blast radius first:

1. setTimeout → microtask. Internal only, fixes the background-tab clamp.
2. Warm-up in safeLoadLevel, synchronous. Fixes the reported stall, still no API change.
3. level.loadAsync() returning the internal promise, if and when it is wanted. Additive.

[obiot]

Body updated to consolidate the discussion above, so the proposal reads as one piece rather than four layered comments. The substantive changes:

• The level.load() hook, the exact insertion point in safeLoadLevel, and why it covers glTF/GLB scenes as well as TMX.
• A synchronous warm-up is enough and needs no API change — the loop is already stopped at that point, so the cost moves off the first rendered frame either way. The asynchronous pipeline path is a refinement, not a prerequisite.
• The caller inventory: two internal call sites, both in renderable/trigger.js, and the reveal effect there already chains off onLoaded (which runs before state.restart()), so the ordering works out with no extra sequencing.
• The engine's preloader deliberately has no level involvement, so this does not belong there.

The awaitable-load half has moved to #1646 — it stands on its own merits (it fixes a background-tab setTimeout clamp, and removes a callback monkey-patch the engine currently performs in trigger.js) and is not required by this ticket.

Correction to my earlier comment: I claimed changing level.load() to return a Promise was safe because a Promise is truthy. That is true at runtime but wrong overall — build/level/level.d.ts declares : boolean, so a typed consumer stops compiling. That is why #1646 proposes a sibling rather than a changed return type.