reze-engine 0.43.0 → 0.50.1

package/dist/shaders/passes/hosted-api.js

@@ -0,0 +1,166 @@
+// 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, dtExpr) {
+    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) {
+    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) {
+    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));
+}
+`;

package/dist/shaders/passes/id-debug.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The id attachment, drawn so a person can look at it.
+ *
+ * The id buffer is correct or incorrect in ways nothing else in the frame can
+ * show: with no consumer, a perfect id buffer and a completely wrong one
+ * produce exactly the same picture. This pass exists so that "it works" is
+ * something seen rather than inferred.
+ *
+ * WHAT CORRECT LOOKS LIKE, and what each failure looks like instead:
+ *
+ *   - Every material is ONE FLAT COLOUR, with hard edges. Ids are names, not
+ *     quantities: a gradient anywhere, or fringing along an edge, means
+ *     something is interpolating or resolving them — the two failures the
+ *     no-resolve/no-blend rules exist to prevent.
+ *   - Parts differ from each other. A whole model in one colour means the
+ *     material index never made it into the uniform.
+ *   - The FLOOR is a fixed light grey, the reserved id, and never shares a
+ *     colour with a body part.
+ *   - Where nothing was drawn is BLACK — id 0, the reserved nothing, which is
+ *     also what the attachment clears to. Black *over geometry* means that draw
+ *     wrote no id; colour where the sky should be means the clear is wrong.
+ *
+ * Colours come from a hash of the pair, so neighbouring materials land on
+ * unrelated hues rather than adjacent shades of one — the point is telling them
+ * apart, not ordering them.
+ */
+export declare const ID_DEBUG_SHADER_WGSL = "\n// Multisampled and NEVER resolved, so it is read the way it is written: one\n// sample, by texel. Sample 0 is what every consumer of this attachment reads.\n@group(0) @binding(0) var idTex: texture_multisampled_2d<u32>;\n\n@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {\n  let x = f32((vi & 1u) << 2u) - 1.0;\n  let y = f32((vi & 2u) << 1u) - 1.0;\n  return vec4f(x, y, 0.0, 1.0);\n}\n\n/** Integer hash \u2192 0..1. Distinct inputs land on unrelated outputs, which is the\n *  whole requirement: adjacent ids must not read as adjacent colours. */\nfn hashId(x: u32) -> f32 {\n  var h = x * 747796405u + 2891336453u;\n  h = ((h >> ((h >> 28u) + 4u)) ^ h) * 277803737u;\n  return f32((h >> 22u) ^ h) / 4294967295.0;\n}\n\n@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {\n  let ids = textureLoad(idTex, vec2<i32>(fragCoord.xy), 0);\n  let materialId = ids.x;\n  let objectId = ids.y;\n\n  // Nothing drawn here. Black, and it must cover exactly the empty space.\n  if (materialId == 0u && objectId == 0u) {\n    return vec4f(0.0, 0.0, 0.0, 1.0);\n  }\n  // The floor, at the top of the range. Flat light grey so it is unmistakable\n  // and cannot be confused with a hashed colour.\n  if (materialId == 65535u) {\n    return vec4f(0.72, 0.72, 0.75, 1.0);\n  }\n  // Hue from the material, brightness from the object, so two models wearing\n  // the same material index still read apart.\n  let h = hashId(materialId * 1973u + 9277u);\n  let shade = 0.55 + 0.45 * hashId(objectId * 6151u + 1u);\n  // Cheap hue ramp: three offset cosines. Saturated on purpose \u2014 this is a\n  // diagnostic, not a look.\n  let rgb = vec3f(\n    0.5 + 0.5 * cos(6.28318 * (h + 0.00)),\n    0.5 + 0.5 * cos(6.28318 * (h + 0.33)),\n    0.5 + 0.5 * cos(6.28318 * (h + 0.67)),\n  );\n  return vec4f(rgb * shade, 1.0);\n}\n";
+//# sourceMappingURL=id-debug.d.ts.map

package/dist/shaders/passes/id-debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-debug.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/id-debug.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB,20DA8ChC,CAAA"}

package/dist/shaders/passes/id-debug.js

@@ -0,0 +1,74 @@
+import { GROUND_MATERIAL_ID } from "./ground";
+/**
+ * The id attachment, drawn so a person can look at it.
+ *
+ * The id buffer is correct or incorrect in ways nothing else in the frame can
+ * show: with no consumer, a perfect id buffer and a completely wrong one
+ * produce exactly the same picture. This pass exists so that "it works" is
+ * something seen rather than inferred.
+ *
+ * WHAT CORRECT LOOKS LIKE, and what each failure looks like instead:
+ *
+ *   - Every material is ONE FLAT COLOUR, with hard edges. Ids are names, not
+ *     quantities: a gradient anywhere, or fringing along an edge, means
+ *     something is interpolating or resolving them — the two failures the
+ *     no-resolve/no-blend rules exist to prevent.
+ *   - Parts differ from each other. A whole model in one colour means the
+ *     material index never made it into the uniform.
+ *   - The FLOOR is a fixed light grey, the reserved id, and never shares a
+ *     colour with a body part.
+ *   - Where nothing was drawn is BLACK — id 0, the reserved nothing, which is
+ *     also what the attachment clears to. Black *over geometry* means that draw
+ *     wrote no id; colour where the sky should be means the clear is wrong.
+ *
+ * Colours come from a hash of the pair, so neighbouring materials land on
+ * unrelated hues rather than adjacent shades of one — the point is telling them
+ * apart, not ordering them.
+ */
+export const ID_DEBUG_SHADER_WGSL = /* wgsl */ `
+// Multisampled and NEVER resolved, so it is read the way it is written: one
+// sample, by texel. Sample 0 is what every consumer of this attachment reads.
+@group(0) @binding(0) var idTex: texture_multisampled_2d<u32>;
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+/** Integer hash → 0..1. Distinct inputs land on unrelated outputs, which is the
+ *  whole requirement: adjacent ids must not read as adjacent colours. */
+fn hashId(x: u32) -> f32 {
+  var h = x * 747796405u + 2891336453u;
+  h = ((h >> ((h >> 28u) + 4u)) ^ h) * 277803737u;
+  return f32((h >> 22u) ^ h) / 4294967295.0;
+}
+
+@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {
+  let ids = textureLoad(idTex, vec2<i32>(fragCoord.xy), 0);
+  let materialId = ids.x;
+  let objectId = ids.y;
+
+  // Nothing drawn here. Black, and it must cover exactly the empty space.
+  if (materialId == 0u && objectId == 0u) {
+    return vec4f(0.0, 0.0, 0.0, 1.0);
+  }
+  // The floor, at the top of the range. Flat light grey so it is unmistakable
+  // and cannot be confused with a hashed colour.
+  if (materialId == ${GROUND_MATERIAL_ID}u) {
+    return vec4f(0.72, 0.72, 0.75, 1.0);
+  }
+  // Hue from the material, brightness from the object, so two models wearing
+  // the same material index still read apart.
+  let h = hashId(materialId * 1973u + 9277u);
+  let shade = 0.55 + 0.45 * hashId(objectId * 6151u + 1u);
+  // Cheap hue ramp: three offset cosines. Saturated on purpose — this is a
+  // diagnostic, not a look.
+  let rgb = vec3f(
+    0.5 + 0.5 * cos(6.28318 * (h + 0.00)),
+    0.5 + 0.5 * cos(6.28318 * (h + 0.33)),
+    0.5 + 0.5 * cos(6.28318 * (h + 0.67)),
+  );
+  return vec4f(rgb * shade, 1.0);
+}
+`;

package/dist/shaders/passes/particles.d.ts

@@ -4,11 +4,18 @@ export type CastLayout = {
     samples: number;
     base: number;
     trailBase: number;
+    /** The scene's anchor CAP — the address space, not how many asked for trails. */
     slots: number;
+    /** How many of this effect's anchors asked for a trail. AUTHOR-VISIBLE as
+     *  RZ_TRAIL_SLOTS: published effects loop over it, so its meaning is pinned
+     *  even though the address space it used to share is now a separate number. */
+    trailCount: number;
+    /** This effect's local slot → scene slot. Identity while one effect exists. */
+    alias: number[];
 };
 /** How the author's quads combine with the scene. */
-export type ParticleBlend = "alpha" | "additive";
-export type ParticleSource = {
+type ParticleBlend = "alpha" | "additive";
+type ParticleSource = {
     /** The author's WGSL verbatim. */
     wgsl: string;
     /** Simultaneous particles. Fixed at install; the pool recycles rather than grows. */
@@ -55,4 +62,5 @@ export declare function buildParticleComputeShader(src: ParticleSource, cast: Ca
  * readback every frame to save vertices the rasteriser was going to reject anyway.
  */
 export declare function buildParticleRenderShader(src: ParticleSource, cast: CastLayout): string;
+export {};
 //# sourceMappingURL=particles.d.ts.map

package/dist/shaders/passes/particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AAkBA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAmC9G,qDAAqD;AACrD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,CAAA;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAiIjC,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE9D;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAMlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAwCxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA2GvF"}
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AAwBA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;mFAE+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB,CAAA;AAiCD,qDAAqD;AACrD,KAAK,aAAa,GAAG,OAAO,GAAG,UAAU,CAAA;AAEzC,KAAK,cAAc,GAAG;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAkDjC,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE9D;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAMlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA0CxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA6GvF"}

package/dist/shaders/passes/particles.js

@@ -1,4 +1,10 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights";
 import { audioApi } from "../audio-api";
+import { lyricsApi } from "../lyrics-api";
+import { anchorAliasWgsl } from "../anchor-table";
+import { midiApi } from "../midi-api";
+import { CAST_API } from "../cast-api";
+import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api";
 /**
  * The trail accessors, in the PARTICLE module.
  *
@@ -7,11 +13,15 @@ import { audioApi } from "../audio-api";
  * particleInit reading the same recorded history the trail draws from. One
  * effect file, two mounts, one buffer.
  */
+/** Shared with the grid pass, which reads the same buffer for the same reason:
+ *  a kernel that displaces fog has to know where the dancer's feet are. */
 function castApi(cast) {
-    return `
-const RZ_SUBJECTS: i32 = ${cast.subjects};
-const RZ_SAMPLES: i32 = ${cast.samples};
-const RZ_TRAIL_SLOTS: i32 = ${cast.slots};
+    return (
+    // rzSubjectCount FIRST, because CAST_API is written against it and this
+    // module has no view uniform to read the engine's count out of. Scanning
+    // for a subject whose bounding sphere has a radius is the same answer by a
+    // different route — the seam is named at the top of cast-api.ts.
+    `
 fn rzSubjectCount() -> i32 {
   var n = 0;
   for (var i = 0; i < RZ_SUBJECTS; i++) {
@@ -19,47 +29,13 @@ fn rzSubjectCount() -> i32 {
   }
   return n;
 }
-fn rzTrailCount(subject: i32, slot: i32) -> i32 {
-  if (subject < 0 || subject >= RZ_SUBJECTS || slot < 0 || slot >= RZ_TRAIL_SLOTS) { return 0; }
-  return i32(_rzCast[${cast.base} + (slot * RZ_SUBJECTS + subject) * 3 + 2].w);
-}
-/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */
-fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
-  let n = rzTrailCount(subject, slot);
-  if (i < 0 || i >= n) { return vec4f(0.0); }
-  return _rzCast[${cast.trailBase} + (slot * RZ_SUBJECTS + subject) * RZ_SAMPLES + i];
-}
-`;
+` +
+        CAST_API +
+        trailSlotsApi(cast.trailCount) +
+        anchorAliasWgsl(cast.alias));
 }
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export const PARTICLE_STRIDE = 48;
-/**
- * The particle record, laid out by hand.
- *
- * `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.
- */
-const PARTICLE_STRUCT = /* 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,
-}
-`;
 const CAMERA_STRUCT = /* wgsl */ `
 struct CameraU {
   view: mat4x4f,
@@ -77,72 +53,21 @@ struct ParticleU {
 }
 `;
 /**
- * The shared prelude, everything `rz`-prefixed.
+ * This module's half of the prelude: the camera, from its own uniform.
  *
- * Not convenience — correctness. Every effect written against the old contract
- * re-derived its own hash and its own falloff, which is duplicated code and
- * duplicated bugs; `rzFalloff` in particular has COMPACT SUPPORT (it reaches
- * exactly zero at r), because an exponential glow that never quite reaches zero
- * 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.
+ * The rest — hashes, noise, falloff, clock, viewport — is shared with every
+ * other module that hosts an effect's source, because an author's helper must
+ * mean the same thing in whichever one it lands in.
  */
-const PRELUDE = /* 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);
-}
-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);
-}
-/** 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));
-}
-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 + vec3f(0.0, 0.0, 0.0));
-  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 standard drifting-air force. Snow and mist want this. */
-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));
-}
-/** Compact-support falloff: 1 at the centre, exactly 0 at r, smooth between. */
-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 rzTime() -> f32 { return pu.time; }
-fn rzViewportHeight() -> f32 { return cam.targetHeight; }
+const PRELUDE = 
+// The hashes, the noise and rzFalloff, identical in every module that hosts an
+// effect's source; then the clock and the viewport, which cannot be, because
+// this module keeps both in its own uniforms.
+EFFECT_MATH_API +
+    clockApi("pu.time", "pu.dt") +
+    viewportApi("cam.targetHeight") +
+    /* wgsl */ `
+${RZ_LIGHT_STRUCT_WGSL}
 fn rzCameraPos() -> vec3f { return cam.camPos; }
 fn rzCameraRight() -> vec3f { return vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]); }
 fn rzCameraUp() -> vec3f { return vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]); }
@@ -153,7 +78,6 @@ fn rzProject(p: vec3f) -> vec3f {
   let w = max(clip.w, 1e-4);
   return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
 }
-fn rzDt() -> f32 { return pu.dt; }
 fn rzCamPos() -> vec3f { return cam.camPos; }
 `;
 /** `// @particles 4096` — how many live at once. */
@@ -192,7 +116,7 @@ export function particleEntryPoints(wgsl) {
  * snow is exactly right, and for a burst is what the age offset is for.
  */
 export function buildParticleComputeShader(src, cast) {
-    return (PARTICLE_STRUCT +
+    return (PARTICLE_STRUCT_WGSL +
         CAMERA_STRUCT +
         PARTICLE_UNIFORMS +
         `
@@ -203,6 +127,8 @@ export function buildParticleComputeShader(src, cast) {
 ` +
         castApi(cast) +
         audioApi(0, 4) +
+        midiApi(0, 5) +
+        lyricsApi(0, 6) +
         PRELUDE +
         "\n// ── user effect ──\n" +
         src.wgsl +
@@ -246,7 +172,7 @@ fn main(@builtin(global_invocation_id) gid: vec3u) {
 export function buildParticleRenderShader(src, cast) {
     return (`override BLOOM: bool = ${src.bloom ? "true" : "false"};
 override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
-        PARTICLE_STRUCT +
+        PARTICLE_STRUCT_WGSL +
         CAMERA_STRUCT +
         PARTICLE_UNIFORMS +
         `
@@ -257,6 +183,8 @@ override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
 ` +
         castApi(cast) +
         audioApi(0, 4) +
+        midiApi(0, 5) +
+        lyricsApi(0, 6) +
         PRELUDE +
         "\n// ── user effect ──\n" +
         src.wgsl +

package/dist/shaders/passes/scene-contract.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The scene pass's attachment contract, in one place.
+ *
+ * Everything drawn INSIDE the scene pass — models, ground, outline hulls,
+ * particles, ribbons, and the transparent depth prepass — shares one set of
+ * attachments, and therefore one set of formats, blends and write masks. That
+ * agreement used to be restated at every pipeline that joins the pass and in
+ * every shader that writes to it, which is why adding an attachment was
+ * dangerous rather than tedious: a class left behind does not fail loudly, it
+ * fails as a validation error naming a pipeline that was never edited.
+ *
+ * So the contract is DATA here, and the pipelines ask for it by render class.
+ * Adding the id attachment (MRT) becomes one edit in this file plus a per-class
+ * decision about whether that class writes it — which is the shape of the
+ * question, and now the shape of the code.
+ *
+ * WHAT IS NOT HERE. Two passes look like they belong and do not:
+ *   - the FIELD pass has its own pair of rgba16float targets, its own blend and
+ *     no MSAA. It is a different pass with a different contract.
+ *   - the gizmo and selection-edge pipelines draw to the SWAPCHAIN in their own
+ *     unmultisampled pass, so the presentation format is the whole of their
+ *     contract. The plan listed gizmo as a scene render class; the code says
+ *     otherwise, and the code is right.
+ */
+/** The scene pass's attachments, as the engine has them at init. Passed in
+ *  rather than imported: hdr is chosen per device (rg11b10ufloat where it is
+ *  available and blendable, rgba16float otherwise). */
+export type SceneFormats = {
+    /** The HDR colour attachment, @location(0). */
+    hdr: GPUTextureFormat;
+    /** The aux attachment, @location(1) — (bloom mask, coverage). */
+    aux: GPUTextureFormat;
+};
+/**
+ * The id attachment's format: (material index, object index), one u16 each.
+ *
+ * Two 16-bit channels rather than one 32-bit: 32-bit formats are not
+ * multisamplable, and this attachment is multisampled with the rest of the
+ * pass. Uint targets take no blend at all per spec, which is exactly right —
+ * an averaged id is not an id.
+ */
+export declare const SCENE_ID_FORMAT: GPUTextureFormat;
+/** Called by the engine at init, after probing the device. */
+export declare function setMrtIds(on: boolean): void;
+export declare function mrtIdsEnabled(): boolean;
+/**
+ * What is being drawn, which is the only thing that varies.
+ *
+ * The classes differ ONLY in blend and write mask; formats are the pass's, not
+ * the draw's. A class here is a thing with a reason, not a pipeline name — two
+ * pipelines that blend the same way share one.
+ */
+type SceneRenderClass = 
+/** Models, opaque and transparent. Straight alpha over. */
+"material"
+/** The shadow-catcher floor. Blends PREMULTIPLIED, not like a material: its
+ *  coverage is a lit surface plus a colourless shadow layer, so it weights
+ *  its own colour before the blend sees it. */
+ | "ground"
+/** Backface-expanded hulls. Also a material blend — it is geometry. */
+ | "outline"
+/** Particles and ribbons in their default, non-additive mode. */
+ | "particle"
+/** Particles declaring `// @blend additive` — LIGHT rather than matter, so
+ *  colour sums and alpha is left alone: a glow must not claim coverage it
+ *  never occluded. The aux target sums with it, which is what lets an
+ *  additive effect reach the bloom gate at all. */
+ | "particle-additive"
+/** Ribbons. Additive colour like the above, but premultiplied by the
+ *  fragment's own alpha on the way in (src-alpha, one) rather than added
+ *  whole, and an ordinary alpha-over aux so a ribbon's mask does not
+ *  saturate along every overlap. */
+ | "trail"
+/** The transparent depth prepass: it exists to write DEPTH after the fabric's
+ *  colour blended, so an outline drawn later is occluded behind it. It must
+ *  therefore write no colour at all — the targets exist only to make the
+ *  pipeline compatible with the pass it joins. */
+ | "depth-prepass";
+/**
+ * The colour targets a scene-pass pipeline of this class declares, in
+ * attachment order.
+ *
+ * Fresh objects every call, deliberately: a caller that mutated a shared
+ * descriptor would change every pipeline built after it, and the ones built
+ * before would keep the old value — a difference that only shows up as one
+ * pipeline blending unlike its neighbours.
+ */
+export declare function sceneTargets(cls: SceneRenderClass, formats: SceneFormats): GPUColorTargetState[];
+/**
+ * The pass's colour attachments, in order — for the things that describe the
+ * pass itself rather than a draw within it.
+ *
+ * A render bundle declares the formats it will be replayed into and is rejected
+ * against a pass that does not match, so the bundle encoder has to move in
+ * lockstep with the targets above. It restated the list independently until
+ * this existed, which made it the one consumer an MRT change would have missed
+ * — a bundle is recorded once and replayed, so the failure would have arrived
+ * at replay, naming the bundle rather than the attachment that changed.
+ */
+export declare function sceneColorFormats(formats: SceneFormats): GPUTextureFormat[];
+/**
+ * The fragment-output struct a scene-pass shader returns.
+ *
+ * Emitted rather than written out per file so that the attachment list has one
+ * author. The struct and the targets above have to agree on count and order,
+ * and they now disagree in one file rather than in five.
+ *
+ * Only the shaders that will GAIN an output take this today — the materials
+ * (hand-written and graph-generated alike, through COMMON_FS_OUT_WGSL) and the
+ * ground. Outline, particles and ribbons keep their own declarations on
+ * purpose: they never write the id, so they would take an `id: false` argument
+ * forever, and their structs carry comments about their own blend that belong
+ * where they are.
+ */
+export declare function sceneFsOutWgsl(opts?: {
+    name?: string;
+    aux?: string;
+}): string;
+/**
+ * The line a fragment shader assigns its id with, or nothing when ids are off.
+ *
+ * Emitted rather than written into each shader for the same reason as the
+ * struct: with ids off there must be no assignment either, and a shader cannot
+ * ask the device what it supports.
+ */
+export declare function sceneIdWriteWgsl(out: string, material: string, object: string): string;
+export {};
+//# sourceMappingURL=scene-contract.d.ts.map

package/dist/shaders/passes/scene-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAwEnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAqBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF"}