reze-engine 0.43.0 → 0.50.0

package/src/shaders/passes/grid.ts

@@ -0,0 +1,178 @@
+import { audioApi } from "../audio-api"
+import { lyricsApi } from "../lyrics-api"
+import { anchorAliasWgsl } from "../anchor-table"
+import { midiApi } from "../midi-api"
+import { EFFECT_SCENE_API } from "./composite"
+import { type CastLayout } from "./particles"
+import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
+
+// A persistent grid an effect can step and read: the one thing an effect could
+// not have before, which is MEMORY.
+//
+// Every other mount is a pure function of position and time. A field shader
+// recomputes its noise from scratch every frame; a trail reads history the
+// engine happens to keep. Neither can build on what it produced last frame, and
+// a whole class of effect is nothing but that:
+//
+//   Fog that a dancer walks through does not "look displaced near her" — it IS
+//   displaced, and stays displaced, and creeps back over seconds. Water does not
+//   look rippled where a foot landed; a ripple leaves and propagates and
+//   reflects off the far edge long after the foot is gone. Both are the same
+//   shape of thing — a grid, stepped by its own previous value.
+//
+// It is also the only way to get the LOOK of a fluid, not merely its motion.
+// Advection compounds: each frame's field is the last one pushed sideways, and a
+// few hundred frames of that stretches and folds a smooth field into filaments
+// and vortex sheets finer than the grid storing them. No noise function
+// produces that, at any octave count, because the structure is not a function of
+// position at all — it is a function of history.
+//
+// The engine owns the ping-pong, the dispatch and the sampling. The author owns
+// the KERNEL, which is the part that differs: advection for smoke, the wave
+// equation for water, a decaying stamp for footprints. That split is the same
+// one the particle mounts make, and for the same reason — the loop is identical
+// in every such effect and the physics never is.
+
+// A megatexel of rgba16float is 8MB, and two of those is the whole cost. What
+// actually bounds this is the STEP: one invocation per texel per frame, each
+// taking a dozen samples, so doubling the side quadruples the work.
+export const GRID_MAX = 1024
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export const SIM_FORMAT: GPUTextureFormat = "rgba16float"
+
+/** `// @grid 256` — the grid's resolution, in texels per side. */
+export function parseGridSize(wgsl: string, max: number): number {
+  const m = /^\s*\/\/\s*@grid\s+(\d+)\s*$/m.exec(wgsl)
+  if (!m) return 0
+  // Clamped rather than rejected, as the particle count is: an author asking for
+  // 4096 gets the most the engine will give and a scene that still runs.
+  return Math.max(8, Math.min(max, parseInt(m[1], 10)))
+}
+
+/** Whether this effect drives a grid at all. */
+export function gridEntryPoint(wgsl: string): boolean {
+  return /\bfn\s+gridStep\s*\(/.test(wgsl)
+}
+
+/**
+ * `rzGrid(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export function gridReadApi(group: number, tex: number, samp: number, size: number): string {
+  return /* wgsl */ `
+const RZ_GRID_SIZE: f32 = ${size > 0 ? size : 1}.0;
+@group(${group}) @binding(${tex}) var _rzGridTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzGridSamp: sampler;
+
+/**
+ * The grid, bilinearly sampled. uv is 0..1 across it, and what that MEANS in
+ * the world is the effect's own business — the engine deliberately does not
+ * impose a mapping, because a fog laid over a stage and a ripple field around a
+ * character want different ones and both are two lines of arithmetic.
+ */
+fn rzGrid(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzGridTex, _rzGridSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+fn rzGridSize() -> f32 { return RZ_GRID_SIZE; }
+fn rzGridTexel() -> f32 { return 1.0 / RZ_GRID_SIZE; }
+
+// ── The step-only half, defined here too and never called here ──
+//
+// One effect file is spliced into EVERY module it has a mount in, so a file
+// with a grid compiles its gridStep inside the field and particle shaders as
+// well — where it is dead code that nothing calls, but still code that has to
+// resolve. Leaving these out is a compile error on a function the author was
+// right to write. rzGridPrev reads the current grid rather than a previous one,
+// which is the honest answer outside the step: there is no previous frame here.
+fn rzGridPrev(uv: vec2f) -> vec4f { return rzGrid(uv); }
+fn rzGridFrame() -> i32 { return 1; }
+`
+}
+
+const SIM_UNIFORMS = /* wgsl */ `
+struct SimU {
+  time: f32,
+  dt: f32,
+  size: f32,
+  frame: f32,
+}
+`
+
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export function buildSimShader(wgsl: string, size: number, cast: CastLayout): string {
+  return (
+    SIM_UNIFORMS +
+    /* wgsl */ `
+@group(0) @binding(0) var<uniform> su: SimU;
+@group(0) @binding(1) var _rzGridPrevTex: texture_2d<f32>;
+@group(0) @binding(2) var _rzGridSamp: sampler;
+@group(0) @binding(3) var _rzGridOut: texture_storage_2d<${SIM_FORMAT}, write>;
+@group(0) @binding(4) var<storage, read> _rzCast: array<vec4f>;
+// The same view uniform the composite reads, so the scene API below is the real
+// thing here rather than a stub — a kernel can ask where a bone is, and a
+// foreground spliced into this module resolves its camera calls.
+@group(0) @binding(6) var<uniform> viewU: array<vec4<f32>, 15>;
+${clockApi("su.time", "su.dt")}${viewportApi("viewU[6].w")}${trailSlotsApi(cast.trailCount)}
+/** Texels per side. */
+fn rzGridSize() -> f32 { return su.size; }
+/** One texel, in uv — the step a neighbour lookup takes. */
+fn rzGridTexel() -> f32 { return 1.0 / su.size; }
+/**
+ * Steps since this effect was installed. Zero on the very first one, which is
+ * the only chance to seed a grid: everything after it builds on what is there.
+ */
+fn rzGridFrame() -> i32 { return i32(su.frame); }
+
+/** The grid as it was LAST frame, bilinear. The only input a kernel really has. */
+fn rzGridPrev(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzGridPrevTex, _rzGridSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+` +
+    EFFECT_SCENE_API +
+    // The alias _rzSlot, which the scene API's accessors route through. Every
+    // module embedding EFFECT_SCENE_API must splice this; the sim module was
+    // the one that did not, and every gridStep effect failed to install with
+    // "unresolved call target" from the day the identity fallback was removed.
+    // Found by tools/validate-wgsl.mjs on its first run.
+    anchorAliasWgsl(cast.alias) +
+    audioApi(0, 5) +
+    midiApi(0, 7) +
+    lyricsApi(0, 8) +
+    // rzGrid itself, so a kernel may read the grid it is writing — through the
+    // PREVIOUS frame's texture, which is the only version of it that exists
+    // while the current one is still being written.
+    /* wgsl */ `
+fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
+` +
+    "\n// ── user effect (setEffect) ──\n" +
+    wgsl +
+    /* wgsl */ `
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let n = u32(${size});
+  if (gid.x >= n || gid.y >= n) { return; }
+  let xy = vec2i(i32(gid.x), i32(gid.y));
+  // The texel CENTRE, so a kernel that reads its own uv back through rzGridPrev
+  // lands on itself rather than a quarter-texel off.
+  let uv = (vec2f(f32(gid.x), f32(gid.y)) + vec2f(0.5)) / su.size;
+  textureStore(_rzGridOut, xy, gridStep(uv, textureLoad(_rzGridPrevTex, xy, 0), su.dt));
+}
+`
+  )
+}

package/src/shaders/passes/ground.ts

@@ -1,23 +1,49 @@
+import { sceneFsOutWgsl, sceneIdWriteWgsl } from "./scene-contract"
+import { lightsApi } from "../lights"
+import { SHADOW_CASCADES } from "../../shadow-cascades"
+import { WORLD_AMBIENT_WGSL } from "../lights"
+
 // Ground shadow-catcher: receives directional shadow, grid lines, frosted noise,
 // radial distance fade. Writes bloom mask = 0 (ground never bloom-bleeds).
+//
+// A FUNCTION, not a constant, since the id attachment is a device capability:
+// the struct this returns depends on what the probe at init found, and a string
+// baked at import time cannot know that. Called once, when the module is built.
 
-export const GROUND_SHADOW_SHADER_WGSL = /* wgsl */ `
+export function groundShaderWgsl(): string {
+  return /* wgsl */ `
 struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
 struct Light { direction: vec4f, color: vec4f, };
-struct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, };
+struct LightUniforms { ambientColor: vec4f, lights: array<Light, 4>, sh: array<vec4f, 9>, };
 struct GroundShadowMat {
   diffuseColor: vec3f, fadeStart: f32,
   fadeEnd: f32, shadowStrength: f32, pcfTexel: f32, gridSpacing: f32,
   gridLineWidth: f32, gridLineOpacity: f32, noiseStrength: f32, opacity: f32,
-  gridLineColor: vec3f, _pad2: f32,
+  gridLineColor: vec3f, mirror: f32,
+  mirrorBlur: f32, _mb0: f32, _mb1: f32, _mb2: f32,
 };
-struct LightVP { viewProj: mat4x4f, };
+// One view-projection per shadow cascade, inner to outer — same buffer and
+// same order the materials read.
+struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 @group(0) @binding(0) var<uniform> camera: CameraUniforms;
 @group(0) @binding(1) var<uniform> light: LightUniforms;
 @group(0) @binding(2) var shadowMap: texture_depth_2d;
 @group(0) @binding(3) var shadowSampler: sampler_comparison;
 @group(0) @binding(4) var<uniform> material: GroundShadowMat;
 @group(0) @binding(5) var<uniform> lightVP: LightVP;
+// The far cascade's map, binding 7 as in the materials' layout.
+@group(0) @binding(7) var shadowMapFar: texture_depth_2d;
+// The floor mirror (step 7D): the reflection target, the camera that rendered
+// it, and an ordinary sampler — the two shadow bindings above are comparison.
+// params = (projA, projB, _, _) — the depth-linearisation pair of the SHARED
+// projection, refreshed per frame beside the matrix.
+struct MirrorVP { viewProj: mat4x4f, params: vec4f, };
+@group(0) @binding(8) var<uniform> mirrorVP: MirrorVP;
+@group(0) @binding(9) var mirrorTex: texture_2d<f32>;
+@group(0) @binding(10) var linearSampler: sampler;
+@group(0) @binding(11) var mirrorDepth: texture_depth_multisampled_2d;
+${WORLD_AMBIENT_WGSL}
+${lightsApi(0, 6)}
 
 fn hash2(p: vec2f) -> f32 {
   var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);
@@ -48,8 +74,7 @@ struct VO { @builtin(position) position: vec4f, @location(0) worldPos: vec3f, @l
   var o: VO; o.worldPos = position; o.normal = normal;
   o.position = camera.projection * camera.view * vec4f(position, 1.0); return o;
 }
-struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
-@fragment fn fs(i: VO) -> FSOut {
+${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // Derivatives first, unconditionally: WGSL requires fwidth in uniform control
   // flow and everything below branches on world position.
   let gp = i.worldPos.xz / material.gridSpacing;
@@ -68,15 +93,20 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
     return out;
   }
 
-  let lclip = lightVP.viewProj * vec4f(i.worldPos, 1.0);
-  let ndc = lclip.xyz / max(lclip.w, 1e-6);
-  // Outside the light's frustum there IS no shadow information — the clamped
+  // Outside a cascade's frustum there IS no shadow information — the clamped
   // border samples compare against unrelated depths and read "shadowed",
   // darkening the whole far plane with a visible band at the frustum edge
   // (masked by the opaque surface normally, glaring in green-screen mode where
-  // only the shadow-catcher term renders). Fade to fully lit near the border.
+  // only the shadow-catcher term renders). So each cascade fades out near its
+  // border — the near one INTO the far one's answer, the far one into lit.
+  let l0 = lightVP.viewProj[0] * vec4f(i.worldPos, 1.0);
+  let ndc = l0.xyz / max(l0.w, 1e-6);
   let inZ = select(0.0, 1.0, ndc.z > 0.0 && ndc.z < 1.0);
   let frustum = (1.0 - smoothstep(0.88, 0.96, abs(ndc.x))) * (1.0 - smoothstep(0.88, 0.96, abs(ndc.y))) * inZ;
+  let l1 = lightVP.viewProj[1] * vec4f(i.worldPos, 1.0);
+  let ndc1 = l1.xyz / max(l1.w, 1e-6);
+  let inZ1 = select(0.0, 1.0, ndc1.z > 0.0 && ndc1.z < 1.0);
+  let frustum1 = (1.0 - smoothstep(0.88, 0.96, abs(ndc1.x))) * (1.0 - smoothstep(0.88, 0.96, abs(ndc1.y))) * inZ1;
 
   // THE cost of this shader, measured: a full-screen ground ran 25 shadow
   // comparisons per pixel, and each one is hardware-bilinear, so ~100 depth
@@ -88,10 +118,23 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
   // almost entirely once the comparison sampler's own 2x2 filter is counted.
   // Nine taps instead of twenty-five for the same blur radius.
   //
-  // Skipped altogether outside the light frustum, where the mix below discards
-  // the result anyway: the shadow map covers a small area around the character
-  // and the ground is vastly larger than it.
+  // The far cascade's taps run ONLY where the near one is fading or absent
+  // (frustum < 1), so a pixel in the near core costs exactly what it did with
+  // one cascade — and that core is where the camera usually looks.
   var vis = 1.0;
+  if (frustum < 1.0 && frustum1 > 0.0) {
+    let suv1 = vec2f(ndc1.x * 0.5 + 0.5, 0.5 - ndc1.y * 0.5);
+    let suv1_c = clamp(suv1, vec2f(0.02), vec2f(0.98));
+    let st1 = ${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize} * 2.0;
+    let compareZ1 = ndc1.z - 0.0035;
+    var acc1 = 0.0;
+    for (var y = -1; y <= 1; y++) {
+      for (var x = -1; x <= 1; x++) {
+        acc1 += textureSampleCompareLevel(shadowMapFar, shadowSampler, suv1_c + vec2f(f32(x), f32(y)) * st1, compareZ1);
+      }
+    }
+    vis = mix(1.0, acc1 * (1.0 / 9.0), frustum1);
+  }
   if (frustum > 0.0) {
     let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
     let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));
@@ -105,7 +148,9 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
         acc += textureSampleCompareLevel(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);
       }
     }
-    vis = mix(1.0, acc * (1.0 / 9.0), frustum);
+    // The base is whatever the far cascade decided, so the near border blends
+    // cascade to cascade rather than snapping to lit mid-floor.
+    vis = mix(vis, acc * (1.0 / 9.0), frustum);
   }
 
   // Frosted/matte micro-texture. Scenes leaving it at zero were still paying
@@ -123,24 +168,126 @@ struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
     smoothstep(halfLine - gridDeriv.x, halfLine + gridDeriv.x, gridFrac.x),
     smoothstep(halfLine - gridDeriv.y, halfLine + gridDeriv.y, gridFrac.y)
   );
-  let sun = light.ambientColor.xyz + light.lights[0].color.xyz * light.lights[0].color.w * max(dot(n, -light.lights[0].direction.xyz), 0.0);
+  let sun = rzWorldAmbient(n) + light.lights[0].color.xyz * light.lights[0].color.w * max(dot(n, -light.lights[0].direction.xyz), 0.0);
+  // The positional layer reaches the floor too. A stage light that lit the
+  // cast and not the ground under her would read as a sticker, which is the
+  // same failure the shadow catcher exists to prevent.
+  let lamps = rzLightsDiffuse(i.worldPos, n);
   let dark = (1.0 - vis) * material.shadowStrength;
-  var baseColor = material.diffuseColor * sun * (1.0 - dark * 0.65);
+  // The shadow darkens the SUN only. The dark term comes from the sun's shadow
+  // map, so applying it to the lamps too would have a lamp on the far side of
+  // the stage dimmed by a shadow cast away from it — the one light in the scene
+  // that provably is not blocking it.
+  // (No backticks in here: this string is a TS template literal and one ends it
+  // mid-shader, which is exactly how this line broke the build a moment ago.)
+  var baseColor = material.diffuseColor * (sun * (1.0 - dark * 0.65) + lamps);
   baseColor *= noiseTint;
-  let finalColor = mix(baseColor, material.gridLineColor, gridLine * material.gridLineOpacity * edgeFade);
-  // Whole-ground opacity fades the SURFACE (color, grid) but the shadow stays —
-  // as opacity drops, the received shadow becomes a translucent dark layer
-  // (Blender's Shadow Catcher), so models still feel grounded on a photo or
-  // 360 backdrop. At opacity 1 this reduces exactly to the plain surface.
+  // The floor mirror — its OWN LAYER, not a blend into the surface. The
+  // reflection was rendered by the MIRROR camera, so projecting this
+  // fragment's world position through that camera yields exactly the texel
+  // where its reflection landed — projective mapping, no screen-space guess.
+  // There is deliberately NO strength dial: mirror is on or off, and how much
+  // of it shows is the SURFACE's own opacity covering it — the same
+  // independence the grid won earlier. The branch is on a uniform, so the
+  // whole cost vanishes for the scenes that leave it off.
+  var reflShadowed = vec3f(0.0);
+  if (material.mirror > 0.0) {
+    let mc = mirrorVP.viewProj * vec4f(i.worldPos, 1.0);
+    let mndc = mc.xyz / max(mc.w, 1e-6);
+    let muv = clamp(vec2f(mndc.x * 0.5 + 0.5, 0.5 - mndc.y * 0.5), vec2f(0.0), vec2f(1.0));
+    var lod = 0.0;
+    if (material.mirrorBlur > 0.0) {
+      // DEPTH-PROPORTIONAL softness: the real driver is how far BEHIND the
+      // mirror surface the reflected geometry sits — a foot on the floor
+      // reflects sharp, a head reflects soft, the empty backdrop softest.
+      //
+      // Read the mirror pass's own depth at this texel, linearise it with the
+      // shared projection's pair (viewZ = projB / (z - projA); the formula
+      // inverts both depth conventions, see the composite's linearDepth), and
+      // reconstruct the reflected image point along the ray from the MIRRORED
+      // eye through this fragment. The plane is y = 0, so mirroring the eye
+      // and the camera forward is a sign flip on y, and the image point's
+      // depth below the plane IS the reflected object's height above it.
+      let dims = vec2f(textureDimensions(mirrorDepth));
+      let texel = clamp(vec2i(muv * dims), vec2i(0), vec2i(dims) - vec2i(1));
+      let z = textureLoad(mirrorDepth, texel, 0);
+      let viewZ = clamp(mirrorVP.params.y / (z - mirrorVP.params.x), 0.05, 100000.0);
+      let eyeM = vec3f(camera.viewPos.x, -camera.viewPos.y, camera.viewPos.z);
+      let fwd = vec3f(camera.view[0][2], camera.view[1][2], camera.view[2][2]);
+      let fwdM = vec3f(fwd.x, -fwd.y, fwd.z);
+      let toFrag = i.worldPos - eyeM;
+      let dir = toFrag * inverseSqrt(max(dot(toFrag, toFrag), 1e-8));
+      let t = viewZ / max(dot(dir, fwdM), 1e-4);
+      let height = max(-(eyeM.y + dir.y * t), 0.0);
+      // Full softness by BLUR_SPAN units above the floor — about a character's
+      // height. The hardware clamps the level, so the nominal 5.0 needs no
+      // knowledge of the real chain length, and blur 0 reads exactly level 0.
+      let BLUR_SPAN = 14.0;
+      lod = material.mirrorBlur * 5.0 * clamp(height / BLUR_SPAN, 0.0, 1.0);
+    }
+    let refl = textureSampleLevel(mirrorTex, linearSampler, muv, lod).rgb;
+    // Still under the received shadow: a polished floor in shade shows a dim
+    // reflection, and a mirror that ignored the shadow would glow in it.
+    reflShadowed = refl * (1.0 - dark * 0.65);
+  }
+  // THREE LAYERS, composited premultiplied, bottom to top: the shadow the
+  // catcher receives, the ground surface, and the grid.
+  //
+  // The grid used to be MIXED INTO the surface and then weighted by the
+  // surface's own alpha, so turning the ground down to nothing took the grid
+  // with it — you could not have a bare grid over a photo, which is most of
+  // what a grid is for. It is its own layer now: the ground plane keeps an
+  // alpha, and the grid is simply on or off.
   let surfA = edgeFade * material.opacity;
-  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity);
-  let outA = surfA + catchA;
-  out.color = vec4f(finalColor * surfA, outA);
+  let gridA = gridLine * material.gridLineOpacity * edgeFade;
+  // The mirror is opaque across the ground's extent when on — it always shows
+  // SOMETHING, because the backdrop rides in the reflection target itself.
+  let mirrA = material.mirror * edgeFade;
+  // As opacity drops the received shadow becomes a translucent dark layer
+  // (Blender's Shadow Catcher), so models still feel grounded on a photo or a
+  // 360 backdrop. Colourless by construction: it darkens by covering. The
+  // MIRROR subsumes it: the reflection already carries the received shadow,
+  // and a catcher stacked on top would darken the same shadow twice.
+  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity) * (1.0 - material.mirror);
+
+  // FOUR LAYERS, premultiplied, bottom to top: reflection, received shadow,
+  // ground surface, grid. Each with its own coverage, none scaling another —
+  // ground opacity REVEALS the mirror rather than the mirror carrying a
+  // strength of its own.
+  var pm = reflShadowed * mirrA;
+  var cov = mirrA;
+  // Shadow catcher over the reflection-or-nothing: black, it covers.
+  pm = pm * (1.0 - catchA);
+  cov = catchA + cov * (1.0 - catchA);
+  // Surface over shadow.
+  pm = baseColor * surfA + pm * (1.0 - surfA);
+  cov = surfA + cov * (1.0 - surfA);
+  // Grid over surface. Unshadowed, as it has always been — a painted line reads
+  // as paint, and darkening it was never what the mix did either.
+  pm = material.gridLineColor * gridA + pm * (1.0 - gridA);
+  cov = gridA + cov * (1.0 - gridA);
+
+  let outA = cov;
+  out.color = vec4f(pm, outA);
   // mask.r = 0: ground never contributes to bloom. mask.g = 1.0 with src.a =
   // outA turns the aux blend into alpha-over, so the drawable alpha goes
   // from outA at the center to 0 at the radial edge — letting the page
   // background show through under the premultiplied canvas alphaMode.
   out.mask = vec4f(0.0, 1.0, 0.0, outA);
-  return out;
+${sceneIdWriteWgsl("out", `${GROUND_MATERIAL_ID}u`, `${GROUND_OBJECT_ID}u`)}  return out;
 }
 `
+}
+
+/**
+ * The ground belongs to no model instance, so it takes ids of its own — at the
+ * TOP of the u16 range, not at the bottom.
+ *
+ * Both of the engine's counters are 1-based (model id is instance count + 1,
+ * material id counts from one), so 1 is the first model's first material and
+ * the floor would have shared it. 0 stays unclaimed in the other direction: it
+ * is what the attachment clears to, and so what every pixel nothing drew
+ * reports.
+ */
+export const GROUND_MATERIAL_ID = 0xffff
+export const GROUND_OBJECT_ID = 0xffff

package/src/shaders/passes/hosted-api.ts

@@ -0,0 +1,171 @@
+// The half of the effect API whose VALUES are module-local.
+//
+// An effect file is spliced WHOLE into every module it has a mount in. A file
+// with a trail and a lightEmit compiles its trail code inside the light module,
+// where it never runs but still has to resolve — so `rzTime()` has to exist
+// there even though a compute pass that writes lamp positions has no obvious
+// clock, and `rzFalloff()` has to exist there even though nothing calls it.
+//
+// EFFECT_SCENE_API (composite.ts) is the other half: names that mean the same
+// thing everywhere, written once. These are the ones that cannot be, because
+// each module keeps its clock and its viewport in a different uniform. So they
+// are written once HERE and the expression is the parameter — which is the
+// same trick the grid pass already used for one of them, generalised to all.
+//
+// The rule this file exists to make keepable: a hosting module includes every
+// block below. Not the ones its own mount happens to need — every one, because
+// what lands in it is the author's whole file.
+//
+// EXCEPT that EFFECT_SCENE_API already carries EFFECT_MATH_API and the Particle
+// struct, so the three modules built on it take those two by inheritance and
+// must not add them again. tests/hosted-api.test.mjs fails on a name declared
+// twice for exactly this reason — it is the mistake sharing blocks invites.
+
+/**
+ * The particle record, laid out by hand — declared in EVERY hosting module.
+ *
+ * Not only in the particle ones: `fn particleStep(p: Particle)` is part of the
+ * author's file, so the trail, field and lightEmit modules compile that
+ * signature as dead code and a missing struct is a compile error on a function
+ * the author was right to write. The trail module used to carry a hand-copied
+ * duplicate for exactly this reason.
+ *
+ * `age` and `life` sit in the padding that vec3f alignment would waste anyway
+ * (a vec3f occupies 12 bytes but aligns the next field to 16), so the struct is
+ * 48 bytes rather than the 64 a naive ordering costs. At 4096 particles that is
+ * 192KB instead of 256KB, and it is read every frame by both stages.
+ *
+ * `life <= 0` means "not alive" and is what the pool checks to recycle a slot,
+ * so a freshly zeroed buffer is entirely dead and every particle is born on the
+ * first step rather than needing a separate seeding pass.
+ *
+ * RzLight is the same kind of thing and lives in lights.ts, because it is that
+ * module's own type; every hosting module splices it for this same reason.
+ */
+export const PARTICLE_STRUCT_WGSL = /* wgsl */ `
+struct Particle {
+  pos: vec3f,
+  age: f32,
+  vel: vec3f,
+  life: f32,
+  size: f32,
+  rot: f32,
+  seed: f32,
+  // Aspect along the direction of travel. 1 or less is a square billboard; a
+  // raindrop is 10 or 20. Zero-initialised, so an effect that never sets it gets
+  // the square it expects.
+  stretch: f32,
+}
+`
+
+/**
+ * `rzTime`/`rzDt`, from whatever the module calls its clock.
+ *
+ * A module with no clock of its own passes a literal. Zero dt is honest there:
+ * nothing spliced into it is being stepped, so a kernel that integrates would
+ * integrate by nothing rather than by a plausible-looking wrong number.
+ */
+export function clockApi(timeExpr: string, dtExpr: string): string {
+  return /* wgsl */ `
+fn rzTime() -> f32 { return ${timeExpr}; }
+fn rzDt() -> f32 { return ${dtExpr}; }
+`
+}
+
+/** `rzViewportHeight` — the render target's height in pixels, which is what a
+ *  point size in world units has to be divided by to become a pixel radius. */
+export function viewportApi(heightExpr: string): string {
+  return /* wgsl */ `
+fn rzViewportHeight() -> f32 { return ${heightExpr}; }
+`
+}
+
+/**
+ * The one cast number that is PER EFFECT rather than per engine.
+ *
+ * Author-visible, and published effects loop over it, so its meaning is pinned:
+ * how many of THIS effect's anchors asked for a trail. Deliberately not the
+ * anchor address space — that is RZ_MAX_ANCHORS in CAST_API, and the two being
+ * one number was the old trail bug. Everything else about the cast's shape is a
+ * constant and lives there.
+ */
+export function trailSlotsApi(trailCount: number): string {
+  return /* wgsl */ `
+const RZ_TRAIL_SLOTS: i32 = ${trailCount};
+`
+}
+
+/**
+ * Pure math — no bindings, no uniforms, identical in every module.
+ *
+ * These were duplicated in the particle and trail modules, byte for byte in the
+ * case of rzFalloff and to a `+ vec3f(0.0)` in the case of rzValueNoise. Two
+ * copies of a noise function is one bad merge away from an effect that looks
+ * different depending on which mount drew it, which is not a bug anyone would
+ * think to look for.
+ *
+ * EVERY hosting module includes this and none defines any of these itself, so
+ * "which module am I in" can never change what a helper returns.
+ */
+export const EFFECT_MATH_API = /* wgsl */ `
+fn rzHash11(x: f32) -> f32 {
+  var p = fract(x * 0.1031);
+  p = p * (p + 33.33);
+  return fract(p * (p + p));
+}
+fn rzHash21(p: vec2f) -> f32 {
+  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);
+  p3 = p3 + dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+/** Three independent randoms from one seed — the usual need when spawning. */
+fn rzHash13(x: f32) -> vec3f {
+  return vec3f(rzHash11(x), rzHash11(x + 17.13), rzHash11(x + 41.71));
+}
+/**
+ * Compact-support falloff: 1 at the centre, exactly 0 at r, smooth between.
+ *
+ * It reaches exactly zero rather than merely getting small, because a glow that
+ * never quite ends has to be culled somewhere, and culling it wherever it looks
+ * close enough is what put a visible hard edge on the first halo effect.
+ */
+fn rzFalloff(d: f32, r: f32) -> f32 {
+  let x = clamp(d / max(r, 1e-6), 0.0, 1.0);
+  let f = 1.0 - x;
+  return f * f * f;
+}
+fn rzHash31(p: vec3f) -> f32 {
+  var p3 = fract(p * 0.1031);
+  p3 = p3 + dot(p3, p3.zyx + 31.32);
+  return fract((p3.x + p3.y) * p3.z);
+}
+fn rzValueNoise(p: vec3f) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let u = f * f * (3.0 - 2.0 * f);
+  let n000 = rzHash31(i);
+  let n100 = rzHash31(i + vec3f(1.0, 0.0, 0.0));
+  let n010 = rzHash31(i + vec3f(0.0, 1.0, 0.0));
+  let n110 = rzHash31(i + vec3f(1.0, 1.0, 0.0));
+  let n001 = rzHash31(i + vec3f(0.0, 0.0, 1.0));
+  let n101 = rzHash31(i + vec3f(1.0, 0.0, 1.0));
+  let n011 = rzHash31(i + vec3f(0.0, 1.0, 1.0));
+  let n111 = rzHash31(i + vec3f(1.0, 1.0, 1.0));
+  let x00 = mix(n000, n100, u.x);
+  let x10 = mix(n010, n110, u.x);
+  let x01 = mix(n001, n101, u.x);
+  let x11 = mix(n011, n111, u.x);
+  return mix(mix(x00, x10, u.y), mix(x01, x11, u.y), u.z);
+}
+/** Divergence-free flow — the field a wisp of smoke follows without a solver. */
+fn rzCurlNoise(p: vec3f) -> vec3f {
+  let e = 0.1;
+  let dx = vec3f(e, 0.0, 0.0);
+  let dy = vec3f(0.0, e, 0.0);
+  let dz = vec3f(0.0, 0.0, e);
+  let x0 = rzValueNoise(p - dx); let x1 = rzValueNoise(p + dx);
+  let y0 = rzValueNoise(p - dy); let y1 = rzValueNoise(p + dy);
+  let z0 = rzValueNoise(p - dz); let z1 = rzValueNoise(p + dz);
+  return normalize(vec3f((y1 - y0) - (z1 - z0), (z1 - z0) - (x1 - x0), (x1 - x0) - (y1 - y0)) + vec3f(1e-6));
+}
+`