@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/shaders/shader_particle_emit.js

@@ -4,34 +4,24 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
 import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
-import { chunk_lower_bound_branchless } from "../../shader/chunk/math/chunk_lower_bound_branchless.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_USER_WORD_START,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_VM_INSTRUCTION_WORDS,
-} from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_vm_registers_fast } from "../vm/chunk_particle_vm_registers_fast.js";
 import { chunk_particle_curve_disabled } from "./chunk_particle_curve_disabled.js";
-import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
-import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
+import { chunk_particle_emit_step } from "./chunk_particle_emit_step.js";
 
 /**
  * The particle emit pass: one thread per particle born this frame.
  *
- * Its input is the prefix scan of the emitter tick pass's per-row spawn counts. Thread `i` finds
- * the emitter it belongs to by binary search over the inclusive sums — the first row whose sum
- * exceeds `i` — and its place within that emitter's batch from the sum before. That is the
- * meshes-to-meshlets expansion applied to particles: the per-emitter count is unbounded, no thread
- * loops, and the dispatch is sized on the GPU from the scan's total.
+ * Its input is the prefix scan of the emitter tick pass's per-row spawn counts; thread `i` finds the
+ * emitter it belongs to by binary search over the inclusive sums, and its place within that
+ * emitter's batch from the sum before. Then: pop a free slot from the dead list, clear the record,
+ * stamp the header, run the emitter's INIT program, and append the slot to the new alive list.
  *
- * Then, as ever: pop a free slot from the dead list, clear the record, stamp the header with the
- * emitter row and its generation, run the emitter's INIT program to give the particle its state,
- * and append the slot to the new alive list. The emitter's position and axes come from its scene
- * node, so a particle born of an emitter riding a bone starts where the bone is this frame.
+ * The per-newborn work is {@link ./chunk_particle_emit_step.js}, shared with
+ * {@link ./shader_particle_emit_wide.js}. What this file is, is the *fast* register backing plus the
+ * one-lane-per-newborn dispatch that suits it.
  *
  * Runs before simulate in the frame so newborns join the same alive list survivors are compacted
  * into. Shares the VM + context + emitter chunks with simulate.
@@ -54,7 +44,7 @@ export const PARTICLE_EMIT_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
  *
  * @type {WebGPUStruct}
  */
-const EMIT_SETTINGS = WebGPUStruct.from({
+export const EMIT_SETTINGS = WebGPUStruct.from({
     u_dt: f32,
     u_time: f32,
     u_frame: u32,
@@ -78,10 +68,6 @@ resources.createGroup()
 const body = CodeChunk.from(
     /* language=wgsl */
     `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 
@@ -89,77 +75,31 @@ const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
 
-    // The scan's last inclusive sum is the number of particles born this frame. An empty list has
-    // no last element to read; it also has no particles.
-    let emitter_count = spawn_prefix.count;
-    if (emitter_count == 0u) { return; }
-    let total = spawn_prefix.elements[emitter_count - 1u];
-    if (i >= total) { return; }
+    let assignment = particle_emit_assignment(&spawn_prefix.elements, spawn_prefix.count, i);
+    if (!assignment.valid) { return; }
 
-    // The emitter is the first row whose inclusive sum exceeds i; its batch starts at the sum
-    // before, which is the exclusive sum. Rows that spawned nothing this frame have equal sums and
-    // the search steps over them.
-    let emitter_row = lower_bound_branchless(&spawn_prefix.elements, i + 1u, emitter_count);
-    var batch_start = 0u;
-    if (emitter_row > 0u) {
-        batch_start = spawn_prefix.elements[emitter_row - 1u];
-    }
-    let batch_size = spawn_prefix.elements[emitter_row] - batch_start;
-
-    // SPAWN_FRACTION contract: this particle's place in its emitter's batch this frame, n / count,
-    // for spreading a batch along a spawn curve.
-    let spawn_fraction = f32(i - batch_start) / f32(batch_size);
-
-    // Pop a free slot off the dead-list stack; drop the spawn if the pool is exhausted.
-    //
-    // The guard must catch WRAPPED values, not just 0: when many threads race an empty stack, the
-    // first over-pop wraps the counter to 0xFFFFFFFF before its undo lands, and a concurrent thread
-    // then observes a huge old value. Checking only ==0 would let it index dead[old-1] with garbage
-    // and hand out a bogus slot, corrupting a live record. The dead count can never legitimately
-    // exceed the pool capacity, so >settings.u_capacity identifies every wrapped state; each thread that
-    // subtracted also adds back exactly once, so the counter converges to 0.
+    // Pop a free slot off the dead-list stack; drop the spawn if the pool is exhausted. The guard
+    // catches WRAPPED values, not just 0 — see chunk_particle_emit_step for why that matters.
     let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
     if (old_dead == 0u || old_dead > settings.u_capacity) {
         atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
         return;
     }
     let slot = dead[old_dead - 1u];
-    let record_base = slot * PARTICLE_RECORD_WORDS;
-
-    let em = particle_emitter_read(&emitter_database, emitter_row);
-    let node = scene_read_node(&scene_database, em.node);
 
-    // Clear stale user state from a recycled slot (each write targets a distinct word).
-    for (var w = PARTICLE_USER_WORD_START; w < PARTICLE_RECORD_WORDS; w = w + 1u) {
-        pool[record_base + w] = 0u;
-    }
-    pool[record_base + PARTICLE_HEADER_EMITTER] = particle_header_pack(emitter_row, em.generation);
-
-    particle_vm_reset();
-    particle_setup_context(
-        em, node, slot,
-        settings.u_dt, settings.u_time,
-        particle_emitter_age(&emitter_database, emitter_row),
-        spawn_fraction, settings.u_frame,
-    );
-    particle_vm_execute(
-        &program,
-        em.init_offset * PARTICLE_INSTRUCTION_WORDS,
-        em.init_count,
-        em.constant_offset,
-        &pool,
-        record_base,
+    particle_emit_one(
+        &scene_database, &emitter_database, &program, &pool,
+        assignment.emitter_row, slot, assignment.spawn_fraction,
+        settings.u_dt, settings.u_time, settings.u_frame,
     );
 
     let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
     alive_out[a] = slot;
 }
 `, [
-    chunk_particle_setup_context,
-    chunk_particle_emitter_age,
+    chunk_particle_emit_step,
+    chunk_particle_vm_registers_fast,
     chunk_particle_curve_disabled,
-    chunk_particle_header,
-    chunk_lower_bound_branchless,
 ]);
 
 export const shader_particle_emit = ComputeShader.from({

package/src/shade/renderer/particles/shaders/shader_particle_emit_wide.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The emit pass over the WIDE register file — the fallback interpreter's spawn half.
+ *
+ * Same emission as {@link ./shader_particle_emit.js}, down to the shared
+ * {@link ./chunk_particle_emit_step.js}. It differs in the same way
+ * {@link ./shader_particle_simulate_wide.js} does: a bounded launch of
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} lanes with a grid-stride loop, so
+ * the storage register file is sized by a constant rather than by how many particles happen to be
+ * born this frame.
+ *
+ * It therefore does not consume the indirect command the prefix scan produces for the fast pass. The
+ * scan's total is read in the shader as the loop bound instead, which is the same number from the
+ * same buffer — just used as a bound rather than as a dispatch size.
+ *
+ * The register file is indexed by launch lane, so it is reused across the loop's iterations. That is
+ * sound for the same reason it is never cleared: an INIT program writes a register before it reads
+ * it, so nothing carries between one newborn and the next. See
+ * {@link ../vm/chunk_particle_vm_registers_wide.js}.
+ *
+ * Emit's waves span emitters by construction, so — unlike simulate — there was never a wave-uniform
+ * decode here to lose.
+ *
+ * @type {ComputeShader}
+ */
+/**
+ * Workgroups this pass dispatches. Constant: the launch does not depend on how many particles are
+ * born this frame.
+ * @type {number}
+ */
+export const PARTICLE_EMIT_WIDE_WORKGROUP_COUNT: number;
+export const shader_particle_emit_wide: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_emit_wide.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_emit_wide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_emit_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit_wide.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,iDAFU,MAAM,CAGiD;AAiEjE,sDAIG;8BA9G2B,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_emit_wide.js

@@ -0,0 +1,114 @@
+import { atomic_u32, f32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { chunk_particle_vm_registers_wide } from "../vm/chunk_particle_vm_registers_wide.js";
+import { chunk_particle_curve_disabled } from "./chunk_particle_curve_disabled.js";
+import { chunk_particle_emit_step } from "./chunk_particle_emit_step.js";
+import { EMIT_SETTINGS, PARTICLE_EMIT_WORKGROUP_SIZE } from "./shader_particle_emit.js";
+
+/**
+ * The emit pass over the WIDE register file — the fallback interpreter's spawn half.
+ *
+ * Same emission as {@link ./shader_particle_emit.js}, down to the shared
+ * {@link ./chunk_particle_emit_step.js}. It differs in the same way
+ * {@link ./shader_particle_simulate_wide.js} does: a bounded launch of
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} lanes with a grid-stride loop, so
+ * the storage register file is sized by a constant rather than by how many particles happen to be
+ * born this frame.
+ *
+ * It therefore does not consume the indirect command the prefix scan produces for the fast pass. The
+ * scan's total is read in the shader as the loop bound instead, which is the same number from the
+ * same buffer — just used as a bound rather than as a dispatch size.
+ *
+ * The register file is indexed by launch lane, so it is reused across the loop's iterations. That is
+ * sound for the same reason it is never cleared: an INIT program writes a register before it reads
+ * it, so nothing carries between one newborn and the next. See
+ * {@link ../vm/chunk_particle_vm_registers_wide.js}.
+ *
+ * Emit's waves span emitters by construction, so — unlike simulate — there was never a wave-uniform
+ * decode here to lose.
+ *
+ * @type {ComputeShader}
+ */
+
+/**
+ * Workgroups this pass dispatches. Constant: the launch does not depend on how many particles are
+ * born this frame.
+ * @type {number}
+ */
+export const PARTICLE_EMIT_WIDE_WORKGROUP_COUNT =
+    PARTICLE_VM_WIDE_LAUNCH_LANES / PARTICLE_EMIT_WORKGROUP_SIZE;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', EMIT_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addStorageBuffer("program", WebGPUArray.u32, false)
+    .addStorageBuffer("spawn_prefix", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    /* language=wgsl */
+    `
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
+
+@compute @workgroup_size(${PARTICLE_EMIT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    // This invocation's column of the register file. The launch is exactly
+    // PARTICLE_VM_WIDE_LAUNCH_LANES wide, so gid.x is in range by construction.
+    particle_vm_bind_registers(gid.x);
+
+    // The scan's last inclusive sum is the number of particles born this frame — the bound this pass
+    // walks to, in place of the indirect dispatch the fast pass is sized by.
+    let emitter_count = spawn_prefix.count;
+    if (emitter_count == 0u) { return; }
+    let total = spawn_prefix.elements[emitter_count - 1u];
+
+    for (var i = gid.x; i < total; i = i + PARTICLE_VM_WIDE_LAUNCH_LANES) {
+        let assignment = particle_emit_assignment(&spawn_prefix.elements, emitter_count, i);
+        if (!assignment.valid) { continue; }
+
+        // Pop a free slot off the dead-list stack; drop the spawn if the pool is exhausted. The
+        // guard catches WRAPPED values, not just 0 — see chunk_particle_emit_step for why that
+        // matters.
+        let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
+        if (old_dead == 0u || old_dead > settings.u_capacity) {
+            atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
+            continue;
+        }
+        let slot = dead[old_dead - 1u];
+
+        particle_emit_one(
+            &scene_database, &emitter_database, &program, &pool,
+            assignment.emitter_row, slot, assignment.spawn_fraction,
+            settings.u_dt, settings.u_time, settings.u_frame,
+        );
+
+        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+        alive_out[a] = slot;
+    }
+}
+`, [
+    chunk_particle_emit_step,
+    chunk_particle_vm_registers_wide,
+    chunk_particle_curve_disabled,
+]);
+
+export const shader_particle_emit_wide = ComputeShader.from({
+    label: "Particle Emit (wide registers)",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/shaders/shader_particle_simulate.d.ts

@@ -1,5 +1,13 @@
 export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
+/**
+ * Per-dispatch, 12 bytes, read-only — see shader_particle_emit for why the three travel
+ * together rather than as three uniforms.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SIMULATE_SETTINGS: WebGPUStruct;
 export const shader_particle_simulate: ComputeShader;
 import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_particle_simulate.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_simulate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AA+LA,qDAIG;iDAtLI,yBAAyB;8BATF,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AA0DA;;;;;GAKG;AACH,gCAFU,YAAY,CAMS;AAuD/B,qDAIG;iDAxH8C,yBAAyB;6BAJ7C,mCAAmC;8BAClC,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_simulate.js

@@ -5,27 +5,27 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    PARTICLE_SIM_PAD_SLOT,
-    PARTICLE_VM_INSTRUCTION_WORDS,
-} from "../ParticleConstants.js";
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_vm_registers_fast } from "../vm/chunk_particle_vm_registers_fast.js";
 import { chunk_particle_curve_disabled } from "./chunk_particle_curve_disabled.js";
-import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
-import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
+import { chunk_particle_simulate_step } from "./chunk_particle_simulate_step.js";
 
 /**
  * The particle simulate pass — Destiny-style single execution shader.
  *
- * One dispatch processes every live particle across every emitter. Per particle: read its owning
- * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
- * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
- * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
- * because behaviour is data (the bytecode program), not code.
+ * One dispatch processes every live particle across every emitter, one invocation each. Per
+ * particle: read its owning emitter, set up the VM context + RNG, run that emitter's compiled UPDATE
+ * program over the record, then compact — killed particles are pushed back to the dead (free) list,
+ * survivors are appended to the new alive list. There is exactly one pipeline regardless of how many
+ * distinct effects exist, because behaviour is data (the bytecode program), not code.
+ *
+ * The per-particle work is {@link ./chunk_particle_simulate_step.js}, shared with
+ * {@link ./shader_particle_simulate_wide.js}. What this file is, is the *fast* register backing plus
+ * the one-lane-per-particle dispatch that suits it. See
+ * {@link ../vm/chunk_particle_vm_registers_fast.js} for what "fast" costs and buys, and
+ * {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} for when the system runs the other
+ * one instead.
  *
  * ## The input list
  *
@@ -33,23 +33,9 @@ import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js"
  * pass (`../coherence/`) built at the end of last frame: the same pool slots, reordered so that
  * particles running one VM program sit together, each run padded out to a whole workgroup. That is
  * what keeps a wave from spanning two programs — and this shader leans on it rather than merely
- * benefiting from it: the section parameters are read from the wave's first lane
- * (`particle_wave_uniform` below), so a wave that held two programs would run one of them over the
- * other's particles. The coherence pass is part of this shader's correctness, not only of its speed.
- *
- * Padding entries carry {@link PARTICLE_SIM_PAD_SLOT} and are dropped BEFORE the compaction
- * atomics, so a padding lane never appends to the alive list and never pushes a slot onto the free
- * list — pushing the sentinel would put `0xffffffff` on the free list for a later emit to hand out
- * as a record base. Returning early is safe for the lanes that remain: padding only ever appears in
- * the tail of a bucket, and every real lane in that wave belongs to that one bucket, so the `switch`
- * the survivors execute is uniform regardless.
- *
- * ## Orphans
- *
- * A particle whose header generation is not its emitter row's current generation belongs to an
- * emitter that has been removed — the row is either zero-filled or already someone else's. It is
- * killed here, the frame the mismatch appears, before it can run a stranger's program or follow a
- * stranger's node. See `../data/particle_header.js`.
+ * benefiting from it: the section parameters are read from the wave's first lane, so a wave that
+ * held two programs would run one of them over the other's particles. The coherence pass is part of
+ * this shader's correctness, not only of its speed.
  *
  * ## Sizing
  *
@@ -76,7 +62,7 @@ export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
  *
  * @type {WebGPUStruct}
  */
-const SIMULATE_SETTINGS = WebGPUStruct.from({
+export const SIMULATE_SETTINGS = WebGPUStruct.from({
     u_dt: f32,
     u_time: f32,
     u_frame: u32,
@@ -98,33 +84,9 @@ resources.createGroup()
 
 
 const body = CodeChunk.from(/* language=wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
-const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
-
-// The value the wave's first live lane holds, in every lane.
-//
-// Everything that reaches the interpreter in one wave belongs to one bucket of sim_list: the
-// coherence pass grouped the list by program and padded each group to a whole workgroup, and the
-// padding and orphan lanes have left by the time a program runs. So the three numbers that pick a
-// section are the same in every lane. The compiler cannot see that — they come out of a table row
-// found through a per-lane header, which is as divergent as a value gets — and reading them from
-// the first lane is what tells it. The rest follows on its own: the instruction words are then
-// fetched through the scalar unit, the opcode switch branches on a scalar, and the register file is
-// indexed through M0 directly instead of through a waterfall loop over the lanes' indices. The VM
-// chunk is unchanged, and emit keeps its per-lane decode, because its waves span emitters.
-//
-// The uniformity diagnostic is off because the call sits behind per-lane early returns. That is the
-// situation the builtin is defined for — it reads the first ACTIVE lane — and the one WGSL's
-// analysis over-approximates.
-@diagnostic(off, subgroup_uniformity)
-fn particle_wave_uniform(value : u32) -> u32 {
-    return subgroupBroadcastFirst(value);
-}
 
 @compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
@@ -134,57 +96,27 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 
     let slot = sim_list[i];
 
-    // A lane the coherence pass padded the bucket out with. Leave BEFORE the compaction atomics
-    // below: appending here would put the sentinel on the alive or the free list, and the free list
-    // would then hand 0xffffffff to an emit as a record base. The lanes that stay all belong to the
-    // one bucket this wave covers, so their program — and the interpreter's switch — is uniform.
-    if (slot == PARTICLE_SIM_PAD_SLOT) { return; }
-
-    let record_base = slot * PARTICLE_RECORD_WORDS;
-    let header = pool[record_base + PARTICLE_HEADER_EMITTER];
-    let emitter_index = particle_header_emitter(header);
-
-    let em = particle_emitter_read(&emitter_database, emitter_index);
-
-    // An orphan: its emitter is gone and the row is free or somebody else's. Freed without running
-    // a program — there is no program of its own left to run.
-    var killed = particle_header_generation(header) != em.generation;
+    let verdict = particle_simulate_one(
+        &scene_database, &emitter_database, &program, &pool,
+        slot,
+        settings.u_dt, settings.u_time, settings.u_frame,
+    );
 
-    if (!killed) {
-        let node = scene_read_node(&scene_database, em.node);
-
-        particle_vm_reset();
-        particle_setup_context(
-            em, node, slot,
-            settings.u_dt, settings.u_time,
-            particle_emitter_age(&emitter_database, emitter_index),
-            0.0, settings.u_frame,
-        );
-        particle_vm_execute(
-            &program,
-            particle_wave_uniform(em.update_offset) * PARTICLE_INSTRUCTION_WORDS,
-            particle_wave_uniform(em.update_count),
-            particle_wave_uniform(em.constant_offset),
-            &pool,
-            record_base,
-        );
-
-        killed = vm_killed;
-    }
-
-    if (killed) {
-        let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
-        dead[d] = slot;
-    } else {
+    // A padding lane's verdict is SKIP and books nothing. Appending it would put the padding
+    // sentinel on the alive or the free list, and the free list would then hand 0xffffffff to a
+    // later emit as a record base.
+    if (verdict == PARTICLE_SIM_ALIVE) {
         let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
         alive_out[a] = slot;
+    } else if (verdict == PARTICLE_SIM_KILLED) {
+        let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
+        dead[d] = slot;
     }
 }
 `, [
-    chunk_particle_setup_context,
-    chunk_particle_emitter_age,
+    chunk_particle_simulate_step,
+    chunk_particle_vm_registers_fast,
     chunk_particle_curve_disabled,
-    chunk_particle_header,
 ]);
 
 body.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/particles/shaders/shader_particle_simulate_wide.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The simulate pass over the WIDE register file — the fallback interpreter.
+ *
+ * Same simulation as {@link ./shader_particle_simulate.js}, down to the shared
+ * {@link ./chunk_particle_simulate_step.js}: one dispatch, every live particle, the emitter's UPDATE
+ * program, compaction into the alive and free lists. Two things differ, and both follow from the
+ * register file living in a storage buffer.
+ *
+ * ## The launch is bounded, and the loop is grid-stride
+ *
+ * The fast pass runs one invocation per particle and sizes its dispatch indirectly from
+ * `counters[ALIVE_IN]`. This one cannot: it needs a register file per invocation in flight, so
+ * one-lane-per-particle would size the register buffer by pool capacity — a gigabyte at a million
+ * particles.
+ *
+ * So it launches exactly {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} lanes,
+ * whatever the particle count, and each walks `sim_list` in strides of that. The register buffer is
+ * then sized by a constant this engine chose rather than by a number the pool decides. There is no
+ * indirect command and no CPU-side count: the launch is fixed, and the loop bound is still the
+ * on-GPU `counters[ALIVE_IN]` snapshot, read in the shader exactly as before. Every guarantee the
+ * fast pass's sizing comment describes holds here for the same reason.
+ *
+ * The stride is a whole number of workgroups, which is what keeps the coherence pass's bucketing
+ * intact: each iteration covers a workgroup-aligned span of `sim_list`, so a wave still sees one
+ * program and the wave-uniform section decode is still sound. That decode is worth keeping even
+ * here — it is what makes the instruction fetch and the opcode switch scalar. Only the register
+ * indexing goes per-lane, because in this backing it always is.
+ *
+ * ## Nine storage buffers
+ *
+ * The fast passes fit in the eight a stage gets by default; this one adds `vm_registers` and needs
+ * nine. That is inside what the engine already demands of an adapter — {@link
+ * ../../Renderer.js} refuses one offering fewer than ten — so it costs no new capability, but it is
+ * why the particle system's "everything fits in eight" note does not cover this shader.
+ *
+ * @type {ComputeShader}
+ */
+/**
+ * Workgroups this pass dispatches. Constant: the launch does not depend on the particle count.
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WIDE_WORKGROUP_COUNT: number;
+export const shader_particle_simulate_wide: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_simulate_wide.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_simulate_wide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_simulate_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate_wide.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;GAGG;AACH,qDAFU,MAAM,CAGqD;AA8DrE,0DAIG;8BAvH2B,+BAA+B"}