reze-engine 0.54.16 → 0.55.0

package/dist/shaders/passes/field-blit.js

@@ -0,0 +1,65 @@
+import { sceneFsOutWgsl } from "./scene-contract";
+/**
+ * The field layer, drawn INTO the scene.
+ *
+ * Field effects render into their own targets at their own resolution — that
+ * part was always right. What was wrong was where the result landed: the
+ * composite sampled it AFTER tone mapping, which is why a field effect could
+ * never bloom, could never light anything, and tone mapped differently from the
+ * particle and ribbon mounts drawing the same kind of glow.
+ *
+ * Two draws inside the scene pass — background before any geometry, foreground
+ * after all of it — so the bloom pyramid sees field effects and one tone map
+ * covers the whole frame.
+ *
+ * NO DEPTH, neither written nor tested. A foreground is handed the scene's
+ * depth as a parameter and does its own occlusion; testing it here would
+ * occlude it a second time, and a background has nothing to test against.
+ *
+ * COVERAGE IS CLAMPED HERE. Additive field effects SUM their coverage into the
+ * layer (see FIELD_LAYER_BLEND_ADDITIVE), which is what stops the composite's
+ * unpremultiply from dividing colour by nothing — but N additive effects can
+ * sum past 1, and the layer is rgba16float so nothing stopped it on the way in.
+ * A coverage above 1 would darken what the layer is drawn over by more than
+ * fully covering it.
+ */
+export function fieldBlitShaderWgsl() {
+    return /* wgsl */ `
+@group(0) @binding(0) var _rzLayer: texture_2d<f32>;
+@group(0) @binding(1) var _rzLayerSamp: sampler;
+// (bloom, _, fullW, fullH). The size is the SCENE target's, not the layer's:
+// the layer is often half resolution, and normalised uv is what makes that
+// invisible.
+@group(0) @binding(2) var<uniform> _rzBlitU: vec4f;
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+${sceneFsOutWgsl()}
+@fragment fn fs(@builtin(position) fragCoord: vec4f) -> FSOut {
+  var out: FSOut;
+  // Bilinear, because the layer is usually half resolution and the whole point
+  // of that choice is that low-frequency effects upsample invisibly.
+  let uv = fragCoord.xy / max(_rzBlitU.zw, vec2f(1.0));
+  let c = textureSampleLevel(_rzLayer, _rzLayerSamp, uv, 0.0);
+  let cov = clamp(c.a, 0.0, 1.0);
+  // PREMULTIPLIED, and blitted with a premultiplied-over blend — the field
+  // targets have been premultiplied since N effects had to compose into them
+  // associatively. Handing this to the material blend would scale rgb by alpha
+  // a second time and every layer would come out dark.
+  out.color = vec4f(max(c.rgb, vec3f(0.0)), cov);
+  // The aux target: bloom mask, then coverage. THIS is what finally makes
+  // // @bloom mean something on a field effect — the flag has been parsed and
+  // ignored for every mount but particles and ribbons, which is the kind of
+  // author-surface lie the install-time guards exist to kill.
+  //
+  // The mask is written UNWEIGHTED and the blend weights it by src.a — the
+  // convention the materials already follow (they write vec4f(1, 1, 0, alpha)).
+  out.mask = vec4f(_rzBlitU.x, 1.0, 0.0, cov);
+  return out;
+}
+`;
+}

package/dist/shaders/passes/ground-noise.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The tile as 8-bit luminance, plus its mip chain (box-filtered, which is exact
+ * for a repeating texture). Mips are the point as much as the speed: procedural
+ * noise has no mip chain, so at grazing angles it shimmered.
+ */
+export declare function buildGroundNoiseMips(): Uint8Array[];
+//# sourceMappingURL=ground-noise.d.ts.map

package/dist/shaders/passes/ground-noise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-noise.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground-noise.ts"],"names":[],"mappings":"AAkDA;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAsCnD"}

package/dist/shaders/passes/ground-noise.js

@@ -0,0 +1,88 @@
+// Bakes the ground's frosted micro-texture into a seamless, mipmapped tile.
+//
+// The shader used to evaluate four octaves of value noise per pixel — sixteen
+// hash rounds — and the ground covers the entire screen as soon as the camera
+// tilts toward the horizon. This produces the same character of pattern once, at
+// load, so the fragment shader pays one filtered fetch instead.
+//
+// SEAMLESS BY CONSTRUCTION. The original hash was not periodic, so a finite
+// crop of it could never tile. Here every octave's lattice wraps at a whole
+// number of cells across the tile, which makes the result repeat exactly at the
+// edges. The pattern is therefore not pixel-identical to the analytic version —
+// it is the same kind of noise, not the same noise. At the default strength of
+// 0.05 it modulates brightness by ±2.5%, where the repeat is not findable by eye.
+import { GROUND_NOISE_RES, GROUND_NOISE_TILE_WORLD } from "./ground";
+/** Lattice cells across the tile at octave 0. The analytic version sampled fbm
+ *  at worldXZ × 3, so a tile spanning 8 world units covers 24 base cells — the
+ *  same spatial frequency the surface had before. */
+const BASE_CELLS = GROUND_NOISE_TILE_WORLD * 3;
+const OCTAVES = 4;
+/** Deterministic lattice hash. Integer coordinates are wrapped by the caller,
+ *  which is what makes the tile seamless. */
+function hash(ix, iy) {
+    let h = Math.imul(ix, 374761393) + Math.imul(iy, 668265263);
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+/** Value noise on a lattice that repeats every `period` cells. */
+function periodicValueNoise(x, y, period) {
+    const ix = Math.floor(x);
+    const iy = Math.floor(y);
+    const fx = x - ix;
+    const fy = y - iy;
+    // Smoothstep weights — same curve the WGSL used.
+    const ux = fx * fx * (3 - 2 * fx);
+    const uy = fy * fy * (3 - 2 * fy);
+    const x0 = ((ix % period) + period) % period;
+    const y0 = ((iy % period) + period) % period;
+    const x1 = (x0 + 1) % period;
+    const y1 = (y0 + 1) % period;
+    const a = hash(x0, y0);
+    const b = hash(x1, y0);
+    const c = hash(x0, y1);
+    const d = hash(x1, y1);
+    return (a + (b - a) * ux) * (1 - uy) + (c + (d - c) * ux) * uy;
+}
+/**
+ * The tile as 8-bit luminance, plus its mip chain (box-filtered, which is exact
+ * for a repeating texture). Mips are the point as much as the speed: procedural
+ * noise has no mip chain, so at grazing angles it shimmered.
+ */
+export function buildGroundNoiseMips() {
+    const levels = [];
+    const res = GROUND_NOISE_RES;
+    const base = new Uint8Array(res * res);
+    for (let py = 0; py < res; py++) {
+        for (let px = 0; px < res; px++) {
+            // Texel centre, in units of octave-0 lattice cells.
+            const x = ((px + 0.5) / res) * BASE_CELLS;
+            const y = ((py + 0.5) / res) * BASE_CELLS;
+            let v = 0;
+            let amp = 0.5;
+            let freq = 1;
+            for (let o = 0; o < OCTAVES; o++) {
+                v += amp * periodicValueNoise(x * freq, y * freq, BASE_CELLS * freq);
+                freq *= 2;
+                amp *= 0.5;
+            }
+            base[py * res + px] = Math.max(0, Math.min(255, Math.round(v * 255)));
+        }
+    }
+    levels.push(base);
+    let src = base;
+    let size = res;
+    while (size > 1) {
+        const half = size >> 1;
+        const dst = new Uint8Array(half * half);
+        for (let y = 0; y < half; y++) {
+            for (let x = 0; x < half; x++) {
+                const s = y * 2 * size + x * 2;
+                dst[y * half + x] = (src[s] + src[s + 1] + src[s + size] + src[s + size + 1] + 2) >> 2;
+            }
+        }
+        levels.push(dst);
+        src = dst;
+        size = half;
+    }
+    return levels;
+}

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

@@ -0,0 +1,3 @@
+export declare const OVERLAY_SHADER_WGSL = "\nstruct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _pad: f32 };\n// 16 bytes exactly. Scalars rather than a vec3f tail: a vec3f aligns to 16 and\n// would push the struct past the buffer the pipeline is handed.\nstruct OverlayUniforms { viewport: vec2f, dashPeriodPx: f32, _pad0: f32 };\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> overlay: OverlayUniforms;\n\nstruct VSOut {\n  @builtin(position) pos: vec4f,\n  @location(0) @interpolate(flat) color: vec4f,\n}\n\nfn qrot(q: vec4f, v: vec3f) -> vec3f {\n  let t = 2.0 * cross(q.xyz, v);\n  return v + q.w * t + cross(q.xyz, t);\n}\n\n// Placement mode, carried per VERTEX because it belongs to the shape rather than\n// to the copy.\n//\n//   0  world    \u2014 rotate, scale, translate. The shapes that ARE geometry:\n//                 rigidbody volumes, joint crosses, plain lines.\n//   3  facing   \u2014 a flat filled shape in the camera's plane, radius scale.x.\n//                 The bone marker's solid centre.\n//   5  solid    \u2014 placed in world like mode 0, but filled: the rigidbody\n//                 volumes, which read as volumes rather than as a cage of lines.\n//   4  annulus  \u2014 the marker's ring: world radius scale.x, and a stroke that is\n//                 a PIXEL width like every other line, so the two links leave it\n//                 as a continuation of the same stroke rather than a step. The\n//                 inner and outer rims are offset radially in screen space,\n//                 which is what lets a small circle carry a thick stroke \u2014 the\n//                 stroked polyline that preceded it tore into a sunburst as soon\n//                 as the width passed the segment length.\n//   2  link     \u2014 the taper from a bone to its child: along the bone, splayed\n//                 across it in whichever direction the camera can actually see,\n//                 so the two lines never collapse into one.\nfn placeWorld(p: vec3f, capSign: f32, iRot: vec4f, iPos: vec4f, iScale: vec4f, mode: f32) -> vec3f {\n  let right = vec3f(camera.view[0].x, camera.view[1].x, camera.view[2].x);\n  let up = vec3f(camera.view[0].y, camera.view[1].y, camera.view[2].y);\n\n  if (mode > 2.5) {\n    return iPos.xyz + (right * p.x + up * p.y) * iScale.x;\n  }\n  if (mode > 1.5) {\n    let boneDir = normalize(qrot(iRot, vec3f(0.0, 1.0, 0.0)));\n    let camFwd = vec3f(camera.view[0].z, camera.view[1].z, camera.view[2].z);\n    var splay = cross(boneDir, camFwd);\n    let sl = length(splay);\n    // Looking straight down the bone there is no visible across, and any\n    // perpendicular does \u2014 the taper is a dot on screen either way.\n    splay = select(right, splay / max(sl, 1e-6), sl > 1e-4);\n    return iPos.xyz + splay * (p.x * iScale.x) + boneDir * (p.y * iScale.y);\n  }\n  return qrot(iRot, p * iScale.xyz + vec3f(0.0, capSign * iPos.w, 0.0)) + iPos.xyz;\n}\n\n@vertex fn vs(\n  @location(0) pos: vec3f,\n  @location(1) dir: vec3f,\n  @location(2) caps: vec2f,\n  @location(3) side: f32,\n  @location(4) t: f32,\n  @location(5) mode: f32,\n  @location(6) iRot: vec4f,\n  @location(7) iPos: vec4f,\n  @location(8) iScale: vec4f,\n  @location(9) iColor: vec4f,\n) -> VSOut {\n  let vp = camera.projection * camera.view;\n  let half = 0.5 * overlay.viewport;\n\n  var out: VSOut;\n  out.color = iColor;\n\n  // A solid volume is placed in world, like a stroked shape, but filled.\n  if (mode > 4.5) {\n    out.pos = vp * vec4f(placeWorld(pos, caps.x, iRot, iPos, iScale, 0.0), 1.0);\n    return out;\n  }\n\n  // The marker's ring: a circle of world radius, stroked to a pixel width.\n  if (mode > 3.5) {\n    let centre = vp * vec4f(iPos.xyz, 1.0);\n    let w = max(abs(centre.w), 1e-6);\n    let pxPerWorld = camera.projection[1].y * half.y / w;\n    // side is -1 on the inner rim and +1 on the outer.\n    let radiusPx = iScale.x * pxPerWorld + side * abs(iScale.w) * 0.5;\n    let radial = normalize(pos.xy);\n    out.pos = vec4f(centre.xy + ((radial * radiusPx) / half) * centre.w, centre.z, centre.w);\n    return out;\n  }\n\n  let c0 = vp * vec4f(placeWorld(pos, caps.x, iRot, iPos, iScale, mode), 1.0);\n\n  // A filled vertex is already where it belongs.\n  if (mode > 2.5) {\n    out.pos = c0;\n    return out;\n  }\n\n  let c1 = vp * vec4f(placeWorld(pos + dir, caps.y, iRot, iPos, iScale, mode), 1.0);\n  let w0 = max(abs(c0.w), 1e-6);\n  let w1 = max(abs(c1.w), 1e-6);\n  let s0 = (c0.xy / w0) * half;\n  let s1 = (c1.xy / w1) * half;\n  let delta = s1 - s0;\n  let segLenPx = max(length(delta), 1e-6);\n  let tangent = delta / segLenPx;\n  let normalPx = vec2f(-tangent.y, tangent.x);\n  let offsetPx = normalPx * side * abs(iScale.w) * 0.5;\n  out.pos = vec4f(c0.xy + (offsetPx / half) * c0.w, c0.z, c0.w);\n  return out;\n}\n\n@fragment fn fs(in: VSOut) -> @location(0) vec4f {\n  return vec4f(in.color.rgb * in.color.a, in.color.a);\n}\n";
+export declare const OVERLAY_COMPOSITE_SHADER_WGSL = "\n@group(0) @binding(0) var overlayTex: texture_2d<f32>;\n\n@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {\n  let x = f32((vi & 1u) << 2u) - 1.0;\n  let y = f32((vi & 2u) << 1u) - 1.0;\n  return vec4f(x, y, 0.0, 1.0);\n}\n\n@fragment fn fs(@builtin(position) p: vec4f) -> @location(0) vec4f {\n  return textureLoad(overlayTex, vec2<i32>(p.xy), 0);\n}\n";
+//# sourceMappingURL=overlay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/overlay.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,mBAAmB,81JAuH/B,CAAA;AAID,eAAO,MAAM,6BAA6B,kYAYzC,CAAA"}

package/dist/shaders/passes/overlay.js

@@ -0,0 +1,164 @@
+// Editor overlays — bones, rigidbodies and joints — as one instanced pass.
+//
+// Two kinds of geometry, because thick lines and thick rings want different
+// answers.
+//
+// STROKED shapes (mode 0, 2) expand each segment into a screen-space quad, so
+// their width is a pixel count and holds at any zoom. That works while a segment
+// is longer on screen than the stroke is wide; past that, neighbouring quads
+// meet at a corner nothing mitres and a circle drawn this way turns into a
+// sunburst. So the one shape that must be both small and thick — the bone
+// marker — is not stroked at all.
+//
+// FILLED shapes (mode 3) are triangles already: the marker's ring is an annulus
+// and its centre is a disc, both facing the camera. No joins exist to get wrong,
+// and the ring can be as heavy as it likes.
+//
+// The layer is 4x multisampled and composited over the finished frame rather
+// than drawn into it: the swapchain is single-sample and an MSAA attachment
+// cannot load from one. So fragments here are PREMULTIPLIED — rgb already
+// carries alpha — and the two blends compose correctly, once against a
+// transparent layer and once onto the frame.
+//
+// The capsule is why `caps` exists. A PMX capsule is a radius and a cylinder
+// length, so scaling a unit capsule non-uniformly would stretch its hemispheres
+// into ellipsoids. Instead the unit shape carries both caps at the origin and
+// each vertex names which cap it belongs to (-1, 0, +1); the VS pushes it along
+// local Y by that sign times `extent`. A segment can straddle the two — the
+// cylinder's side lines run from +1 to -1 — so `caps` holds the sign at BOTH
+// ends, not one.
+export const OVERLAY_SHADER_WGSL = /* wgsl */ `
+struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _pad: f32 };
+// 16 bytes exactly. Scalars rather than a vec3f tail: a vec3f aligns to 16 and
+// would push the struct past the buffer the pipeline is handed.
+struct OverlayUniforms { viewport: vec2f, dashPeriodPx: f32, _pad0: f32 };
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> overlay: OverlayUniforms;
+
+struct VSOut {
+  @builtin(position) pos: vec4f,
+  @location(0) @interpolate(flat) color: vec4f,
+}
+
+fn qrot(q: vec4f, v: vec3f) -> vec3f {
+  let t = 2.0 * cross(q.xyz, v);
+  return v + q.w * t + cross(q.xyz, t);
+}
+
+// Placement mode, carried per VERTEX because it belongs to the shape rather than
+// to the copy.
+//
+//   0  world    — rotate, scale, translate. The shapes that ARE geometry:
+//                 rigidbody volumes, joint crosses, plain lines.
+//   3  facing   — a flat filled shape in the camera's plane, radius scale.x.
+//                 The bone marker's solid centre.
+//   5  solid    — placed in world like mode 0, but filled: the rigidbody
+//                 volumes, which read as volumes rather than as a cage of lines.
+//   4  annulus  — the marker's ring: world radius scale.x, and a stroke that is
+//                 a PIXEL width like every other line, so the two links leave it
+//                 as a continuation of the same stroke rather than a step. The
+//                 inner and outer rims are offset radially in screen space,
+//                 which is what lets a small circle carry a thick stroke — the
+//                 stroked polyline that preceded it tore into a sunburst as soon
+//                 as the width passed the segment length.
+//   2  link     — the taper from a bone to its child: along the bone, splayed
+//                 across it in whichever direction the camera can actually see,
+//                 so the two lines never collapse into one.
+fn placeWorld(p: vec3f, capSign: f32, iRot: vec4f, iPos: vec4f, iScale: vec4f, mode: f32) -> vec3f {
+  let right = vec3f(camera.view[0].x, camera.view[1].x, camera.view[2].x);
+  let up = vec3f(camera.view[0].y, camera.view[1].y, camera.view[2].y);
+
+  if (mode > 2.5) {
+    return iPos.xyz + (right * p.x + up * p.y) * iScale.x;
+  }
+  if (mode > 1.5) {
+    let boneDir = normalize(qrot(iRot, vec3f(0.0, 1.0, 0.0)));
+    let camFwd = vec3f(camera.view[0].z, camera.view[1].z, camera.view[2].z);
+    var splay = cross(boneDir, camFwd);
+    let sl = length(splay);
+    // Looking straight down the bone there is no visible across, and any
+    // perpendicular does — the taper is a dot on screen either way.
+    splay = select(right, splay / max(sl, 1e-6), sl > 1e-4);
+    return iPos.xyz + splay * (p.x * iScale.x) + boneDir * (p.y * iScale.y);
+  }
+  return qrot(iRot, p * iScale.xyz + vec3f(0.0, capSign * iPos.w, 0.0)) + iPos.xyz;
+}
+
+@vertex fn vs(
+  @location(0) pos: vec3f,
+  @location(1) dir: vec3f,
+  @location(2) caps: vec2f,
+  @location(3) side: f32,
+  @location(4) t: f32,
+  @location(5) mode: f32,
+  @location(6) iRot: vec4f,
+  @location(7) iPos: vec4f,
+  @location(8) iScale: vec4f,
+  @location(9) iColor: vec4f,
+) -> VSOut {
+  let vp = camera.projection * camera.view;
+  let half = 0.5 * overlay.viewport;
+
+  var out: VSOut;
+  out.color = iColor;
+
+  // A solid volume is placed in world, like a stroked shape, but filled.
+  if (mode > 4.5) {
+    out.pos = vp * vec4f(placeWorld(pos, caps.x, iRot, iPos, iScale, 0.0), 1.0);
+    return out;
+  }
+
+  // The marker's ring: a circle of world radius, stroked to a pixel width.
+  if (mode > 3.5) {
+    let centre = vp * vec4f(iPos.xyz, 1.0);
+    let w = max(abs(centre.w), 1e-6);
+    let pxPerWorld = camera.projection[1].y * half.y / w;
+    // side is -1 on the inner rim and +1 on the outer.
+    let radiusPx = iScale.x * pxPerWorld + side * abs(iScale.w) * 0.5;
+    let radial = normalize(pos.xy);
+    out.pos = vec4f(centre.xy + ((radial * radiusPx) / half) * centre.w, centre.z, centre.w);
+    return out;
+  }
+
+  let c0 = vp * vec4f(placeWorld(pos, caps.x, iRot, iPos, iScale, mode), 1.0);
+
+  // A filled vertex is already where it belongs.
+  if (mode > 2.5) {
+    out.pos = c0;
+    return out;
+  }
+
+  let c1 = vp * vec4f(placeWorld(pos + dir, caps.y, iRot, iPos, iScale, mode), 1.0);
+  let w0 = max(abs(c0.w), 1e-6);
+  let w1 = max(abs(c1.w), 1e-6);
+  let s0 = (c0.xy / w0) * half;
+  let s1 = (c1.xy / w1) * half;
+  let delta = s1 - s0;
+  let segLenPx = max(length(delta), 1e-6);
+  let tangent = delta / segLenPx;
+  let normalPx = vec2f(-tangent.y, tangent.x);
+  let offsetPx = normalPx * side * abs(iScale.w) * 0.5;
+  out.pos = vec4f(c0.xy + (offsetPx / half) * c0.w, c0.z, c0.w);
+  return out;
+}
+
+@fragment fn fs(in: VSOut) -> @location(0) vec4f {
+  return vec4f(in.color.rgb * in.color.a, in.color.a);
+}
+`;
+// Lays the resolved overlay layer over the finished frame. Its input is
+// premultiplied, so the blend is a straight `src + dst * (1 - src.a)`.
+export const OVERLAY_COMPOSITE_SHADER_WGSL = /* wgsl */ `
+@group(0) @binding(0) var overlayTex: texture_2d<f32>;
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+@fragment fn fs(@builtin(position) p: vec4f) -> @location(0) vec4f {
+  return textureLoad(overlayTex, vec2<i32>(p.xy), 0);
+}
+`;

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/wireframe.d.ts

@@ -0,0 +1,2 @@
+export declare const WIREFRAME_SHADER_WGSL = "\nstruct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _pad: f32 };\nstruct WireUniforms { color: vec4f, viewport: vec2f, thicknessPx: f32, _pad: f32 };\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> wire: WireUniforms;\n\n@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;\n// The model's own vertex buffer: pos(3), normal(3), uv(2) \u2014 8 floats a vertex.\n@group(1) @binding(1) var<storage, read> vertices: array<f32>;\n// uint16x4 per vertex, so two u32 each.\n@group(1) @binding(2) var<storage, read> joints: array<u32>;\n// unorm8x4 per vertex, one u32 each.\n@group(1) @binding(3) var<storage, read> weights: array<u32>;\n// Pairs of vertex indices, one pair an edge.\n@group(1) @binding(4) var<storage, read> edges: array<u32>;\n\nfn skinnedPos(i: u32) -> vec3f {\n  let o = i * 8u;\n  let rest = vec4f(vertices[o], vertices[o + 1u], vertices[o + 2u], 1.0);\n\n  let j0 = joints[i * 2u];\n  let j1 = joints[i * 2u + 1u];\n  let packed = weights[i];\n  var w = vec4f(\n    f32(packed & 0xffu),\n    f32((packed >> 8u) & 0xffu),\n    f32((packed >> 16u) & 0xffu),\n    f32((packed >> 24u) & 0xffu),\n  ) / 255.0;\n  let sum = w.x + w.y + w.z + w.w;\n  w = select(vec4f(1.0, 0.0, 0.0, 0.0), w / max(sum, 1e-4), sum > 0.0001);\n\n  var acc = vec4f(0.0);\n  acc += (skinMats[j0 & 0xffffu] * rest) * w.x;\n  acc += (skinMats[j0 >> 16u] * rest) * w.y;\n  acc += (skinMats[j1 & 0xffffu] * rest) * w.z;\n  acc += (skinMats[j1 >> 16u] * rest) * w.w;\n  return acc.xyz;\n}\n\n// Six vertices an edge: (a,-1) (a,+1) (b,-1) (a,+1) (b,+1) (b,-1).\n@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4f {\n  let a = edges[ii * 2u];\n  let b = edges[ii * 2u + 1u];\n  let vp = camera.projection * camera.view;\n  let ca = vp * vec4f(skinnedPos(a), 1.0);\n  let cb = vp * vec4f(skinnedPos(b), 1.0);\n\n  let atB = vi == 2u || vi == 4u || vi == 5u;\n  let side = select(-1.0, 1.0, vi == 1u || vi == 3u || vi == 4u);\n  let own = select(ca, cb, atB);\n  let other = select(cb, ca, atB);\n\n  let half = 0.5 * wire.viewport;\n  let s0 = (own.xy / max(abs(own.w), 1e-6)) * half;\n  let s1 = (other.xy / max(abs(other.w), 1e-6)) * half;\n  let d = s1 - s0;\n  // A degenerate edge has no direction on screen; any perpendicular will do,\n  // and it is a dot either way.\n  let tangent = select(vec2f(1.0, 0.0), normalize(d), length(d) > 1e-6);\n  let normalPx = vec2f(-tangent.y, tangent.x);\n  let offsetPx = normalPx * side * wire.thicknessPx * 0.5;\n  return vec4f(own.xy + (offsetPx / half) * own.w, own.z, own.w);\n}\n\n// The depth prepass: the solid mesh through the ordinary vertex stream, writing\n// depth and nothing else, so the far side of a body is hidden behind the near.\n@vertex fn vsDepth(\n  @location(0) position: vec3f,\n  @location(1) joints0: vec4<u32>,\n  @location(2) weights0: vec4<f32>,\n) -> @builtin(position) vec4f {\n  let rest = vec4f(position, 1.0);\n  let sum = weights0.x + weights0.y + weights0.z + weights0.w;\n  let w = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 / max(sum, 1e-4), sum > 0.0001);\n  var acc = vec4f(0.0);\n  for (var i = 0u; i < 4u; i++) {\n    acc += (skinMats[joints0[i]] * rest) * w[i];\n  }\n  return camera.projection * camera.view * vec4f(acc.xyz, 1.0);\n}\n\n@fragment fn fs() -> @location(0) vec4f {\n  // Premultiplied, like every other fragment in this layer.\n  return vec4f(wire.color.rgb * wire.color.a, wire.color.a);\n}\n";
+//# sourceMappingURL=wireframe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wireframe.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/wireframe.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,qBAAqB,u8GAuFjC,CAAA"}