@driftengine/core 3.61.0

package/dist/render/shaders/conditionals.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `#if NAME` / `#else` / `#endif` resolved here rather than left to GLSL.
+ *
+ * The driver's own preprocessor would reach the same compiled program, so this is not
+ * about the result — it is about what the driver is handed at all. A `#define` still ships
+ * every declaration in the source text and asks the compiler to discard them, which leaves
+ * the thing being avoided inside the component being blamed. Cutting the lines out in
+ * JavaScript means a shadowless profile never sends a sampler anywhere, and it turns the
+ * absence into something a test can assert on a string rather than something only a GPU
+ * could confirm.
+ *
+ * Deliberately not a preprocessor: one directive, names only, no expressions. Anything
+ * more belongs in GLSL, which already has one.
+ *
+ * It lived inside `flat.ts` until a second program needed permuting. Nothing about it was
+ * ever specific to that shader, and the reason it moved is the reason it is worth stating:
+ * the cost that justified it, a shadowless profile still compiling every sampler it could
+ * never reach, is paid by whichever program declares them, not by the one that happens to
+ * have found it first.
+ */
+export declare function resolveConditionals(source: string, defines: Readonly<Record<string, boolean>>, shaderName: string): string;

package/dist/render/shaders/conditionals.js

@@ -0,0 +1,55 @@
+/**
+ * `#if NAME` / `#else` / `#endif` resolved here rather than left to GLSL.
+ *
+ * The driver's own preprocessor would reach the same compiled program, so this is not
+ * about the result — it is about what the driver is handed at all. A `#define` still ships
+ * every declaration in the source text and asks the compiler to discard them, which leaves
+ * the thing being avoided inside the component being blamed. Cutting the lines out in
+ * JavaScript means a shadowless profile never sends a sampler anywhere, and it turns the
+ * absence into something a test can assert on a string rather than something only a GPU
+ * could confirm.
+ *
+ * Deliberately not a preprocessor: one directive, names only, no expressions. Anything
+ * more belongs in GLSL, which already has one.
+ *
+ * It lived inside `flat.ts` until a second program needed permuting. Nothing about it was
+ * ever specific to that shader, and the reason it moved is the reason it is worth stating:
+ * the cost that justified it, a shadowless profile still compiling every sampler it could
+ * never reach, is paid by whichever program declares them, not by the one that happens to
+ * have found it first.
+ */
+export function resolveConditionals(source, defines, shaderName) {
+    const kept = [];
+    /** One frame per open `#if`, holding whether its own branch is the live one. */
+    const stack = [];
+    const keeping = () => stack.every((frame) => frame.keep);
+    for (const line of source.split('\n')) {
+        const directive = line.trim();
+        if (directive.startsWith('#if ')) {
+            const name = directive.slice(4).trim();
+            if (!(name in defines)) {
+                throw new Error(`${shaderName} shader: unknown condition ${name}`);
+            }
+            stack.push({ keep: defines[name] === true });
+            continue;
+        }
+        if (directive === '#else') {
+            const frame = stack[stack.length - 1];
+            if (frame === undefined)
+                throw new Error(`${shaderName} shader: #else outside #if`);
+            frame.keep = !frame.keep;
+            continue;
+        }
+        if (directive === '#endif') {
+            if (stack.pop() === undefined) {
+                throw new Error(`${shaderName} shader: #endif outside #if`);
+            }
+            continue;
+        }
+        if (keeping())
+            kept.push(line);
+    }
+    if (stack.length > 0)
+        throw new Error(`${shaderName} shader: unterminated #if`);
+    return kept.join('\n');
+}

package/dist/render/shaders/decalProject.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A decal projected onto whatever the depth buffer holds.
+ *
+ * **The pass is the inverse of the camera and nothing else.** Each pixel inside the projector's
+ * scissor rectangle is turned back into the world point its depth stands for, that point is put
+ * into the box's own space, and a mark lands where all three coordinates come back within one. No
+ * geometry is clipped and no mesh is built, so the receiving surface may deform, stream in, or be
+ * drawn by something with no CPU-side geometry at all — which is exactly what `projectDecal`
+ * cannot do and the whole reason this exists beside it.
+ *
+ * **It multiplies rather than covers, and that is a design decision rather than a shortcut.** A
+ * forward renderer has no G-buffer, so by the time this runs the receiving pixel is already lit
+ * and there is nowhere to write an albedo. Painting a flat colour over it would light the mark by
+ * nothing at all: a scorch mark in an unlit corner would glow. Multiplying takes the receiver's
+ * lighting exactly — for a diffuse surface it is identical to having marked the albedo before the
+ * light was applied — at the cost that a mark can darken and tint and can never brighten. Scorch,
+ * oil, blood, wet patches and blob shadows are what that covers; a glowing rune is not.
+ *
+ * **Nothing here branches and nothing discards.** White is the identity of a multiply, so a pixel
+ * the projector misses writes white and changes nothing, which means the whole shader is one
+ * straight line. That is not tidiness: the surface normal comes from the derivatives of the
+ * reconstructed position, and a derivative taken inside non-uniform control flow is undefined —
+ * the rule `AGENTS.md` states for `texture()` in a branch, arriving through the other door.
+ */
+export declare const DECAL_PROJECT_FRAG: string;

package/dist/render/shaders/decalProject.js

@@ -0,0 +1,125 @@
+/**
+ * A decal projected onto whatever the depth buffer holds.
+ *
+ * **The pass is the inverse of the camera and nothing else.** Each pixel inside the projector's
+ * scissor rectangle is turned back into the world point its depth stands for, that point is put
+ * into the box's own space, and a mark lands where all three coordinates come back within one. No
+ * geometry is clipped and no mesh is built, so the receiving surface may deform, stream in, or be
+ * drawn by something with no CPU-side geometry at all — which is exactly what `projectDecal`
+ * cannot do and the whole reason this exists beside it.
+ *
+ * **It multiplies rather than covers, and that is a design decision rather than a shortcut.** A
+ * forward renderer has no G-buffer, so by the time this runs the receiving pixel is already lit
+ * and there is nowhere to write an albedo. Painting a flat colour over it would light the mark by
+ * nothing at all: a scorch mark in an unlit corner would glow. Multiplying takes the receiver's
+ * lighting exactly — for a diffuse surface it is identical to having marked the albedo before the
+ * light was applied — at the cost that a mark can darken and tint and can never brighten. Scorch,
+ * oil, blood, wet patches and blob shadows are what that covers; a glowing rune is not.
+ *
+ * **Nothing here branches and nothing discards.** White is the identity of a multiply, so a pixel
+ * the projector misses writes white and changes nothing, which means the whole shader is one
+ * straight line. That is not tidiness: the surface normal comes from the derivatives of the
+ * reconstructed position, and a derivative taken inside non-uniform control flow is undefined —
+ * the rule `AGENTS.md` states for `texture()` in a branch, arriving through the other door.
+ */
+import { glslIsFarDepth } from '../depthConvention.js';
+export const DECAL_PROJECT_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/**
+ * The depth the frame has drawn, as a copy.
+ *
+ * **A copy and never the attachment.** Sampling a texture that is attached to the bound
+ * framebuffer is undefined in WebGL2, and undefined here means a plausible picture on this driver
+ * and a different one on the next: \`SceneTarget.snapshotDepth\` exists for exactly this, and the
+ * WebGPU backend reads its resolved depth for the same reason.
+ *
+ * \`highp\` because it is a 32-bit depth and the reconstruction below is a division by it.
+ */
+uniform highp sampler2D uDecalDepth;
+/**
+ * Screen position and stored depth back to the world, which is
+ * \`inverse(viewProjection) * DEPTH_01_TO_CLIP\`.
+ *
+ * The Y-flipped variant of that constant is what the other backend passes, and \`lightVolumeDraw.ts\`
+ * carries the derivation and what one missing negation costs.
+ */
+uniform mat4 uDecalDepthToWorld;
+/** World space into the projector's unit box. See \`worldToDecalMatrix\`. */
+uniform mat4 uWorldToDecal;
+/** Where the eye is, which is what gives the reconstructed normal a defined sign. */
+uniform vec3 uDecalEye;
+/** The projection axis, normalised. A surface is marked when it faces back along this. */
+uniform vec3 uDecalAxis;
+/** What the mark multiplies the surface by. */
+uniform vec3 uDecalColor;
+/** How much of that colour lands. */
+uniform float uDecalOpacity;
+/** How far a surface may be turned from facing the projector, as a cosine. */
+uniform float uDecalFacingCos;
+/** How much of the mark's radius is edge. */
+uniform float uDecalSoftness;
+
+out vec4 fragColor;
+
+void main() {
+  float stored = textureLod(uDecalDepth, vUv, 0.0).r;
+
+  /*
+   * The pixel's world position. \`vUv * 2 - 1\` is the screen half of it and \`stored\` the depth
+   * half, and the matrix carries the remap from the buffer's sense to the clip space the camera
+   * was built in — including, on one backend, the Y flip that the generated WGSL applies to every
+   * vertex stage.
+   */
+  vec4 world = uDecalDepthToWorld * vec4(vUv * 2.0 - 1.0, stored, 1.0);
+  vec3 point = world.xyz / world.w;
+
+  /*
+   * **The surface normal from the reconstruction's own derivatives**, because there is no normal
+   * buffer to read one from and adding one means a second colour attachment on every draw path in
+   * the engine. Two neighbouring pixels of the same surface span it, so their cross product is its
+   * plane — noisy along a silhouette, where one of the two neighbours is a different surface
+   * altogether, and exact everywhere else.
+   *
+   * **Turned to face the eye rather than trusted.** Which way \`cross\` points depends on which way
+   * the framebuffer's rows run, and the two backends disagree about that — so a sign taken from
+   * the cross product alone marks the tops of things on one and the undersides on the other, with
+   * nothing raising. A visible surface faces the eye by definition, so that is what fixes it.
+   */
+  vec3 plane = cross(dFdx(point), dFdy(point));
+  float span = length(plane);
+  vec3 normal = span > 0.0 ? plane / span : uDecalAxis;
+  normal *= sign(dot(uDecalEye - point, normal));
+
+  vec3 box = (uWorldToDecal * vec4(point, 1.0)).xyz;
+
+  /* Inside the box on every axis, as a product of three steps rather than three branches. */
+  vec3 inside = step(abs(box), vec3(1.0));
+  float mark = inside.x * inside.y * inside.z;
+
+  /*
+   * An ellipse across the face with a soft edge, rather than the box's own rectangle. A mark with
+   * no texture has nothing else to shape it, and a hard rectangle reads as a decal cut out with
+   * scissors.
+   */
+  float radius = length(box.xy);
+  mark *= 1.0 - smoothstep(1.0 - uDecalSoftness, 1.0, radius);
+
+  /*
+   * Faded rather than cut where the surface turns away from the projector. A wall standing edge-on
+   * to the projector occupies one pixel of depth per metre of wall, so an unfaded mark aimed at
+   * the floor smears the whole depth of the box up it — the classic failure of a projected decal,
+   * and what \`facingCos\` is for on the static half of this too.
+   */
+  float facing = dot(normal, -uDecalAxis);
+  mark *= smoothstep(uDecalFacingCos, min(1.0, uDecalFacingCos + 0.25), facing);
+
+  /* Nothing was drawn here at all, so there is no surface to mark — only the sky. */
+  mark *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
+
+  /* White is the identity of a multiply, so a pixel the projector missed changes nothing. */
+  fragColor = vec4(mix(vec3(1.0), uDecalColor, mark * uDecalOpacity), 1.0);
+}
+`;

package/dist/render/shaders/depth.d.ts

@@ -0,0 +1,14 @@
+/** The rigid variant: the world, a prop, a mesh with no rig behind it. */
+export declare const DEPTH_VERT: string;
+/** The skinned variant, which reads a joint palette and moves the vertex by it. */
+export declare const DEPTH_SKINNED_VERT: string;
+/**
+ * The variant an instanced draw casts its shadow through.
+ *
+ * **It exists because a shadow is not optional.** An instanced mesh whose depth pass still read
+ * uModel would cast every instance's shadow from the last matrix uploaded — one shadow in the
+ * right place and the rest stacked underneath it, which reads as a lighting fault rather than as
+ * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
+ */
+export declare const DEPTH_INSTANCED_VERT: string;
+export declare const DEPTH_FRAG = "#version 300 es\nprecision highp float;\nin vec4 vLightPosition;\n\nuniform highp sampler2D uPreviousShadowMap;\nuniform int uPeelShadowLayer;\n\nvoid main() {\n  if (uPeelShadowLayer != 0) {\n    vec3 p = vLightPosition.xyz / vLightPosition.w;\n    vec2 uv = p.xy * 0.5 + 0.5;\n    float previousDepth = texture(uPreviousShadowMap, uv).r;\n    // Discard the already-recorded surface and everything in front of it. The\n    // ordinary depth test then stores the next independently fading occluder.\n    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;\n  }\n}\n";

package/dist/render/shaders/depth.js

@@ -0,0 +1,114 @@
+import { resolveConditionals } from './conditionals.js';
+import { SKINNING_GLSL } from './skinning.js';
+import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.js';
+/**
+ * Depth-only shadow pass. Its optional peel mode rejects the first recorded
+ * surface so the next independently fading occluder can be retained.
+ *
+ * **Two vertex variants, skinned and not**, for the reason `ShadowCasterSink.scatter` already
+ * states about the wind: handing the depth pass a different deformation from the colour pass is
+ * how a shadow comes loose from its caster. A skinned character cast rigidly does not drift
+ * slightly — it casts its bind pose, so a running figure throws the shadow of a statue.
+ *
+ * The permutation rather than a uniform gate is the same decision `skinning.ts` measured for the
+ * flat shader, and it is cheaper here: this vertex shader is a fifth the size of that one, so the
+ * second copy dedupes almost entirely inside deflate's window.
+ */
+const DEPTH_VERT_SOURCE = `#version 300 es
+layout(location = 0) in vec3 aPosition;
+#if SKINNED
+${SKINNING_GLSL}
+#endif
+
+uniform mat4 uLightViewProj;
+/*
+ * Placement last, and in the instanced variant not at all — see the flat shader, where the same
+ * arrangement is load-bearing. Here it costs nothing to keep: uModel is already the last field,
+ * so the instanced block is this one without its tail and uLightViewProj does not move.
+ */
+#if INSTANCED
+/**
+ * One instance's placement, four vec4 columns, at the same locations the flat stage uses.
+ *
+ * No tint: this stage writes depth and nothing samples its colour.
+ *
+ * The same exclusions apply and for the same reasons — skinning owns locations 11 and 12, and a
+ * shadow must be deformed exactly as its caster is or it comes loose from the body casting it.
+ */
+layout(location = 11) in vec4 aInstanceModel0;
+layout(location = 12) in vec4 aInstanceModel1;
+layout(location = 13) in vec4 aInstanceModel2;
+layout(location = 14) in vec4 aInstanceModel3;
+#else
+uniform mat4 uModel;
+
+/*
+ * **The same channel and the same bend the colour pass runs, and it is not optional here.**
+ * scatter.ts records why it shares one expression between its two programs: a canopy that bends
+ * in the picture and stands still in the shadow map slides its whole shade off the ground it
+ * belongs to, and the offset follows the gust, so it never reads as a fixed error anybody could
+ * find by looking at one frame.
+ *
+ * Only .x is read. The sky and alpha lanes are shading, and this stage writes depth.
+ */
+${CHANNEL_ATTRIBUTE}
+${CHANNEL_BEND}
+#endif
+
+out vec4 vLightPosition;
+
+void main() {
+#if SKINNED
+  /* In model space, before uModel, because a palette entry already carries the bind pose —
+     the same order the flat shader applies it in, and the two must agree or a shadow parts
+     from the body casting it. */
+  vec4 local = skinMatrix() * vec4(aPosition, 1.0);
+#else
+  vec4 local = vec4(aPosition, 1.0);
+#endif
+#if INSTANCED
+  mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+#else
+  mat4 model = uModel;
+#endif
+  vec4 world = model * local;
+#if INSTANCED
+  vec3 bent = world.xyz;
+#else
+  vec3 bent = channelBend(world.xyz, aChannel.x);
+#endif
+  vLightPosition = uLightViewProj * vec4(bent, world.w);
+  gl_Position = vLightPosition;
+}
+`;
+/** The rigid variant: the world, a prop, a mesh with no rig behind it. */
+export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false }, 'depth');
+/** The skinned variant, which reads a joint palette and moves the vertex by it. */
+export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false }, 'depth-skinned');
+/**
+ * The variant an instanced draw casts its shadow through.
+ *
+ * **It exists because a shadow is not optional.** An instanced mesh whose depth pass still read
+ * uModel would cast every instance's shadow from the last matrix uploaded — one shadow in the
+ * right place and the rest stacked underneath it, which reads as a lighting fault rather than as
+ * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
+ */
+export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true }, 'depth-instanced');
+export const DEPTH_FRAG = `#version 300 es
+precision highp float;
+in vec4 vLightPosition;
+
+uniform highp sampler2D uPreviousShadowMap;
+uniform int uPeelShadowLayer;
+
+void main() {
+  if (uPeelShadowLayer != 0) {
+    vec3 p = vLightPosition.xyz / vLightPosition.w;
+    vec2 uv = p.xy * 0.5 + 0.5;
+    float previousDepth = texture(uPreviousShadowMap, uv).r;
+    // Discard the already-recorded surface and everything in front of it. The
+    // ordinary depth test then stores the next independently fading occluder.
+    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;
+  }
+}
+`;

package/dist/render/shaders/depthOfField.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Depth of field: a circle of confusion from the depth buffer, and a disc blur that follows it.
+ *
+ * **A snippet spliced into the composite rather than a pass of its own**, because the composite
+ * already holds everything this needs — the resolved scene, its depth, and a place in the chain
+ * where the picture is finished but not yet graded. A second fullscreen pass would mean a second
+ * read and a second write of the whole frame to add eight taps to the pixels that are out of
+ * focus, which is the shape `ambientOcclusion.ts` takes only because it must blur its own noisy
+ * estimate first. Nothing here is noisy.
+ *
+ * **Off costs one comparison.** `uDofStrength` at zero is a branch on a uniform — provably uniform
+ * control flow, so it is not the 2026-08-07 case — and the frame is the frame that existed before
+ * the effect did, bit for bit.
+ *
+ * **The model, and why it is stated in metres.** A lens has a plane it is focused on and a depth
+ * either side of it that is acceptably sharp; past that, a point becomes a disc whose diameter
+ * grows with how far out of focus it is. So the two numbers a caller gives are a *distance* and a
+ * *range*, both in metres of the world, and the shader turns them into a radius in pixels. A
+ * formulation in depth-buffer units would be cheaper and would mean nothing to anyone: a camera
+ * focuses on a thing at a distance, not on a value of `gl_FragCoord.z`.
+ *
+ * **What the ramp is, exactly.** Zero inside `range` metres of the plane, reaching full blur one
+ * more `range` beyond it, clamped there. Linear rather than physical: a real circle of confusion
+ * grows without bound behind the plane and toward the lens in front of it, and reproducing that
+ * needs an aperture, a focal length and a sensor size — three numbers a game camera does not have
+ * and would have to invent. *What that gives up* is that a caller cannot reproduce a particular
+ * lens. *What would reverse it* is a consumer matching real optics, and the answer then is those
+ * three numbers rather than a different curve on these two.
+ *
+ * **The bleed, and the one line that handles it.** The classic artefact of a gather blur is a
+ * sharp foreground subject collecting colour from the blurred background behind it, so it wears a
+ * halo of whatever it is standing in front of. A tap here is weighted by whether it is *behind*
+ * the pixel it is blurring into — which it may always contribute to — or in front of it, where it
+ * contributes only as far as it is itself defocused. That is one compare per tap and it removes
+ * the halo. *What it does not do* is spread a blurred foreground *over* a sharp background, which
+ * a gather cannot do at all: no tap on the background ever reaches out to find it. A scatter pass
+ * or a separate near field is the answer, and neither is here.
+ */
+/** How many taps the disc takes. Eight, fixed, so the cost of the effect is a constant. */
+export declare const DOF_TAPS = 8;
+export declare const DEPTH_OF_FIELD_GLSL: string;

package/dist/render/shaders/depthOfField.js

@@ -0,0 +1,139 @@
+import { glslSceneDepthToNdc } from '../depthConvention.js';
+/**
+ * Depth of field: a circle of confusion from the depth buffer, and a disc blur that follows it.
+ *
+ * **A snippet spliced into the composite rather than a pass of its own**, because the composite
+ * already holds everything this needs — the resolved scene, its depth, and a place in the chain
+ * where the picture is finished but not yet graded. A second fullscreen pass would mean a second
+ * read and a second write of the whole frame to add eight taps to the pixels that are out of
+ * focus, which is the shape `ambientOcclusion.ts` takes only because it must blur its own noisy
+ * estimate first. Nothing here is noisy.
+ *
+ * **Off costs one comparison.** `uDofStrength` at zero is a branch on a uniform — provably uniform
+ * control flow, so it is not the 2026-08-07 case — and the frame is the frame that existed before
+ * the effect did, bit for bit.
+ *
+ * **The model, and why it is stated in metres.** A lens has a plane it is focused on and a depth
+ * either side of it that is acceptably sharp; past that, a point becomes a disc whose diameter
+ * grows with how far out of focus it is. So the two numbers a caller gives are a *distance* and a
+ * *range*, both in metres of the world, and the shader turns them into a radius in pixels. A
+ * formulation in depth-buffer units would be cheaper and would mean nothing to anyone: a camera
+ * focuses on a thing at a distance, not on a value of `gl_FragCoord.z`.
+ *
+ * **What the ramp is, exactly.** Zero inside `range` metres of the plane, reaching full blur one
+ * more `range` beyond it, clamped there. Linear rather than physical: a real circle of confusion
+ * grows without bound behind the plane and toward the lens in front of it, and reproducing that
+ * needs an aperture, a focal length and a sensor size — three numbers a game camera does not have
+ * and would have to invent. *What that gives up* is that a caller cannot reproduce a particular
+ * lens. *What would reverse it* is a consumer matching real optics, and the answer then is those
+ * three numbers rather than a different curve on these two.
+ *
+ * **The bleed, and the one line that handles it.** The classic artefact of a gather blur is a
+ * sharp foreground subject collecting colour from the blurred background behind it, so it wears a
+ * halo of whatever it is standing in front of. A tap here is weighted by whether it is *behind*
+ * the pixel it is blurring into — which it may always contribute to — or in front of it, where it
+ * contributes only as far as it is itself defocused. That is one compare per tap and it removes
+ * the halo. *What it does not do* is spread a blurred foreground *over* a sharp background, which
+ * a gather cannot do at all: no tap on the background ever reaches out to find it. A scatter pass
+ * or a separate near field is the answer, and neither is here.
+ */
+/** How many taps the disc takes. Eight, fixed, so the cost of the effect is a constant. */
+export const DOF_TAPS = 8;
+export const DEPTH_OF_FIELD_GLSL = `
+/** Where the lens is focused, in metres from the camera. */
+uniform float uFocusDistance;
+/**
+ * How many metres either side of that plane stay sharp, and over how many more the blur reaches
+ * full strength. One number for both, because two would be a second dial with no second question.
+ */
+uniform float uFocusRange;
+/**
+ * The widest the blur may reach, as a fraction of the frame's height. 0 turns the effect off and
+ * is the whole of the off path.
+ */
+uniform float uDofStrength;
+/**
+ * \`vec2(height / width, 1.0)\`, so a radius given in fractions of the frame's height traces a
+ * circle on screen rather than an ellipse stretched by the aspect.
+ */
+uniform vec2 uDofAspect;
+/**
+ * The four elements of the inverse projection that turn a depth sample into a view-space distance:
+ * \`(m[10], m[14], m[11], m[15])\` in gl-matrix's column-major order, which are \`M[2][2]\`,
+ * \`M[2][3]\`, \`M[3][2]\` and \`M[3][3]\`.
+ *
+ * Four floats rather than the whole matrix, because the other twelve are multiplied by the x and y
+ * of a clip position this never needs: a perspective projection's inverse has zeroes where they
+ * would land. \`ambientOcclusion.ts\` uploads the full \`uInvProjection\` because it reconstructs a
+ * *position* and needs them.
+ */
+uniform vec4 uDepthToView;
+
+/**
+ * Metres in front of the camera, from a depth sample.
+ *
+ * \`depth * 2.0 - 1.0\` is the same recovery \`cameraBlur\` makes and for the same reason: the depth
+ * attachment holds [0, 1] on both backends, the projection whose inverse this carries is the
+ * uncorrected OpenGL-convention one, and the engine settles the difference between the two clip
+ * spaces in the matrix rather than in the shaders.
+ */
+float viewDepthOf(vec2 uv) {
+  float z = ${glslSceneDepthToNdc('textureLod(uDepth, uv, 0.0).r')};
+  return -(uDepthToView.x * z + uDepthToView.y) / (uDepthToView.z * z + uDepthToView.w);
+}
+
+/** 0 inside the sharp zone, 1 at full blur. See the header for the shape of the ramp. */
+float circleOfConfusion(float viewDepth) {
+  float offPlane = abs(viewDepth - uFocusDistance) - uFocusRange;
+  return clamp(offPlane / uFocusRange, 0.0, 1.0);
+}
+
+/**
+ * The eight offsets of the disc, written out.
+ *
+ * A golden-angle spiral at radii spaced by \`sqrt((i + 0.5) / 8)\`, which fills a disc evenly
+ * rather than stacking the taps into a ring. Literals rather than a loop over \`cos\` and \`sin\`,
+ * because these are constants and evaluating them per pixel is eight transcendentals for a table.
+ * Successive taps turned by the golden angle never line up into spokes, which is the same
+ * property \`ambientOcclusion.ts\` picks it for.
+ *
+ * The colour comes back premultiplied by the weight and the weight rides in \`w\`, rather than an
+ * \`inout\` parameter — one value out of one function, which is what the generator translates most
+ * predictably.
+ */
+vec4 dofTap(vec2 direction, float radius, float centreDepth) {
+  vec2 uv = vUv + direction * radius * uDofAspect;
+  float depth = viewDepthOf(uv);
+  /* Behind the pixel it is blurring into, or defocused enough to have spread this far. */
+  float weight = depth >= centreDepth ? 1.0 : circleOfConfusion(depth);
+  /* textureLod: this is reached through a branch on the circle of confusion, which varies across
+     the frame, so it is not uniform control flow. Identical output — one storage level. */
+  return vec4(textureLod(uScene, uv, 0.0).rgb * weight, weight);
+}
+
+/**
+ * The disc, gathered.
+ *
+ * The centre sample is the colour handed in rather than a fresh fetch, so a pixel that has already
+ * been camera-blurred keeps that blur at the middle of its own disc. *What that gives up* is that
+ * the eight taps read the unblurred scene, so the two effects compose approximately rather than
+ * exactly. *What would make it wrong* is a consumer running both at full strength and caring which
+ * order they were applied in, and the answer then is a second scene target for the intermediate.
+ */
+vec3 depthOfField(vec3 centre) {
+  float depth = viewDepthOf(vUv);
+  float coc = circleOfConfusion(depth);
+  if (coc <= 0.0) return centre;
+  float radius = coc * uDofStrength;
+  vec4 sum = vec4(centre, 1.0);
+  sum += dofTap(vec2( 0.250000,  0.000000), radius, depth);
+  sum += dofTap(vec2(-0.319290,  0.292496), radius, depth);
+  sum += dofTap(vec2( 0.048872, -0.556877), radius, depth);
+  sum += dofTap(vec2( 0.402444,  0.524918), radius, depth);
+  sum += dofTap(vec2(-0.738535, -0.130636), radius, depth);
+  sum += dofTap(vec2( 0.699605, -0.445031), radius, depth);
+  sum += dofTap(vec2(-0.234004,  0.870484), radius, depth);
+  sum += dofTap(vec2(-0.446271, -0.859268), radius, depth);
+  return sum.rgb / sum.w;
+}
+`;

package/dist/render/shaders/film.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A thin, wet, iridescent film lying on a surface.
+ *
+ * The material an oil slick is made of, described without knowing what oil is.
+ * Flat dark geometry cannot do this job — it reads as a hole in the world, which
+ * is exactly how the first version looked. What makes a film read as *wet* is
+ * that it changes with the angle you see it from: almost black looking straight
+ * down, and a shifting sheen at a glance.
+ *
+ * Textureless, per the standing rule. The iridescence is a hue swept by the
+ * view angle plus a slow travelling ripple, both evaluated per fragment; the
+ * rainbow is generated rather than sampled.
+ */
+export declare const FILM_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec3 aNormal;\nlayout(location = 2) in vec3 aColor;\n/*\n * Coverage, on the attribute the mesh format calls emissive.\n *\n * A film has no use for self-illumination, and it very much needs an edge that\n * dissolves: the first oil was flat squares, and a hard straight edge is what made\n * it read as a decal dropped on the world rather than a puddle lying in it. One\n * float per vertex, 1 in the middle of a slick and 0 at its rim.\n */\nlayout(location = 3) in float aCoverage;\n\nuniform mat4 uViewProj;\n/* The mirrored camera's projection, so a film can sample the planar target the way water does. */\nuniform mat4 uReflectionViewProj;\n\nout vec3 vWorld;\nout vec3 vNormal;\nout vec3 vTint;\nout vec4 vReflectionClip;\nout float vCoverage;\n\nvoid main() {\n  vWorld = aPosition;\n  vNormal = normalize(aNormal);\n  vTint = aColor;\n  vCoverage = aCoverage;\n  vReflectionClip = uReflectionViewProj * vec4(aPosition, 1.0);\n  gl_Position = uViewProj * vec4(aPosition, 1.0);\n}\n";
+export declare const FILM_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorld;\nin vec3 vNormal;\nin vec3 vTint;\nin vec4 vReflectionClip;\n/*\n * The scene mirrored across the plane this film lies on, and how much of it to show.\n *\n * **Sheen is iridescence and this is the image**, which is the split a consumer asked for after\n * finding that raising sheen to make a road wetter only made it oilier. A wet street at night is\n * defined by everything above it appearing twice, and no amount of interference pattern is that.\n *\n * The projection is the water shader's, unchanged and deliberately so: reproducing it outside the\n * engine is the piece most likely to be subtly wrong and least likely to be noticed, since a\n * mirror off by a small skew looks like a wet road until somebody puts a straight line across it.\n */\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform float uReflectionStrength;\nin float vCoverage;\n\nuniform vec3 uCameraPos;\nuniform float uTime;\n/*\n * The mirrored pass clips at the water plane, and it does so **in the fragment\n * shader** rather than with gl_ClipDistance.\n *\n * That is not a style choice. Clip distances in WebGL2 need\n * EXT_clip_cull_distance both enabled on the context and declared with an\n * #extension line, and without the declaration the shader fails to *compile* \u2014\n * which, since programs are built when the renderer is constructed, takes the\n * whole boot with it and leaves a black screen. This shader had never been\n * compiled when it was written, so the mistake sat harmlessly in the file until\n * the day it was wired to something. Discarding is what flat.ts does, it needs\n * no extension, and a film is a thin translucent layer where the cost of a\n * discarded fragment is nothing.\n */\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/** How strong the sheen is. Zero leaves a plain dark film. */\nuniform float uSheen;\n\n/**\n * How rough the film's own surface is, 0 to 1, and how coarse that roughness is.\n *\n * **A film had exactly one finish before this: mirror.** That is right for standing water and\n * wrong for the thing this pass is most used for, because a wet road is not a mirror \u2014 it is\n * water lying *in* aggregate, and the stone underneath breaks the reflection into a smear. With\n * no way to say so, a patch of film over a textured road met it at a hard rim: mirror on one\n * side, stone on the other, with nothing able to cross it. Feathering the coverage cannot fix\n * that, and it was tried \u2014 the alpha was never what the eye was reading.\n *\n * So the reflection is displaced by a noise field rather than blurred. **Displaced, because a\n * blur is the wrong phenomenon**: a rough surface does not soften what it reflects, it scatters\n * it, and a lamp on wet tarmac smears into a streak rather than becoming a soft disc. It is also\n * what a blur cannot afford here \u2014 the mirror has no mip chain (see the `textureLod` note\n * below), so softening it honestly would cost several taps where this costs none.\n *\n * `uFilmRoughnessCycles` is bumps to the metre, and it is the same quantity\n * `Renderer.setSurfaceRelief` takes. **Matching it to the surface underneath is the point**:\n * given the same field at the same scale, the water is broken up by the aggregate that the dry\n * road beside it is showing, and the two stop being different materials.\n *\n * Zero is the mirror this pass has always been, exactly, so nothing that does not ask for\n * roughness renders differently.\n */\nuniform float uFilmRoughness;\nuniform float uFilmRoughnessCycles;\n\nout vec4 fragColor;\n\n/** A hue wheel, without a texture. Standard 6-segment ramp. */\nvec3 hue(float h) {\n  h = fract(h) * 6.0;\n  vec3 c = clamp(vec3(abs(h - 3.0) - 1.0, 2.0 - abs(h - 2.0), 2.0 - abs(h - 4.0)), 0.0, 1.0);\n  return c;\n}\n\n/**\n * The same value noise `flat.ts` builds its relief from, and deliberately the same.\n *\n * Copied rather than shared because these two shaders have no common include beyond the fog, and\n * a film that used a *different* field would defeat the whole purpose of taking a cycle count:\n * the water would be broken up by one pattern and the road by another, which is two materials\n * again with extra steps.\n */\nfloat filmHash(vec3 p) {\n  p = fract(p * 0.1031);\n  p += dot(p, p.zyx + 31.32);\n  return fract((p.x + p.y) * p.z);\n}\n\nfloat filmNoise(vec3 p) {\n  vec3 i = floor(p);\n  vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 0.0)), filmHash(i + vec3(1.0, 0.0, 0.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 0.0)), filmHash(i + vec3(1.0, 1.0, 0.0)), u.x),\n      u.y\n    ),\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 1.0)), filmHash(i + vec3(1.0, 0.0, 1.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 1.0)), filmHash(i + vec3(1.0, 1.0, 1.0)), u.x),\n      u.y\n    ),\n    u.z\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorld, 1.0), uClipPlane) < 0.0) discard;\n\n  vec3 view = normalize(uCameraPos - vWorld);\n  float facing = max(dot(normalize(vNormal), view), 0.0);\n  /*\n   * Fresnel-ish: dark looking straight down at it, bright at a grazing angle.\n   * This is the whole effect \u2014 it is what makes a wet patch look wet rather\n   * than looking like a patch of dark paint.\n   */\n  float grazing = pow(1.0 - facing, 3.0);\n\n  /*\n   * A slow travelling interference, so the sheen crawls rather than sitting\n   * still. Two frequencies that do not divide each other, or the pattern\n   * repeats visibly across a long slick.\n   */\n  float ripple =\n    sin(vWorld.x * 0.73 + vWorld.z * 0.41 + uTime * 0.55) *\n    cos(vWorld.z * 0.91 - vWorld.x * 0.29 - uTime * 0.37);\n\n  vec3 sheen = hue(grazing * 1.35 + ripple * 0.14 + 0.55);\n  /*\n   * Dark underneath, so the film always reads as *less* than the surface it lies on even where\n   * the sheen is strongest \u2014 but not so dark that it disappears.\n   *\n   * A slick that has just launched somebody has to be findable afterwards. It was rounded,\n   * feathered and iridescent \u2014 and at a fifth of an opaque tint on a pale deck at dusk,\n   * invisible. A hazard you cannot find is not a hazard, it is a trap.\n   *\n   * So the base is darker and the sheen has a floor: even looking straight down, where the\n   * Fresnel term is nearly nothing, a slick is a distinctly wet patch rather than a faint one.\n   */\n  vec3 base = vTint * 0.9;\n  vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);\n\n  /*\n   * The mirrored scene, under the sheen rather than instead of it.\n   *\n   * Screen-space from the mirrored clip position, exactly as the water pass does it, with the\n   * same fade as the sample leaves the target: a reflection that stopped dead at the edge of its\n   * own buffer would draw a line across the road where nothing is.\n   *\n   * Weighted by the grazing term as well as by strength, because that is what a reflection does:\n   * a wet surface underfoot shows almost nothing and the same surface down the street shows the\n   * whole scene. Added before the fog so the image recedes with everything else in the frame.\n   */\n  if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    float valid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    /*\n     * An explicit level, not an implicit one, and the branch above is the whole reason.\n     *\n     * An implicit derivative inside control flow that is not provably uniform is what lets a\n     * compiler flatten the branch and pay for every arm \u2014 AGENTS.md, 2026-08-07 \u2014 and WGSL\n     * does not merely warn: the module fails to compile with \"textureSample must only be\n     * called from uniform control flow\", which invalidates the pipeline, which invalidates\n     * the command buffer, and the frame still presents. The fifth time on this branch. The\n     * mirror has no mip chain, so level 0 is the only level there is; the water shader\n     * reaches the same conclusion for the same lookup.\n     */\n    /*\n     * The aggregate under the water, as a displacement of what the water shows.\n     *\n     * The gradient of the same field the road's relief uses, taken across the surface and used\n     * to push the lookup. **Stretched along the reflection rather than isotropic**, and that is\n     * the half that makes it read as a road: a reflection on a rough horizontal surface smears\n     * *towards the viewer*, because a bump tilts the ray in the plane it is already travelling\n     * in. Displacing in a circle gives frosted glass instead, which is a different wet thing.\n     *\n     * Scaled by the grazing term for the same reason the mirror is: looking straight down at a\n     * puddle the reflection is compressed into almost nothing and a displacement of it would be\n     * enormous, so the scatter has to fall off exactly where the image does.\n     */\n    if (uFilmRoughness > 0.0) {\n      vec3 at = vWorld * uFilmRoughnessCycles;\n      float here = filmNoise(at);\n      vec2 slope = vec2(\n        filmNoise(at + vec3(0.5, 0.0, 0.0)) - here,\n        filmNoise(at + vec3(0.0, 0.0, 0.5)) - here\n      );\n      /* Along the view, which on a horizontal film is where the image runs. */\n      vec2 along = normalize(vec2(view.x, view.z) + vec2(1e-5, 0.0));\n      vec2 smear = along * dot(slope, along) * 3.0 + slope * 0.35;\n      reflectionUv += smear * uFilmRoughness * 0.016 * (0.2 + grazing * 0.8);\n      /* Re-fade at the border: a displaced sample can leave the target the original did not. */\n      vec2 movedBorder = min(reflectionUv, 1.0 - reflectionUv);\n      valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));\n    }\n    vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;\n    color = mix(color, mirrored, valid * uReflectionStrength * (0.25 + grazing * 0.75));\n  }\n\n  // The same fog every other pass applies \u2014 and now literally the same code, which\n  // it was not: this ran its own curve while claiming otherwise, so a slick receded\n  // at a different rate than the deck it was lying on.\n  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);\n  color = mix(color, mediumColor(), fog);\n\n  /*\n   * Alpha from coverage, squared.\n   *\n   * Squared because a linear ramp across the rim still reads as a visible band \u2014\n   * the eye finds the constant-gradient edge. Squaring pushes the falloff outward\n   * so the slick has a soft shoulder and no perceptible boundary. The sheen fades\n   * with it, which is right: the thinnest part of a film is the least iridescent.\n   */\n  /*\n   * Alpha from coverage, and the rim is what is squared \u2014 not the whole patch.\n   *\n   * Squaring the coverage outright made the *middle* translucent too, which is most of why a\n   * slick could not be found. The shoulder still needs to be soft, so the square is mixed in\n   * near the edge only: solid through the body, dissolving at the rim.\n   */\n  float coverage = clamp(vCoverage, 0.0, 1.0);\n  float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;\n  fragColor = vec4(color, alpha);\n}\n";