reze-engine 0.42.3 → 0.50.0

package/dist/shaders/passes/trails.js

@@ -0,0 +1,340 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights";
+import { audioApi } from "../audio-api";
+import { lyricsApi } from "../lyrics-api";
+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";
+/**
+ * Sub-segments drawn between each pair of recorded samples.
+ *
+ * The path is sampled at a fixed rate on the scene clock, so a fast hand leaves
+ * its samples far apart and a strip drawn straight between them is visibly
+ * faceted. Four sub-segments on a Catmull-Rom curve through the neighbours costs
+ * four times the vertices — which is nothing, they are vertices — and removes
+ * both the faceting and most of the jitter, since a spline tangent varies
+ * smoothly where a per-segment direction snaps about whenever the hand slows.
+ */
+export const TRAIL_SUBDIVISIONS = 6;
+/** Does the source define the trail contract? Both are required together. */
+export function trailEntryPoints(wgsl) {
+    return {
+        width: /\bfn\s+trailWidth\s*\(/.test(wgsl),
+        shade: /\bfn\s+trailShade\s*\(/.test(wgsl),
+    };
+}
+/**
+ * One quad per segment, laid out flat across every anchor and character.
+ *
+ * The instance index encodes all three — segment, subject, slot — so a scene
+ * with three dancers and eight declared bones is still ONE draw call and needs
+ * nothing computed on the CPU per frame. Instances past the end of a real trail
+ * collapse to a degenerate quad, which costs a vertex shader invocation and no
+ * fragments; the alternative is a compacted instance list, which costs a
+ * readback every frame to save exactly that.
+ *
+ * The ribbon faces the camera per SEGMENT rather than as a whole: the side
+ * vector is the segment direction crossed with the direction to the eye, so a
+ * ribbon that loops back on itself stays visible along its entire length instead
+ * of vanishing edge-on where it turns.
+ */
+export function buildTrailShader(src, cast) {
+    return (CAST_API +
+        trailSlotsApi(src.slots) +
+        EFFECT_MATH_API +
+        PARTICLE_STRUCT_WGSL +
+        clockApi("tu.time", "0.0") +
+        viewportApi("cam.targetHeight") +
+        // RZ_SLOTS is this module's alone: how many ribbons to DRAW, which is the
+        // instance loop's bound. RZ_MAX_ANCHORS in CAST_API is the address space the
+        // accessors are bounded by, and the two being one number was the old trail
+        // bug — the comment that said so lived here, so it stays here.
+        `const RZ_SLOTS: i32 = ${src.slots};
+${ribbonSlotWgsl(src.ribbonSlots)}
+${anchorAliasWgsl(cast.alias)}
+const SUB: i32 = ${TRAIL_SUBDIVISIONS};
+
+// World units a sample pair must span to count as a FULL contribution — the
+// original's REF_SEG_PX, converted out of pixels.
+//
+// This is a line integral along a path, so a segment should contribute in
+// proportion to the path it covers. Without it a hand that pauses stacks fifty
+// samples on one point and every one of them contributes fully, which is what
+// turned the ribbon white wherever it slowed. It scales INTENSITY, not width:
+// scaling width pinches the strip shut at exactly the moments a hand decelerates,
+// which is every turn — and a ribbon that closes to nothing at each turn reads as
+// dark breaks in the middle of it.
+const RZ_REF_SPAN: f32 = 0.37;
+
+struct CameraU {
+  view: mat4x4f,
+  proj: mat4x4f,
+  camPos: vec3f,
+  targetHeight: f32,
+}
+struct TrailU {
+  time: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
+}
+@group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
+@group(0) @binding(1) var<uniform> tu: TrailU;
+@group(0) @binding(2) var<uniform> cam: CameraU;
+// Binding 3 is GONE, and it had to go. Ribbons draw inside the scene pass now,
+// and the depth buffer is that pass's render attachment — binding it for
+// sampling in the same pass is a usage conflict WebGPU rejects outright:
+// "includes writable usage and another usage in the same synchronization
+// scope". The hardware depth test replaced what it was read for.
+
+${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]); }
+fn rzCameraForward() -> vec3f { return vec3f(cam.view[0][2], cam.view[1][2], cam.view[2][2]); }
+/** World point → (uv, view distance), same contract as the field mounts' rzProject. */
+fn rzProject(p: vec3f) -> vec3f {
+  let clip = cam.proj * cam.view * vec4f(p, 1.0);
+  let w = max(clip.w, 1e-4);
+  return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
+}
+fn rzCamPos() -> vec3f { return cam.camPos; }
+fn rzSubjectCount() -> i32 {
+  var n = 0;
+  for (var i = 0; i < RZ_SUBJECTS; i++) {
+    if (_rzCast[i * 3 + 2].w > 0.0) { n = i + 1; }
+  }
+  return n;
+}
+/** Catmull-Rom through four samples — passes through p1 and p2. */
+fn rzSpline(p0: vec3f, p1: vec3f, p2: vec3f, p3: vec3f, t: f32) -> vec3f {
+  let t2 = t * t;
+  let t3 = t2 * t;
+  return 0.5 * ((2.0 * p1) + (-p0 + p2) * t + (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3) * t2 +
+                (-p0 + 3.0 * p1 - 3.0 * p2 + p3) * t3);
+}
+/** Its derivative — the ribbon's direction, smooth by construction. */
+fn rzSplineTangent(p0: vec3f, p1: vec3f, p2: vec3f, p3: vec3f, t: f32) -> vec3f {
+  let t2 = t * t;
+  let d = 0.5 * ((-p0 + p2) + 2.0 * (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3) * t +
+                 3.0 * (-p0 + 3.0 * p1 - 3.0 * p2 + p3) * t2);
+  if (length(d) < 1e-6) { return vec3f(0.0, 1.0, 0.0); }
+  return normalize(d);
+}
+fn rzTrailAt(subject: i32, slot: i32, i: i32, n: i32) -> vec4f {
+  return rzTrail(subject, slot, clamp(i, 0, n - 1));
+}
+
+/**
+ * The direction the ribbon runs AT a sample, not along one segment.
+ *
+ * Averaging the incoming and outgoing directions gives a mitre joint: both quads
+ * meeting at a sample compute the same tangent, so they share an edge exactly.
+ * Taking each segment's own direction instead leaves a wedge at every bend —
+ * which under additive blending is a bright band, and is what put visible
+ * stripes across the ribbon wherever the hand turned.
+ */
+fn rzTangentAt(subject: i32, slot: i32, i: i32, n: i32) -> vec3f {
+  let p = rzTrail(subject, slot, i).xyz;
+  var d = vec3f(0.0);
+  if (i > 0) {
+    let q = rzTrail(subject, slot, i - 1).xyz;
+    let e = p - q;
+    if (length(e) > 1e-7) { d = d + normalize(e); }
+  }
+  if (i + 1 < n) {
+    let q = rzTrail(subject, slot, i + 1).xyz;
+    let e = q - p;
+    if (length(e) > 1e-7) { d = d + normalize(e); }
+  }
+  if (length(d) < 1e-6) { return vec3f(0.0, 1.0, 0.0); }
+  return normalize(d);
+}
+/**
+ * Circumradius of three consecutive samples — the path's local turn radius.
+ *
+ * The ribbon's half-width must not exceed this. Where it does, the inner edges
+ * of adjacent quads cross the centre of the turn and overlap, and under
+ * additive blending every overlap doubles into a bright transverse wedge — the
+ * bands that survived every brightness fix, because they were geometry, not
+ * shading. Collinear or stationary samples return a huge radius: a straight
+ * path clamps nothing.
+ */
+fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
+  let ab = b - a;
+  let bc = c - b;
+  let ca = a - c;
+  let la = length(ab);
+  let lb = length(bc);
+  let cr = length(cross(ab, ca));
+  if (la < 1e-5 || lb < 1e-5 || cr < 1e-7) { return 1e6; }
+  return (la * lb * length(ca)) / (2.0 * cr);
+}
+` +
+        audioApi(0, 4) +
+        midiApi(0, 5) +
+        lyricsApi(0, 6) +
+        "\n// ── user effect ──\n" +
+        src.wgsl +
+        /* wgsl */ `
+struct VSOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) age: f32,
+  @location(2) weight: f32,
+  // Which declared anchor this quad belongs to — so one effect can dress its
+  // hand and foot ribbons differently instead of sharing a single look.
+  @location(3) @interpolate(flat) slot: u32,
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {
+  var out: VSOut;
+  let subs = u32((RZ_SAMPLES - 1) * SUB);
+  let k = i32(ii % subs);
+  let rest = ii / subs;
+  let seg = k / SUB;
+  let sub = k % SUB;
+  let subject = i32(rest % u32(RZ_SUBJECTS));
+  // 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 slot = _rzRibbonSlot(ribbon);
+
+  let n = rzTrailCount(subject, slot);
+  if (ribbon >= RZ_SLOTS || seg + 1 >= n) {
+    out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
+    out.uv = vec2f(0.0);
+    out.age = 0.0;
+    return out;
+  }
+
+  let quad = array<vec2f, 6>(
+    vec2f(0.0, -1.0), vec2f(1.0, -1.0), vec2f(0.0, 1.0),
+    vec2f(0.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),
+  );
+  let c = quad[vi];
+  let atEnd = c.x > 0.5;
+
+  // Position ON THE CURVE, not on the chord. Both quads meeting at a sub-sample
+  // evaluate the same t, so they share an edge exactly — no wedge to double-blend
+  // into a bright band, which is what the per-segment version left at every bend.
+  let t0 = f32(sub) / f32(SUB);
+  let t1 = (f32(sub) + 1.0) / f32(SUB);
+  let t = select(t0, t1, atEnd);
+  let p0 = rzTrailAt(subject, slot, seg - 1, n).xyz;
+  let p1 = rzTrail(subject, slot, seg).xyz;
+  let p2 = rzTrail(subject, slot, seg + 1).xyz;
+  let p3 = rzTrailAt(subject, slot, seg + 2, n).xyz;
+  let H = cam.targetHeight;
+  let toPx = vec2f((cam.proj[1][1] / cam.proj[0][0]) * H, H) * 0.5;
+  // The original's MIN_SEG_PX gate, restored as a HARD gate — not a fade.
+  //
+  // "Below this the hand is not moving", its comment said, and it meant it: a
+  // segment under 0.7px contributed NOTHING. Softening that into a weight that
+  // approaches zero let a pause stack dozens of near-stationary quads at full
+  // glow width, each individually faint, summing into a wide bright bar exactly
+  // where the hand slows — aggregation the width taper never clamps, because
+  // width follows AGE, not speed. Where the hand is not moving there is no path,
+  // and a path effect should draw nothing there at all.
+  let c1 = cam.proj * cam.view * vec4f(p1, 1.0);
+  let c2 = cam.proj * cam.view * vec4f(p2, 1.0);
+  if (c1.w <= 0.01 || c2.w <= 0.01 ||
+      distance(c1.xy / c1.w * toPx, c2.xy / c2.w * toPx) < 0.7 * (H / 1080.0)) {
+    out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
+    out.uv = vec2f(0.0);
+    out.age = 0.0;
+    out.weight = 0.0;
+    return out;
+  }
+  let pA = rzSpline(p0, p1, p2, p3, t0);
+  let pB = rzSpline(p0, p1, p2, p3, t1);
+  let p = select(pA, pB, atEnd);
+
+  // Age and position along the ribbon interpolate across the sub-segment too.
+  let ageA = rzTrail(subject, slot, seg).w;
+  let ageB = rzTrail(subject, slot, seg + 1).w;
+  let age = mix(ageA, ageB, t);
+  let u = (f32(seg) + t) / f32(max(1, n - 1));
+
+  // SCREEN-SPACE extrusion — the fresh take, and the faithful one.
+  //
+  // Every artefact this ribbon has had came from building it in 3D with a
+  // camera-facing side vector: fold-over wedges at tight turns, bowties when the
+  // tangent swept past the view axis, and twisted quads whose core line rotated
+  // ACROSS the strip and drew as a bright rung. The fullscreen original had none
+  // of them, because it never left 2D: it shaded distance to the PROJECTED path,
+  // in pixels. So project the spline to pixel space and extrude there — the same
+  // geometry the original shaded, at a quad's price. A 2D perpendicular cannot
+  // twist, and pixel width is what the original's constants meant all along.
+  let clipA = cam.proj * cam.view * vec4f(pA, 1.0);
+  let clipB = cam.proj * cam.view * vec4f(pB, 1.0);
+  if (clipA.w <= 0.01 || clipB.w <= 0.01) {
+    out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
+    out.uv = vec2f(0.0);
+    out.age = 0.0;
+    out.weight = 0.0;
+    return out;
+  }
+  // The projected tangent by the quotient rule — exact at the knot, so the two
+  // quads meeting there derive the identical perpendicular and share their edge.
+  let dA4 = cam.proj * cam.view * vec4f(rzSplineTangent(p0, p1, p2, p3, t0), 0.0);
+  let dB4 = cam.proj * cam.view * vec4f(rzSplineTangent(p0, p1, p2, p3, t1), 0.0);
+  var tanA = (dA4.xy * clipA.w - clipA.xy * dA4.w) * toPx;
+  var tanB = (dB4.xy * clipB.w - clipB.xy * dB4.w) * toPx;
+  if (length(tanA) < 1e-5) { tanA = vec2f(1.0, 0.0); }
+  if (length(tanB) < 1e-5) { tanB = vec2f(1.0, 0.0); }
+  var perpA = normalize(vec2f(-tanA.y, tanA.x));
+  var perpB = normalize(vec2f(-tanB.y, tanB.x));
+  // A projected cusp flips the perpendicular. The shade is symmetric in |v|, so
+  // forcing the quad's ends to agree is invisible — and without it the quad is a
+  // 2D bowtie.
+  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));
+  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);
+  // The line-integral weight: how far the hand travelled, evaluated AT EACH KNOT
+  // by central difference and mixed by t so it is continuous across boundaries —
+  // per-pair spans made dashes, per-segment averages made terraces.
+  let spanA = distance(p2, p0) * 0.5;
+  let spanB = distance(p3, p1) * 0.5;
+  out.weight = clamp(mix(spanA, spanB, t) / RZ_REF_SPAN, 0.0, 1.0);
+  out.uv = vec2f(u, c.y);
+  out.age = age;
+  return out;
+}
+
+struct TrailFSOut {
+  @location(0) color: vec4f,
+  // 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,
+}
+
+@fragment
+fn fs(in: VSOut) -> TrailFSOut {
+  // No manual depth test any more. This drew into its own attachment-less
+  // layer and compared position.z against the scene's depth texture by hand,
+  // with the direction baked per depth convention. Inside the scene pass the
+  // hardware does it, correctly and for free, and the reversed-Z trap that
+  // needed its own regression test goes with it.
+  let c = trailShade(in.uv.x, in.uv.y, in.age, in.weight, i32(in.slot));
+  if (c.a <= 0.0) { discard; }
+  var o: TrailFSOut;
+  // STRAIGHT colour into an ADDITIVE target, which reverses the old MAX rule
+  // deliberately: max existed so parallel strands could not double into bright
+  // dashes on a layer composited after tone mapping. In HDR before bloom,
+  // overlapping light SHOULD sum — that is what neon does — and the tone
+  // 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;
+}
+`);
+}

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/dist/shadow-cascades.d.ts

@@ -0,0 +1,45 @@
+type ShadowCascade = {
+    /** World units across the ortho box, both axes. */
+    span: number;
+    /** How far behind the target the light's eye sits, along -sunDir. */
+    back: number;
+    /** Ortho near/far, in world units from that eye. */
+    near: number;
+    far: number;
+    /** Texels per side of this cascade's map — sets the snap quantum. */
+    mapSize: number;
+};
+/**
+ * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
+ * each cascade's box must CONTAIN the previous one (same snapped target, wider
+ * span, deeper reach), because
+ *
+ *   - the sampler falls from cascade i to i+1 at the box edge, which is only
+ *     seamless if i+1 covers where i ends, and
+ *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
+ *     each cascade to its own box. That is the same argument that made
+ *     single-volume shadow culling exact: anything rejected was contributing
+ *     nothing anywhere. Concentric containment is what keeps it true for a
+ *     LIST. tests/shadow-cascades.test.mjs pins it.
+ */
+export declare const SHADOW_CASCADES: readonly ShadowCascade[];
+/**
+ * One cascade's view-projection, following the camera target.
+ *
+ * The target is snapped to this cascade's OWN texel quantum in the light's
+ * right/up plane, so a moving volume doesn't shimmer its shadow edges while
+ * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ *
+ * Writes the 16 floats into `out` at `offset` and returns `out`.
+ */
+export declare function buildShadowVP(target: {
+    x: number;
+    y: number;
+    z: number;
+}, sunDirection: {
+    x: number;
+    y: number;
+    z: number;
+}, cascade: ShadowCascade, out: Float32Array, offset: number): Float32Array;
+export {};
+//# sourceMappingURL=shadow-cascades.d.ts.map

package/dist/shadow-cascades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-cascades.d.ts","sourceRoot":"","sources":["../src/shadow-cascades.ts"],"names":[],"mappings":"AAeA,KAAK,aAAa,GAAG;IACnB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAWnD,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3C,YAAY,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,GACb,YAAY,CA4Bd"}

package/dist/shadow-cascades.js

@@ -0,0 +1,70 @@
+// The shadow volumes, as data — a list the engine iterates rather than one
+// hardcoded box, so a second cascade is a list entry and not a rewrite.
+//
+// Pure math, its own module for the same reason param-track.ts is: the engine
+// class needs a GPU to construct, and the one thing that ever goes WRONG with a
+// shadow volume is arithmetic — a snap that stops snapping, an eye that lands
+// inside the near plane. Headless tests can hold this half to golden values.
+//
+// The arithmetic is the shipped single-volume code, operation for operation:
+// float addition is not associative, so "the same formula, reordered" is not
+// the same matrix, and cascade 0 must be BIT-IDENTICAL to the volume every
+// published scene was lit by.
+import { Mat4, Vec3 } from "./math";
+/**
+ * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
+ * each cascade's box must CONTAIN the previous one (same snapped target, wider
+ * span, deeper reach), because
+ *
+ *   - the sampler falls from cascade i to i+1 at the box edge, which is only
+ *     seamless if i+1 covers where i ends, and
+ *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
+ *     each cascade to its own box. That is the same argument that made
+ *     single-volume shadow culling exact: anything rejected was contributing
+ *     nothing anywhere. Concentric containment is what keeps it true for a
+ *     LIST. tests/shadow-cascades.test.mjs pins it.
+ */
+export const SHADOW_CASCADES = [
+    // The shipped volume: 64 units at 4096² ≈ 64 texels/unit — crisp contact
+    // shadows on the ground catcher (2048 read visibly blurry).
+    { span: 64, back: 72, near: 1, far: 140, mapSize: 4096 },
+    // The stage volume: 4× the span on each side, so a set piece 100 units out
+    // still throws and receives shade instead of popping lit at the near box's
+    // edge. 2048² over 256 units ≈ 8 texels/unit — soft, and read at distances
+    // where soft is what a shadow looks like anyway. 16 MB where the near map
+    // is 64. Depth reach scales with the span (same eye direction, deeper box),
+    // keeping the containment invariant checkable from the specs alone.
+    { span: 256, back: 288, near: 1, far: 560, mapSize: 2048 },
+];
+/**
+ * One cascade's view-projection, following the camera target.
+ *
+ * The target is snapped to this cascade's OWN texel quantum in the light's
+ * right/up plane, so a moving volume doesn't shimmer its shadow edges while
+ * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ *
+ * Writes the 16 floats into `out` at `offset` and returns `out`.
+ */
+export function buildShadowVP(target, sunDirection, cascade, out, offset) {
+    const dir = new Vec3(sunDirection.x, sunDirection.y, sunDirection.z);
+    dir.normalize();
+    const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0);
+    const t = new Vec3(target.x, target.y, target.z);
+    const right = Vec3.crossInto(up, dir, new Vec3(0, 0, 0)).normalize();
+    const upv = Vec3.crossInto(dir, right, new Vec3(0, 0, 0));
+    const texel = cascade.span / cascade.mapSize;
+    const tr = Math.round(t.dot(right) / texel) * texel;
+    const tu = Math.round(t.dot(upv) / texel) * texel;
+    const td = t.dot(dir);
+    const snapped = new Vec3(right.x * tr + upv.x * tu + dir.x * td, right.y * tr + upv.y * tu + dir.y * td, right.z * tr + upv.z * tu + dir.z * td);
+    const eye = new Vec3(snapped.x - dir.x * cascade.back, snapped.y - dir.y * cascade.back, snapped.z - dir.z * cascade.back);
+    const view = Mat4.lookAt(eye, snapped, up);
+    const half = cascade.span / 2;
+    // The shadow map keeps the NON-reversed convention (orthographicLh maps z to
+    // [0,1] front-to-back) — reversing it buys nothing for an ortho box and the
+    // +2 pipeline depth bias is signed against this direction.
+    const proj = Mat4.orthographicLh(-half, half, -half, half, cascade.near, cascade.far);
+    const vp = proj.multiply(view);
+    out.set(vp.values, offset);
+    return out;
+}

package/dist/vmd-loader.d.ts

@@ -1,12 +1,12 @@
 import { Quat, Vec3 } from "./math";
-export interface BoneFrame {
+interface BoneFrame {
     boneName: string;
     frame: number;
     rotation: Quat;
     translation: Vec3;
     interpolation: Uint8Array;
 }
-export interface MorphFrame {
+interface MorphFrame {
     morphName: string;
     frame: number;
     weight: number;
@@ -70,4 +70,5 @@ export declare class VMDLoader {
     private getString;
     private skip;
 }
+export {};
 //# sourceMappingURL=vmd-loader.d.ts.map

package/dist/vmd-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACjD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EAAE;IAIvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}
+{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,UAAU,UAAU;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACjD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EAAE;IAIvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}

package/package.json

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