reze-engine 0.42.2 → 0.43.0

package/src/model.ts

@@ -2340,6 +2340,34 @@ export class Model {
     // morph-touched bone at its first posed frame.
     this.undoBoneMorphs()
 
+    // Clear last frame's IK result off the chain links, so a solve starts from
+    // the animation instead of from itself.
+    //
+    // solveIK bakes its output into localRotations, and applyPoseFromClip only
+    // writes bones the clip actually KEYS. A motion that keys 足ＩＫ but not the
+    // knees — which is most of them — therefore fed each frame's solve the
+    // previous frame's solved knee: θₙ = g(θₙ₋₁), where MMD computes
+    // θₙ = g(rest) afresh every frame. Near the two-bone chain's collinear
+    // singularity that map is expansive, and the knee falls into a period-2
+    // limit cycle: the foot stays pinned by IK while the thigh and calf whip
+    // around it, frame after frame. Rigs with a generous knee pre-bend and a
+    // tight extension limit never reach the singular zone, which is why this
+    // read as a model-specific bug rather than an engine one.
+    //
+    // Links only, and only when a pose source is about to run: a blanket reset
+    // would wipe bones the host posed by hand through localRotations, and a
+    // suspended clip means the current pose IS the authority.
+    if (!this.clipApplySuspended) {
+      const solvers = this.runtimeSkeleton.ikSolvers
+      if (solvers) {
+        const rots = this.runtimeSkeleton.localRotations
+        for (const solver of solvers) {
+          if (this.ikDisabled.has(solver.ikBoneIndex)) continue
+          for (const link of solver.links) rots[link.boneIndex].setIdentity()
+        }
+      }
+    }
+
     if (!this.clipApplySuspended) {
       if (this.oneShot !== null) {
         this.applyOneShot(deltaTime)

package/src/shaders/audio-api.ts

@@ -0,0 +1,82 @@
+// The audio data interface, as WGSL — shared verbatim by every effect module.
+//
+// The buffer is PRECOMPUTED for the whole track and sampled by time, never fed
+// live from an AnalyserNode. That is not an optimisation: an export steps the
+// engine frame by frame instead of playing in real time, so a live analyser
+// would return silence during a render and every audio-reactive effect would
+// quietly vanish from the exported video — the same class of bug the scene
+// clock exists to prevent. Layout: an 8-float header [frames, bands,
+// secondsPerFrame, audioTime, playing, 3 spare] then per frame
+// [level, onset, band0..bandN-1]. audioTime and playing are rewritten every frame by
+// whoever owns playback — the editor's audio clock, the viewer's, or the export
+// loop — so "now" is always the clock that is actually running.
+//
+// Every module binds the SAME buffer, so a spawn rule in a particle effect and
+// a bar in a background read identical numbers for the same instant.
+
+/** The rzAudio* accessors, with the buffer declared at the given binding. */
+export function audioApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzAudio: array<f32>;
+
+/** Frames of analysis available; 0 when the scene has no audio. */
+fn rzAudioFrames() -> i32 { return i32(_rzAudio[0]); }
+/** 1 while the track is actually PLAYING, 0 paused or absent — so an effect can
+ *  go calm instead of oscillating over a frozen spectrum. */
+fn rzAudioPlaying() -> f32 { return select(0.0, _rzAudio[4], i32(_rzAudio[0]) > 0); }
+/** Where the track is NOW, in seconds — the clock rzAudioLevelAt offsets hang
+ *  from. An effect that detects an onset k seconds back can anchor a ring to
+ *  the ABSOLUTE moment of the hit and age it continuously. */
+fn rzAudioTime() -> f32 { return _rzAudio[3]; }
+/** Bands per frame — log-spaced, bass first. */
+fn rzAudioBandCount() -> i32 { return i32(_rzAudio[1]); }
+
+fn _rzAudioFrameAt(offset: f32) -> i32 {
+  let frames = i32(_rzAudio[0]);
+  let t = _rzAudio[3] + offset;
+  return clamp(i32(t / max(_rzAudio[2], 1e-5)), 0, frames - 1);
+}
+
+/**
+ * Loudness at now + offset seconds, 0..1.
+ *
+ * The offset is what makes a WAVEFORM drawable: a column at x samples the
+ * envelope at (x - 0.5) * window seconds, and the playhead is the centre of the
+ * screen by construction. Offsets past either end clamp to the track's edges.
+ */
+fn rzAudioLevelAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2)];
+}
+
+/**
+ * The KICK track: how hard the bass is rising at now + offset, 0..1 —
+ * precomputed, so a beat-triggered effect is one comparison instead of a
+ * per-pixel history scan. Scan a short window of NEGATIVE offsets to find
+ * recent hits and age things from them (quantise the hit to the analysis grid
+ * so ages stay continuous).
+ */
+fn rzAudioOnsetAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 1];
+}
+fn rzAudioOnset() -> f32 { return rzAudioOnsetAt(0.0); }
+/** Loudness now, 0..1. */
+fn rzAudioLevel() -> f32 { return rzAudioLevelAt(0.0); }
+
+/** Band i at now + offset seconds, 0..1. Band 0 is the deepest bass. */
+fn rzAudioBandAt(i: i32, offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  if (i < 0 || i >= bands) { return 0.0; }
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 2 + i];
+}
+/** Band i now — the visualiser call. */
+fn rzAudioBand(i: i32) -> f32 { return rzAudioBandAt(i, 0.0); }
+`
+}

package/src/shaders/passes/composite.ts

@@ -1,3 +1,4 @@
+import { audioApi } from "../audio-api"
 // Composite: HDR scene + bloom pyramid → Filmic tone map → gamma → swapchain.
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
 //
@@ -162,6 +163,16 @@ override APPLY_GAMMA: bool = true;
 // vec4 slots: [0 .. 11] four subjects, three each (root+valid, hip, bounds);
 // then MAX_ANCHORS × four subjects, three each (pos+valid, vel, fwd).
 @group(0) @binding(11) var<storage, read> _rzCast: array<vec4f>;
+// The FIELD LAYER: the user's background/foreground mounts, rendered at half
+// resolution in their own pass (see buildFieldShader) and sampled here. Field
+// effects are glows, fog, shafts, gradients — low-frequency by nature — and
+// running them per quarter-pixel was the single largest per-frame cost an
+// effect could add. Bilinear upsampling is invisible at that frequency.
+@group(0) @binding(15) var fieldBgTex: texture_2d<f32>;
+@group(0) @binding(16) var fieldFgTex: texture_2d<f32>;
+// Geometry ribbons, max-blended in their own layer (trails.ts). Composited in
+// display space below, where the fullscreen ribbon effects always ran.
+@group(0) @binding(12) var trailTex: texture_2d<f32>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -302,6 +313,11 @@ fn rzProject(p: vec3f) -> vec3f {
   return vec3f(ndc * 0.5 + 0.5, z);
 }
 
+fn rzCamPos() -> vec3f { return rzCameraPos(); }
+fn rzCameraRight() -> vec3f { return viewU[3].xyz; }
+fn rzCameraUp() -> vec3f { return viewU[4].xyz; }
+fn rzCameraForward() -> vec3f { return viewU[5].xyz; }
+
 /** A character, as much of one as a shader needs. */
 struct RzSubject {
   /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
@@ -577,6 +593,11 @@ const COMPOSITE_BODY = /* wgsl */ `
   // expression, because the foreground mount composites onto it.
   var outRgb = disp * sceneAlpha + bgPm * (1.0 - sceneAlpha);
   var outA = sceneAlpha + bgA * (1.0 - sceneAlpha);
+  // The trail layer, straight-alpha over the tone-mapped frame — the author's
+  // colours verbatim, never through AgX.
+  let trailFx = textureLoad(trailTex, vec2i(fragCoord.xy), 0);
+  outRgb = trailFx.rgb * trailFx.a + outRgb * (1.0 - trailFx.a);
+  outA = trailFx.a + outA * (1.0 - trailFx.a);
   FOREGROUND_CALL
   return vec4f(outRgb, outA);
 }
@@ -587,8 +608,7 @@ const COMPOSITE_BODY = /* wgsl */ `
 // OVER onto the base layer. No `if` around it: the pipeline is rebuilt per
 // effect, so this text only exists in variants whose WGSL defines background().
 const BACKGROUND_CALL = /* wgsl */ `
-    let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-    let bgFx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
+    let bgFx = clamp(textureSampleLevel(fieldBgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0));
     bgPm = bgFx.rgb * bgFx.a + bgPm * (1.0 - bgFx.a);
     bgA = bgFx.a + bgA * (1.0 - bgFx.a);
 `
@@ -597,12 +617,7 @@ const BACKGROUND_CALL = /* wgsl */ `
 // base. Ungated by design: a foreground runs at every pixel, including the ones
 // the model covers, because covering them is the point.
 const FOREGROUND_CALL = /* wgsl */ `
-  let fgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-  // The scene's own depth, so the effect can tell what is in front of it: a
-  // petal compares its distance against this and lets the model take the pixel,
-  // and fog's alpha is nothing but a function of it. Pixels the scene never drew
-  // read the far plane, so distance fog closes over the backdrop too.
-  let fgFx = clamp(foreground(dir, fgUv, viewU[6].x, linearDepth(coord)), vec4f(0.0), vec4f(1.0));
+  let fgFx = clamp(textureSampleLevel(fieldFgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0));
   outRgb = fgFx.rgb * fgFx.a + outRgb * (1.0 - fgFx.a);
   outA = fgFx.a + outA * (1.0 - fgFx.a);
 `
@@ -629,24 +644,74 @@ const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/
 function backgroundCondition(effect?: CompositeEffectSource | null): string {
   // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
   // sharp scene fully covered can end up needing background behind its blur.
+  // (The old derivative carve-out is gone with the inline user code: the field
+  // pass runs the whole quad, which is uniform control flow by construction.)
   const coverage = "sceneAlpha < 0.999"
   if (!effect?.hasBackground) return `bg.w > 1.5 && ${coverage}`
-  return USES_DERIVATIVES.test(effect.wgsl) ? "true" : coverage
+  return coverage
 }
 
 export function buildCompositeShader(effect?: CompositeEffectSource | null): string {
   const body = COMPOSITE_BODY.replace("BACKGROUND_COND", backgroundCondition(effect))
     .replace("BACKGROUND_CALL", effect?.hasBackground ? BACKGROUND_CALL.trim() : "")
     .replace("FOREGROUND_CALL", effect?.hasForeground ? FOREGROUND_CALL.trim() : "")
-  if (!effect) return COMPOSITE_HEAD + body
+  // The composite is STATIC either way now: the user's code compiles in the
+  // field module alone, and the composite only decides whether to sample it.
+  return COMPOSITE_HEAD + audioApi(0, 13) + body
+}
+
+/**
+ * The field pass: the user's background/foreground mounts at half resolution,
+ * into two rgba16f targets the composite bilinearly upsamples.
+ *
+ * The fragment reconstructs the FULL-resolution pixel it stands in for and runs
+ * the original derivation verbatim — same ndc, same ray, same uv, same depth
+ * read — so an effect cannot tell it moved; it is simply asked half as often
+ * in each direction.
+ */
+export function buildFieldShader(effect: CompositeEffectSource): string {
+  const bgLine = effect.hasBackground
+    ? "out.bg = clamp(background(dir, uv, viewU[6].x), vec4f(0.0), vec4f(1.0));"
+    : ""
+  const fgLine = effect.hasForeground
+    ? "out.fg = clamp(foreground(dir, uv, viewU[6].x, linearDepth(vec2<i32>(min(fx, fullSz - 1.0)))), vec4f(0.0), vec4f(1.0));"
+    : ""
   return (
     COMPOSITE_HEAD +
+    audioApi(0, 13) +
     "\n// ── user effect (setEffect) ──\n" +
     effect.paramsDecl +
     "\n" +
     effect.wgsl +
     "\n" +
-    body
+    /* wgsl */ `
+@group(0) @binding(14) var<uniform> fieldU: vec4f;
+
+@vertex fn fieldVs(@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);
+}
+
+struct FieldOut {
+  @location(0) bg: vec4f,
+  @location(1) fg: vec4f,
+}
+
+@fragment fn fieldFs(@builtin(position) fragCoord: vec4f) -> FieldOut {
+  let fullSz = fieldU.zw;
+  let fx = fragCoord.xy * (fullSz / max(fieldU.xy, vec2f(1.0)));
+  let ndc = vec2f(fx.x / fullSz.x * 2.0 - 1.0, 1.0 - fx.y / fullSz.y * 2.0);
+  let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+  let uv = vec2f(fx.x / fullSz.x, 1.0 - fx.y / fullSz.y);
+  var out: FieldOut;
+  out.bg = vec4f(0.0);
+  out.fg = vec4f(0.0);
+  ${bgLine}
+  ${fgLine}
+  return out;
+}
+`
   )
 }
 

package/src/shaders/passes/particles.ts

@@ -0,0 +1,398 @@
+import { audioApi } from "../audio-api"
+// GPU particles for user effects: a compute step and an instanced quad draw.
+//
+// Its own shader MODULE rather than more source spliced into composite.ts, for
+// three reasons that all point the same way. Cost: a fullscreen effect pays for
+// every pixel on screen whether it drew anything there or not, so a ribbon walked
+// as a field cost O(pixels × samples) where the same picture as geometry costs
+// O(segments) — the difference between one effect and a scene full of them.
+// Occlusion: geometry drawn inside the scene pass is depth-tested, so a particle
+// behind the character is simply hidden, which a composited field can only fake.
+// And names: separate modules cannot collide, so two effects may both define
+// `hash21` and never meet — which is what makes running several at once safe.
+//
+// The author writes three functions and the engine owns the loop. That split is
+// deliberate: spawning, ageing, recycling, billboarding and sorting are the same
+// in every particle effect ever written, and an author who has to re-derive them
+// gets them subtly wrong in a way that only shows up on someone else's machine.
+
+/** Where the cast/trail history sits in the shared storage buffer. */
+export type CastLayout = { subjects: number; samples: number; base: number; trailBase: number; slots: number }
+
+/**
+ * The trail accessors, in the PARTICLE module.
+ *
+ * Sparks are the reason: the original hand ribbon shed sparks along its path,
+ * and as real particles they need to SPAWN on that path — which means
+ * particleInit reading the same recorded history the trail draws from. One
+ * effect file, two mounts, one buffer.
+ */
+function castApi(cast: CastLayout): string {
+  return `
+const RZ_SUBJECTS: i32 = ${cast.subjects};
+const RZ_SAMPLES: i32 = ${cast.samples};
+const RZ_TRAIL_SLOTS: i32 = ${cast.slots};
+fn rzSubjectCount() -> i32 {
+  var n = 0;
+  for (var i = 0; i < RZ_SUBJECTS; i++) {
+    if (_rzCast[i * 3 + 2].w > 0.0) { n = i + 1; }
+  }
+  return n;
+}
+fn rzTrailCount(subject: i32, slot: i32) -> i32 {
+  if (subject < 0 || subject >= RZ_SUBJECTS || slot < 0 || slot >= RZ_TRAIL_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];
+}
+`
+}
+
+/** How the author's quads combine with the scene. */
+export type ParticleBlend = "alpha" | "additive"
+
+export type ParticleSource = {
+  /** The author's WGSL verbatim. */
+  wgsl: string
+  /** Simultaneous particles. Fixed at install; the pool recycles rather than grows. */
+  count: number
+  blend: ParticleBlend
+  /** Feed the bloom pyramid. Off by default — rain should not glow. */
+  bloom: boolean
+}
+
+/** Bytes per particle. Explicitly padded — see the struct below. */
+export const PARTICLE_STRIDE = 48
+
+/**
+ * The particle record, laid out by hand.
+ *
+ * `age` and `life` sit in the padding that vec3f alignment would waste anyway
+ * (a vec3f occupies 12 bytes but aligns the next field to 16), so the struct is
+ * 48 bytes rather than the 64 a naive ordering costs. At 4096 particles that is
+ * 192KB instead of 256KB, and it is read every frame by both stages.
+ *
+ * `life <= 0` means "not alive" and is what the pool checks to recycle a slot,
+ * so a freshly zeroed buffer is entirely dead and every particle is born on the
+ * first step rather than needing a separate seeding pass.
+ */
+const PARTICLE_STRUCT = /* wgsl */ `
+struct Particle {
+  pos: vec3f,
+  age: f32,
+  vel: vec3f,
+  life: f32,
+  size: f32,
+  rot: f32,
+  seed: f32,
+  // Aspect along the direction of travel. 1 or less is a square billboard; a
+  // raindrop is 10 or 20. Zero-initialised, so an effect that never sets it gets
+  // the square it expects.
+  stretch: f32,
+}
+`
+
+const CAMERA_STRUCT = /* wgsl */ `
+struct CameraU {
+  view: mat4x4f,
+  proj: mat4x4f,
+  camPos: vec3f,
+  targetHeight: f32,
+}
+`
+
+const PARTICLE_UNIFORMS = /* wgsl */ `
+struct ParticleU {
+  time: f32,
+  dt: f32,
+  count: u32,
+  frame: u32,
+}
+`
+
+/**
+ * The shared prelude, everything `rz`-prefixed.
+ *
+ * Not convenience — correctness. Every effect written against the old contract
+ * re-derived its own hash and its own falloff, which is duplicated code and
+ * duplicated bugs; `rzFalloff` in particular has COMPACT SUPPORT (it reaches
+ * exactly zero at r), because an exponential glow that never quite reaches zero
+ * has to be culled somewhere, and culling it wherever it "looks close enough"
+ * is what put a visible hard edge on the first halo effect.
+ */
+const PRELUDE = /* wgsl */ `
+fn rzHash11(x: f32) -> f32 {
+  var p = fract(x * 0.1031);
+  p = p * (p + 33.33);
+  return fract(p * (p + p));
+}
+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);
+}
+/** Three independent randoms from one seed — the usual need when spawning. */
+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 + vec3f(0.0, 0.0, 0.0));
+  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);
+}
+/** Divergence-free flow — the standard drifting-air force. Snow and mist want this. */
+fn rzCurlNoise(p: vec3f) -> vec3f {
+  let e = 0.1;
+  let dx = vec3f(e, 0.0, 0.0);
+  let dy = vec3f(0.0, e, 0.0);
+  let dz = vec3f(0.0, 0.0, e);
+  let x0 = rzValueNoise(p - dx); let x1 = rzValueNoise(p + dx);
+  let y0 = rzValueNoise(p - dy); let y1 = rzValueNoise(p + dy);
+  let z0 = rzValueNoise(p - dz); let z1 = rzValueNoise(p + dz);
+  return normalize(vec3f((y1 - y0) - (z1 - z0), (z1 - z0) - (x1 - x0), (x1 - x0) - (y1 - y0)) + vec3f(1e-6));
+}
+/** Compact-support falloff: 1 at the centre, exactly 0 at r, smooth between. */
+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 rzTime() -> f32 { return pu.time; }
+fn rzViewportHeight() -> f32 { return cam.targetHeight; }
+fn rzCameraPos() -> vec3f { return cam.camPos; }
+fn rzCameraRight() -> vec3f { return vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]); }
+fn rzCameraUp() -> vec3f { return vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]); }
+fn rzCameraForward() -> vec3f { return vec3f(cam.view[0][2], cam.view[1][2], cam.view[2][2]); }
+/** World point → (uv, view distance), same contract as the field mounts' rzProject. */
+fn rzProject(p: vec3f) -> vec3f {
+  let clip = cam.proj * cam.view * vec4f(p, 1.0);
+  let w = max(clip.w, 1e-4);
+  return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
+}
+fn rzDt() -> f32 { return pu.dt; }
+fn rzCamPos() -> vec3f { return cam.camPos; }
+`
+
+/** `// @particles 4096` — how many live at once. */
+export function parseParticleCount(wgsl: string, max: number): number {
+  const m = /^\s*\/\/\s*@particles\s+(\d+)\s*$/m.exec(wgsl)
+  if (!m) return 0
+  // Clamped rather than rejected: an author asking for a million gets the most
+  // the engine will give and a scene that still runs, which is a better failure
+  // than a compile error naming a number they had no way to know.
+  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
+}
+
+/** `// @bloom` — opt in to the bloom pyramid. Sparks want it; rain does not. */
+export function parseParticleBloom(wgsl: string): boolean {
+  return /^\s*\/\/\s*@bloom\s*$/m.test(wgsl)
+}
+
+/** `// @blend additive` — default is straight alpha. */
+export function parseParticleBlend(wgsl: string): ParticleBlend {
+  return /^\s*\/\/\s*@blend\s+additive\s*$/m.test(wgsl) ? "additive" : "alpha"
+}
+
+/** Does the source define the particle contract? All three are required together. */
+export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean } {
+  return {
+    init: /\bfn\s+particleInit\s*\(/.test(wgsl),
+    step: /\bfn\s+particleStep\s*\(/.test(wgsl),
+    shade: /\bfn\s+particleShade\s*\(/.test(wgsl),
+  }
+}
+
+/**
+ * Spawn, age, recycle.
+ *
+ * One kernel for both birth and update, because a dead slot and a new particle
+ * are the same write — a pool that recycles has no allocation and therefore no
+ * spawn-rate bookkeeping to get wrong. The cost is that lifetimes are staggered
+ * only by whatever the author randomises in `particleInit`, which for rain and
+ * snow is exactly right, and for a burst is what the age offset is for.
+ */
+export function buildParticleComputeShader(src: ParticleSource, cast: CastLayout): string {
+  return (
+    PARTICLE_STRUCT +
+    CAMERA_STRUCT +
+    PARTICLE_UNIFORMS +
+    `
+@group(0) @binding(0) var<storage, read_write> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> pu: ParticleU;
+@group(0) @binding(2) var<uniform> cam: CameraU;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+` +
+    castApi(cast) +
+    audioApi(0, 4) +
+    PRELUDE +
+    "\n// ── user effect ──\n" +
+    src.wgsl +
+    /* wgsl */ `
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= pu.count) { return; }
+  var p = particles[i];
+  if (p.life <= 0.0 || p.age >= p.life) {
+    // The seed is stable per SLOT and per generation, so a particle looks the
+    // same every time the scene is replayed at the same moment — which is what
+    // keeps an exported video identical to the preview.
+    let generation = floor(pu.time * 0.37) + f32(i) * 0.618;
+    p = particleInit(i, rzHash11(generation));
+    // age is NOT reset here. WGSL zero-initialises a var, so an author who
+    // ignores it starts at zero anyway — while one who sets it to a fraction of
+    // its life staggers the pool, which is the difference between snow and a
+    // pulse of snow arriving all at once every few seconds.
+  } else {
+    p = particleStep(p, pu.dt);
+    p.age = p.age + pu.dt;
+  }
+  particles[i] = p;
+}
+`
+  )
+}
+
+/**
+ * One camera-facing quad per live particle.
+ *
+ * Six vertices, no index or vertex buffer: the corners are derived from
+ * `vertex_index` and the particle is read from storage by `instance_index`, so a
+ * draw is `draw(6, count)` and there is nothing to upload per frame. The billboard
+ * basis comes from the VIEW matrix's rows rather than from a look-at, which keeps
+ * the quad square on screen no matter where the camera rolls.
+ *
+ * A dead particle collapses to a degenerate quad instead of being culled on the
+ * CPU — the alternative is a compacted draw list, which costs a prefix sum and a
+ * readback every frame to save vertices the rasteriser was going to reject anyway.
+ */
+export function buildParticleRenderShader(src: ParticleSource, cast: CastLayout): string {
+  return (
+    `override BLOOM: bool = ${src.bloom ? "true" : "false"};
+override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
+    PARTICLE_STRUCT +
+    CAMERA_STRUCT +
+    PARTICLE_UNIFORMS +
+    `
+@group(0) @binding(0) var<storage, read> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> pu: ParticleU;
+@group(0) @binding(2) var<uniform> cam: CameraU;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+` +
+    castApi(cast) +
+    audioApi(0, 4) +
+    PRELUDE +
+    "\n// ── user effect ──\n" +
+    src.wgsl +
+    /* wgsl */ `
+struct VSOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) @interpolate(flat) id: u32,
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {
+  var out: VSOut;
+  out.id = ii;
+  let p = particles[ii];
+  // Two triangles, corners in the order 0,1,2, 2,1,3.
+  let quad = array<vec2f, 6>(
+    vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0),
+    vec2f(-1.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),
+  );
+  let c = quad[vi];
+  out.uv = c * 0.5 + 0.5;
+  if (p.life <= 0.0) {
+    // Degenerate: off the near plane, rasterises nothing.
+    out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
+    return out;
+  }
+  let right = vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]);
+  let up = vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]);
+  let s = sin(p.rot);
+  let k = cos(p.rot);
+  var r = vec2f(c.x * k - c.y * s, c.x * s + c.y * k);
+  // Stretched along the direction of travel ON SCREEN — which is not the world
+  // direction once the camera is off-axis. Rain falling straight down is nearly
+  // a point when viewed from above and a long streak from the side, and taking
+  // the velocity's components in the camera's own basis is what gets both right.
+  // Rotation is ignored while stretched: the velocity IS the orientation.
+  if (p.stretch > 1.0) {
+    let vr = dot(p.vel, right);
+    let vu = dot(p.vel, up);
+    let vlen = length(vec2f(vr, vu));
+    if (vlen > 1e-5) {
+      let d = vec2f(vr, vu) / vlen;
+      r = vec2f(d.y, -d.x) * c.x + d * (c.y * p.stretch);
+    }
+  }
+  let world = p.pos + (right * r.x + up * r.y) * p.size;
+  out.clip = cam.proj * cam.view * vec4f(world, 1.0);
+  return out;
+}
+
+struct FSOut {
+  @location(0) color: vec4f,
+  // The scene's aux target: (bloom mask, coverage). Materials write it, so a
+  // particle that skipped it would punch a hole in the mask of whatever it drew
+  // over.
+  //
+  // vec4f even though the target is rg8unorm and only .rg land: that target's
+  // blend factors reference SrcAlpha, and a fragment with no alpha channel is
+  // rejected outright — "reading alpha but it is missing from fragment output".
+  // The material shaders declare vec4f here for the same reason.
+  @location(1) mask: vec4f,
+}
+
+@fragment
+fn fs(in: VSOut) -> FSOut {
+  let p = particles[in.id];
+  let c = particleShade(p, in.uv);
+  if (c.a <= 0.0) { discard; }
+  var out: FSOut;
+  // PREMULTIPLIED: the scene's colour target blends with srcFactor \"one\", so a
+  // straight-alpha fragment would come out over-bright wherever it is
+  // translucent — which is most of a soft particle.
+  out.color = vec4f(c.rgb * c.a, c.a);
+  // The mask's OPERATOR must match the colour's, or the composite invents bands.
+  //
+  // The composite divides the HDR colour by this coverage to un-premultiply
+  // before tone mapping. An ALPHA effect writes (gate, 1.0) and lets the
+  // src-alpha blend make alpha-over coverage, exactly as the materials do. An
+  // ADDITIVE effect's pipeline blends this target with factor ONE instead, and
+  // writes its values directly — coverage SUMS like the colour does, so
+  // Σ(rgb·a)/Σa returns the true colour even where the effect overlaps itself.
+  // With summed colour over alpha-over coverage, every self-overlap divided into
+  // a bright white bar — visible only over the background, because the model's
+  // own coverage is already 1 there and the divide is a no-op. That mismatch,
+  // not geometry, was the banding that survived every geometry fix.
+  let mg = select(vec2f(select(0.0, 1.0, BLOOM), 1.0), vec2f(select(0.0, c.a, BLOOM), c.a), ADDITIVE);
+  out.mask = vec4f(mg.x, mg.y, 0.0, c.a);
+  return out;
+}
+`
+  )
+}