reze-engine 0.50.3 → 0.50.4

package/dist/shaders/passes/scene-contract.js

@@ -89,12 +89,14 @@ const ADD_PREMULTIPLIED = {
     alpha: { srcFactor: "zero", dstFactor: "one", operation: "add" },
 };
 /**
- * Which classes actually WRITE an id, and so gain a fragment output for it.
+ * Which classes write a MEANINGFUL id.
  *
- * Everything else keeps its shader exactly as it is and takes the id target at
- * writeMask 0 — legal, specified, and free. The alternative (leaving the target
- * off those pipelines) is not available: every pipeline in a pass must agree
- * with the pass's attachments.
+ * Not the same question as which shaders declare the output — every scene-pass
+ * shader declares all three now (see sceneFsOutWgsl). This set decides only
+ * whose id survives: writeMask 0xf here, writeMask 0 for everyone else, so the
+ * others compute an id nothing stores. Leaving the target off those pipelines
+ * is not available: every pipeline in a pass must agree with the pass's
+ * attachments.
  *
  * The ground is in because a mark placed by id needs the floor to have one.
  * Transparent fabric writes ids too — dissolving a dress needs the dress's own
@@ -127,11 +129,10 @@ const BLENDS = {
  */
 export function sceneTargets(cls, formats) {
     const targets = cls === "depth-prepass"
-        ? // Format only, and writeMask 0. Note the asymmetry this leans on, which
-            // is the same one the id target leans on below: a target the shader has
-            // no output for is legal at writeMask 0 (gpuweb#1918), while an output
-            // with no target is NOT governed (gpuweb#5341). This is the specified
-            // direction, and it is the only one this file ever uses.
+        ? // Format only, and writeMask 0 — the pipeline writes no colour. It still
+            // DECLARES every output, which is the part that used to be missing; see
+            // the note on sceneFsOutWgsl about why writeMask 0 is not a licence to
+            // leave the output off.
             [
                 { format: formats.hdr, writeMask: 0 },
                 { format: formats.aux, writeMask: 0 },
@@ -168,12 +169,19 @@ export function sceneColorFormats(formats) {
  * 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.
+ * EVERY scene-pass shader takes this — outline, particles, ribbons and the
+ * depth prepass included, none of which write a meaningful id (and the prepass
+ * no meaningful colour either). They did not, once. The reasoning was that a
+ * target at writeMask 0 needs no matching output: true of Dawn, and the reading
+ * of gpuweb#1918 this file used to assert. It is not a reading every browser
+ * shares, and the failure mode when a browser disagrees is the worst kind —
+ * createRenderPipeline does not throw, it returns a pipeline that is already
+ * invalid, and the pass that binds it is dropped whole. Missing geometry, clean
+ * console, and a bug that reproduces on one vendor's browser only.
+ *
+ * So the rule is now the strict one, and it costs nothing to hold: declare
+ * every output the pass has attachments for, and let writeMask decide what is
+ * kept. A shader with no id to write pads it — see sceneIdPadWgsl.
  */
 export function sceneFsOutWgsl(opts) {
     const name = opts?.name ?? "FSOut";
@@ -205,3 +213,32 @@ ${id}};
 export function sceneIdWriteWgsl(out, material, object) {
     return mrtIds ? `  ${out}.id = vec2u(${material}, ${object});\n` : "";
 }
+/**
+ * Just the id FIELD, for a shader that keeps its own struct.
+ *
+ * Particles and ribbons declare their outputs by hand because the comments on
+ * their aux field are about their own blend and belong beside it — taking the
+ * whole struct from sceneFsOutWgsl would move that prose away from what it
+ * explains. They still need the id output when the pass has the attachment, so
+ * they splice this in and pad it with sceneIdPadWgsl.
+ */
+export function sceneIdFieldWgsl() {
+    return mrtIds ? `  @location(2) id: vec2u,\n` : "";
+}
+/**
+ * The id assignment for a shader that has no id to give.
+ *
+ * The counterpart to the strict rule on sceneFsOutWgsl: outline hulls,
+ * particles, ribbons and the depth prepass all declare the output because the
+ * pass has the attachment, and all of them take writeMask 0, so what they
+ * assign is never stored. Zero, which is the reserved "nothing" id the pass
+ * clears to — so if one of these ever did reach the target, it would read as
+ * absence rather than as a plausible wrong answer pointing at material 0.
+ *
+ * A separate function from sceneIdWriteWgsl rather than a call to it with "0u"
+ * twice, because the two say different things: that one records an identity,
+ * this one satisfies a declaration.
+ */
+export function sceneIdPadWgsl(out) {
+    return mrtIds ? `  ${out}.id = vec2u(0u, 0u);\n` : "";
+}

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

@@ -0,0 +1,34 @@
+import { type CastLayout } from "./particles";
+export declare const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export declare const SIM_FORMAT: GPUTextureFormat;
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export declare function parseSimSize(wgsl: string, max: number): number;
+/** Whether this effect drives a grid at all. */
+export declare function simEntryPoint(wgsl: string): boolean;
+/**
+ * `rzSim(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 declare function simReadApi(group: number, tex: number, samp: number, size: number): string;
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export declare function simClockApi(timeExpr: string): string;
+/**
+ * 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 declare function buildSimShader(wgsl: string, size: number, _cast: CastLayout): string;
+//# sourceMappingURL=sim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/sim.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAgC7C,eAAO,MAAM,OAAO,OAAO,CAAA;AAC3B,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,gBAAgC,CAAA;AAEzD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BzF;AAED;8DAC8D;AAC9D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAwDpF"}

package/dist/shaders/passes/sim.js

@@ -0,0 +1,169 @@
+import { audioApi } from "../audio-api";
+import { scoreApi } from "../score-api";
+import { EFFECT_SCENE_API } from "./composite";
+// 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 SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export const SIM_FORMAT = "rgba16float";
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export function parseSimSize(wgsl, max) {
+    const m = /^\s*\/\/\s*@sim\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 simEntryPoint(wgsl) {
+    return /\bfn\s+simStep\s*\(/.test(wgsl);
+}
+/**
+ * `rzSim(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 simReadApi(group, tex, samp, size) {
+    return /* wgsl */ `
+const RZ_SIM_SIZE: f32 = ${size > 0 ? size : 1}.0;
+@group(${group}) @binding(${tex}) var _rzSimTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzSimSamp: 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 rzSim(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+fn rzSimSize() -> f32 { return RZ_SIM_SIZE; }
+fn rzSimTexel() -> f32 { return 1.0 / RZ_SIM_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 simStep 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. rzSimPrev reads the current grid rather than a previous one,
+// which is the honest answer outside the step: there is no previous frame here.
+fn rzSimPrev(uv: vec2f) -> vec4f { return rzSim(uv); }
+fn rzSimFrame() -> i32 { return 1; }
+`;
+}
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export function simClockApi(timeExpr) {
+    return /* wgsl */ `
+fn rzTime() -> f32 { return ${timeExpr}; }
+fn rzDt() -> f32 { return 0.0; }
+`;
+}
+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, size, _cast) {
+    return (SIM_UNIFORMS +
+        /* wgsl */ `
+@group(0) @binding(0) var<uniform> su: SimU;
+@group(0) @binding(1) var _rzSimPrevTex: texture_2d<f32>;
+@group(0) @binding(2) var _rzSimSamp: sampler;
+@group(0) @binding(3) var _rzSimOut: 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>;
+
+fn rzTime() -> f32 { return su.time; }
+fn rzDt() -> f32 { return su.dt; }
+/** Texels per side. */
+fn rzSimSize() -> f32 { return su.size; }
+/** One texel, in uv — the step a neighbour lookup takes. */
+fn rzSimTexel() -> 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 rzSimFrame() -> i32 { return i32(su.frame); }
+
+/** The grid as it was LAST frame, bilinear. The only input a kernel really has. */
+fn rzSimPrev(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimPrevTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+` +
+        EFFECT_SCENE_API +
+        audioApi(0, 5) +
+        scoreApi(0, 7) +
+        // rzSim 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 rzSim(uv: vec2f) -> vec4f { return rzSimPrev(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 rzSimPrev
+  // lands on itself rather than a quarter-texel off.
+  let uv = (vec2f(f32(gid.x), f32(gid.y)) + vec2f(0.5)) / su.size;
+  textureStore(_rzSimOut, xy, simStep(uv, textureLoad(_rzSimPrevTex, xy, 0), su.dt));
+}
+`);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAwBA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6SR"}
+{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAyBA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CAwUR"}

package/dist/shaders/passes/trails.js

@@ -5,6 +5,7 @@ import { anchorAliasWgsl, ribbonSlotWgsl } 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";
+import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract";
 /**
  * Sub-segments drawn between each pair of recorded samples.
  *
@@ -74,7 +75,14 @@ struct CameraU {
 }
 struct TrailU {
   time: f32,
-  _pad0: f32,
+  // How many subjects the cast ACTUALLY holds this frame, not the four the
+  // layout has room for. The instance count is sized by this on the CPU and
+  // decoded by it here, and the two must use the same number or the flattened
+  // [ribbon][subject][segment] index lands on the wrong ribbon. It is a uniform
+  // rather than the RZ_SUBJECTS constant precisely because it changes when a
+  // model is added or removed, and recompiling every trail shader for that
+  // would be absurd.
+  subjects: f32,
   _pad1: f32,
   _pad2: f32,
 }
@@ -195,11 +203,14 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   let rest = ii / subs;
   let seg = k / SUB;
   let sub = k % SUB;
-  let subject = i32(rest % u32(RZ_SUBJECTS));
+  // The LIVE subject count, floored at one so a cast that is momentarily empty
+  // divides by something. See TrailU.subjects.
+  let live = max(1u, u32(tu.subjects));
+  let subject = i32(rest % live);
   // Instance index counts RIBBONS; the cast buffer is addressed by anchor slot.
   // One ribbon per trailed anchor, so these are the same number only when every
   // anchor is trailed — _rzRibbonSlot is what bridges them.
-  let ribbon = i32(rest / u32(RZ_SUBJECTS));
+  let ribbon = i32(rest / live);
   let slot = _rzRibbonSlot(ribbon);
 
   let n = rzTrailCount(subject, slot);
@@ -293,9 +304,23 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   if (dot(perpA, perpB) < 0.0) { perpB = -perpB; }
   let clipP = select(clipA, clipB, atEnd);
   let perp = select(perpA, perpB, atEnd);
-  // trailWidth speaks PIXELS, like the original's constants; rzViewportHeight()
-  // lets the effect scale them to the frame.
-  let wPx = max(0.0, trailWidth(u, age));
+  // trailWidth speaks WORLD UNITS — the model's units, not the screen's.
+  //
+  // It spoke pixels, like the fullscreen original's constants, and that made
+  // the ribbon a screen ornament: zoom out and it grew relative to the hand
+  // that drew it, zoom in and it thinned to a thread. A ribbon is a thing in
+  // the scene, so its width belongs in the scene's units and should foreshorten
+  // like everything else.
+  //
+  // The EXTRUSION stays in 2D pixel space untouched — every 3D-extrusion
+  // artefact this ribbon ever had (fold-over wedges, bowties, twisted quads) is
+  // recorded above, and none of it comes back. Only the width's SOURCE changes:
+  // a world length L perpendicular to view at depth w projects to
+  // L * proj[1][1] / w in NDC y, so half the frame height converts it to the
+  // pixels the 2D offset wants. Per vertex, so a ribbon receding along its own
+  // length tapers with distance exactly as geometry would.
+  let wWorld = max(0.0, trailWidth(u, age));
+  let wPx = wWorld * cam.proj[1][1] * (H * 0.5) / max(clipP.w, 0.01);
   let ndc = clipP.xy / clipP.w + perp * (c.y * wPx) / toPx;
   out.clip = vec4f(ndc * clipP.w, clipP.z, clipP.w);
   out.slot = u32(slot);
@@ -315,7 +340,10 @@ struct TrailFSOut {
   // The scene's aux target: (bloom mask, coverage). Writing mask 1 is what
   // makes a ribbon BLOOM — it is light, and the gate is what says so.
   @location(1) aux: vec4f,
-}
+  // Declared whenever the pass carries the attachment, and padded rather than
+  // written: a ribbon is not a thing you would address by id, so its pipeline
+  // takes this target at writeMask 0. Declared anyway — see sceneFsOutWgsl.
+${sceneIdFieldWgsl()}}
 
 @fragment
 fn fs(in: VSOut) -> TrailFSOut {
@@ -334,7 +362,7 @@ fn fs(in: VSOut) -> TrailFSOut {
   // mapper is what keeps the sum from clipping.
   o.color = vec4f(c.rgb, c.a);
   o.aux = vec4f(${src.bloom ? "1.0" : "0.0"}, 1.0, 0.0, c.a);
-  return o;
+${sceneIdPadWgsl("o")}  return o;
 }
 `);
 }

package/dist/shaders/score-api.d.ts

@@ -0,0 +1,10 @@
+/** Floats before the key map: count, pitch range, clock, duration, release. */
+export declare const SCORE_HEADER = 8;
+/** One energy slot per MIDI pitch. 128 is the MIDI range, not a cap we chose. */
+export declare const SCORE_KEYS = 128;
+/** Where the note records begin. */
+export declare const SCORE_NOTES: number;
+/** Floats per note: start, duration, pitch, velocity. */
+export declare const SCORE_STRIDE = 4;
+/** The rzNote*/ export declare function scoreApi(group: number, binding: number): string;
+//# sourceMappingURL=score-api.d.ts.map

package/dist/shaders/score-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-api.d.ts","sourceRoot":"","sources":["../../src/shaders/score-api.ts"],"names":[],"mappings":"AA8BA,+EAA+E;AAC/E,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,iFAAiF;AACjF,eAAO,MAAM,UAAU,MAAM,CAAA;AAC7B,oCAAoC;AACpC,eAAO,MAAM,WAAW,QAA4B,CAAA;AACpD,yDAAyD;AACzD,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B,gBAAgB,CAChB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2E/D"}

package/dist/shaders/score-api.js

@@ -0,0 +1,114 @@
+// The score data interface, as WGSL — shared verbatim by every effect module.
+//
+// The sibling of the audio interface, and precomputed for the same reason: an
+// export steps the engine frame by frame rather than playing in real time, so
+// anything read live from a player would render empty into the exported video.
+// A note list is inherently precomputed, so it cannot even be tempted.
+//
+// WHY THIS EXISTS BESIDE rzAudio* RATHER THAN INSTEAD OF IT. The audio interface
+// answers "how loud is the bass right now" — a spectrum, smeared across
+// frequency and time. That is the right shape for a reactive backdrop and the
+// wrong shape for a note: you cannot recover a discrete onset, a pitch and a
+// duration from band energy, and the crispness of a falling note is the whole
+// point of the look. The two are complementary — a scene can pulse its fog on
+// rzAudioOnset while its notes fall on rzNoteAge.
+//
+// LAYOUT. An 8-float header, then a 128-float live key map, then the notes at 4
+// floats each (start, duration, pitch, velocity). `time` and `playing` are
+// rewritten every frame by whoever owns playback, exactly as the audio header
+// is, so "now" is always the clock actually running.
+//
+// THE KEY MAP IS THE POINT OF THE DESIGN. Falling notes index the note list
+// directly — one particle per note, which is what makes the geometry trivial.
+// But a keyboard glow asks the opposite question, per pixel: is anything
+// sounding at THIS pitch? Answering that by scanning the note list would be
+// thousands of iterations per fragment. So the engine keeps a 128-entry
+// per-pitch energy map, updated once per frame on the CPU, and the glow becomes
+// one lookup — the same trade the audio interface makes by precomputing onset
+// so "a beat-triggered effect is one comparison instead of a per-pixel history
+// scan".
+/** Floats before the key map: count, pitch range, clock, duration, release. */
+export const SCORE_HEADER = 8;
+/** One energy slot per MIDI pitch. 128 is the MIDI range, not a cap we chose. */
+export const SCORE_KEYS = 128;
+/** Where the note records begin. */
+export const SCORE_NOTES = SCORE_HEADER + SCORE_KEYS;
+/** Floats per note: start, duration, pitch, velocity. */
+export const SCORE_STRIDE = 4;
+/** The rzNote*/ /* rzKey* accessors, with the buffer declared at the given binding. */
+export function scoreApi(group, binding) {
+    return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzScore: array<f32>;
+
+/** Notes in the score; 0 when none is loaded, which every accessor below
+ *  tolerates by returning zero rather than reading past the end. */
+fn rzNoteCount() -> i32 { return i32(_rzScore[0]); }
+/** Where the score is NOW, in seconds — the clock every age below hangs from. */
+fn rzScoreTime() -> f32 { return _rzScore[3]; }
+/** 1 while the score is advancing, 0 paused or absent. */
+fn rzScorePlaying() -> f32 { return select(0.0, _rzScore[4], i32(_rzScore[0]) > 0); }
+/** Last note-off, in seconds — the length of the piece. */
+fn rzScoreDuration() -> f32 { return _rzScore[5]; }
+/** Lowest and highest pitch the score actually uses. Lay a keyboard out against
+ *  these rather than against 0..127 and a piano piece fills the screen instead
+ *  of occupying its middle third. */
+fn rzPitchLow() -> f32 { return _rzScore[1]; }
+fn rzPitchHigh() -> f32 { return _rzScore[2]; }
+
+fn _rzNoteAt(i: i32, field: i32) -> f32 {
+  if (i < 0 || i >= i32(_rzScore[0])) { return 0.0; }
+  return _rzScore[${SCORE_NOTES} + i * ${SCORE_STRIDE} + field];
+}
+
+/** When note i begins, in seconds. */
+fn rzNoteStart(i: i32) -> f32 { return _rzNoteAt(i, 0); }
+/** How long note i sounds, in seconds. */
+fn rzNoteLength(i: i32) -> f32 { return _rzNoteAt(i, 1); }
+/** MIDI pitch of note i — 60 is middle C. */
+fn rzNotePitch(i: i32) -> f32 { return _rzNoteAt(i, 2); }
+/** How hard note i was struck, 0..1. */
+fn rzNoteVelocity(i: i32) -> f32 { return _rzNoteAt(i, 3); }
+
+/**
+ * Seconds since note i began — NEGATIVE before it does.
+ *
+ * The falling-note function, and the sign is the whole of it: a note's height is
+ * -rzNoteAge(i) * speed, so a note not yet played sits above the keyboard at a
+ * distance proportional to how long is left, crosses zero exactly as it sounds,
+ * and keeps going. One expression, no state, no spawning — which is why one
+ * particle per note is the natural mapping and the pool index IS the note index.
+ */
+fn rzNoteAge(i: i32) -> f32 { return _rzScore[3] - rzNoteStart(i); }
+
+/** 1 while note i is sounding, 0 either side of it. */
+fn rzNoteHeld(i: i32) -> f32 {
+  let age = rzNoteAge(i);
+  return select(0.0, 1.0, age >= 0.0 && age < rzNoteLength(i));
+}
+
+/**
+ * Energy at a MIDI pitch right now: 1 the instant it is struck, holding while
+ * sounding, then falling away over the release set at install time.
+ *
+ * Per PITCH rather than per note, because that is the question a keyboard asks
+ * and a note list cannot answer cheaply — see the header. Fractional pitches
+ * read the nearest key, so a caller can hand this a continuous x across the
+ * keyboard without rounding first.
+ */
+fn rzKeyEnergy(pitch: f32) -> f32 {
+  let k = i32(round(pitch));
+  if (k < 0 || k >= ${SCORE_KEYS}) { return 0.0; }
+  return _rzScore[${SCORE_HEADER} + k];
+}
+
+/**
+ * A pitch's place across the score's own range, 0..1 — the x of a falling note
+ * and of the key it lands on, which have to agree or the effect is nonsense.
+ */
+fn rzPitchX(pitch: f32) -> f32 {
+  let lo = _rzScore[1];
+  let hi = _rzScore[2];
+  return select(0.5, (pitch - lo) / max(hi - lo, 1.0), hi > lo);
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.50.3",
+  "version": "0.50.4",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",