reze-engine 0.54.16 → 0.55.1

package/dist/shaders/passes/composite.js

@@ -109,7 +109,7 @@ override APPLY_GAMMA: bool = true;
 // monotone-cubic (Fritsch–Carlson) fit through the same 14 anchors — same values, C1
 // continuity kills the banding — sampled with hardware linear filtering.
 @group(0) @binding(5) var filmicLut: texture_2d<f32>;
-// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)
+// viewU[0] = (exposure, invGamma, grain amount, grain seed);  viewU[1] = (tint.rgb, intensity)
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
@@ -495,6 +495,23 @@ const COMPOSITE_BODY = /* wgsl */ `
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
+  // ── Film grain, on the SCENE ONLY ─────────────────────────────────────────
+  //
+  // Applied here, before the background is composited under, so it rides on what
+  // the engine drew and nothing else. That placement is the whole point when the
+  // background is footage: the plate came off a real sensor and already carries
+  // its own grain, and a second helping over the top would grade the photograph
+  // rather than match it. A clean CG figure on a grainy plate is one of the
+  // loudest tells there is — the noise gives it away long before the geometry.
+  //
+  // Multiplicative and weighted toward the mid-tones, which is how film behaves:
+  // little grain in the blacks, and the highlights clip it off.
+  if (viewU[0].z > 0.0) {
+    let gp = fragCoord.xy + vec2f(viewU[0].w, viewU[0].w * 1.7);
+    let gn = fract(sin(dot(gp, vec2f(12.9898, 78.233))) * 43758.5453) - 0.5;
+    let glum = dot(disp, vec3f(0.2126, 0.7152, 0.0722));
+    disp = max(disp * (1.0 + gn * viewU[0].z * 4.0 * glum * (1.0 - glum)), vec3f(0.0));
+  }
   // Composite over the background in display space (premultiplied out). The
   // background is TWO layers: a base (transparent / solid color / 360 equirect)
   // and an optional user WGSL effect over-composited onto it.

package/dist/shaders/passes/field-blit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 declare function fieldBlitShaderWgsl(): string;
+//# sourceMappingURL=field-blit.d.ts.map

package/dist/shaders/passes/field-blit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-blit.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/field-blit.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAuC5C"}

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

@@ -1 +1 @@
-{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,IAAI,MAAM,CAkUzC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}
+{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAmEA,wBAAgB,gBAAgB,IAAI,MAAM,CA2TzC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}

package/dist/shaders/passes/ground.js

@@ -8,6 +8,59 @@ import { WORLD_AMBIENT_WGSL } from "../lights";
 // A FUNCTION, not a constant, since the id attachment is a device capability:
 // the struct this returns depends on what the probe at init found, and a string
 // baked at import time cannot know that. Called once, when the module is built.
+// How far the softest setting spreads the taps, in units of the sharp kernel's
+// own step, and how many taps carry that spread. Sixteen is what keeps a wide
+// disk reading as a penumbra instead of sixteen shadows.
+const SOFT_TAPS = 16;
+const SOFT_MAX_SPREAD = 14;
+/**
+ * PCF taps for one cascade, emitted per shadow map.
+ *
+ * At softness 0 this is the 3x3 box the ground has always used — same offsets,
+ * same weights, same result to the bit. Above it the taps spread over a Vogel
+ * disk whose radius IS the penumbra: an overcast sky throws no edge, and a
+ * razor-edged shadow under one is the loudest thing wrong in a composite.
+ *
+ * The branch is on a uniform, so a scene at softness 0 genuinely takes the
+ * nine-tap side rather than masking the wide one — the same reasoning the
+ * shadowStrength branch above it already documents.
+ *
+ * A string rather than a WGSL function because a texture is the one handle type
+ * this shader has never passed as a parameter, and the file is already a
+ * template that interpolates its constants.
+ *
+ * `acc` must already be declared and zeroed; the caller reads it back
+ * normalised, so there is no `/ 9.0` left at the call site.
+ */
+function pcfWgsl(map, uv, texel, z, acc, pad) {
+    const golden = 2.39996323;
+    return [
+        `if (material.shadowSoftness <= 0.0) {`,
+        `  let st = ${texel} * 2.0;`,
+        `  for (var y = -1; y <= 1; y++) {`,
+        `    for (var x = -1; x <= 1; x++) {`,
+        // ...Level, not the implicit-derivative form: identical on a single-mip
+        // shadow map, and legal inside a branch.
+        `      ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(f32(x), f32(y)) * st, ${z});`,
+        `    }`,
+        `  }`,
+        `  ${acc} *= ${1 / 9};`,
+        `} else {`,
+        `  let radius = ${texel} * 2.0 * (1.0 + material.shadowSoftness * ${SOFT_MAX_SPREAD}.0);`,
+        `  for (var s = 0; s < ${SOFT_TAPS}; s++) {`,
+        `    let fs = f32(s);`,
+        // sqrt of the index spaces the ring radii evenly by AREA; the golden angle
+        // keeps successive taps from lining up into spokes.
+        `    let r = sqrt((fs + 0.5) * ${1 / SOFT_TAPS});`,
+        `    let a = fs * ${golden} + rot;`,
+        `    ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(cos(a), sin(a)) * (r * radius), ${z});`,
+        `  }`,
+        `  ${acc} *= ${1 / SOFT_TAPS};`,
+        `}`,
+    ]
+        .map((l) => pad + l)
+        .join("\n");
+}
 export function groundShaderWgsl() {
     return /* wgsl */ `
 struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
@@ -20,7 +73,7 @@ struct GroundShadowMat {
   gridLineColor: vec3f, mirror: f32,
   // farCascade: 1 while a stage is loaded, 0 otherwise. See the branch below —
   // with no stage the far map is never drawn into, so its taps are known.
-  mirrorBlur: f32, farCascade: f32, _mb1: f32, _mb2: f32,
+  mirrorBlur: f32, farCascade: f32, shadowSoftness: f32, _mb2: f32,
   // Every shadow caster in one sphere, refreshed per frame. w = radius; 0 means
   // nothing casts, negative means "do not use this" (a rigid caster has no
   // sphere, so a scene with a stage keeps the taps). See rzShadowPossible.
@@ -150,6 +203,11 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // The same reasoning the noise tint below already got, applied to the term
   // that costs a hundred times more.
   if (material.shadowStrength > 0.0 && shadowPossible) {
+  // Per-pixel rotation for the soft disk, so its rings break up into fine noise
+  // rather than banding. Interleaved gradient noise: a function of the pixel
+  // alone, so a still camera gives a still shadow — the sharp path ignores it.
+  let ign = fract(52.9829189 * fract(dot(i.position.xy, vec2f(0.06711056, 0.00583715))));
+  let rot = ign * 6.28318530718;
   // The far cascade's taps, skipped entirely when nothing ever drew into it.
   //
   // This branch is the expensive one on a wide floor: it runs wherever the NEAR
@@ -163,32 +221,20 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   if (material.farCascade > 0.0 && frustum < 1.0 && frustum1 > 0.0) {
     let suv1 = vec2f(ndc1.x * 0.5 + 0.5, 0.5 - ndc1.y * 0.5);
     let suv1_c = clamp(suv1, vec2f(0.02), vec2f(0.98));
-    let st1 = ${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize} * 2.0;
     let compareZ1 = ndc1.z - 0.0035;
     var acc1 = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        acc1 += textureSampleCompareLevel(shadowMapFar, shadowSampler, suv1_c + vec2f(f32(x), f32(y)) * st1, compareZ1);
-      }
-    }
-    vis = mix(1.0, acc1 * (1.0 / 9.0), frustum1);
+${pcfWgsl("shadowMapFar", "suv1_c", `${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}`, "compareZ1", "acc1", "    ")}
+    vis = mix(1.0, acc1, frustum1);
   }
   if (frustum > 0.0) {
     let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
     let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));
-    let st = material.pcfTexel * 2.0;
     let compareZ = ndc.z - 0.0035;
     var acc = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        // ...Level, not the implicit-derivative form: identical on a single-mip
-        // shadow map, and legal inside this branch.
-        acc += textureSampleCompareLevel(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);
-      }
-    }
+${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ")}
     // The base is whatever the far cascade decided, so the near border blends
     // cascade to cascade rather than snapping to lit mid-floor.
-    vis = mix(vis, acc * (1.0 / 9.0), frustum);
+    vis = mix(vis, acc, frustum);
   }
   }
 

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"}