@woosh/meep-engine 3.14.5 → 3.15.0

package/src/shade/renderer/particles/graph_particles.js

@@ -1,9 +1,10 @@
 import { graph_compute_indirect_pass } from "../shader/graph/compute/graph_compute_indirect_pass.js";
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
 import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./ParticleConstants.js";
+import { graph_particle_bucket } from "./coherence/graph_particle_bucket.js";
 import { PARTICLE_EMIT_WORKGROUP_SIZE, shader_particle_emit } from "./shaders/shader_particle_emit.js";
 import {
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
     shader_particle_build_indirect,
     shader_particle_reset_counters,
 } from "./shaders/shader_particle_finalize.js";
@@ -16,20 +17,32 @@ import { shader_particle_simulate } from "./shaders/shader_particle_simulate.js"
  *
  * The passes run in dependency order:
  *
- *   reset counters  ->  emit (spawn)  ->  simulate (advance + compact)  ->  build indirect args
+ *   reset counters -> emit (spawn) -> simulate (advance + compact) -> bucket -> build indirect args
  *
  * with the depth sort + billboard render appended by the caller (the render pass needs the frame's
  * colour + depth attachments, which live in the caller's graph). Alive lists ping-pong by frame
- * parity: `alive_read` is the previous frame's survivors (this frame's simulate input), `alive_write`
- * receives this frame's survivors + newborns.
+ * parity: `alive_write` receives this frame's survivors + newborns.
+ *
+ * ## Two orderings, kept apart
+ *
+ * Simulate does NOT read the alive list. It reads `sim_list`, the program-coherent indirection list
+ * the bucketing pass (`coherence/`) built from last frame's alive list: the same pool slots
+ * regrouped so each wave runs one VM program, with every run padded out to a whole workgroup. That
+ * ordering is camera-independent and changes only when emitters or their programs change.
+ *
+ * The RENDER ordering — back-to-front by view depth, from `sort/` — is a different list in a
+ * different buffer, produced by different passes, and the billboard draw is what consumes it.
+ * Reordering the render list for coherence would break premultiplied transparency; depth-sorting the
+ * simulation list would destroy the coherence. They share no buffer and no counter slot.
  *
  * The simulate pass is fully GPU-driven: its workgroup count comes from `dispatch_args` (written by
  * LAST frame's build-indirect pass) via `dispatchWorkgroupsIndirect`, and its element bound comes
- * from the `ALIVE_IN` counter snapshot — never from a CPU count. A CPU count is inevitably stale and
- * corrupts the pool (orphaned slots when the population grows, double-freed slots when it shrinks).
- * Only the spawn count is CPU-provided, because the CPU authored the spawn-request list and knows its
- * exact length. The caller renders with `drawIndirect(draw_args)`, which build-indirect writes THIS
- * frame, so the instance count is exact too.
+ * from the `ALIVE_IN` counter snapshot — never from a CPU count. Both are derived from one value,
+ * the padded list length, so the thread count and the bound agree by construction. A CPU count is
+ * inevitably stale and corrupts the pool (orphaned slots when the population grows, double-freed
+ * slots when it shrinks). Only the spawn count is CPU-provided, because the CPU authored the
+ * spawn-request list and knows its exact length. The caller renders with `drawIndirect(draw_args)`,
+ * which build-indirect writes THIS frame, so the instance count is exact too.
  *
  * All persistent buffers are imported (owned by the feature, not the graph). Writing an imported
  * buffer marks the pass a side-effect so it always executes, and returns a renamed handle downstream
@@ -45,25 +58,34 @@ import { shader_particle_simulate } from "./shaders/shader_particle_simulate.js"
  * @param {GPUBuffer} params.gpu.program
  * @param {GPUBuffer} params.gpu.constants
  * @param {GPUBuffer} params.gpu.pool
- * @param {GPUBuffer} params.gpu.alive_read previous-frame alive list
- * @param {GPUBuffer} params.gpu.alive_write this-frame alive list
+ * @param {GPUBuffer} params.gpu.alive_read the other half of the ping-pong. These passes no longer
+ *   read it — simulate's input is `sim_list` — but the caller keeps swapping the two so this frame's
+ *   render is not read-after-written by next frame's emit, which would serialise them
+ * @param {GPUBuffer} params.gpu.alive_write this-frame alive list: survivors + newborns
  * @param {GPUBuffer} params.gpu.dead free-list stack
  * @param {GPUBuffer} params.gpu.counters atomic counters
  * @param {GPUBuffer} params.gpu.spawn_requests
  * @param {GPUBuffer} params.gpu.dispatch_args indirect simulate dispatch (usage must include INDIRECT)
  * @param {GPUBuffer} params.gpu.draw_args indirect billboard draw (usage must include INDIRECT)
+ * @param {GPUBuffer} params.gpu.sim_list program-coherent simulate input, rebuilt here for next frame
+ * @param {GPUBuffer} params.gpu.sim_keys see {@link graph_particle_bucket}
+ * @param {GPUBuffer} params.gpu.sim_histogram see {@link graph_particle_bucket}
+ * @param {GPUBuffer} params.gpu.sim_bucket_counts see {@link graph_particle_bucket}
+ * @param {GPUBuffer} params.gpu.sim_cursor see {@link graph_particle_bucket}
+ * @param {GPUBuffer} params.gpu.sim_dispatch_args see {@link graph_particle_bucket} (usage must include INDIRECT)
  * @param {number} params.capacity pool capacity in particles (bounds the emit pass's free-list pops)
+ * @param {number} params.bucket_count distinct compiled programs — `GPUParticleSystem#bucketCount()`
  * @param {object} params.frame per-frame scalars
  * @param {number} params.frame.dt
  * @param {number} params.frame.time
  * @param {number} params.frame.index
  * @param {number} params.frame.spawn_count number of spawn requests this frame (CPU-authored, exact)
  */
-export function graph_particles({ graph, gpu, capacity, frame }) {
+export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
     const gr_emitters = graph_import_buffer(graph, gpu.emitters, "particles/emitters");
     const gr_program = graph_import_buffer(graph, gpu.program, "particles/program");
     const gr_constants = graph_import_buffer(graph, gpu.constants, "particles/constants");
-    const gr_alive_read = graph_import_buffer(graph, gpu.alive_read, "particles/alive_read");
+    const gr_sim_list = graph_import_buffer(graph, gpu.sim_list, "particles/sim_list");
     const gr_spawn = graph_import_buffer(graph, gpu.spawn_requests, "particles/spawn_requests");
     const gr_dispatch = graph_import_buffer(graph, gpu.dispatch_args, "particles/dispatch_args");
     const gr_draw = graph_import_buffer(graph, gpu.draw_args, "particles/draw_args");
@@ -76,7 +98,7 @@ export function graph_particles({ graph, gpu, capacity, frame }) {
     let alive_write = graph_import_buffer(graph, gpu.alive_write, "particles/alive_write");
     let dead = graph_import_buffer(graph, gpu.dead, "particles/dead");
 
-    // 1. Reset the alive/spawn/sorted counters (the dead count + ALIVE_IN snapshot persist).
+    // 1. Reset the alive/spawn/sorted/sim-padded counters (dead count + ALIVE_IN snapshot persist).
     counters = graph_compute_pass({
         graph,
         shader: shader_particle_reset_counters,
@@ -102,17 +124,18 @@ export function graph_particles({ graph, gpu, capacity, frame }) {
         pool = out.pool; alive_write = out.alive_out; dead = out.dead; counters = out.counters;
     }
 
-    // 3. Simulate — one indirect dispatch runs every emitter's UPDATE over the previous alive list,
-    //    compacting survivors into the new alive list and freed slots into the dead list. The
-    //    workgroup count comes from LAST frame's dispatch_args (read here, re-written in step 4 —
-    //    insertion order keeps the read before the write).
+    // 3. Simulate — one indirect dispatch runs every emitter's UPDATE over the program-coherent list
+    //    the bucketing pass built LAST frame, compacting survivors into the new alive list and freed
+    //    slots into the dead list. The workgroup count comes from last frame's dispatch_args and the
+    //    list itself from last frame's sim_list — both read here and re-written in steps 4 and 5,
+    //    with insertion order keeping the read before the write.
     {
         const out = graph_compute_indirect_pass({
             graph,
             shader: shader_particle_simulate,
             bindings: {
                 emitters: gr_emitters, program: gr_program, vm_constants: gr_constants,
-                pool, alive_in: gr_alive_read, alive_out: alive_write, dead, counters,
+                pool, sim_list: gr_sim_list, alive_out: alive_write, dead, counters,
                 settings: { u_dt: frame.dt, u_time: frame.time, u_frame: frame.index },
             },
             command: gr_dispatch,
@@ -120,7 +143,24 @@ export function graph_particles({ graph, gpu, capacity, frame }) {
         pool = out.pool; alive_write = out.alive_out; dead = out.dead; counters = out.counters;
     }
 
-    // 4. Snapshot the final alive count (next frame's simulate input length) and build the indirect
+    // 4. Bucket — regroup the frame's alive list by VM program, padded to whole workgroups, into the
+    //    list NEXT frame's simulate consumes. Must follow BOTH emit and simulate, since both append
+    //    to the alive list.
+    //    `gr_sim_list` is handed over rather than re-imported: two imports of one GPUBuffer are two
+    //    resource entries the graph cannot tell apart, which would put simulate's read of the list
+    //    and this pass's rewrite of it on unrelated dependency chains.
+    counters = graph_particle_bucket({
+        graph,
+        gpu,
+        emitters: gr_emitters,
+        pool,
+        alive: alive_write,
+        counters,
+        sim_list: gr_sim_list,
+        bucket_count,
+    }).counters;
+
+    // 5. Snapshot the padded list length (next frame's simulate input length) and build the indirect
     //    dispatch args for next frame + the indirect draw args for this frame's render.
     const indirect = graph_compute_pass({
         graph,

package/src/shade/renderer/particles/runtime/EmitterRegistry.d.ts

@@ -50,12 +50,19 @@ export class EmitterRegistry {
     }): number;
     /**
      * Pack all emitters + their programs into upload-ready buffers.
-     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array }}
+     *
+     * `program_count` is the number of DISTINCT programs across the emitter set — the bucket count
+     * the simulation-order coherence pass histograms into. It is CPU-known and low-churn (it only
+     * changes when the emitter set does), which is why that pass can size its histogram, its cursor
+     * and its padding dispatch on the host without any of the per-frame counts ever leaving the GPU.
+     *
+     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array, program_count: number }}
      */
     build(): {
         emitters: Uint32Array;
         program: Uint32Array;
         constants: Uint32Array;
+        program_count: number;
     };
     /**
      * The scene-node row an emitter is attached to (for bone attachment), or the "none" sentinel.

package/src/shade/renderer/particles/runtime/EmitterRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH;IAEQ,uBAAuB;IACvB,UADW,MAAM,EAAE,CACD;IAGtB,sDAAsD;IACtD,oBAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;QAZqD,MAAM,EAAhD;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACf,SAAS,GAA3B,MAAM,EAAE;QACQ,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,KAAK,GAArB,MAAM;QACwC,MAAM,GAApD;YAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACL,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACF,YAAY,GAA9B,MAAM,EAAE;QACU,QAAQ,GAA1B,MAAM,EAAE;QACQ,UAAU,GAA1B,MAAM;QACJ,MAAM,CASlB;IAED;;;OAGG;IACH;kBAFyB,WAAW;iBAAW,WAAW;mBAAa,WAAW;MAwCjF;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH;IAEQ,uBAAuB;IACvB,UADW,MAAM,EAAE,CACD;IAGtB,sDAAsD;IACtD,oBAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;QAZqD,MAAM,EAAhD;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACf,SAAS,GAA3B,MAAM,EAAE;QACQ,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,KAAK,GAArB,MAAM;QACwC,MAAM,GAApD;YAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACL,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACF,YAAY,GAA9B,MAAM,EAAE;QACU,QAAQ,GAA1B,MAAM,EAAE;QACQ,UAAU,GAA1B,MAAM;QACJ,MAAM,CASlB;IAED;;;;;;;;;OASG;IACH;kBAFyB,WAAW;iBAAW,WAAW;mBAAa,WAAW;uBAAiB,MAAM;MAyCxG;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

package/src/shade/renderer/particles/runtime/EmitterRegistry.js

@@ -57,7 +57,13 @@ export class EmitterRegistry {
 
     /**
      * Pack all emitters + their programs into upload-ready buffers.
-     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array }}
+     *
+     * `program_count` is the number of DISTINCT programs across the emitter set — the bucket count
+     * the simulation-order coherence pass histograms into. It is CPU-known and low-churn (it only
+     * changes when the emitter set does), which is why that pass can size its histogram, its cursor
+     * and its padding dispatch on the host without any of the per-frame counts ever leaving the GPU.
+     *
+     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array, program_count: number }}
      */
     build() {
         const arena = new ProgramArena();
@@ -96,6 +102,7 @@ export class EmitterRegistry {
             emitters,
             program: arena.build_instruction_buffer(),
             constants: arena.build_constant_buffer(),
+            program_count: Math.max(1, arena.program_count),
         };
     }
 

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts

@@ -15,10 +15,29 @@ export class ProgramArena {
     instruction_count: number;
     /** @type {number} running vec4 constant index */
     constant_count: number;
+    /** @type {Map<string, object>} content key -> the placement the first identical program got */
+    programs: Map<string, object>;
     /**
-     * Append a program.
+     * Number of distinct programs in the arena — and therefore the number of buckets the
+     * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
+     * @returns {number}
+     */
+    get program_count(): number;
+    /**
+     * Append a program, or hand back the placement an identical one already has.
+     *
+     * Deduplication is by CONTENT, not object identity: two emitters that authored the same graph
+     * separately compile to distinct {@link ParticleProgram} objects holding the same bytecode, and
+     * they should still land in one simulation bucket. Emitters are few and long-lived, so hashing
+     * the words is not a cost worth avoiding.
+     *
+     * The `program_id` it returns is what the emitter record carries and what the coherence pass
+     * buckets on. Keying on the emitter index instead would be simpler but strictly worse: N
+     * emitters running one shared effect would become N buckets, each padded to a whole workgroup,
+     * which both wastes lanes and splits a run that was already program-coherent.
+     *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number}}
+     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program: import("../isa/ParticleProgram.js").ParticleProgram): {
         spawn_offset: number;
@@ -26,6 +45,7 @@ export class ProgramArena {
         update_offset: number;
         update_count: number;
         constant_offset: number;
+        program_id: number;
     };
     /** @returns {Uint32Array} the packed instruction buffer (at least length 1) */
     build_instruction_buffer(): Uint32Array;

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IAEQ,8CAA8C;IAC9C,mBADW,MAAM,EAAE,CACQ;IAC3B,8DAA8D;IAC9D,gBADW,MAAM,EAAE,CACK;IACxB,yFAAyF;IACzF,mBADW,MAAM,CACS;IAC1B,iDAAiD;IACjD,gBADW,MAAM,CACM;IAG3B;;;;OAIG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;sBAClC,MAAM;qBAAe,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;MAmB5H;IAUD,+EAA+E;IAC/E,4BADc,WAAW,CAGxB;IAED,yFAAyF;IACzF,yBADc,WAAW,CAGxB;;CACJ"}
+{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IAEQ,8CAA8C;IAC9C,mBADW,MAAM,EAAE,CACQ;IAC3B,8DAA8D;IAC9D,gBADW,MAAM,EAAE,CACK;IACxB,yFAAyF;IACzF,mBADW,MAAM,CACS;IAC1B,iDAAiD;IACjD,gBADW,MAAM,CACM;IACvB,+FAA+F;IAC/F,UADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACL;IAG7B;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;sBAClC,MAAM;qBAAe,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAgChJ;IAUD,+EAA+E;IAC/E,4BADc,WAAW,CAGxB;IAED,yFAAyF;IACzF,yBADc,WAAW,CAGxB;;CACJ"}

package/src/shade/renderer/particles/runtime/ProgramArena.js

@@ -18,14 +18,43 @@ export class ProgramArena {
         this.instruction_count = 0;
         /** @type {number} running vec4 constant index */
         this.constant_count = 0;
+        /** @type {Map<string, object>} content key -> the placement the first identical program got */
+        this.programs = new Map();
     }
 
     /**
-     * Append a program.
+     * Number of distinct programs in the arena — and therefore the number of buckets the
+     * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
+     * @returns {number}
+     */
+    get program_count() {
+        return this.programs.size;
+    }
+
+    /**
+     * Append a program, or hand back the placement an identical one already has.
+     *
+     * Deduplication is by CONTENT, not object identity: two emitters that authored the same graph
+     * separately compile to distinct {@link ParticleProgram} objects holding the same bytecode, and
+     * they should still land in one simulation bucket. Emitters are few and long-lived, so hashing
+     * the words is not a cost worth avoiding.
+     *
+     * The `program_id` it returns is what the emitter record carries and what the coherence pass
+     * buckets on. Keying on the emitter index instead would be simpler but strictly worse: N
+     * emitters running one shared effect would become N buckets, each padded to a whole workgroup,
+     * which both wastes lanes and splits a run that was already program-coherent.
+     *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number}}
+     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program) {
+        const key = program_content_key(program);
+
+        const existing = this.programs.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+
         const spawn_offset = this.instruction_count;
         this.#append_instructions(program.spawn);
         const spawn_count = program.spawn_instruction_count;
@@ -41,7 +70,13 @@ export class ProgramArena {
         }
         this.constant_count += program.constant_count;
 
-        return { spawn_offset, spawn_count, update_offset, update_count, constant_offset };
+        const placement = {
+            spawn_offset, spawn_count, update_offset, update_count, constant_offset,
+            program_id: this.programs.size,
+        };
+        this.programs.set(key, placement);
+
+        return placement;
     }
 
     /** @param {Uint32Array} words */
@@ -62,3 +97,19 @@ export class ProgramArena {
         return new Uint32Array(this.constant_words.length > 0 ? this.constant_words : [0, 0, 0, 0]);
     }
 }
+
+/**
+ * A key that is equal exactly when two programs would execute identically.
+ *
+ * Constants are keyed by their `u32` bit patterns rather than their float values, so `-0` and `0`
+ * — which stringify the same but differ in the buffer the shader reads — stay distinct.
+ *
+ * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+ * @returns {string}
+ */
+function program_content_key(program) {
+    const constants = program.constants;
+    const constant_u32 = new Uint32Array(constants.buffer, constants.byteOffset, constants.length);
+
+    return `${program.register_count}|${program.spawn.join(",")}|${program.update.join(",")}|${constant_u32.join(",")}`;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAYG;AAaH,2DA0BG;;8BA7E2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AAoCA,2DAaG;AAaH,2DAmCG;;8BA/F2B,+BAA+B;iDAIZ,+BAA+B"}

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

@@ -9,16 +9,24 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./shader_particle_simulate.js"
 /**
  * Small housekeeping passes that keep the pipeline GPU-driven:
  *
- * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted counters at the top of
- *   the frame (the dead count and the ALIVE_IN snapshot persist across frames).
- * - {@link shader_particle_build_indirect} — read the frame's final alive count and (a) snapshot it
- *   into {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b)
- *   write the indirect dispatch args next frame's simulate consumes, and (c) write the indirect draw
- *   args for THIS frame's billboard render. Nothing round-trips to the CPU. Sizing the dispatch or
- *   draw from a stale CPU readback instead is a correctness bug: when the alive count grows the tail
- *   of the list is never simulated (slots leak into limbo), and when it shrinks stale entries beyond
- *   the written range get re-simulated — a dead slot is pushed to the free list twice and later
- *   popped twice, leaving two live particles sharing one record.
+ * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted / sim-padded counters
+ *   at the top of the frame (the dead count and the ALIVE_IN snapshot persist across frames).
+ * - {@link shader_particle_build_indirect} — turn the frame's two final counts into next frame's
+ *   input contract: (a) snapshot the coherence pass's padded list length into
+ *   {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b) write
+ *   the indirect dispatch args next frame's simulate consumes, from that SAME value, and (c) write
+ *   the indirect draw args for THIS frame's billboard render, from the alive count. Nothing
+ *   round-trips to the CPU. Sizing the dispatch or draw from a stale CPU readback instead is a
+ *   correctness bug: when the alive count grows the tail of the list is never simulated (slots leak
+ *   into limbo), and when it shrinks stale entries beyond the written range get re-simulated — a
+ *   dead slot is pushed to the free list twice and later popped twice, leaving two live particles
+ *   sharing one record.
+ *
+ * The two lengths are deliberately different quantities and must not be conflated. Simulate consumes
+ * the SIMULATION order: the program-coherent list from `../coherence/`, padded so no wave spans two
+ * VM programs, and therefore longer than the alive count and always a whole number of workgroups.
+ * The billboard draw consumes the RENDER order: one instance per live particle, unpadded — a
+ * padding entry drawn as an instance would read a garbage record.
  */
 
 // --- reset ---
@@ -36,6 +44,7 @@ fn main() {
     atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
     atomicStore(&counters[${PARTICLE_COUNTER.SPAWN}u], 0u);
     atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SIM_PADDED}u], 0u);
 }
 `),
 });
@@ -61,16 +70,25 @@ export const shader_particle_build_indirect = ComputeShader.from({
 fn main() {
     let alive = atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]);
 
-    // Snapshot: this frame's final alive count is next frame's exact simulate input length.
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], alive);
+    // The length of the padded, program-coherent list the coherence pass just built — NOT the alive
+    // count. Padding makes it longer, and a whole number of workgroups.
+    let sim_length = atomicLoad(&counters[${PARTICLE_COUNTER.SIM_PADDED}u]);
+
+    // Snapshot: that list is next frame's simulate input, and this is its exact length.
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], sim_length);
 
-    // Simulate dispatch (consumed NEXT frame): one thread per alive particle, whole workgroups.
-    let groups = (alive + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
+    // Simulate dispatch (consumed NEXT frame): one thread per entry of that same list. Derived from
+    // the same value as the bound above, so thread count and bound agree by construction — and
+    // because a padded length is a whole number of workgroups, they agree exactly: every thread the
+    // dispatch launches has an entry, real or sentinel.
+    let groups = (sim_length + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
     dispatch_args[0] = groups;
     dispatch_args[1] = 1u;
     dispatch_args[2] = 1u;
 
     // Instanced billboard draw (consumed THIS frame): 6 verts per particle, one instance per alive.
+    // The render list is the unpadded one — an instance per padding entry would read a garbage
+    // record.
     draw_args[0] = 6u;
     draw_args[1] = alive;
     draw_args[2] = 0u;

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

@@ -1,26 +1,5 @@
-/**
- * The particle simulate pass — Destiny-style single execution shader.
- *
- * One dispatch processes the entire alive list 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.
- *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
- *
- * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
- * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
- * animation-database-backed one.
- *
- * @type {ComputeShader}
- */
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE: ComputeShader;
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
 export const shader_particle_simulate: ComputeShader;
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.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":"AAcA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AAuEnD,qDAIG;8BA7G2B,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AAyIA,qDAIG;iDAjII,yBAAyB;8BATF,+BAA+B"}

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

@@ -7,6 +7,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 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_COUNTER } from "../data/PARTICLE_COUNTERS.js";
@@ -15,18 +17,37 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
 /**
  * The particle simulate pass — Destiny-style single execution shader.
  *
- * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
+ * 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.
  *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
+ * ## The input list
+ *
+ * `sim_list` is NOT the raw alive list. It is the program-coherent indirection list the coherence
+ * 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, which would make the interpreter's opcode `switch`
+ * diverge and multiply the register file's `v_movrels` waterfall by the number of distinct register
+ * indices in the wave.
+ *
+ * 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.
+ *
+ * ## Sizing
+ *
+ * The input length is read from `counters[ALIVE_IN]` — the padded length of that list, snapshotted
+ * on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count is inevitably
+ * stale (readback latency) and corrupts the pool: under-counting orphans the tail of the list (slots
+ * leak into limbo), over-counting re-simulates stale entries and double-frees their slots. Dispatch
+ * this shader with `dispatchWorkgroupsIndirect` using the args the build-indirect pass wrote last
+ * frame from that same value, so thread count and bound agree by construction — and, because the
+ * padded length is a whole number of workgroups, agree exactly.
  *
  * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
  * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
@@ -35,7 +56,7 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
  * @type {ComputeShader}
  */
 
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
 
 /**
  * Per-dispatch, 12 bytes, read-only — see shader_particle_emit for why the three travel
@@ -58,7 +79,7 @@ resources.createGroup()
     .addStorageBuffer("program", WebGPUArray.u32, false)
     .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("alive_in", WebGPUArray.u32, false)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
@@ -71,14 +92,22 @@ 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;
 
 @compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
-    // The exact alive-list length, snapshotted on-GPU last frame — never a stale CPU value.
+    // The exact input length, snapshotted on-GPU last frame — never a stale CPU value.
     if (i >= atomicLoad(&counters[COUNTER_ALIVE_IN])) { return; }
 
-    let slot = alive_in[i];
+    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 emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
 

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts

@@ -1,23 +1,12 @@
+export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 /**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
- * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
- *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
- *    `keys`, and atomically bump the per-bucket `histogram`.
- * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
- * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
- *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
- *    into `sorted` at that position.
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
+ * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
+ * and the scan adds them in.
  *
- * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
- * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
- * algorithm.
+ * @type {ComputeShader}
  */
-export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 export const shader_particle_sort_reset: ComputeShader;
 export const shader_particle_sort_histogram: ComputeShader;
 export const shader_particle_sort_scatter: ComputeShader;

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA+C;AAkC/C,uDAIG;AAyEH,2DAIG;AAqCH,yDAIG;8BAvL2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAsDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AA0EH,2DAIG;AAyCH,yDAIG;8BA1O2B,+BAA+B"}