@driftengine/core 4.7.0 → 4.7.1

package/CHANGELOG.json

@@ -1,4 +1,35 @@
 [
+  {
+    "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",
@@ -2907,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/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/pass.d.ts

@@ -34,7 +34,8 @@ import type { FrameResource } from './frame/index.ts';
  */
 export type PassDevice = {
     /**
-     * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. Identity on WebGL2.
+     * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. On WebGL2 it is
+     * the depth remap while that context draws reversed depth, and the identity where it cannot.
      *
      * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
      * renderer built for its own verbs. Without this it would have to copy four numbers — and a
@@ -55,7 +56,8 @@ export type PassDevice = {
      */
     readonly clipCorrection: Float32Array;
     /**
-     * Pre-multiply a projection by this **if you wrote your WGSL by hand**. Identity on WebGL2.
+     * Pre-multiply a projection by this **if you wrote your WGSL by hand**. On WebGL2 it is the same
+     * matrix as `clipCorrection`.
      *
      * The same matrix without the Y negation, because there is no generated negation to cancel.
      * Taking `clipCorrection` in a hand-written shader mirrors the picture vertically — and mirrors

package/dist/render/renderQuality.d.ts

@@ -595,10 +595,10 @@ export interface RenderQuality {
      * the output size with no upscaling, which is a temporal antialiaser with a better neighbourhood
      * rule than `temporalAa`'s. A sentinel that collided with it would make that unaskable.
      *
-     * The range is 1.3 to 2 and a value inside it is clamped to the end it is nearest. Below 1.3 the
-     * render saves less than a third of the fragment work and the resolve's own cost eats it; above 2
-     * the render is a quarter of the output and no reconstruction holds an edge through that. A
-     * negative number is off, not a clamp to the bottom: it cannot mean "a little".
+     * The range is 1.3 to 2 and a positive value outside it is clamped to the end it is nearest.
+     * Below 1.3 the render saves less than a third of the fragment work and the resolve's own cost
+     * eats it; above 2 the render is a quarter of the output and no reconstruction holds an edge
+     * through that. A negative number is off, not a clamp to the bottom: it cannot mean "a little".
      *
      * **What it needs from you.** A `createMover()` per moving object, passed with that object's
      * draws where `drawMesh` takes last frame's matrix — the renderer keeps last frame's model and,

package/dist/render/rendererHarness.js

@@ -123,7 +123,15 @@ export function recordingGl(options = {}) {
                and a small answer is read as a device that cannot do the thing. */
             return 4096;
         },
-        getExtension: (name) => (extensions.has(String(name)) ? {} : null),
+        getExtension: (name) => {
+            if (!extensions.has(String(name)))
+                return null;
+            /* Clip control is called as well as asked for, so its object has to carry the call. */
+            if (name === 'EXT_clip_control') {
+                return { LOWER_LEFT_EXT: 0x8ca1, ZERO_TO_ONE_EXT: 0x935f, clipControlEXT: () => undefined };
+            }
+            return {};
+        },
         getShaderParameter: () => true,
         /*
          * A shader remembers its own source, and a program remembers its fragment one, so a link can

package/dist/world/freeze.d.ts

@@ -23,7 +23,7 @@
  * What freezing needs of a world.
  *
  * Taken as a parameter rather than imported, on `AGENTS.md`'s rule: core has no entity store and a
- * consumer may be holding one of several. Six methods, all of which any store can answer.
+ * consumer may be holding one of several. Five methods, all of which any store can answer.
  */
 export interface FreezableWorld {
     /** Every entity whose home is this cell, live or not. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@driftengine/core",
-  "version": "4.7.0",
-  "description": "DriftEngine reusable browser 3D runtime",
+  "version": "4.7.1",
+  "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.7.0",
-    "@driftengine/physics": "4.7.0",
+    "@driftengine/drft": "4.7.1",
+    "@driftengine/physics": "4.7.1",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -39,7 +39,7 @@
     "url": "git+https://github.com/drftrun/driftengine.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "homepage": "https://driftengine.dev/docs",
   "bugs": "https://github.com/drftrun/driftengine/issues",
   "keywords": [
     "driftengine",
@@ -51,7 +51,11 @@
     "webgl2",
     "scene-graph",
     "game-engine",
-    "game-loop"
+    "game-loop",
+    "gamedev",
+    "webgpu-game-engine",
+    "physics",
+    "rigid-body"
   ],
   "engines": {
     "node": ">=22.12.0"
@@ -63,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.7.0",
-    "@driftengine/network": "4.7.0",
-    "@driftengine/texture": "4.7.0"
+    "@driftengine/nav": "4.7.1",
+    "@driftengine/network": "4.7.1",
+    "@driftengine/texture": "4.7.1"
   }
 }

package/src/render/backend/webgl2/renderer.ts

@@ -2093,14 +2093,20 @@ export class WebGL2Renderer implements RendererApi {
    */
   registerPass(definition: PassDefinition): PassHandle {
     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++;
     definition.init?.(this.passDevice);
@@ -4746,17 +4752,14 @@ export 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.**
-   *
-   * 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
@@ -8447,9 +8450,9 @@ export 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,

package/src/render/pass.ts

@@ -37,7 +37,8 @@ import type { FrameResource } from './frame/index.ts';
  */
 export type PassDevice = {
   /**
-   * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. Identity on WebGL2.
+   * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. On WebGL2 it is
+   * the depth remap while that context draws reversed depth, and the identity where it cannot.
    *
    * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
    * renderer built for its own verbs. Without this it would have to copy four numbers — and a
@@ -58,7 +59,8 @@ export type PassDevice = {
    */
   readonly clipCorrection: Float32Array;
   /**
-   * Pre-multiply a projection by this **if you wrote your WGSL by hand**. Identity on WebGL2.
+   * Pre-multiply a projection by this **if you wrote your WGSL by hand**. On WebGL2 it is the same
+   * matrix as `clipCorrection`.
    *
    * The same matrix without the Y negation, because there is no generated negation to cancel.
    * Taking `clipCorrection` in a hand-written shader mirrors the picture vertically — and mirrors

package/src/render/renderQuality.ts

@@ -604,10 +604,10 @@ export interface RenderQuality {
    * the output size with no upscaling, which is a temporal antialiaser with a better neighbourhood
    * rule than `temporalAa`'s. A sentinel that collided with it would make that unaskable.
    *
-   * The range is 1.3 to 2 and a value inside it is clamped to the end it is nearest. Below 1.3 the
-   * render saves less than a third of the fragment work and the resolve's own cost eats it; above 2
-   * the render is a quarter of the output and no reconstruction holds an edge through that. A
-   * negative number is off, not a clamp to the bottom: it cannot mean "a little".
+   * The range is 1.3 to 2 and a positive value outside it is clamped to the end it is nearest.
+   * Below 1.3 the render saves less than a third of the fragment work and the resolve's own cost
+   * eats it; above 2 the render is a quarter of the output and no reconstruction holds an edge
+   * through that. A negative number is off, not a clamp to the bottom: it cannot mean "a little".
    *
    * **What it needs from you.** A `createMover()` per moving object, passed with that object's
    * draws where `drawMesh` takes last frame's matrix — the renderer keeps last frame's model and,

package/src/render/rendererHarness.ts

@@ -160,7 +160,14 @@ export function recordingGl(
          and a small answer is read as a device that cannot do the thing. */
       return 4096;
     },
-    getExtension: (name: unknown) => (extensions.has(String(name)) ? {} : null),
+    getExtension: (name: unknown) => {
+      if (!extensions.has(String(name))) return null;
+      /* Clip control is called as well as asked for, so its object has to carry the call. */
+      if (name === 'EXT_clip_control') {
+        return { LOWER_LEFT_EXT: 0x8ca1, ZERO_TO_ONE_EXT: 0x935f, clipControlEXT: () => undefined };
+      }
+      return {};
+    },
     getShaderParameter: () => true,
     /*
      * A shader remembers its own source, and a program remembers its fragment one, so a link can

package/src/world/freeze.ts

@@ -24,7 +24,7 @@
  * What freezing needs of a world.
  *
  * Taken as a parameter rather than imported, on `AGENTS.md`'s rule: core has no entity store and a
- * consumer may be holding one of several. Six methods, all of which any store can answer.
+ * consumer may be holding one of several. Five methods, all of which any store can answer.
  */
 export interface FreezableWorld {
   /** Every entity whose home is this cell, live or not. */