@driftengine/core 4.6.1 → 4.7.1

package/CHANGELOG.json

@@ -1,4 +1,61 @@
 [
+  {
+    "version": "4.7.1",
+    "date": "2026-10-02",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "The manual: installation to a complete game, then every system in turn, sixty-nine chapters whose code is compiled from forty-six examples that switch live and run their behaviour in DriftScript.",
+        "text": "**The manual lives in `docs/manual/`**, one Markdown file a chapter and `manual.json` for their order: Getting started, from installation to a complete 3D game and a 2D one; Concepts; Rendering; Worlds; Simulation; Content, for models, the `.drft` container, sound and the command-line tools; and Interface, for input, cameras, sprites and menus. **Every code block is a region of a file under `examples/`**, which the typecheck compiles and `npm run manual:sync` copies in, so a sample cannot drift from code that runs. Forty-six examples run on WebGPU and WebGL2, their switches change the running scene, and where a scene has behaviour it lives in a `.drs` file that reloads in place. `docs/manual/uncovered.json` lists what has no chapter yet and can only shrink, and `undocumented.json` the exports with no comment, which can only shrink too. **`@driftengine/core`'s README is a package page**: what the engine is, a quickstart a test keeps equal to `examples/starter`, its systems linked to their chapters, and the other packages."
+      },
+      {
+        "kind": "added",
+        "short": "Scripts reach further: drift/audio ducks, fades and recalls the mix and reads the kick, drift/input reads a touch screen, and drift/chemistry asks whether a thing can be wet.",
+        "text": "**`drift/audio` turns the mix by name.** `duck`, `fade` and `recall` move a bus or a snapshot the host made, and answer `false` for a name nothing has; `pulse` reads the kick detector the host runs, `0` without one. `MixConsole.recall` returns whether the snapshot existed. **`drift/input` reads a touch screen** through a `Touch` handle beside `Actions`: `touchX`, `touchY`, `touchHeld`, `touchTap` and `touchSlide`, so a game whose controls are a script can be played on a phone. **`drift/chemistry` gains `wettable`**, so rain poured over every parcel passes over a nail instead of stopping at it."
+      },
+      {
+        "kind": "fixed",
+        "short": "A navigation mesh goes round a wall standing on the floor, and the regions a room is split into meet edge to edge, so a route crosses rooms it could not; the climb is a setting, maxStep.",
+        "text": "**`voxeliseWalkable` sees walls.** It sampled surfaces at cell centres, which never meet a vertical face, so a building on the ground read as a roof over open floor and a route went through it; a face too steep to stand on is now a solid in every cell it crosses, and erosion judges a neighbour at the span's own height. **Regions meet edge to edge**: each outline was simplified on its own, so a shared border came out as two lines that overlap nowhere and a portal vanished; a room with a pillar at the deviation the README recommends had no route between opposite corners. Border points are held across regions and each stretch is simplified once. `VoxeliseSettings.maxStep` takes the climb `buildRegions` takes."
+      },
+      {
+        "kind": "fixed",
+        "short": "Sprites and tiles drawn in a 2D world are the right way up, and a clipping node in an interface clips what its children draw and where the pointer reaches them.",
+        "text": "**A picture keeps its top up in a 2D world.** Every sprite and tile drawn through `worldToNdc` came out upside down, because the frame's top row was read at the sprite's corner, which in a world is its bottom; the vertex stage reads the affine's orientation now, and `scripts/sprite-check.mjs` draws the same rectangles in both spaces and asserts the frames match byte for byte. **`clip` is drawn and hit tested**: `drawUiTree` cuts every quad under a clipping node to what it leaves, an image's frame in proportion, and gives the content sink the visible rectangle; `uiHitTest` finds nothing under a clipping node outside its box. A scrolled list's rows drew wherever they had scrolled to, and took clicks there."
+      },
+      {
+        "kind": "fixed",
+        "short": "A script makes an entity from a prefab with ecs.instantiate and counts entities inside a system; splats hide behind what stands in front of them; a ragdoll whose root has no bone holds together.",
+        "text": "**`drift/prefab` could not be called**, since its one function is named `spawn`, a keyword; a script makes an entity from a prefab with `ecs.instantiate` now, and the module is refused by name. **`ecs.count`, `ecs.at` and `ecs.alive` work inside a system**, where they threw and the schedule skipped the system every tick. **Splats are occluded by the geometry in front of them on both backends**: WebGPU compared depth one way under reversed depth, and a contributed pass on WebGL2 was handed the identity in place of the depth remap. **A ragdoll built from a rig whose root has no bone holds together**: bones hanging from that root were jointed to nothing, so a humanoid fell as a torso and two loose legs. **Pale smoke is drawn**, because droplets now count toward how thick smoke is."
+      }
+    ]
+  },
+  {
+    "version": "4.7.0",
+    "date": "2026-10-01",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "Blender files bake directly: .blend from 2.79 to 5.x, compressed or not, with meshes, normals, materials, lights, cameras, shape keys and animation, and through your Blender where needed.",
+        "text": "**A `.blend` file is read directly, with nothing installed.** `readModel` and `npm run bake` take Blender's own format from 2.79 to 5.x, plain, gzip or zstd, because the reader learns every struct from the file's `DNA1` catalogue rather than from a list of Blender releases. It reads meshes in all three layouts Blender has stored them in (the legacy structs, 3.5's named attributes and 5.0's attribute storage), their normals by Blender's own rule — sharp edges and faces, auto smooth, custom split normals — with UVs, colour attributes and shape keys; Principled materials wired the way the glTF importer wires them, with their packed pictures; point, spot and sun lights, blackbody colour included; cameras; parents, collection instances and render visibility; and keyed object animation, layered actions and NLA strips included. It builds the same glTF the rest of the pipeline reads, so a `.blend` and a `.glb` reach the baker as the same thing, and the fixtures in `scripts/fixtures/blend/` hold it to what Blender's own exporter writes for the same file. **What only Blender can evaluate is refused by name** — a rig, a constraint, a modifier past the smoothing ones — as `BlendNeedsBlender`, never as half a scene; the baker then drives the user's own Blender through its bundled glTF exporter, `--via-blender` asks for that outright and `--direct` refuses it, and every import says which route it took."
+      },
+      {
+        "kind": "added",
+        "short": "materialChangesPerFrame: a scene that changes material more than 1,024 times a frame on WebGPU can now ask for a larger ring instead of losing the draws past it.",
+        "text": "**How many material changes a WebGPU frame holds is a quality option, `materialChangesPerFrame`.** A frame spends a slot of a uniform ring each time it changes material and skips every draw past the last slot, which is geometry missing rather than geometry drawn wrong — and 1,024 was a constant. A bought city of eleven hundred materials spends about nine hundred on a street, and a planar mirror of that street spends as many again, so its reflection came and went as the camera turned. The default stays 1,024; a scene that measures past it asks for more at construction and pays seven to thirteen kilobytes a slot, and `frameBudget`'s materials line reports the ceiling it got. WebGL2 keeps no ring and reads the option without effect."
+      },
+      {
+        "kind": "fixed",
+        "short": "The PNG reader in core's scripts reads palettes, one- to four-bit greys, sixteen-bit images and tRNS transparency, so a bake no longer drops those pictures and draws their surfaces white.",
+        "text": "**`@driftengine/core/scripts/png.mjs` reads every non-interlaced PNG.** It refused palettes (colour type 3), greys below eight bits and sixteen-bit images, and the baker and the native host read model pictures through it: measured on one bought city, 219 of its 2,447 pictures, every material wearing one baked with no colour map and drew white. Rows are now un-filtered as packed bytes and then widened to eight-bit samples — a palette to RGB, or RGBA where it carries `tRNS`; a grey or RGB `tRNS` key to an alpha of nought at that value; sixteen bits to the high byte; a grey below eight bits scaled to the full byte. An eight-bit image with no key still takes the path that copies nothing, so a screenshot decodes as it did. Interlacing is still refused by name."
+      },
+      {
+        "kind": "fixed",
+        "short": "A glTF material with no metallic texture and no metallicFactor is a full metal, as the specification says, and now reflects like one instead of reading as matte.",
+        "text": "**An untextured glTF metal that states no `metallicFactor` mirrors.** The specification's default for the factor is 1, and the reader took the material's reflectivity from the factor alone with a default of 0, so every such material — an exporter writes none when the value is the default — drew as a matte surface. The reflectivity of a material with no base colour texture now follows its metallic value, defaulted as the specification defaults it; a textured or vertex-coloured one is unchanged."
+      }
+    ]
+  },
  {
   "version": "4.6.1",
   "date": "2026-10-01",
@@ -2881,7 +2938,7 @@
    },
    {
     "kind": "added",
-    "text": "`KickDetector.level` is a low-end level a visual can actually follow. `energy`, the only one there was, is the raw sum of the two lowest bands with a gain on it: honest about what it says and useless on anything mastered loud, because it reaches its ceiling and stays there, so a consumer driving a light or a particle field from it draws a constant. Measured on a phonk track through this detector, it read 1.000 in every frame sampled. The detector already computed the quantity that does move with the kick and threw it away after gating on it, which is the whitened signal: what is left once the bassline, the mud and the low mids are masked out. That is now readable, unscaled, because how far a consumer opens it up is a decision about its own picture rather than about the music. `energy` keeps its meaning and its arithmetic, and a production consumer reads only `pulse`, so nothing existing moves",
+    "text": "`KickDetector.level` is a low-end level a visual can actually follow. `energy`, the only one there was, is the raw sum of the two lowest bands with a gain on it: honest about what it says and useless on anything mastered loud, because it reaches its ceiling and stays there, so a consumer driving a light or a particle field from it draws a constant. Measured on a bass-heavy track through this detector, it read 1.000 in every frame sampled. The detector already computed the quantity that does move with the kick and threw it away after gating on it, which is the whitened signal: what is left once the bassline, the mud and the low mids are masked out. That is now readable, unscaled, because how far a consumer opens it up is a decision about its own picture rather than about the music. `energy` keeps its meaning and its arithmetic, and a production consumer reads only `pulse`, so nothing existing moves",
     "short": "`KickDetector.level` exposes the whitened low end, which keeps its dynamics where `energy` saturates on a loud master."
    },
    {

package/README.md

@@ -1,9 +1,170 @@
 # @driftengine/core
 
-The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
+The runtime of DriftEngine, a WebGPU game engine for the web and for native apps. It draws through
+WebGPU where the browser has a device and through WebGL2 everywhere else, behind one API, and it
+carries the loop, the renderer, cameras, input, the scene graph, geometry, text
+and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
+which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
-3% — the number is a fact about the build rather than a claim in a document.
+**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+which fails the build if the figure drifts by more than 3%.
 
-Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)
-for how the packages divide, and why some features are compiled into core on demand instead.
+The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running
+beside every chapter, and the reference for every export at
+[driftengine.dev/docs/api](https://driftengine.dev/docs/api).
+
+## Install
+
+```sh
+npm install @driftengine/core
+```
+
+It needs a browser with WebGL2, which is every current one, and an ES module bundler such as Vite.
+[Installation](https://driftengine.dev/docs/start/installation) covers the page, TypeScript and the
+backends.
+
+## Quickstart
+
+A lit cube turning on a fixed step, on a page with `<canvas id="stage">`:
+
+```ts
+import {
+  Camera,
+  MeshBuilder,
+  SceneNode,
+  createEnvironment,
+  createRenderer,
+  startLoop,
+} from '@driftengine/core';
+
+const canvas = document.querySelector<HTMLCanvasElement>('#stage');
+if (canvas === null) throw new Error('the page must carry <canvas id="stage">');
+
+/*
+ * Asynchronous because it has to be: asking for a WebGPU adapter returns a promise, and there
+ * is no synchronous way to learn whether a usable device exists. The fall back to WebGL2 is
+ * automatic and silent, so `reason` is the only thing that says why. Print it: the first
+ * question asked about any picture is what drew it.
+ */
+const { renderer, backend, reason } = await createRenderer(canvas, {
+  maxDevicePixelRatio: 1.75,
+});
+
+const readout = document.querySelector('#backend');
+if (readout !== null) readout.textContent = `${backend}: ${reason}`;
+
+renderer.resize();
+addEventListener('resize', () => renderer.resize());
+
+/** Light, air and ground bounce. Chosen once, because these are allocation-sized decisions. */
+const ENV = createEnvironment({
+  directionalDir: [0.4, 0.7, 0.35],
+  directionalColor: [1, 0.96, 0.88],
+  ambient: [0.2, 0.22, 0.28],
+  ambientGround: [0.08, 0.08, 0.1],
+  emissiveGain: 0,
+  nightFactor: 0,
+  fogColor: [0.16, 0.18, 0.24],
+  fogDensity: 0.004,
+  fogHeightFalloff: 0.03,
+  fogBaseY: 0,
+});
+
+/*
+ * Colour is vertex data here, which is what lets a whole world be flat-shaded draw calls.
+ * `addBox` takes a centre and *half* extents, so this ground is 24 units across and the cube
+ * is two units on a side.
+ */
+const shapes = new MeshBuilder();
+shapes.addBox([0, 1, 0], [1, 1, 1], [0.85, 0.45, 0.25]);
+const cube = renderer.createMesh(shapes.build());
+
+const slab = new MeshBuilder();
+slab.addBox([0, -0.25, 0], [12, 0.25, 12], [0.3, 0.32, 0.36]);
+const ground = renderer.createMesh(slab.build());
+
+const spinner = new SceneNode();
+spinner.setPosition(0, 1, 0);
+const stillness = new SceneNode();
+stillness.updateWorld();
+
+const camera = new Camera();
+camera.position[0] = 6;
+camera.position[1] = 4.5;
+camera.position[2] = 8;
+camera.lookAt(0, 1, 0);
+
+/*
+ * Two angles, because that is what `alpha` is for. The simulation advances in fixed steps and
+ * the display does not, so a frame almost never lands on a step boundary: drawing `spin`
+ * directly judders at any refresh rate that is not a multiple of the step. Interpolating
+ * between the last two states is the whole reason the loop hands `alpha` over.
+ */
+let spin = 0;
+let previousSpin = 0;
+
+startLoop({
+  simulate(dt) {
+    previousSpin = spin;
+    spin += dt * 0.8;
+  },
+  render(alpha) {
+    spinner.setRotationAxisAngle(0, 1, 0, previousSpin + (spin - previousSpin) * alpha);
+    spinner.updateWorld();
+
+    camera.updateMatrices(canvas.height > 0 ? canvas.width / canvas.height : 1);
+
+    renderer.beginFrame([0.05, 0.06, 0.09]);
+    renderer.bindMeshPass(camera, ENV);
+    renderer.drawMesh(ground, stillness.worldMatrix);
+    renderer.drawMesh(cube, spinner.worldMatrix);
+    renderer.endFrame();
+  },
+});
+```
+
+This is the engine's `examples/starter`, and a test keeps the two the same.
+[Hello world](https://driftengine.dev/docs/start/hello-world) walks through it, and
+[Your first game](https://driftengine.dev/docs/start/first-game) builds a complete one.
+
+## What is in it
+
+|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The frame      | A fixed-step [loop](https://driftengine.dev/docs/start/the-loop) with interpolation, [two backends](https://driftengine.dev/docs/concepts/backends) behind one API, [quality profiles](https://driftengine.dev/docs/concepts/quality), and a [frame](https://driftengine.dev/docs/concepts/the-frame) whose order you can read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Drawing        | [Meshes](https://driftengine.dev/docs/rendering/meshes), [materials](https://driftengine.dev/docs/rendering/materials), [instancing](https://driftengine.dev/docs/rendering/instancing), [lights](https://driftengine.dev/docs/rendering/lights) and [shadows](https://driftengine.dev/docs/rendering/shadows), [the sky](https://driftengine.dev/docs/rendering/sky-and-atmosphere), [fog and weather](https://driftengine.dev/docs/rendering/fog-and-weather), [water](https://driftengine.dev/docs/rendering/water), [reflections](https://driftengine.dev/docs/rendering/reflections), [post-processing](https://driftengine.dev/docs/rendering/post-processing), [particles](https://driftengine.dev/docs/rendering/particles), [text](https://driftengine.dev/docs/rendering/text-and-overlays) and [passes of your own](https://driftengine.dev/docs/rendering/custom-passes). |
+| Light at scale | [DriftLight](https://driftengine.dev/docs/rendering/driftlight) for hundreds of fixed lights, [DriftRay](https://driftengine.dev/docs/rendering/driftray) for bounced light traced every frame, [DriftTR](https://driftengine.dev/docs/rendering/drifttr) for temporal reconstruction, and the [GPU-driven pipeline](https://driftengine.dev/docs/rendering/gpu-driven).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Worlds         | [Worlds bigger than a float](https://driftengine.dev/docs/worlds/large-worlds), streamed in cells, with [hierarchical detail](https://driftengine.dev/docs/worlds/hierarchical-detail) and [worlds built from a kit](https://driftengine.dev/docs/worlds/worlds-from-a-kit).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Physics        | Deterministic [rigid bodies](https://driftengine.dev/docs/simulation/rigid-bodies), [joints](https://driftengine.dev/docs/simulation/joints), [queries](https://driftengine.dev/docs/simulation/queries), [characters](https://driftengine.dev/docs/simulation/characters), [vehicles](https://driftengine.dev/docs/simulation/vehicles), and [ragdolls and cloth](https://driftengine.dev/docs/simulation/ragdolls-and-cloth).                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Play           | [Input](https://driftengine.dev/docs/interface/input) from every device through one action map, [cameras that cut](https://driftengine.dev/docs/interface/cameras), [picking](https://driftengine.dev/docs/rendering/picking) and the [scene graph](https://driftengine.dev/docs/concepts/scene-graph).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+## The other packages
+
+Each is added when a game reaches for it, and a game that never imports one carries none of it.
+
+| Package                                               | What it adds                                                                                                           |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `@driftengine/animation`                              | Skeletons, clips, blend trees and IK. [Guide](https://driftengine.dev/docs/simulation/animation)                       |
+| `@driftengine/nav`                                    | Navigation meshes and routes. [Guide](https://driftengine.dev/docs/simulation/navigation)                              |
+| `@driftengine/entities`                               | An entity component system with prefabs and rewind. [Guide](https://driftengine.dev/docs/simulation/entities)          |
+| `@driftengine/chemistry`                              | Heat, burning, phase changes and smoke. [Guide](https://driftengine.dev/docs/simulation/chemistry)                     |
+| `@driftengine/ai`                                     | Behaviour trees and agents. [Guide](https://driftengine.dev/docs/simulation/agents)                                    |
+| `@driftengine/audio`                                  | A mix of buses, placed sounds, rooms and rhythm. [Guide](https://driftengine.dev/docs/content/audio)                   |
+| `@driftengine/assets` and `@driftengine/drft`         | Model importers and the streaming `.drft` container. [Guide](https://driftengine.dev/docs/content/importing-models)    |
+| `@driftengine/terrain`                                | Terrain drawn as a clipmap. [Guide](https://driftengine.dev/docs/worlds/terrain)                                       |
+| `@driftengine/splats`                                 | Gaussian splat captures among meshes. [Guide](https://driftengine.dev/docs/worlds/splats)                              |
+| `@driftengine/texture`                                | Materials as programs decoded on the device. [Guide](https://driftengine.dev/docs/worlds/drifttexture)                 |
+| `@driftengine/capture`                                | A video clip turned into a surface, a collider and entities. [Guide](https://driftengine.dev/docs/worlds/driftcapture) |
+| `@driftengine/ui2d`                                   | Sprites, tilemaps and interfaces. [Guide](https://driftengine.dev/docs/interface/sprites)                              |
+| `@driftengine/script`                                 | DriftScript, the engine's scripting language, with hot reload. [Reference](https://driftengine.dev/docs/api/script)    |
+| `@driftengine/network`                                | Rollback netcode. [Reference](https://driftengine.dev/docs/api/network)                                                |
+| `@driftengine/xr`                                     | WebXR sessions. [Reference](https://driftengine.dev/docs/api/xr)                                                       |
+| `@driftengine/media`                                  | Recording and exporting clips. [Reference](https://driftengine.dev/docs/api/media)                                     |
+| `@driftengine/editor` and `@driftengine/tools`        | The editor and in-game tools. [Reference](https://driftengine.dev/docs/api/editor)                                     |
+| `@driftengine/package` and `@driftengine/native-host` | Installable apps built from the same game. [Reference](https://driftengine.dev/docs/api/package)                       |
+
+## Licence
+
+Apache-2.0. Part of [DriftEngine](https://github.com/drftrun/driftengine); see
+[`docs/ARCHITECTURE.md`](https://github.com/drftrun/driftengine/blob/main/docs/ARCHITECTURE.md) for
+how the packages divide.

package/dist/render/backend/budget.d.ts

@@ -47,6 +47,12 @@ export interface BudgetCounter extends BudgetLine {
     ask(): void;
     /** One of them was refused, and the frame is marked. */
     drop(): void;
+    /**
+     * The ceiling, where it is a construction-time option and not known when the line is declared.
+     * Called at construction, once; a line keeps the place it was declared in, which is the order a
+     * report reads in.
+     */
+    limit(ceiling: number): void;
 }
 /**
  * Every ceiling a backend imposes, counted for the frame just drawn.

package/dist/render/backend/budget.js

@@ -30,6 +30,9 @@ class Line {
         this.ceiling = ceiling;
         this.budget = budget;
     }
+    limit(ceiling) {
+        this.ceiling = ceiling;
+    }
     /** One more of this thing was asked for, whether or not it will fit. */
     ask() {
         this.used += 1;

package/dist/render/backend/webgl2/renderer.d.ts

@@ -2316,17 +2316,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * `endPlanarReflection`; the next water draw samples the completed target.
      */
     /**
-     * **This is a water feature, not a renderer one, and the name hides that.**
+     * **Two things sample the target: water, and a wet film.** It is allocated when `water` and
+     * `waterReflections` are both on, or when `RenderQuality.planarReflections` asks for it in a
+     * scene with no water, and `drawFilm` reads it through `FilmOptions.reflectionStrength` for a
+     * film on the plane it was rendered for. This said the pass was water-only after both of those
+     * had landed, which is how a stale limitation outlives its cause: it read as a decision.
      *
-     * The target is allocated only when `water` *and* `waterReflections` are both on, and the
-     * only thing that samples it is `WaterRenderer`. So a scenario whose ground is a mesh slab
-     * with `drawFilm` patches over it, which is what a wet street is, cannot mirror the scene
-     * into it however it calls this. Reported from outside after being attempted, which is the
-     * cost of a name that promises more than the wiring does.
-     *
-     * What is available to a surface that is not water: `bakeReflectionProbe`, which is a room
-     * rather than a mirror, and `drawFilm`'s sheen, which is iridescence rather than reflection.
-     * Neither is a substitute for a mirrored pass and this comment is not pretending otherwise.
+     * A surface on any other plane, or that is not a film, reflects a probe
+     * (`bakeReflectionProbe`), which is a room rather than a mirror.
      */
     beginPlanarReflection(source: Camera, planeY: number, clearColor: Vec3): Camera | null;
     endPlanarReflection(): void;
@@ -3431,9 +3428,9 @@ export declare class WebGL2Renderer implements RendererApi {
      * tarmac at night by bisection twice, at 0.7 and again at 0.24, and landed on **0.15 to
      * 0.18**. Start there rather than repeating the search.
      *
-     * There is no mirror term here to raise instead. A surface that should reflect the scene
-     * rather than shimmer needs a planar pass, and `beginPlanarReflection` is water-only; see the
-     * comment on it. Splitting the two is an open request from outside and is not built.
+     * The mirror is a separate dial: `FilmOptions.reflectionStrength` shows the planar reflection
+     * a frame rendered for the film's plane, weighted by the viewing angle. See
+     * `beginPlanarReflection` for when that target exists.
      */
     drawFilm(mesh: Mesh, camera: Camera, timeSeconds: number, env: Environment, sheen: number, options?: FilmOptions): void;
     /**

package/dist/render/backend/webgl2/renderer.js

@@ -1348,14 +1348,20 @@ export class WebGL2Renderer {
      */
     registerPass(definition) {
         const handle = registerIn(this.passes, definition);
-        /* Identity: this backend's clip space is the one the projections are built for. */
-        /* Both are identity here: this backend runs the GLSL natively, so there is nothing to
-           correct and nothing a generator has flipped. */
+        /*
+         * Both the same here: this backend runs the GLSL natively, so no generator has flipped
+         * anything. **What they carry is the depth remap whenever this context draws reversed**, and
+         * they were the identity until a splat capture was drawn among meshes on this backend: the
+         * renderer's own draws go through `GL_DEPTH_REMAP` (`sceneMatrix`), a pass's projection did
+         * not, so a pass wrote conventional depth into a reversed buffer and a splat behind a post was
+         * drawn over it. Identity where clip control is missing and depth stays conventional.
+         */
+        const correction = this.reversedDepth ? GL_DEPTH_REMAP : IDENTITY_CLIP;
         this.passDevice ??= {
             backend: 'webgl2',
             gl: this.gl,
-            clipCorrection: IDENTITY_CLIP,
-            depthCorrection: IDENTITY_CLIP,
+            clipCorrection: correction,
+            depthCorrection: correction,
         };
         if (definition.prepare !== undefined)
             this.preparingPasses++;
@@ -3588,17 +3594,14 @@ export class WebGL2Renderer {
      * `endPlanarReflection`; the next water draw samples the completed target.
      */
     /**
-     * **This is a water feature, not a renderer one, and the name hides that.**
-     *
-     * The target is allocated only when `water` *and* `waterReflections` are both on, and the
-     * only thing that samples it is `WaterRenderer`. So a scenario whose ground is a mesh slab
-     * with `drawFilm` patches over it, which is what a wet street is, cannot mirror the scene
-     * into it however it calls this. Reported from outside after being attempted, which is the
-     * cost of a name that promises more than the wiring does.
+     * **Two things sample the target: water, and a wet film.** It is allocated when `water` and
+     * `waterReflections` are both on, or when `RenderQuality.planarReflections` asks for it in a
+     * scene with no water, and `drawFilm` reads it through `FilmOptions.reflectionStrength` for a
+     * film on the plane it was rendered for. This said the pass was water-only after both of those
+     * had landed, which is how a stale limitation outlives its cause: it read as a decision.
      *
-     * What is available to a surface that is not water: `bakeReflectionProbe`, which is a room
-     * rather than a mirror, and `drawFilm`'s sheen, which is iridescence rather than reflection.
-     * Neither is a substitute for a mirrored pass and this comment is not pretending otherwise.
+     * A surface on any other plane, or that is not a film, reflects a probe
+     * (`bakeReflectionProbe`), which is a room rather than a mirror.
      */
     /* Like `bakeReflectionProbe`, this re-enters the **mesh pass only**: anything a scene draws
        after the world, particles, light volumes, the sky, is missing from the mirror unless it is
@@ -6922,9 +6925,9 @@ export class WebGL2Renderer {
      * tarmac at night by bisection twice, at 0.7 and again at 0.24, and landed on **0.15 to
      * 0.18**. Start there rather than repeating the search.
      *
-     * There is no mirror term here to raise instead. A surface that should reflect the scene
-     * rather than shimmer needs a planar pass, and `beginPlanarReflection` is water-only; see the
-     * comment on it. Splitting the two is an open request from outside and is not built.
+     * The mirror is a separate dial: `FilmOptions.reflectionStrength` shows the planar reflection
+     * a frame rendered for the film's plane, weighted by the viewing angle. See
+     * `beginPlanarReflection` for when that target exists.
      */
     drawFilm(mesh, camera, timeSeconds, env, sheen, options = {}) {
         const { gl } = this;

package/dist/render/backend/webgpu/renderer.d.ts

@@ -242,6 +242,35 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private readonly budget;
     private readonly drawBudget;
+    /**
+     * Distinct materials a frame may set: `materialChangesPerFrame`, 1,024 unless a consumer asks.
+     *
+     * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
+     * material rather than how much it draws.
+     *
+     * **A thousand and twenty-four by default, and it is the expensive one of the two.** A slot is the fragment
+     * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
+     * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
+     * Raising it from 256 costs 5.25 to 9.75 MB.
+     *
+     * It is worth paying for how it *fails* rather than how it performs. Past the ring
+     * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
+     * a stretch of the world simply not drawn, which has been reported from a consumer as
+     * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
+     * ceiling is a budget that ships this the first time somebody adds a model.
+     *
+     * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
+     * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
+     * halves in one diff. It is recorded because the wrong failure was the stated argument for
+     * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
+     * looking in completely different places — one at materials, the other at culling, which is
+     * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
+     * consumer reads a number instead of a sentence.
+     *
+     * **What would make it wrong** is a scene switching material every draw: a thousand material
+     * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
+     * ring size answers — many copies of one mesh want one material and one instanced draw.
+     */
     private readonly materialBudget;
     /**
      * Native bind groups built this frame, which is the one cost a consumer could not see.
@@ -2277,7 +2306,7 @@ export declare class WebGPURenderer implements RendererApi {
      * *unchanged*, so a run of entries sharing one material has no shorter spelling and the sink
      * bound once per entry. On this backend that is a cliff rather than a slope: `setMaterial`
      * dirties `materialSlot`, so a bind per entry is a **slot per draw** out of
-     * `MAX_MATERIALS_PER_FRAME` — and past the ring `materialSlotForDraw` returns null and the draw
+     * `materialChangesPerFrame` — and past the ring `materialSlotForDraw` returns null and the draw
      * is skipped, which is the world that appears and disappears that constant's own comment
      * describes. A consumer measured 82 materials a model over two to four draws each, and a
      * reflection replaying the frame shares the ring with the pass that recorded it.

package/dist/render/backend/webgpu/renderer.js

@@ -139,7 +139,9 @@ import { LightField } from '../../driftLight/lightField.js';
 import { WorldLightField } from '../../driftLight/worldLightField.js';
 import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.js';
 /**
- * How many draws one frame may make before the ring is full.
+ * How many draws one frame is prepared for before anything grows: `drawsPerFrame`'s default, and
+ * the starting size of the arena and the command pool, which reallocate on demand. The two rings
+ * that cannot grow take `drawsPerFrame` itself.
  *
  * **Four thousand and ninety-six, and the number is an allocation rather than a limit.**
  * `UniformRing.flush` uploads `used * slotSize`, so a frame that draws two hundred pays for two
@@ -194,36 +196,6 @@ const MAX_OVERLAYS = 64;
  * and passes nobody has written yet; the cost is sixteen kilobytes.
  */
 const MAX_SKY_DRAWS = 64;
-/**
- * Distinct materials a frame may set.
- *
- * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
- * material rather than how much it draws.
- *
- * **A thousand and twenty-four, and it is the expensive one of the two.** A slot is the fragment
- * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
- * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
- * Raising it from 256 costs 5.25 to 9.75 MB.
- *
- * It is worth paying for how it *fails* rather than how it performs. Past the ring
- * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
- * a stretch of the world simply not drawn, which has been reported from a consumer as
- * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
- * ceiling is a budget that ships this the first time somebody adds a model.
- *
- * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
- * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
- * halves in one diff. It is recorded because the wrong failure was the stated argument for
- * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
- * looking in completely different places — one at materials, the other at culling, which is
- * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
- * consumer reads a number instead of a sentence.
- *
- * **What would make it wrong** is a scene switching material every draw: a thousand material
- * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
- * ring size answers — many copies of one mesh want one material and one instanced draw.
- */
-const MAX_MATERIALS_PER_FRAME = 1024;
 /**
  * Whether the environment probe's permutation fits this device's per-stage binding limits.
  *
@@ -992,8 +964,37 @@ export class WebGPURenderer {
      * geometry come first.
      */
     budget = new FrameBudget();
-    drawBudget = this.budget.line('draws', MAX_DRAWS_PER_FRAME);
-    materialBudget = this.budget.line('materials', MAX_MATERIALS_PER_FRAME);
+    drawBudget = this.budget.line('draws', null);
+    /**
+     * Distinct materials a frame may set: `materialChangesPerFrame`, 1,024 unless a consumer asks.
+     *
+     * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
+     * material rather than how much it draws.
+     *
+     * **A thousand and twenty-four by default, and it is the expensive one of the two.** A slot is the fragment
+     * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
+     * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
+     * Raising it from 256 costs 5.25 to 9.75 MB.
+     *
+     * It is worth paying for how it *fails* rather than how it performs. Past the ring
+     * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
+     * a stretch of the world simply not drawn, which has been reported from a consumer as
+     * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
+     * ceiling is a budget that ships this the first time somebody adds a model.
+     *
+     * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
+     * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
+     * halves in one diff. It is recorded because the wrong failure was the stated argument for
+     * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
+     * looking in completely different places — one at materials, the other at culling, which is
+     * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
+     * consumer reads a number instead of a sentence.
+     *
+     * **What would make it wrong** is a scene switching material every draw: a thousand material
+     * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
+     * ring size answers — many copies of one mesh want one material and one instanced draw.
+     */
+    materialBudget = this.budget.line('materials', null);
     /**
      * Native bind groups built this frame, which is the one cost a consumer could not see.
      *
@@ -1004,7 +1005,7 @@ export class WebGPURenderer {
      * in draw order, precisely because the frame reported draws and material changes and never this.
      */
     bindGroupBudget = this.budget.line('bind groups', null);
-    shadowDrawBudget = this.budget.line('shadow draws', MAX_DRAWS_PER_FRAME);
+    shadowDrawBudget = this.budget.line('shadow draws', null);
     scatterDepthBudget = this.budget.line('scatter shadow draws', MAX_SCATTER_DEPTH_DRAWS);
     waterBudget = this.budget.line('water bodies', MAX_WATER_BODIES_PER_FRAME);
     lightVolumeBudget = this.budget.line('light volumes', MAX_LIGHT_VOLUMES_PER_FRAME);
@@ -4782,6 +4783,9 @@ export class WebGPURenderer {
             }
             : quality;
         quality = this.quality;
+        this.materialBudget.limit(quality.materialChangesPerFrame);
+        this.drawBudget.limit(quality.drawsPerFrame);
+        this.shadowDrawBudget.limit(quality.drawsPerFrame);
         this.maxDrawingBufferPixels = quality.maxDrawingBufferPixels;
         this.exposure = quality.outputExposure;
         this.flushSchedule =
@@ -4879,7 +4883,7 @@ export class WebGPURenderer {
         this.skinnedBindGroupLayout = createFlatBindGroupLayout(device, this.variant, true);
         this.morphedBindGroupLayout = createFlatBindGroupLayout(device, this.variant, false, true);
         this.bothBindGroupLayout = createFlatBindGroupLayout(device, this.variant, true, true);
-        this.perDraw = new UniformRing(device, FLAT_VERT_SIZE, MAX_DRAWS_PER_FRAME, USAGE_UNIFORM_DST, 'flat.vertRing', this.drawBudget);
+        this.perDraw = new UniformRing(device, FLAT_VERT_SIZE, quality.drawsPerFrame, USAGE_UNIFORM_DST, 'flat.vertRing', this.drawBudget);
         this.perFrameStaging = new ArrayBuffer(this.fragment.uniformSize);
         this.perFrameFloats = new Float32Array(this.perFrameStaging);
         this.perFrameInts = new Int32Array(this.perFrameStaging);
@@ -4896,7 +4900,7 @@ export class WebGPURenderer {
          * A slot per *material change* rather than per draw: `drawMesh` reuses the open slot until
          * something dirties it, so a scene drawing a hundred meshes of one material spends one.
          */
-        this.perFrame = new UniformRing(device, this.fragment.uniformSize, MAX_MATERIALS_PER_FRAME, USAGE_UNIFORM_DST, 'flat.fragRing', this.materialBudget);
+        this.perFrame = new UniformRing(device, this.fragment.uniformSize, this.quality.materialChangesPerFrame, USAGE_UNIFORM_DST, 'flat.fragRing', this.materialBudget);
         /*
          * A one-pixel stand-in for the albedo binding. `uAlbedoEnabled` is zero for untextured
          * geometry, which is nearly all of it, so the shader never samples this — but WebGPU
@@ -5488,7 +5492,7 @@ export class WebGPURenderer {
         this.shadowCutoutLayout = createDepthBindGroupLayout(device, false, true);
         this.shadowDraws = new UniformRing(device, 
         /* The cutout block is the plain one and two fields more, and a slot must hold either. */
-        Math.max(DEPTH_VERT_SIZE, DEPTH_CUTOUT_VERT_SIZE), MAX_DRAWS_PER_FRAME, USAGE_UNIFORM_DST, 'shadow.drawRing', this.shadowDrawBudget);
+        Math.max(DEPTH_VERT_SIZE, DEPTH_CUTOUT_VERT_SIZE), quality.drawsPerFrame, USAGE_UNIFORM_DST, 'shadow.drawRing', this.shadowDrawBudget);
         const depthPassUniforms = device.createBuffer({
             label: 'depth.passUniforms',
             size: DEPTH_FRAG_SIZE,
@@ -6639,7 +6643,7 @@ export class WebGPURenderer {
         if (slot === null) {
             if (!this.warnedMaterialsFull) {
                 this.warnedMaterialsFull = true;
-                console.warn(`WebGPU: more than ${MAX_MATERIALS_PER_FRAME} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`);
+                console.warn(`WebGPU: more than ${this.quality.materialChangesPerFrame} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`);
             }
             return null;
         }
@@ -6832,7 +6836,7 @@ export class WebGPURenderer {
         if (slot === null) {
             if (!this.warnedFull) {
                 this.warnedFull = true;
-                console.warn(`WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`);
+                console.warn(`WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`);
             }
             return;
         }
@@ -6975,7 +6979,7 @@ export class WebGPURenderer {
         /*
          * Guards the draw call only, not the restore below.
          *
-         * `materialSlotForDraw` returns null once `MAX_MATERIALS_PER_FRAME` is exhausted, and an
+         * `materialSlotForDraw` returns null once `materialChangesPerFrame` is exhausted, and an
          * early `return` here used to skip the restore too — which left `uOpacity`,
          * `uLightingEnabled` and `uFogEnabled` dirtied in `perFrameFloats`/`perFrameInts` for the
          * rest of the frame, since that scratch block is cumulative state shared by every draw
@@ -7232,7 +7236,7 @@ export class WebGPURenderer {
         if (slot === null) {
             if (!this.warnedFull) {
                 this.warnedFull = true;
-                console.warn(`WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`);
+                console.warn(`WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`);
             }
             return;
         }
@@ -7576,7 +7580,7 @@ export class WebGPURenderer {
      * *unchanged*, so a run of entries sharing one material has no shorter spelling and the sink
      * bound once per entry. On this backend that is a cliff rather than a slope: `setMaterial`
      * dirties `materialSlot`, so a bind per entry is a **slot per draw** out of
-     * `MAX_MATERIALS_PER_FRAME` — and past the ring `materialSlotForDraw` returns null and the draw
+     * `materialChangesPerFrame` — and past the ring `materialSlotForDraw` returns null and the draw
      * is skipped, which is the world that appears and disappears that constant's own comment
      * describes. A consumer measured 82 materials a model over two to four draws each, and a
      * reflection replaying the frame shares the ring with the pass that recorded it.