reze-engine 0.54.15 → 0.55.0

package/dist/shaders/passes/wireframe.js

@@ -0,0 +1,107 @@
+// The mesh itself, as lines, in the overlay layer.
+//
+// It skins here rather than reading the loader's CPU positions, and that is most
+// of why the pass exists. What is on screen is skinned and morphed on the GPU;
+// the CPU-side array is BIND POSE. Draw from that and the wireframe sits
+// perfectly on a T-posed model and slides off every animated one — which is
+// exactly the state a user is in while looking at weights.
+//
+// Each edge is expanded into a screen-space QUAD rather than drawn with line
+// topology. WebGPU pins a line to one device pixel, and one device pixel on a 2x
+// display is half a CSS pixel, which 4x MSAA then spreads across two of them:
+// the result is a grey suggestion of a wireframe rather than a wireframe. So the
+// draw is six vertices per edge, instanced, and the mesh is read through STORAGE
+// buffers — there is no per-vertex stream, because a quad's two corners come
+// from two different vertices of the model.
+//
+// The depth prepass shares this module's `vs` through its own entry point: it
+// draws the solid triangles with vertex buffers, writing depth only, so the
+// wireframe can be occluded by the body it belongs to.
+export const WIREFRAME_SHADER_WGSL = /* wgsl */ `
+struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _pad: f32 };
+struct WireUniforms { color: vec4f, viewport: vec2f, thicknessPx: f32, _pad: f32 };
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> wire: WireUniforms;
+
+@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
+// The model's own vertex buffer: pos(3), normal(3), uv(2) — 8 floats a vertex.
+@group(1) @binding(1) var<storage, read> vertices: array<f32>;
+// uint16x4 per vertex, so two u32 each.
+@group(1) @binding(2) var<storage, read> joints: array<u32>;
+// unorm8x4 per vertex, one u32 each.
+@group(1) @binding(3) var<storage, read> weights: array<u32>;
+// Pairs of vertex indices, one pair an edge.
+@group(1) @binding(4) var<storage, read> edges: array<u32>;
+
+fn skinnedPos(i: u32) -> vec3f {
+  let o = i * 8u;
+  let rest = vec4f(vertices[o], vertices[o + 1u], vertices[o + 2u], 1.0);
+
+  let j0 = joints[i * 2u];
+  let j1 = joints[i * 2u + 1u];
+  let packed = weights[i];
+  var w = vec4f(
+    f32(packed & 0xffu),
+    f32((packed >> 8u) & 0xffu),
+    f32((packed >> 16u) & 0xffu),
+    f32((packed >> 24u) & 0xffu),
+  ) / 255.0;
+  let sum = w.x + w.y + w.z + w.w;
+  w = select(vec4f(1.0, 0.0, 0.0, 0.0), w / max(sum, 1e-4), sum > 0.0001);
+
+  var acc = vec4f(0.0);
+  acc += (skinMats[j0 & 0xffffu] * rest) * w.x;
+  acc += (skinMats[j0 >> 16u] * rest) * w.y;
+  acc += (skinMats[j1 & 0xffffu] * rest) * w.z;
+  acc += (skinMats[j1 >> 16u] * rest) * w.w;
+  return acc.xyz;
+}
+
+// Six vertices an edge: (a,-1) (a,+1) (b,-1) (a,+1) (b,+1) (b,-1).
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4f {
+  let a = edges[ii * 2u];
+  let b = edges[ii * 2u + 1u];
+  let vp = camera.projection * camera.view;
+  let ca = vp * vec4f(skinnedPos(a), 1.0);
+  let cb = vp * vec4f(skinnedPos(b), 1.0);
+
+  let atB = vi == 2u || vi == 4u || vi == 5u;
+  let side = select(-1.0, 1.0, vi == 1u || vi == 3u || vi == 4u);
+  let own = select(ca, cb, atB);
+  let other = select(cb, ca, atB);
+
+  let half = 0.5 * wire.viewport;
+  let s0 = (own.xy / max(abs(own.w), 1e-6)) * half;
+  let s1 = (other.xy / max(abs(other.w), 1e-6)) * half;
+  let d = s1 - s0;
+  // A degenerate edge has no direction on screen; any perpendicular will do,
+  // and it is a dot either way.
+  let tangent = select(vec2f(1.0, 0.0), normalize(d), length(d) > 1e-6);
+  let normalPx = vec2f(-tangent.y, tangent.x);
+  let offsetPx = normalPx * side * wire.thicknessPx * 0.5;
+  return vec4f(own.xy + (offsetPx / half) * own.w, own.z, own.w);
+}
+
+// The depth prepass: the solid mesh through the ordinary vertex stream, writing
+// depth and nothing else, so the far side of a body is hidden behind the near.
+@vertex fn vsDepth(
+  @location(0) position: vec3f,
+  @location(1) joints0: vec4<u32>,
+  @location(2) weights0: vec4<f32>,
+) -> @builtin(position) vec4f {
+  let rest = vec4f(position, 1.0);
+  let sum = weights0.x + weights0.y + weights0.z + weights0.w;
+  let w = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 / max(sum, 1e-4), sum > 0.0001);
+  var acc = vec4f(0.0);
+  for (var i = 0u; i < 4u; i++) {
+    acc += (skinMats[joints0[i]] * rest) * w[i];
+  }
+  return camera.projection * camera.view * vec4f(acc.xyz, 1.0);
+}
+
+@fragment fn fs() -> @location(0) vec4f {
+  // Premultiplied, like every other fragment in this layer.
+  return vec4f(wire.color.rgb * wire.color.a, wire.color.a);
+}
+`;

package/dist/shaders/scene-tap.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The scene tap: the frame as the scene left it, for effects that bend light.
+ *
+ * ITS OWN FILE, AND IT IMPORTS NOTHING — the same rule and the same reason as
+ * cast-layout.ts. composite.ts already imports from lights.ts, so putting the
+ * stub in composite and importing it back into lights closes a cycle, and the
+ * first thing to touch that cycle throws "Cannot access RZ_LIGHT_STRUCT_WGSL
+ * before initialization" at module load: the whole engine failing to start on
+ * an import order nobody chose. Three modules need these strings; none of them
+ * may depend on another to get them.
+ */
+/**
+ * rzScene(uv) — the frame as the scene left it.
+ *
+ * The one thing a foreground could not do: an effect knew WHERE the scene was,
+ * through bgWorldPos and the depth tap, but never what COLOUR it was. Anything
+ * that RESAMPLES the picture needs this — refraction, heat haze, glass, a
+ * pixelated cast, and every CRT trick worth having (barrel curve, the RGB
+ * ghost, a torn line dragged sideways) is a read of the frame at a uv other
+ * than this pixel's own.
+ *
+ * WHAT IT IS NOT. The field pass runs BEFORE the composite, so this is the
+ * resolved scene — models, stage, ground — and nothing the composite adds
+ * afterwards: not the background colour, not a background effect, not the tone
+ * map, not the grade. Warping it warps the cast and the floor while the
+ * backdrop behind them stays put. That is a real limit, not a bug to route
+ * around, and an effect that wants the whole finished picture wants a pass
+ * after the composite instead.
+ *
+ * HDR and LINEAR for the same reason — it is read before the tone map, so
+ * values run past 1 and an effect doing display-space arithmetic on them
+ * should tone them itself.
+ *
+ * Legal because of pass order, and only that: the field pass runs after the
+ * scene pass has ended and RESOLVED, so this samples a finished texture rather
+ * than one being written into. Same reason the depth tap works, and it breaks
+ * the same way if either ever moves.
+ *
+ * ITS OWN SAMPLER, deliberately. castDistanceApi and gridReadApi already both
+ * declare one at binding 18, which is legal only while no single entry point
+ * references both; borrowing either made every effect that also touches the
+ * grid reference two variables at one binding, and WGSL rejects the module.
+ * Clamp-to-edge is what stops a warped offset wrapping the far side of the
+ * screen into the picture.
+ */
+export declare function sceneTapApi(group: number, tex: number, samp: number): string;
+/**
+ * The same names, for the modules with no finished scene to give.
+ *
+ * An effect file is spliced into EVERY module it has a mount in, so a water
+ * effect with a gridStep compiles its foreground() inside the SIM shader as
+ * well — dead code there that nothing calls, but code that still has to
+ * resolve. Without this, adding a scene read to any effect that also drives a
+ * grid fails to install with "unresolved call target rzScene".
+ *
+ * Black, not a guess: every one of these modules steps BEFORE the scene pass
+ * resolves, so at the moment they run the frame does not exist.
+ */
+export declare const SCENE_TAP_STUB = "\nfn rzScene(uv: vec2f) -> vec3f { return vec3f(0.0); }\nfn bgScene(uv: vec2f) -> vec3f { return rzScene(uv); }\n/** Far, which in these modules is true: no geometry has been drawn yet. */\nfn rzSceneDepth(uv: vec2f) -> f32 { return 1e9; }\nfn rzSceneFar() -> f32 { return 1e9; }\nfn rzSceneHit(uv: vec2f) -> bool { return false; }\nfn rzSceneAlpha(uv: vec2f) -> f32 { return 0.0; }\nfn rzSceneDisplay(uv: vec2f) -> vec3f { return vec3f(0.0); }\nfn rzSceneFrame(uv: vec2f) -> vec3f { return vec3f(0.0); }\nfn rzBackground() -> vec4f { return vec4f(0.0); }\n";
+//# sourceMappingURL=scene-tap.d.ts.map

package/dist/shaders/scene-tap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-tap.d.ts","sourceRoot":"","sources":["../../src/shaders/scene-tap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoK5E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,kjBAW1B,CAAA"}

package/dist/shaders/scene-tap.js

@@ -0,0 +1,234 @@
+/**
+ * The scene tap: the frame as the scene left it, for effects that bend light.
+ *
+ * ITS OWN FILE, AND IT IMPORTS NOTHING — the same rule and the same reason as
+ * cast-layout.ts. composite.ts already imports from lights.ts, so putting the
+ * stub in composite and importing it back into lights closes a cycle, and the
+ * first thing to touch that cycle throws "Cannot access RZ_LIGHT_STRUCT_WGSL
+ * before initialization" at module load: the whole engine failing to start on
+ * an import order nobody chose. Three modules need these strings; none of them
+ * may depend on another to get them.
+ */
+/**
+ * rzScene(uv) — the frame as the scene left it.
+ *
+ * The one thing a foreground could not do: an effect knew WHERE the scene was,
+ * through bgWorldPos and the depth tap, but never what COLOUR it was. Anything
+ * that RESAMPLES the picture needs this — refraction, heat haze, glass, a
+ * pixelated cast, and every CRT trick worth having (barrel curve, the RGB
+ * ghost, a torn line dragged sideways) is a read of the frame at a uv other
+ * than this pixel's own.
+ *
+ * WHAT IT IS NOT. The field pass runs BEFORE the composite, so this is the
+ * resolved scene — models, stage, ground — and nothing the composite adds
+ * afterwards: not the background colour, not a background effect, not the tone
+ * map, not the grade. Warping it warps the cast and the floor while the
+ * backdrop behind them stays put. That is a real limit, not a bug to route
+ * around, and an effect that wants the whole finished picture wants a pass
+ * after the composite instead.
+ *
+ * HDR and LINEAR for the same reason — it is read before the tone map, so
+ * values run past 1 and an effect doing display-space arithmetic on them
+ * should tone them itself.
+ *
+ * Legal because of pass order, and only that: the field pass runs after the
+ * scene pass has ended and RESOLVED, so this samples a finished texture rather
+ * than one being written into. Same reason the depth tap works, and it breaks
+ * the same way if either ever moves.
+ *
+ * ITS OWN SAMPLER, deliberately. castDistanceApi and gridReadApi already both
+ * declare one at binding 18, which is legal only while no single entry point
+ * references both; borrowing either made every effect that also touches the
+ * grid reference two variables at one binding, and WGSL rejects the module.
+ * Clamp-to-edge is what stops a warped offset wrapping the far side of the
+ * screen into the picture.
+ */
+export function sceneTapApi(group, tex, samp) {
+    return /* wgsl */ `
+@group(${group}) @binding(${tex}) var _rzSceneTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzSceneSamp: sampler;
+
+/** uv as the mount gives it (y=0 at the BOTTOM, the shadertoy convention the
+ *  composite documents) turned into a texture coordinate (y=0 at the top).
+ *  Sampling the mount's uv straight returns the scene upside down, which is a
+ *  bug that looks like an art direction — so it is done here once rather than in
+ *  every effect that reads the frame. */
+fn _rzTapUv(uv: vec2f) -> vec2f {
+  return clamp(vec2f(uv.x, 1.0 - uv.y), vec2f(0.0), vec2f(1.0));
+}
+
+/**
+ * How much of this pixel the scene COVERS, 0..1.
+ *
+ * The half of the frame that colour alone cannot tell you, and the reason a
+ * ground that fades to nothing at its rim came back as a hard-edged slab. The
+ * scene renders into a PREMULTIPLIED target, so a plane drawn at 48% with a
+ * radial falloff stores a dimmer colour, not a lighter one — read the colour and
+ * ignore this and you get an opaque dark rectangle where there was a fading
+ * sheet. It is also finer than any depth test: depth is binary and a plane
+ * writes it across its whole square whatever its alpha does.
+ */
+fn rzSceneAlpha(uv: vec2f) -> f32 {
+  let sz = vec2f(textureDimensions(maskTex));
+  let p = clamp(_rzTapUv(uv) * sz, vec2f(0.0), sz - vec2f(1.0));
+  return textureLoad(maskTex, vec2<i32>(p), 0).g;
+}
+
+/**
+ * The scene at uv in LINEAR light, straight rather than premultiplied, with the
+ * bloom the composite would add to it. What the view transform takes.
+ *
+ * Divided back out by coverage, so this is the colour the geometry HAS rather
+ * than the colour it contributes. Where nothing was drawn the division is
+ * meaningless and the result is black — pair it with rzSceneAlpha, never use it
+ * alone.
+ */
+fn rzScene(uv: vec2f) -> vec3f {
+  let p = _rzTapUv(uv);
+  let pm = textureSampleLevel(_rzSceneTex, _rzSceneSamp, p, 0.0).rgb;
+  let straight = pm / max(rzSceneAlpha(uv), 1e-6);
+  let bloom = textureSampleLevel(bloomTex, bloomSamp, p, 0.0).rgb * viewU[1].xyz * viewU[1].w;
+  return straight + bloom;
+}
+/** Alias, matching bgWorldPos and the rest of the bg-prefixed surface. */
+fn bgScene(uv: vec2f) -> vec3f { return rzScene(uv); }
+
+/**
+ * How far the scene is at ANY pixel — the depth tap, off this fragment's leash.
+ *
+ * foreground() is handed the depth of its OWN pixel, which answers "is this
+ * behind me" and nothing else. Anything that resamples asks a different
+ * question: it reads the frame somewhere else and needs to know whether the
+ * scene was even drawn THERE. One pixel's depth cannot say, and without it an
+ * effect that replaces pixels has to replace all of them — painting the empty
+ * sky black because that is what the scene texture holds where nothing drew.
+ *
+ * NO NEW BINDING. The depth buffer has been in this group since foreground got
+ * its argument and linearDepth already inverts it; this only lets an effect name
+ * a pixel other than its own. Metres along the view axis, the same units as the
+ * depth argument and as rzProject's z, so comparing them is a subtraction.
+ *
+ * Cleared depth inverts to the far plane, so "nothing here" reads as a very
+ * large number rather than as zero.
+ */
+fn rzSceneDepth(uv: vec2f) -> f32 {
+  let sz = vec2f(textureDimensions(depthTex));
+  let p = clamp(vec2f(uv.x, 1.0 - uv.y) * sz, vec2f(0.0), sz - vec2f(1.0));
+  return linearDepth(vec2<i32>(p));
+}
+
+/**
+ * The far plane, in the same metres rzSceneDepth answers in.
+ *
+ * Read straight from the uniform the camera writes it into, NOT re-derived by
+ * inverting a cleared depth. That inversion is projB / (1 - projA), whose sign
+ * depends on which way round the projection maps z — and when it comes out
+ * wrong it does not error, it clamps to the near plane and every rzSceneHit
+ * answers false, so the effect silently draws nothing at all.
+ */
+fn rzSceneFar() -> f32 {
+  return max(dofU[2].z, 0.05);
+}
+
+/**
+ * Was anything actually DRAWN at this uv?
+ *
+ * The question every effect that resamples has to ask, and the one no author
+ * should answer with a constant. The far plane is not a fixed number here — it
+ * tracks the camera (roughly its orbit radius times twelve), so a threshold
+ * picked by eye is right at one distance and wrong at every other. Guess high
+ * and empty sky reads as geometry, and an effect that replaces pixels paints the
+ * background black; guess low and the far half of a stage disappears.
+ *
+ * Compared against the plane itself, with a hair of margin for the precision the
+ * inversion loses out there.
+ */
+fn rzSceneHit(uv: vec2f) -> bool {
+  return rzSceneDepth(uv) < rzSceneFar() * 0.995;
+}
+
+/**
+ * The scene at uv, in the SAME space as the pixel it would replace.
+ *
+ * rzScene is linear and pre-tone-map. Anything that resamples has to put what it
+ * fetched back into display space, and every effect that tried did it by hand —
+ * a Reinhard shoulder and a 2.2 gamma, near enough at a glance and wrong
+ * everywhere it mattered. The tell is a mosaic or a glitch applied to part of
+ * the frame: the treated region reads a shade off from the untreated one beside
+ * it, and no amount of tuning closes it, because the engine's curve is Filmic or
+ * AgX with the scene's own exposure and grade, not a shoulder.
+ *
+ * So it is not approximated. This is the composite's own chain — exposure,
+ * viewTransform, the grade when the scene has one, then the display gamma —
+ * applied to the same sample. Fetch a pixel at its own uv through this and you
+ * get the pixel that is already there, so a displacement of zero is invisible
+ * and the boundary of any masked effect disappears.
+ *
+ * The gamma is applied unconditionally rather than behind APPLY_GAMMA: the
+ * override is a pipeline constant the field pass need not share, and pow(x, 1)
+ * is the identity, so writing it out is both safer and equivalent.
+ */
+fn rzSceneDisplay(uv: vec2f) -> vec3f {
+  var c = max(viewTransform(rzScene(uv) * exp2(viewU[0].x)), vec3f(0.0));
+  if (viewU[9].w > 0.5) { c = grade(c); }
+  return pow(max(c, vec3f(0.0)), vec3f(viewU[0].y));
+}
+
+/**
+ * The finished pixel: the scene over its background, exactly as the composite
+ * would lay it down. One call, and the answer already carries the ground's
+ * fade, its opacity, and the background showing through both.
+ *
+ * This is what a FILTER wants — anything re-rendering the whole frame on a tube
+ * or a low-resolution screen. Reaching for rzSceneDisplay and a depth test
+ * instead rebuilds this by hand and gets it wrong in one specific way every
+ * time: coverage is not a yes or no, and treating it as one turns every soft
+ * edge in the scene into a hard one.
+ *
+ * NOT INCLUDED: depth of field, background effects, and an equirect background
+ * (a 360 dome reads as its average rather than its texture). Foregrounds compose
+ * after this in any case.
+ */
+fn rzSceneFrame(uv: vec2f) -> vec3f {
+  let a = clamp(rzSceneAlpha(uv), 0.0, 1.0);
+  let bg = viewU[2];
+  let bgRgb = bg.rgb * select(0.0, 1.0, bg.w > 0.5);
+  return rzSceneDisplay(uv) * a + bgRgb * (1.0 - a);
+}
+
+/**
+ * The scene's background: rgb is the picked colour in DISPLAY space, and w says
+ * what kind it is — 0 transparent (a backdrop or an alpha export is showing
+ * through), 1 a flat colour, above 1 an equirect dome.
+ *
+ * For effects that need to know what sits behind the scene. It is NOT what a
+ * background effect drew — those compose in the pass after this one — so an
+ * effect that paints over the background with this erases them.
+ */
+fn rzBackground() -> vec4f { return viewU[2]; }
+`;
+}
+/**
+ * The same names, for the modules with no finished scene to give.
+ *
+ * An effect file is spliced into EVERY module it has a mount in, so a water
+ * effect with a gridStep compiles its foreground() inside the SIM shader as
+ * well — dead code there that nothing calls, but code that still has to
+ * resolve. Without this, adding a scene read to any effect that also drives a
+ * grid fails to install with "unresolved call target rzScene".
+ *
+ * Black, not a guess: every one of these modules steps BEFORE the scene pass
+ * resolves, so at the moment they run the frame does not exist.
+ */
+export const SCENE_TAP_STUB = /* wgsl */ `
+fn rzScene(uv: vec2f) -> vec3f { return vec3f(0.0); }
+fn bgScene(uv: vec2f) -> vec3f { return rzScene(uv); }
+/** Far, which in these modules is true: no geometry has been drawn yet. */
+fn rzSceneDepth(uv: vec2f) -> f32 { return 1e9; }
+fn rzSceneFar() -> f32 { return 1e9; }
+fn rzSceneHit(uv: vec2f) -> bool { return false; }
+fn rzSceneAlpha(uv: vec2f) -> f32 { return 0.0; }
+fn rzSceneDisplay(uv: vec2f) -> vec3f { return vec3f(0.0); }
+fn rzSceneFrame(uv: vec2f) -> vec3f { return vec3f(0.0); }
+fn rzBackground() -> vec4f { return vec4f(0.0); }
+`;

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.54.15",
+  "version": "0.55.0",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",