@driftengine/core 3.61.0

package/src/render/shaders/vertexChannel.ts

@@ -0,0 +1,71 @@
+/**
+ * The per-vertex channel's declaration and its wind displacement, authored once for two programs.
+ *
+ * **Shared source rather than two copies, for the reason `scatter.ts` gives about its own.** The
+ * colour pass and the depth pass have to agree *exactly*: a canopy that bends in one and stands
+ * still in the other slides its whole shade off the ground it belongs to, and the drift follows
+ * the gust, so it never reads as a constant offset anybody could find by looking. One expression,
+ * two callers.
+ *
+ * The lanes are `MeshData.channel`: `.x` sway, `.y` skyDirect, `.z` alpha, `.w` reserved. Only
+ * `.x` is read here; the other two are varyings the fragment stage consumes.
+ */
+
+/**
+ * The attribute, and the wind the bend below reads.
+ *
+ * Declared unconditionally in every vertex variant. **No lane is a permutation**: the fragment
+ * stage already carries sixteen of those at 282.2 KB gzipped, where the whole vertex stage is
+ * 4.1 KB across five, so a `#if` here would buy nothing measurable and cost a variant axis.
+ */
+export const CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection;
+uniform float uWindSpeed;
+uniform float uWindGust;
+uniform float uWindTime;
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase;
+`;
+
+/**
+ * Where the wind puts a vertex, given how much of it that vertex takes.
+ *
+ * Phase comes from world position, so neighbouring geometry is never in lockstep and a gust
+ * visibly travels across a canopy instead of the whole canopy pulsing at once. That is the scatter
+ * shader's reasoning and it transfers without change.
+ *
+ * **The lane scales the bend once, where `scatter.ts` squares its own falloff.** That file derives
+ * its falloff from height, and a linear response there slides a whole plant sideways and reads as
+ * the ground moving, so it squares to keep the base planted. Here the falloff is *authored* — 0 on
+ * a trunk, 1 at a leaf tip — and squaring it would silently overrule a curve somebody had already
+ * shaped. What that costs is that a lane filled linearly up a trunk gives a tree that slides at
+ * its base; the fix is the curve the author meant, not a square in the shader.
+ *
+ * The early return is not an optimisation. Geometry that never said it bends must reach exactly
+ * the position it reached before this existed, and `sin` of a phase multiplied by zero is not
+ * bit-identical to not moving at all.
+ */
+export const CHANNEL_BEND = `
+vec3 channelBend(vec3 worldPos, float sway) {
+  if (sway <= 0.0) return worldPos;
+  float phase = dot(worldPos.xz, uWindSpatialPhase) + uWindTime;
+  float bend = (uWindSpeed + uWindGust) * sin(phase) * sway;
+  return vec3(
+    worldPos.x + uWindDirection.x * bend,
+    worldPos.y,
+    worldPos.z + uWindDirection.y * bend
+  );
+}
+`;

package/src/render/shaders/water.ts

@@ -0,0 +1,356 @@
+import { MAX_POINT_LIGHTS } from '../lightBudget.ts';
+import { MAX_WATER_REFLECTION_FILTER_TAPS } from '../renderQuality.ts';
+import { GERSTNER_GLSL } from './gerstner.ts';
+import { FOG_GLSL } from './fog.ts';
+
+/**
+ * The sky-ocean, as an actual wave simulation rather than a tinted plane.
+ *
+ * Four summed Gerstner waves: unlike a sine heightfield, Gerstner displaces
+ * vertices *horizontally* toward crests as well as vertically, which is what
+ * produces sharp peaks and broad troughs instead of a rolling blanket. Normals
+ * come analytically from the same sum, so lighting matches the geometry exactly
+ * and needs no derivative tricks.
+ *
+ * The wave field itself lives in `gerstner.ts` because it is shared: the caustics
+ * in `caustics.ts` are the light *this* surface throws onto what covers it, and
+ * they must be the same water, not a lookalike animated separately.
+ *
+ * The grid follows the camera and is snapped to whole cells, giving an endless
+ * ocean from a fixed vertex budget without the surface sliding underfoot.
+ */
+export const WATER_VERT = `#version 300 es
+layout(location = 0) in vec2 aGrid;
+
+uniform mat4 uViewProj;
+uniform mat4 uReflectionViewProj;
+uniform vec3 uCameraPos;
+uniform float uTime;
+/**
+ * Where the sheet is laid, in world XZ.
+ *
+ * The ocean passes its own camera position snapped to whole cells, which is what
+ * gives an endless sea from a fixed vertex budget without the surface sliding
+ * underfoot. A *bounded* sheet — a pool in a courtyard — passes the middle of the
+ * thing it is filling instead, and is world-fixed by construction.
+ *
+ * Snapped on the CPU rather than here so that one number is the only difference
+ * between an ocean and a basin, and the shader has no idea which it is drawing.
+ */
+uniform vec2 uGridOrigin;
+/**
+ * Metres per unit of the sheet's own grid, along each of the body's own axes.
+ *
+ * One and one for the ocean, whose grid is authored in metres and is two meshes wide.
+ * A bounded body — a pool, a tank, a puddle, a channel — is drawn from a unit sheet
+ * and scaled by its own half-extents, which is what lets one mesh and one material
+ * serve every body of water in the world.
+ *
+ * **Two numbers and not one since 2026-08-28.** A single span makes every bounded
+ * body square, and a square that contains a channel floods the ground either side
+ * of it. The ocean passes the same number twice and is bit-identical to what it was.
+ */
+uniform vec2 uGridSpan;
+uniform vec2 uGridHalf;
+uniform vec2 uNearHalf;
+/**
+ * The body's own +z, in world XZ, unit length. (0, 1) leaves the sheet unturned.
+ *
+ * A direction rather than an angle, so nothing here needs a trig call and a consumer
+ * bounding a channel can hand over the direction its run already takes. The across
+ * axis is world up crossed with this, \`(fz, -fx)\`, which is the basis
+ * \`MeshBuilder.addOrientedBox\` builds from a forward vector — one convention for an
+ * oriented thing, so a reader who has met one has met both.
+ */
+uniform vec2 uGridForward;
+/** Prevailing wind bearing, normalised. Waves are steered toward it. */
+uniform vec2 uWindDir;
+/** Multiplier on authored steepness — how built-up the sea is. */
+uniform float uWaveGain;
+uniform float uWaterLevel;
+
+out vec3 vWorldPos;
+out vec3 vNormal;
+out float vCrest;
+out vec4 vReflectionClip;
+/** Grid-local offset, so the sheet can fade out its own boundary. */
+out vec2 vGrid;
+
+${GERSTNER_GLSL}
+
+void main() {
+  /*
+   * Waves must reach nothing by the near sheet's edge, because beyond it lies
+   * the flat skirt. A displaced rim meeting an undisplaced skirt would tear the
+   * surface open along a visible seam; fading first makes the two meshes agree
+   * exactly where they meet. Chebyshev distance, so the fade band follows the
+   * rectangular boundary rather than cutting an ellipse inside it.
+   *
+   * **Measured as a fraction of each axis' own extent**, which is what lets a
+   * channel three metres across and twenty-one long fade evenly at both its ends
+   * and both its sides. Against one shared extent the narrow axis would be inside
+   * the fade band along its whole length and the water would never reach its own
+   * bank. For the ocean, whose two extents are equal, this is the same arithmetic
+   * with the division moved one step earlier.
+   *
+   * It is also the honest thing to draw. At a few hundred metres a 1 m swell is
+   * well under a pixel, and out on the skirt a float32 phase argument has lost
+   * most of its meaningful bits — a calm horizon is what an ocean actually looks
+   * like from that far away.
+   */
+  vec2 grid = aGrid * uGridSpan;
+  /* The same offset the fragment stage fades the rim on, so the two cannot disagree. */
+  vGrid = grid;
+  vec2 rimFraction = abs(grid) / max(uNearHalf, vec2(1e-4));
+  float rimDistance = max(rimFraction.x, rimFraction.y);
+  float waveFade = 1.0 - smoothstep(0.35, 0.97, rimDistance);
+
+  /*
+   * Into the world: across the body, then along it. \`right = up x forward\` is
+   * \`(fz, -fx)\`, and getting that pair the wrong way round is a sheet mirrored
+   * about its own axis, which on a square is invisible and on a channel is a
+   * channel across the road instead of along it.
+   */
+  vec2 laid = vec2(uGridForward.y, -uGridForward.x) * grid.x + uGridForward * grid.y;
+
+  vec3 base = vec3(uGridOrigin.x + laid.x, uWaterLevel, uGridOrigin.y + laid.y);
+
+  GerstnerSurface sea = gerstnerSurface(base.xz, uTime, uWindDir, waveFade * uWaveGain);
+  vec3 pos = base + sea.offset;
+
+  vWorldPos = pos;
+  vNormal = normalize(sea.normal);
+  vCrest = sea.crest;
+  vReflectionClip = uReflectionViewProj * vec4(pos, 1.0);
+  gl_Position = uViewProj * vec4(pos, 1.0);
+}
+`;
+
+export const WATER_FRAG = `#version 300 es
+precision highp float;
+
+in vec3 vWorldPos;
+in vec3 vNormal;
+in float vCrest;
+in vec4 vReflectionClip;
+in vec2 vGrid;
+
+uniform vec2 uGridHalf;
+uniform float uFoamGain;
+/**
+ * How much of what is beneath it a body of water hides, looked straight down.
+ *
+ * The *density* of the water rather than a rendering trick: a sea hides its own
+ * floor, a fountain shows the tiles at the bottom of it, and a puddle is nearly
+ * clear. Only the nadir end is configurable — at a grazing angle every water
+ * surface goes reflective, which is Fresnel and not a property of the liquid.
+ */
+uniform float uNadirOpacity;
+/** The whole surface's visibility, 0 to 1. Zero draws nothing at all. */
+uniform float uVisibility;
+/**
+ * How much this body mirrors regardless of the angle it is seen at, 0 to 1.
+ *
+ * Zero is physics: reflection is Fresnel alone, which is right for an ocean seen
+ * across its own surface and which means *almost nothing* when you stand over a
+ * basin and look down into it — the angle is steep, the Fresnel term is a few
+ * percent, and a reflection nobody can see is the same as no reflection: the
+ * character's reflection is technically present and far too faint to perceive.
+ *
+ * So a body may declare itself more mirror than water. It is a lie about optics
+ * and an honest one about what a small pool is *for*: you look into it to see
+ * something. The sea keeps zero and behaves exactly as it always has.
+ */
+uniform float uMirror;
+uniform vec3 uDeepColor;
+uniform vec3 uShallowColor;
+uniform vec3 uDirectionalDir;
+uniform vec3 uDirectionalColor;
+uniform vec3 uAmbient;
+/**
+ * The scene's point lights, which water is entitled to as much as stone is.
+ *
+ * The surface used to answer to the sun alone, on the reasonable assumption that water
+ * is a thing that sits under the sky. It is not: a flooded corridor, a cistern, an
+ * indoor pool and a harbour at night are all water lit entirely by lamps, and under
+ * those this shaded to flat ambient — a coloured plane, with the specular glitter that
+ * is the single strongest cue that a surface *is* water switched off because no
+ * directional source existed to make it. A lantern on a jetty threw nothing.
+ *
+ * Same slots, same weights and the same two falloff shapes as the surface shader, so a
+ * lamp behaves the same way over water as it does over the ground beside it.
+ */
+#define MAX_LIGHTS ${MAX_POINT_LIGHTS}
+uniform int uLightCount;
+uniform vec3 uLightPos[MAX_LIGHTS];
+uniform vec3 uLightColor[MAX_LIGHTS];
+uniform float uLightRadius[MAX_LIGHTS];
+uniform float uLightWeight[MAX_LIGHTS];
+uniform int uLightFalloff;
+${FOG_GLSL}
+uniform vec3 uCameraPos;
+uniform sampler2D uReflectionMap;
+uniform int uReflectionEnabled;
+uniform vec2 uReflectionTexelSize;
+uniform int uReflectionFilterTaps;
+
+const vec2 REFLECTION_FILTER[${MAX_WATER_REFLECTION_FILTER_TAPS}] = vec2[${MAX_WATER_REFLECTION_FILTER_TAPS}](
+  vec2( 0.00,  0.00), vec2(-0.62, -0.31), vec2( 0.54,  0.43),
+  vec2(-0.34,  0.76), vec2( 0.78, -0.57), vec2(-0.88,  0.28),
+  vec2( 0.22, -0.91), vec2( 0.91,  0.08), vec2(-0.18,  0.94)
+);
+// Preserve small moving silhouettes such as a character while still spreading
+// the surrounding taps enough to make the target read as rough water.
+const float REFLECTION_FILTER_WEIGHT[${MAX_WATER_REFLECTION_FILTER_TAPS}] = float[${MAX_WATER_REFLECTION_FILTER_TAPS}](
+  0.28, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09
+);
+
+out vec4 outColor;
+
+void main() {
+  vec3 n = normalize(vNormal);
+  vec3 view = normalize(uCameraPos - vWorldPos);
+
+  // Fresnel: water is nearly a mirror at grazing angles and clear straight down.
+  // abs keeps the underside physically continuous with the top instead of
+  // turning the entire surface into an opaque mirror below the waterline.
+  float facing = clamp(abs(dot(n, view)), 0.0, 1.0);
+  float fresnel = 0.02 + 0.98 * pow(1.0 - facing, 5.0);
+
+  vec3 atmosphereColor = mediumColor();
+
+  vec3 col = mix(uDeepColor, uShallowColor, clamp(vCrest * 1.4 + 0.4, 0.0, 1.0));
+  vec3 incident = uAmbient +
+    uDirectionalColor * max(dot(n, uDirectionalDir), 0.0) * 0.6;
+
+  // Specular glitter along the crests — the strongest single cue that a surface
+  // is water rather than a coloured plane.
+  vec3 halfVec = normalize(uDirectionalDir + view);
+  float spec = pow(max(dot(n, halfVec), 0.0), 220.0);
+  vec3 highlight = uDirectionalColor * spec * 1.6;
+
+  /*
+   * And the same from every lamp in range: a light over water lights it, and glitters
+   * on it. Indoors this is the whole of the surface's lighting.
+   *
+   * The exponent is the sun's, so a crest picks a lamp out as tightly as it picks out
+   * the sky — which is what makes a strip light read as a *streak* across a pool rather
+   * than a broad sheen. Weighted by presence like every other consumer of these slots,
+   * so a light entering the set fades in instead of appearing.
+   */
+  for (int i = 0; i < MAX_LIGHTS; i++) {
+    if (i >= uLightCount) break;
+    vec3 toLight = uLightPos[i] - vWorldPos;
+    float lightDist = length(toLight);
+    float falloff;
+    if (uLightFalloff == 1) {
+      float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);
+      falloff = window * window / max(lightDist * lightDist, 0.01);
+    } else {
+      falloff = clamp(1.0 - lightDist / max(uLightRadius[i], 1e-4), 0.0, 1.0);
+    }
+    if (falloff <= 0.0) continue;
+    vec3 lightDir = toLight / max(lightDist, 1e-4);
+    float shaped = falloff * uLightWeight[i];
+    incident += uLightColor[i] * max(dot(n, lightDir), 0.0) * shaped * 0.6;
+    vec3 lampHalf = normalize(lightDir + view);
+    highlight += uLightColor[i] * pow(max(dot(n, lampHalf), 0.0), 220.0) * shaped * 1.6;
+  }
+
+  col *= incident;
+  col += highlight;
+
+  // Foam where crests peak — and only when the wind is actually breaking them.
+  float foam = smoothstep(0.55, 0.85, vCrest) * uFoamGain;
+  col = mix(col, vec3(0.92, 0.96, 1.0), foam * 0.5);
+
+  float dist = distance(vWorldPos, uCameraPos);
+  float fog = mediumFog(dist, vWorldPos.y);
+  col = mix(col, atmosphereColor, fog);
+
+  // Transparency is angle-dependent, like real water: looking down you see
+  // straight through to the seabed, at grazing angles it turns reflective.
+  // This is computed before reflection because straight-alpha compositing must
+  // not attenuate reflected radiance a second time below.
+  float airOpacity = mix(uNadirOpacity, 0.96, fresnel);
+  float underwaterOpacity = mix(uNadirOpacity * 0.55, 0.88, fresnel);
+  float opacity = mix(airOpacity, underwaterOpacity, uUnderwaterFactor);
+  opacity = mix(opacity, 0.96, foam * 0.7);
+
+  // Project the displaced surface into the mirrored camera. The Gerstner
+  // displacement supplies broad distortion; the analytic normal adds the
+  // smaller ripples that make reflected silhouettes move with each crest.
+  vec3 reflected = atmosphereColor;
+  float reflectionValid = 0.0;
+  if (uReflectionEnabled != 0 && vReflectionClip.w > 0.0) {
+    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;
+    reflectionUv += n.xz * mix(0.008, 0.022, fresnel);
+    vec2 border = min(reflectionUv, 1.0 - reflectionUv);
+    reflectionValid = smoothstep(0.0, 0.025, min(border.x, border.y));
+    // A planar target is optically sharp, which is correct for a mirror but
+    // wrong for a moving water surface. Broaden it over a Poisson footprint
+    // that grows gently with viewing distance; normal displacement above
+    // still makes every crest steer that softened image independently.
+    float blurPixels = 1.35 + min(dist * 0.022, 3.5);
+    vec3 sceneReflection = vec3(0.0);
+    float filterWeight = 0.0;
+    for (int i = 0; i < ${MAX_WATER_REFLECTION_FILTER_TAPS}; i++) {
+      if (i >= uReflectionFilterTaps) break;
+      vec2 sampleUv = reflectionUv +
+        REFLECTION_FILTER[i] * uReflectionTexelSize * blurPixels;
+      float weight = REFLECTION_FILTER_WEIGHT[i];
+      /*
+       * \`textureLod\` rather than \`texture\`, by the rule \`AGENTS.md\` records on 2026-08-07:
+       * this loop is reached through a branch on \`vReflectionClip\`, which is not uniform, and
+       * an implicit derivative there is undefined. **WGSL does not merely leave it undefined,
+       * it refuses to compile the module**: *"'textureSample' must only be called from uniform
+       * control flow"*, with the note that reading \`vReflectionClip\` may be non-uniform.
+       *
+       * Bit-identical on WebGL2: \`planarReflection.ts\` allocates one level and filters
+       * \`LINEAR\`, so there is no mip to select and level zero is the only thing \`texture\`
+       * could have read.
+       */
+      sceneReflection +=
+        textureLod(uReflectionMap, clamp(sampleUv, 0.0, 1.0), 0.0).rgb * weight;
+      filterWeight += weight;
+    }
+    sceneReflection /= max(filterWeight, 0.001);
+    reflected = mix(atmosphereColor, sceneReflection, reflectionValid);
+  }
+  // The atmosphere-colour fallback preserves the old sky reflection when a
+  // quality profile disables the extra scene pass. Foam scatters rather than
+  // mirroring, so it masks the reflection at breaking crests.
+  float sceneWeight = float(uReflectionEnabled) * reflectionValid;
+  float reflectionGain = mix(0.75, 0.94, sceneWeight);
+  // Angle-honest by default, and a mirror where a body says so. See uMirror above.
+  float reflectivity = mix(fresnel, 1.0, uMirror);
+  float reflectedRadiance = min(
+    reflectivity * reflectionGain * (1.0 - foam * 0.8),
+    opacity
+  );
+  // With SRC_ALPHA blending, mixing by Fresnel directly would multiply the
+  // reflection by opacity again. Divide it out here so the framebuffer gets
+  // the intended reflected fraction while the remainder stays transmissive.
+  float reflectionWeight = reflectedRadiance / max(opacity, 0.001);
+  col = mix(col, reflected, reflectionWeight);
+
+  /*
+   * Dissolve the sheet at its own boundary.
+   *
+   * Fading on fog alone made the horizon a function of the daily palette: a
+   * clear day never reached the threshold, so the grid's rim — corner and all —
+   * became the skyline. Fading on the grid coordinate cannot fail that way,
+   * because alpha reaches zero at the last row of vertices by construction.
+   * Chebyshev distance because the sheet is a rectangle, so the fade band
+   * follows its four edges instead of cutting an ellipse out of it — and it is
+   * measured per axis, or a channel's narrow sides would be one continuous fade
+   * and it would have no visible edge at all.
+   */
+  vec2 rimFraction = abs(vGrid) / max(uGridHalf, vec2(0.001));
+  float rimT = max(rimFraction.x, rimFraction.y);
+  float rim = 1.0 - smoothstep(0.9, 1.0, rimT);
+  // Fog still helps where it is thick, it just is no longer load-bearing.
+  float edge = 1.0 - smoothstep(0.82, 1.0, fog);
+  outColor = vec4(col, opacity * edge * rim * uVisibility);
+}
+`;

package/src/render/shaders/windStreaks.ts

@@ -0,0 +1,130 @@
+/**
+ * Visible wind: streaks of dust and debris carried past the camera.
+ *
+ * Wind you cannot see is a force from nowhere. Once it pushes the player even
+ * slightly, it has to be legible — otherwise a drift in the air reads as the
+ * controls being imprecise rather than as weather, which is the worst possible
+ * reading because it blames the game's feel for something that is deliberate.
+ *
+ * Entirely GPU-side: particles live on a repeating lattice that follows the
+ * camera, so there is no spawning, no pooling, no per-frame CPU work, and no
+ * bookkeeping that could disagree with the wind everything else is using.
+ */
+export const WIND_STREAK_VERT = `#version 300 es
+layout(location = 0) in vec2 aCorner;
+layout(location = 1) in float aIndex;
+
+uniform mat4 uViewProj;
+uniform vec3 uCameraPos;
+/*
+ * No uCameraRight. It was declared here and read nowhere, which GLSL answers by optimising the
+ * location away — so the WebGL2 path never bound it and nothing was wrong. A uniform block is
+ * laid out whole, though, so the generated WGSL carried sixteen bytes of it at offset 80 and
+ * pushed everything after it along, leaving a field in the layout with no writer. That is the
+ * shape AGENTS.md 2026-08-13 is about, arriving as dead weight rather than as a bug.
+ */
+uniform vec2 uWind;
+uniform vec2 uDrift;
+uniform float uSpeed;
+uniform float uStrength;
+uniform float uCount;
+uniform float uCellSize;
+uniform float uTime;
+
+out float vFade;
+out float vAlong;
+
+void main() {
+  float id = aIndex;
+  float rx = fract(sin(id * 12.9898) * 43758.5453);
+  float ry = fract(sin(id * 39.3467) * 24634.6345);
+  float rz = fract(sin(id * 78.2330) * 12934.1234);
+
+  /*
+   * Scatter through a box that follows the camera, wrapped so a particle
+   * leaving one side re-enters the other. That wrap is what makes a finite
+   * count look like endless weather, and why nothing ever needs respawning.
+   */
+  /*
+   * Biased low. You do not see air — you see what the wind has picked up, and
+   * it picks things up from surfaces. Spreading debris evenly through a volume
+   * puts streaks at head height in open sky, which is the single thing that
+   * makes this read as an effect rather than as weather.
+   */
+  float lowBias = ry * ry;
+  vec3 cell = vec3(rx * uCellSize, lowBias * uCellSize * 0.42, rz * uCellSize);
+  vec3 base = vec3(
+    uCameraPos.x + cell.x - uCellSize * 0.5 - uDrift.x,
+    uCameraPos.y + cell.y - uCellSize * 0.3,
+    uCameraPos.z + cell.z - uCellSize * 0.5 - uDrift.y
+  );
+  vec3 rel = base - uCameraPos;
+  rel.x = mod(rel.x + uCellSize * 0.5, uCellSize) - uCellSize * 0.5;
+  rel.z = mod(rel.z + uCellSize * 0.5, uCellSize) - uCellSize * 0.5;
+  vec3 centre = uCameraPos + rel;
+
+  // Streaks lie along the wind and lengthen with it: a smear is how speed
+  // reads when the thing moving is too small to resolve.
+  vec2 alongXZ = uSpeed > 0.001 ? uWind / uSpeed : vec2(1.0, 0.0);
+  vec3 along = vec3(alongXZ.x, 0.0, alongXZ.y);
+  vec3 across = normalize(cross(along, vec3(0.0, 1.0, 0.0)));
+
+  /*
+   * Turbulent, not ruled. A dead-straight line is the giveaway that something
+   * was drawn rather than blown, so each streak curls on its own slow phase and
+   * varies in length — a gust is made of eddies, and eddies are what the eye is
+   * actually reading when it decides air is moving.
+   */
+  float curl = sin(uTime * 1.7 + id * 2.3) * 0.35 + sin(uTime * 0.9 + id) * 0.2;
+  float length = (0.18 + uSpeed * 0.09) * (0.5 + rz);
+  vec3 world = centre
+    + along * (aCorner.y * length)
+    + across * (aCorner.x * 0.012 + aCorner.y * curl * length * 0.35);
+
+  // Fade with distance from the camera so the lattice edge is never a visible
+  // boundary, and with strength so a calm day shows nothing at all.
+  float dist = distance(centre, uCameraPos);
+  /*
+   * Three fades, all of which have to hold for a streak to be visible at all:
+   * distance, so the lattice edge is never a boundary; a per-streak weight, so
+   * they are not a uniform field; and a near fade, because debris a metre from
+   * the eye is a smear across the screen rather than a cue.
+   */
+  /*
+   * Fades spread across the whole volume rather than clipped into a band.
+   *
+   * Narrow near and far fades carve a spherical shell out of the lattice, and a
+   * shell centred on the camera is seen as a curtain hanging in front of the
+   * player — every particle at roughly the same distance, moving together. The
+   * cure is depth: a long ramp at both ends, so density falls away gradually
+   * and no distance is privileged.
+   */
+  float far = 1.0 - smoothstep(uCellSize * 0.12, uCellSize * 0.5, dist);
+  float near = smoothstep(2.0, 16.0, dist);
+  // Most particles are faint; a few carry the effect. A uniform field is a veil.
+  float weight = rx * rx * rx;
+  vFade = uStrength * far * near * weight;
+  vAlong = aCorner.y * 0.5 + 0.5;
+
+  gl_Position = uViewProj * vec4(world, 1.0);
+}
+`;
+
+export const WIND_STREAK_FRAG = `#version 300 es
+precision highp float;
+
+in float vFade;
+in float vAlong;
+uniform vec3 uTint;
+out vec4 outColor;
+
+void main() {
+  // Tapered at both ends, so a streak reads as motion rather than as a stick.
+  // Squared taper: a streak should be a smear that thins to nothing, not a
+  // capsule with visible ends.
+  float taper = sin(vAlong * 3.14159);
+  float alpha = vFade * taper * taper * 0.13;
+  if (alpha <= 0.002) discard;
+  outColor = vec4(uTint, alpha);
+}
+`;

package/src/render/shadowCasters.ts

@@ -0,0 +1,124 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { InstanceData } from './instancedMesh.ts';
+import type { InstancedHandle, MeshHandle, ScatterHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+import type { SurfaceTextureHandle } from './backend/api.ts';
+
+/**
+ * What a shadow-caster enumeration may hand to a depth pass.
+ *
+ * **Occluding light and stopping a body are two independent properties of a piece
+ * of geometry, and this interface exists to keep them apart.** The set that
+ * collides is a physics question; the set that casts is an optics one. They overlap
+ * heavily — most solid things do both — but neither contains the other, and a
+ * renderer that derives one from the other gets a whole class of geometry wrong in
+ * one stroke.
+ *
+ * The failure this was written for: a tree's canopy is deliberately not a collider
+ * (nothing should be halted mid-run by leaves) and is therefore not merged into the
+ * static world mesh either, because it bends in the wind and merged geometry cannot.
+ * The only thing a depth pass could accept was a rigid `Mesh`, so the canopy had no
+ * way in — and a crown that occludes nothing reads as sunlight passing straight
+ * through several metres of solid foliage. Nothing was switched off; there was
+ * simply no route for that kind of geometry to travel.
+ *
+ * So a sink takes both kinds. A caller enumerates what casts, once, and the same
+ * enumeration serves the directional cascade and every point-light cubemap.
+ *
+ * **Every draw may also carry its material, which is what lets one enumeration serve a colour
+ * pass as well as a depth one.** A depth pass ignores it, correctly: a material cannot change a
+ * depth, which is why this interface was right to carry only a handle, a matrix and a palette for
+ * as long as depth was the only thing replaying it. What that cost was measured from outside. A
+ * consumer wanting the scene from a second viewpoint — a mirror, a probe face — had one option,
+ * which was to run its whole draw path again; the first attempt to avoid it replayed this sink
+ * into the mirror and got **every car unpainted**, because the list carries no material. So the
+ * game re-enters its own draw with a mirrored camera, and pays its heaviest phase twice.
+ *
+ * Optional, and for the reason `instanced` gives at length: this interface is implemented
+ * outwards, so a required parameter added in a minor stops every consumer's sink and every test
+ * double compiling. A sink that ignores it behaves exactly as it did.
+ */
+export type SceneCasterMaterial = SurfaceMaterial<SurfaceTextureHandle> | null;
+
+export interface ShadowCasterSink {
+  /** A rigid mesh at a model transform: the world, a prop, a static piece of scenery. */
+  mesh(mesh: MeshHandle, model: ReadonlyMat4, material?: SceneCasterMaterial): void;
+  /**
+   * A skinned mesh, deformed by the same palette the visible draw uses.
+   *
+   * **The palette is not optional in spirit**, for the reason `scatter` below 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 submitted through `mesh` does not drift
+   * slightly — it casts its **bind pose**, so a running figure throws the shadow of a statue.
+   *
+   * Sixteen floats a joint, column-major, exactly as `Skeleton.palette` produces.
+   */
+  skinnedMesh(
+    mesh: MeshHandle,
+    model: ReadonlyMat4,
+    palette: Float32Array,
+    material?: SceneCasterMaterial,
+  ): void;
+  /**
+   * An instanced batch of rigid meshes, placed by the same matrices the visible draw uses.
+   *
+   * **Not optional in spirit, for the reason `scatter` gives about the wind**: a batch whose
+   * depth pass read a different placement casts shadows that have come loose from the things
+   * casting them — and a batch submitted through `mesh` instead casts *one* shadow, from
+   * whichever matrix happened to be bound, with the other twenty-nine missing entirely.
+   *
+   * **Optional in the type, and only because this interface is implemented outwards.** A
+   * consumer's own sinks and its test doubles satisfy this type, so a required member added in a
+   * minor stops every one of them compiling — which is what happened: 3.29.0 broke three test
+   * doubles in a consumer that has no instanced batches at all. The renderer always supplies
+   * it, so `sink.instanced?.(batch, data)` never actually skips, and a consumer written before
+   * instanced draws existed has nothing to declare through it.
+   */
+  instanced?(batch: InstancedHandle, data: MeshInstances, material?: SceneCasterMaterial): void;
+  /**
+   * A scatter batch, deformed exactly as the visible draw deforms it.
+   *
+   * The wind and press arguments are the same values the matching `drawScatter`
+   * receives, and they are not optional in spirit: handing the depth pass a
+   * different gust from the colour pass is how a shadow comes loose from its
+   * caster. Positional rather than a bundled object, so a per-frame call site
+   * allocates nothing.
+   */
+  scatter(
+    scatter: ScatterHandle,
+    data: InstanceData,
+    windX: number,
+    windZ: number,
+    windGust: number,
+    timeSeconds: number,
+    trample?: Float32Array | null,
+  ): void;
+}
+
+/**
+ * A caller-supplied enumeration of everything that casts.
+ *
+ * Called once per directional layer and once per cubemap face, so it must be
+ * allocation-free — close over the meshes and read them, never build a list.
+ */
+export type ShadowCasters = (sink: ShadowCasterSink) => void;
+
+/**
+ * Replay a caster enumeration into the colour pass that is open, materials and all.
+ *
+ * The counterpart of `drawShadowCasters`, and the reason `ShadowCasterSink` carries a material at
+ * all. A consumer enumerates what its frame contains once and hands the same closure to the
+ * shadow cascade, to every cubemap face, and to a mirror or a probe face — rather than re-entering
+ * its own draw path with a second camera, which is what the alternative costs: a consumer
+ * measures the phase it would run twice at 2.3 to 9.4 ms, the largest single row in its frame.
+ *
+ * **Scatter is declined rather than drawn**, and visibly. A scatter batch's colour draw needs the
+ * camera and the environment of the frame it is being drawn into, and this enumeration carries
+ * neither — it records what a thing *is*, not what the pass around it looks like. Handing the
+ * colour path a stale camera would put the grass of the last pass into this one, which is the
+ * silent-plausible-picture failure the two-backends rule exists to forbid. So a replayed pass has
+ * no scatter in it, the absence is in the picture rather than in a comment, and a caller wanting
+ * grass in a mirror draws it itself with the camera it already has.
+ */
+export type SceneCasters = ShadowCasters;