@woosh/meep-engine 3.14.5 → 3.14.6

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js

@@ -36,10 +36,21 @@ export const EMITTER_FIELD = Object.freeze({
     FLIPBOOK: 37,         // vec2<f32> — grid columns, rows (37..38)
 
     RENDER_VELOCITY: 39,  // u32 — attribute word offset of velocity (STRETCHED projection; or ABSENT)
+
+    /**
+     * u32 — dense id of the compiled program this emitter runs, assigned by
+     * {@link ../runtime/ProgramArena.js}. Emitters sharing a program share an id.
+     *
+     * The simulation-order bucketing (`coherence/`) histograms on this: it needs a small dense
+     * integer to index a bin with, which neither the emitter index (one bucket per emitter, even
+     * when they run the same code) nor `UPDATE_OFFSET` (an arena word offset, arbitrarily large
+     * and sparse) gives it.
+     */
+    PROGRAM_ID: 40,
 });
 
 /** Number of `u32` words per emitter record. */
-export const EMITTER_STRIDE = 40;
+export const EMITTER_STRIDE = 41;
 
 /** Sentinel for an absent render-attribute binding. */
 export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
@@ -137,6 +148,7 @@ export const EMITTER_FLAG_ENCODING = Object.freeze({
  * @param {object} [def.render] { position, size, color, rotation, frame } attribute word offsets
  * @param {number[]} [def.atlas_region] length-4 [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
  * @param {number[]} [def.flipbook] length-2 [cols, rows]
+ * @param {number} [def.program_id] dense program id, the simulation-order bucket key
  */
 export function pack_emitter(u32, f32, index, def) {
     const base = index * EMITTER_STRIDE;
@@ -176,6 +188,8 @@ export function pack_emitter(u32, f32, index, def) {
     const flipbook = def.flipbook ?? [1, 1];
     f32[base + EMITTER_FIELD.FLIPBOOK] = flipbook[0];
     f32[base + EMITTER_FIELD.FLIPBOOK + 1] = flipbook[1];
+
+    u32[base + EMITTER_FIELD.PROGRAM_ID] = (def.program_id ?? 0) >>> 0;
 }
 
 /**

package/src/shade/renderer/particles/data/chunk_particle_emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,qCAFU,SAAS,CAoEhB;0BAjFuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,qCAFU,SAAS,CAuEhB;0BApFuB,oCAAoC"}

package/src/shade/renderer/particles/data/chunk_particle_emitter.js

@@ -40,6 +40,7 @@ struct ParticleEmitter {
     render_velocity : u32,
     atlas_region : vec4<f32>,
     flipbook : vec2<f32>,
+    program_id : u32,
 }
 
 fn particle_emitter_read(e : ptr<storage, array<u32>, read>, index : u32) -> ParticleEmitter {
@@ -74,6 +75,8 @@ fn particle_emitter_read(e : ptr<storage, array<u32>, read>, index : u32) -> Par
 
     r.atlas_region = vec4<f32>(bitcast<f32>((*e)[b + ${F.ATLAS_REGION}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 1}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 2}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 3}u]));
     r.flipbook = vec2<f32>(bitcast<f32>((*e)[b + ${F.FLIPBOOK}u]), bitcast<f32>((*e)[b + ${F.FLIPBOOK + 1}u]));
+
+    r.program_id = (*e)[b + ${F.PROGRAM_ID}u];
     return r;
 }
 

package/src/shade/renderer/particles/graph_particles.d.ts

@@ -5,20 +5,32 @@
  *
  * 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
@@ -34,21 +46,30 @@
  * @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 }: {
     graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     gpu: {
         emitters: GPUBuffer;
@@ -62,8 +83,15 @@ export function graph_particles({ graph, gpu, capacity, frame }: {
         spawn_requests: GPUBuffer;
         dispatch_args: GPUBuffer;
         draw_args: GPUBuffer;
+        sim_list: GPUBuffer;
+        sim_keys: GPUBuffer;
+        sim_histogram: GPUBuffer;
+        sim_bucket_counts: GPUBuffer;
+        sim_cursor: GPUBuffer;
+        sim_dispatch_args: GPUBuffer;
     };
     capacity: number;
+    bucket_count: number;
     frame: {
         dt: number;
         time: number;

package/src/shade/renderer/particles/graph_particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IApBkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,GAAG;QACI,QAAQ;QACR,OAAO;QACP,SAAS;QACT,IAAI;QACJ,UAAU;QACV,WAAW;QACX,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,aAAa;QACb,SAAS;;IAChB,QAAQ,EAAvB,MAAM;IACS,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACe,WAAW,EAAhC,MAAM;;;;;;;;EAsFhB"}
+{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH;IA7BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,GAAG;QACI,QAAQ;QACR,OAAO;QACP,SAAS;QACT,IAAI;QACJ,UAAU;QAGV,WAAW;QACX,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,aAAa;QACb,SAAS;QACT,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACS,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACe,WAAW,EAAhC,MAAM;;;;;;;;EAwGhB"}

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