Technical requirements

The WebGPU migration, performance budgets, and the browser constraints that shape every visual decision in art.

Architecture is in docs/architecture.md and is not repeated here. This page covers what the game requires that the platform does not yet provide.

---

What exists

---

The WebGPU migration

The single largest technical item in the plan, and the enabler for M2.

What it buys

What has landed

The renderer swap itself, on 2026-08-20. apps/game/src/render/ holds it: WebGPURenderer with logarithmicDepthBuffer, TSL node materials for every surface the game draws, the extended-range output path behind a capability probe and its three-state override, and an ACES-derived tone curve that is the stock curve exactly at headroom 1 and lifts only the highlights above it. WebGL 2 is retained as WebGPURenderer's own fallback backend rather than a second renderer, so there is one set of node graphs and no second material path to keep in sync.

The frame is drawn by a chain rather than by the renderer, since 2026-09-04: render/sensor.ts is one RenderPipeline around the scene pass and the tone curve, MSAA on the pass and the canvas single-sampled, measured level with the frame it replaced at five operating points (ADR-0029). Lens exposure and the optical passes are implemented in ADR-0031. ADR-0037 accepts a three-mode camera direction, with implementation still planned. It preserves this chain and separates Enhanced processing, photographic exposure and display output.

The chain carries no patch to three: the renderer draws nothing for a pipeline the warm-up is still building, because Pipelines.isReady gates the backend's draw, and warmup.gpu.test.ts holds that gate (ADR-0030).

What has not: indirect draw and GPU-driven culling — capabilities in the table above that the table promised. The heightfield producer is the one compute pass, a TSL kernel over storage buffers (ADR-0023); the star field is instanced, and it is the only thing that is. The atmosphere is an analytic shell awaiting its LUTs.

Three things came out of doing it that are worth carrying forward:

• WebGPU has no point size. PointsNodeMaterial.sizeNode is silently ignored on a Points object under the WebGPU backend — every point is one pixel — and works fine on the WebGL fallback. Anything wanting sized points is a Sprite with an instanced position attribute. A rendering bug that appears only on the primary backend is the worst-shaped one available.
• A vec3 clamped against float bounds compiles and renders black. TSL builds the node from whatever it is handed; the generated WGSL clamp had arguments that did not agree on a type, and it produced no warning, no exception and no console output — just an entirely black frame.
• React Three Fiber cannot release a WebGPURenderer. Its unmount path calls renderLists.dispose() and forceContextLoss(), both WebGL-only and both optional-chained, so both are silent no-ops. Two renderers then share a canvas and disagree about its size, every frame submits an invalid command buffer, and the tab dies. It does not reproduce at devicePixelRatio 1, so a headless check calls it fixed when it is not.

The path

Three.js WebGPURenderer with TSL first, not a hand-written WebGPU renderer.

Rationale. packages/rendering deliberately does not import Three.js — it emits positions, scales, orientations and vertex buffers as plain data, and apps/game applies them. That boundary means the renderer swap is confined to the app layer and can be done incrementally, with the WebGL path kept working alongside it. A hand-written renderer is a six-month project that buys control this game does not yet need; TSL gets compute and HDR immediately.

The escape hatch matters. Terrain, atmosphere and the star-field passes are the three places where a custom pipeline may eventually be worth it. The design should keep them expressible as standalone passes so that decision stays available.

Measured: TSL costs nothing

Spike 2 wrote the same single-scattering atmosphere raymarch twice — once in TSL, once by hand in WGSL — harvested the WGSL that three's node system generates, and ran both through one raw WebGPU harness: same rgba16float 1920×1080 target, same fullscreen triangle, GPU time from timestamp-query, A and B interleaved, outputs verified pixel-identical first.

Resolved: TSL for everything, including the atmosphere. The generator inlines every Fn and hoists every intermediate to a function-scope var where a person would write let — the one structural difference that could have cost register pressure — and on Metal the backend compiler removes the difference entirely. The 15% threshold the spike set was met by a factor of ten.

three's renderer around it is nearly free too: the canvas output pass costs 0.11 ms (1.5%), measured as wall clock across a drained queue.

⚠️ renderer.info.render.timestamp is not trustworthy on the canvas path. It reported 14.615 ms for a frame whose true cost is 7.27 ms — it double-counts when there is an output pass, and the first run of this spike concluded "TSL is 2× slower" on the strength of it. Measure with a raw timestamp query, or with wall clock across queue.onSubmittedWorkDone(). This will bite the benchmark harness too.

The escape hatch stays open on principle, but it is no longer pointed at the atmosphere. What the atmosphere actually needs is precomputed LUTs, which is a different problem.

Fallback

WebGPU availability is good on desktop Chrome, Edge and Safari 26+, and weaker elsewhere. Measured 2026-08-19 on macOS: navigator.gpu is present in all three of Chrome 151, Safari 26.5 and Firefox 153 — but Firefox rejects rgba16float canvas configuration, so WebGPU present and HDR possible are different questions and must be probed separately. The WebGL path is retained as a reduced-fidelity fallback, not deleted: no compute terrain, simpler atmosphere, fewer instances, lower LOD ceiling. The game must remain playable on it, because "it's a link" is the pitch and a link that fails is worse than an install.

---

Performance budgets

Target: 60 fps at 1920×1080 on a 2023-class laptop with integrated or entry discrete graphics. That is the machine the audience actually has, and a browser game that requires a desktop GPU has given up its only distribution advantage.

Frame budget — 16.6 ms

The atmosphere does not fit the budget at any language

The measurement that came out of spike 2 sideways, and it is the more important half of it:

7.274 ms for 256 samples per pixel at 1080p on an Apple M5 — a GPU far above the target machine — is already 2.4× over this table's 3.0 ms line. Scaled to fit, the budget buys about 105 samples per pixel, roughly 16 view × 6 light, which is not enough for a clean horizon.

So Bruneton's precomputed transmittance and multiple-scattering LUTs are a requirement, not an optimization. The spike asked whether TSL could express the integral cheaply enough; it can, and the integral still cannot be evaluated per-pixel per-frame in any language. Budget for LUT precomputation and its invalidation policy at M2, not for a faster inner loop.

Other budgets

The measurements below retain their original rigs and dates. They are historical operating points unless a newer date is named, not a fresh whole-app benchmark. Galaxy allocations and measured limits are in ADR-0038; startup and shell ownership are in ADR-0039.

Where these numbers come from now. The dev dock's perf panel (P) plots frame period, engine time, ticks per frame, draw calls, worker queue depth and JS heap over a four-second window, with a measure gpu button that times GPU frames the way spike 2 says to — wall clock across a drained queue, never renderer.info.render.timestamp. The right-hand column below is what it read on 2026-08-20.

Read the machine before the numbers. They were taken on an Apple M5 in a 1000×760 window at devicePixelRatio 2 — a GPU far above the target machine and about a third of the target's pixels. They establish that the instrument works and that nothing is pathological; they are not evidence that the budget is met on a 2023-class laptop at 1920×1080, and the row that matters most — cold load — is still unmeasured.

🎮 Designer's Note: The right-hand column used to be mostly "unmeasured", and the first thing the instrument found was not a budget overrun. It was that time warp did not work: the simulation clock capped every frame at eight ticks, which is 7.5× real time at 60 fps, so of the seven detents the dock offers — 1× to 100,000× — everything past 5× ran at the same speed and the difference went into a droppedTicks counter nothing displayed. It had been that way since the clock was written and no amount of playing found it, because the only symptom was a number that did not do anything.

That is the argument for the harness, made better than the argument could be. An overlay is not a nicety for a project whose defects are shaped like this one — a plot that showed requested against delivered would have shown it on the first afternoon. That plot is the perf panel's warp row now, and the seven detents are seven speeds: the ceiling is on integration, and a coasting ship has none to be capped by (ADR-0025).

---

Browser-specific constraints

The ones that will actually cause problems, with what they force.

---

Required engineering, by area

Nothing here is architectural. Everything lands on a seam that already exists.

---

Third-party dependencies

Deliberately few, and the list should be read as a commitment rather than an inventory.

The absence of a vendor SDK in the package graph is ADR-0008's explicit requirement and is enforced by the layer check. It should survive the persistent universe.

---

Related

• art — the rendering doctrine this must deliver
• production — when each item lands
• docs/architecture.md — the system as built
• docs/roadmap.md — the engineering gap list this draws from