reze-engine 0.43.0 → 0.50.0

package/src/shaders/passes/trails.ts

@@ -1,4 +1,10 @@
+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"
 // Ribbons along a bone's recorded path, drawn as geometry.
 //
 // This is the effect the whole geometry path was built for. As a fullscreen
@@ -16,11 +22,14 @@ import { audioApi } from "../audio-api"
 // colour. Everything else — which bones, which characters, where the samples
 // are, how to face the camera — is the engine's.
 
-export type TrailSource = {
+type TrailSource = {
   /** The author's WGSL verbatim. */
   wgsl: string
-  /** Declared anchors with `trail`, in slot order. */
+  /** How many ribbons to draw — one per trailed anchor. */
   slots: number
+  /** For each ribbon, the LOCAL anchor slot it belongs to. Identity when every
+   *  anchor is trailed; otherwise it skips the untrailed ones. */
+  ribbonSlots: number[]
   /** Additive, like most glowing ribbons, or straight alpha. */
   blend: "alpha" | "additive"
   bloom: boolean
@@ -61,62 +70,39 @@ export function trailEntryPoints(wgsl: string): { width: boolean; shade: boolean
  * ribbon that loops back on itself stays visible along its entire length instead
  * of vanishing edge-on where it turns.
  */
-export function buildTrailShader(src: TrailSource, cast: { subjects: number; samples: number; base: number; trailBase: number }): string {
+export function buildTrailShader(
+  src: TrailSource,
+  cast: {
+    subjects: number
+    samples: number
+    base: number
+    trailBase: number
+    slots: number
+    alias: number[]
+    /** Depth convention of the scene buffer this layer tests against. The
+     *  occlusion compare below is MANUAL (the layer has no depth attachment),
+     *  so it does not flip with the pipelines' depthCompare — it has to be
+     *  emitted the right way round at build time. On a reversed-Z device,
+     *  larger z is CLOSER; the unflipped test drew ribbons only when occluded. */
+    reversedZ: boolean
+  },
+): string {
   return (
-    `const RZ_SUBJECTS: i32 = ${cast.subjects};
-const RZ_SAMPLES: i32 = ${cast.samples};
-const RZ_SLOTS: i32 = ${src.slots};
-const RZ_TRAIL_SLOTS: i32 = ${src.slots};
+    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};
 
-// The same struct and helpers the particle modules define. The whole effect
-// file is spliced into EVERY module its mounts compile into, so an effect that
-// declares both trails and particles carries its particle functions through
-// this module as dead code — dead code that still has to type-check. Keeping
-// the two preludes' public surface identical is what makes one file, two
-// mounts work.
-struct Particle {
-  pos: vec3f,
-  age: f32,
-  vel: vec3f,
-  life: f32,
-  size: f32,
-  rot: f32,
-  seed: f32,
-  stretch: f32,
-}
-fn rzDt() -> f32 { return 0.0; }
-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);
-}
-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);
-  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);
-}
 // World units a sample pair must span to count as a FULL contribution — the
 // original's REF_SEG_PX, converted out of pixels.
 //
@@ -144,9 +130,13 @@ struct TrailU {
 @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;
-@group(0) @binding(3) var sceneDepth: texture_depth_multisampled_2d;
+// 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.
 
-fn rzTime() -> f32 { return tu.time; }
+${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]); }
@@ -157,7 +147,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 rzViewportHeight() -> f32 { return cam.targetHeight; }
 fn rzCamPos() -> vec3f { return cam.camPos; }
 fn rzSubjectCount() -> i32 {
   var n = 0;
@@ -166,16 +155,6 @@ fn rzSubjectCount() -> i32 {
   }
   return n;
 }
-fn rzTrailCount(subject: i32, slot: i32) -> i32 {
-  if (subject < 0 || subject >= RZ_SUBJECTS || slot < 0 || slot >= RZ_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];
-}
 /** 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;
@@ -240,18 +219,10 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
   if (la < 1e-5 || lb < 1e-5 || cr < 1e-7) { return 1e6; }
   return (la * lb * length(ca)) / (2.0 * cr);
 }
-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 rzHash11(x: f32) -> f32 {
-  var p = fract(x * 0.1031);
-  p = p * (p + 33.33);
-  return fract(p * (p + p));
-}
 ` +
     audioApi(0, 4) +
+    midiApi(0, 5) +
+    lyricsApi(0, 6) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `
@@ -274,10 +245,14 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   let seg = k / SUB;
   let sub = k % SUB;
   let subject = i32(rest % u32(RZ_SUBJECTS));
-  let slot = 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 (slot >= RZ_SLOTS || seg + 1 >= n) {
+  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;
@@ -384,22 +359,31 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   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) -> @location(0) vec4f {
-  // Manual depth test against the scene's own buffer — the layer has no depth
-  // attachment, and a per-fragment compare is exactly what the fullscreen
-  // version did (segZ <= depth). position.z IS this fragment's depth.
-  let sceneD = textureLoad(sceneDepth, vec2i(in.clip.xy), 0);
-  if (in.clip.z > sceneD) { discard; }
+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; }
-  // STRAIGHT colour, into a layer that blends with MAX — which is the
-  // original's core-takes-the-max rule turned into a blend mode. Parallel
-  // strands of a circling hand meet as max, so they can never sum into the
-  // doubled bright dashes that additive drew along the path. The layer then
-  // composites over the frame AFTER tone mapping, where the fullscreen ribbon
-  // always ran — so these colours reach the screen verbatim.
-  return vec4f(c.rgb, c.a);
+  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/src/shadow-cascades.ts

@@ -0,0 +1,97 @@
+// 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"
+
+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 const SHADOW_CASCADES: readonly ShadowCascade[] = [
+  // 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: { x: number; y: number; z: number },
+  sunDirection: { x: number; y: number; z: number },
+  cascade: ShadowCascade,
+  out: Float32Array,
+  offset: number,
+): Float32Array {
+  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/src/vmd-loader.ts

@@ -1,6 +1,6 @@
 import { Quat, Vec3 } from "./math"
 
-export interface BoneFrame {
+interface BoneFrame {
   boneName: string
   frame: number
   rotation: Quat
@@ -8,7 +8,7 @@ export interface BoneFrame {
   interpolation: Uint8Array // 64 bytes of interpolation parameters
 }
 
-export interface MorphFrame {
+interface MorphFrame {
   morphName: string
   frame: number
   weight: number // 0.0 to 1.0