@driftengine/core 3.61.0

package/src/render/shaders/decalProject.ts

@@ -0,0 +1,127 @@
+/**
+ * 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.ts';
+
+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/src/render/shaders/depth.ts

@@ -0,0 +1,131 @@
+import { resolveConditionals } from './conditionals.ts';
+import { SKINNING_GLSL } from './skinning.ts';
+import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.ts';
+
+/**
+ * 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/src/render/shaders/depthOfField.ts

@@ -0,0 +1,141 @@
+import { glslSceneDepthToNdc } from '../depthConvention.ts';
+/**
+ * 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/src/render/shaders/film.ts

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