@woosh/meep-engine 3.14.4 → 3.14.6

package/src/shade/renderer/particles/coherence/shader_particle_bucket.js

@@ -0,0 +1,344 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SIM_PAD_SLOT,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+
+/**
+ * Simulation-order bucketing — the passes that make each simulate wave run ONE VM program.
+ *
+ * ## Why
+ *
+ * The alive list is produced by compaction (`atomicAdd(&counters[ALIVE])`), so its order is
+ * arbitrary with respect to emitters and a single wave routinely holds particles running different
+ * programs. That costs twice: the interpreter's ~40-case opcode `switch` diverges, so the wave
+ * serially executes the union of the opcodes its lanes want; and `vm_reg[dst]` / `vm_reg[s0]` index
+ * a VGPR-resident register file dynamically, which AMD reaches with `v_movrels`/`v_movreld` behind
+ * a waterfall loop whose trip count is the number of DISTINCT register indices live in the wave.
+ * Grouping the wave by program collapses both at once.
+ *
+ * ## Shape
+ *
+ * The same three-phase shape the depth sort uses, with two small passes added for the padding:
+ *
+ *   reset -> histogram -> pad -> graph_prefix_scan_csdldf -> scatter -> fill
+ *
+ * 0. {@link shader_particle_bucket_reset} — write the `{count}` header the scan sizes itself from,
+ *    clear the bins and the scatter cursors, and build the indirect args the next two passes are
+ *    dispatched with (one thread per alive particle, from the GPU's own alive count).
+ * 1. {@link shader_particle_bucket_histogram} — per alive entry, look up the owning emitter's
+ *    program id and bump that bin.
+ * 2. {@link shader_particle_bucket_pad} — round every bin up to a whole simulate workgroup, keeping
+ *    the raw count aside. Rounding BEFORE the scan is what puts every bucket boundary on a wave
+ *    boundary; rounding after would leave the offsets unpadded and each boundary back mid-wave.
+ * 3. `graph_prefix_scan_csdldf`, reused as-is — inclusive prefix sums of the padded bins, so every
+ *    bucket's start offset is a multiple of the workgroup size.
+ * 4. {@link shader_particle_bucket_scatter} — per alive entry, exclusive offset plus an atomic rank
+ *    within the bucket, then write the pool slot there.
+ * 5. {@link shader_particle_bucket_fill} — write the padding sentinel into the tail of each bucket
+ *    and publish the padded total, which sizes next frame's simulate dispatch.
+ *
+ * ## Invariants this file rests on
+ *
+ * - **Indirection only.** Everything here permutes indices into `pool`. Records never move: slots
+ *   are referenced by the dead (free) list and across frames, and relocating one would leave both
+ *   pointing at the wrong particle.
+ * - **No CPU readback.** Only the bucket COUNT is host-known, and that is static topology (it
+ *   changes when the emitter set does, not per frame). Every per-frame quantity — the alive count,
+ *   the bin sizes, the padded total — is produced and consumed on the GPU.
+ * - **This is not the render order.** `../sort/` produces the camera-dependent back-to-front list
+ *   the billboard draw consumes. Separate buffers, separate passes, separate counter slots.
+ *
+ * @see ./particle_program_buckets.js for the CPU statement of the same answer.
+ */
+
+/** @type {number} words of `{count, elements}` header in front of the scan's bins */
+const HEADER = PREFIX_SCAN_CSDLDF_HEADER_WORDS;
+
+const WG = PARTICLE_SIMULATE_WORKGROUP_SIZE;
+
+/**
+ * Mask that rounds a count down to a whole workgroup; `(n + WG - 1) & PAD_MASK` rounds up.
+ *
+ * A mask rather than `(n + WG - 1u) / WG * WG` because the WGSL emulator's `/` is float division —
+ * the divide form would read differently there than on a device, and the round-up is exactly the
+ * property the specs have to pin. Correct only because {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} is
+ * a power of two.
+ *
+ * @type {number}
+ */
+const PAD_MASK = (~(WG - 1)) >>> 0;
+
+/** log2 of the workgroup size — the fill pass splits its thread id into (bucket, lane) with it. */
+const WG_LOG = Math.log2(WG);
+
+/** Constants every pass in this file interpolates. */
+const COMMON = /* wgsl */ `
+const BUCKET_HEADER_WORDS : u32 = ${HEADER}u;
+const BUCKET_ALIGNMENT : u32 = ${WG}u;
+const BUCKET_PAD_MASK : u32 = ${PAD_MASK}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_SIM_PADDED : u32 = ${PARTICLE_COUNTER.SIM_PADDED}u;
+`;
+
+// --- 0. reset ---------------------------------------------------------------------------------
+
+const reset_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+reset_resources.setImmediate("u_bucket_count", u32);
+reset_resources.createGroup()
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics need read_write even for atomicLoad
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sim_dispatch_args", WebGPUArray.u32, true); // {x,y,z}
+
+/**
+ * Per-frame reset, and the only place the bucketing decides how big it is.
+ *
+ * WebGPU zero-fills a buffer on CREATION only, so without this the scan would consume last frame's
+ * bins and the scatter would compound last frame's ranks.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_reset = ComputeShader.from({
+    label: "Particle Bucket Reset",
+    resources: reset_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    if (i == 0u) {
+        // The {count, elements} header the csdldf scan sizes itself from.
+        atomicStore(&histogram[0], u_bucket_count);
+
+        // One thread per alive particle for the histogram and the scatter. The alive count exists
+        // only on the GPU — the host's copy is a frame stale at best — so the dispatch that
+        // consumes it is built here rather than passed in.
+        let alive = atomicLoad(&counters[COUNTER_ALIVE]);
+        sim_dispatch_args[0] = (alive + BUCKET_ALIGNMENT - 1u) / BUCKET_ALIGNMENT;
+        sim_dispatch_args[1] = 1u;
+        sim_dispatch_args[2] = 1u;
+    }
+
+    // Header padding: never read by the scan, but it shares the buffer and the pool may have left
+    // something in it.
+    if (i > 0u && i < BUCKET_HEADER_WORDS) {
+        atomicStore(&histogram[i], 0u);
+    }
+
+    // The scan reads whole vec4s, so the bins are cleared up to the vec4 the last one lands in.
+    if (i < ((u_bucket_count + 3u) & 0xfffffffcu)) {
+        atomicStore(&histogram[BUCKET_HEADER_WORDS + i], 0u);
+    }
+
+    if (i < u_bucket_count) {
+        atomicStore(&cursor[i], 0u);
+    }
+}
+`),
+});
+
+// --- 1. histogram -----------------------------------------------------------------------------
+
+const histogram_resources = new ShaderResourceSetDescriptor();
+
+histogram_resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("keys", WebGPUArray.u32, true)
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One bin per PROGRAM, not per emitter: emitters compiled from the same graph share a program id
+ * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
+ * emitter index would split a run that was already coherent into one padded bucket per emitter.
+ *
+ * The emitter's program id is read by direct indexing rather than through
+ * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * word would be pure waste in a pass that touches every live particle.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_histogram = ComputeShader.from({
+    label: "Particle Bucket Histogram",
+    resources: histogram_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_EMITTER_RECORD_WORDS : u32 = ${EMITTER_STRIDE}u;
+const EMITTER_WORD_PROGRAM_ID : u32 = ${EMITTER_FIELD.PROGRAM_ID}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let slot = alive[i];
+    let emitter_index = pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER];
+    let program = emitters[emitter_index * PARTICLE_EMITTER_RECORD_WORDS + EMITTER_WORD_PROGRAM_ID];
+
+    keys[i] = program;
+    atomicAdd(&histogram[BUCKET_HEADER_WORDS + program], 1u);
+}
+`),
+});
+
+// --- 2. pad -----------------------------------------------------------------------------------
+
+const pad_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+pad_resources.setImmediate("u_bucket_count", u32);
+pad_resources.createGroup()
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("bucket_counts", WebGPUArray.u32, true);
+
+/**
+ * Round every bin up to a whole workgroup, keeping the raw count in `bucket_counts` for the fill
+ * pass (which needs to know where the real entries stop and the padding starts).
+ *
+ * This is THE step that makes the bucketing worth doing. Scanning the raw counts would put a
+ * bucket boundary at an arbitrary index, and the wave straddling it would span two programs again —
+ * the exact divergence the pass exists to remove. An empty bin rounds up to zero, so a program with
+ * no live particles costs no lanes and shifts nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_pad = ComputeShader.from({
+    label: "Particle Bucket Pad",
+    resources: pad_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let b = gid.x;
+    if (b >= u_bucket_count) { return; }
+
+    let raw = atomicLoad(&histogram[BUCKET_HEADER_WORDS + b]);
+
+    bucket_counts[b] = raw;
+    atomicStore(&histogram[BUCKET_HEADER_WORDS + b], (raw + BUCKET_ALIGNMENT - 1u) & BUCKET_PAD_MASK);
+}
+`),
+});
+
+// --- 3. (graph_prefix_scan_csdldf) ------------------------------------------------------------
+// --- 4. scatter -------------------------------------------------------------------------------
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+
+scatter_resources.createGroup()
+    .addStorageBuffer("keys", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Place each alive entry's pool slot at its bucket's exclusive offset plus an atomic rank.
+ *
+ * Order within a bucket is therefore arbitrary, which is exactly as much order as the simulation
+ * needs: every lane in the bucket runs the same program, so which of them runs where changes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_scatter = ComputeShader.from({
+    label: "Particle Bucket Scatter",
+    resources: scatter_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let bucket = keys[i];
+
+    // The scan is inclusive, so bucket b's exclusive offset is bucket b-1's inclusive value, one
+    // word earlier. For bucket 0 the index lands on the last header word — in bounds, and unused,
+    // because select() takes the 0 branch there.
+    let exclusive = select(0u, scanned[BUCKET_HEADER_WORDS + bucket - 1u], bucket > 0u);
+    let rank = atomicAdd(&cursor[bucket], 1u);
+
+    sim_list[exclusive + rank] = alive[i];
+}
+`),
+});
+
+// --- 5. fill ----------------------------------------------------------------------------------
+
+const fill_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+fill_resources.setImmediate("u_bucket_count", u32);
+fill_resources.createGroup()
+    .addStorageBuffer("bucket_counts", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Stamp the padding sentinel into the tail of every bucket, and publish the padded total.
+ *
+ * Dispatched over one workgroup per bucket — a bucket's padding is at most `BUCKET_ALIGNMENT - 1`
+ * entries, so a workgroup always covers it. It cannot ride along with the scatter, which has no
+ * thread at all for a bucket whose particles all died.
+ *
+ * The padded total is the last bucket's inclusive scan value. It, and not the alive count, is what
+ * sizes next frame's simulate dispatch — the build-indirect pass reads it out of
+ * {@link PARTICLE_COUNTER.SIM_PADDED}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_fill = ComputeShader.from({
+    label: "Particle Bucket Fill",
+    resources: fill_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    // One workgroup per bucket. Shift and mask rather than / and %: the emulator's / is float
+    // division, and BUCKET_ALIGNMENT is a power of two anyway.
+    let bucket = gid.x >> ${WG_LOG}u;
+    let lane = gid.x & (BUCKET_ALIGNMENT - 1u);
+
+    if (gid.x == 0u) {
+        // Inclusive scan, so the last bucket's value is the whole padded length.
+        atomicStore(&counters[COUNTER_SIM_PADDED], scanned[BUCKET_HEADER_WORDS + u_bucket_count - 1u]);
+    }
+
+    if (bucket >= u_bucket_count) { return; }
+
+    let raw = bucket_counts[bucket];
+    let padded = (raw + BUCKET_ALIGNMENT - 1u) & BUCKET_PAD_MASK;
+    // The scan is inclusive, so subtracting this bucket's own (padded) size gives its start.
+    let start = scanned[BUCKET_HEADER_WORDS + bucket] - padded;
+
+    if (lane < padded - raw) {
+        sim_list[start + raw + lane] = PARTICLE_SIM_PAD_SLOT;
+    }
+}
+`),
+});

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.d.ts

@@ -10,15 +10,37 @@ export const PARTICLE_COUNTER: Readonly<{
     DEAD: 1;
     /** number of particles requested to spawn this frame */
     SPAWN: 2;
-    /** length of the sorted index list */
+    /**
+     * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
+     * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
+     * ordering and to nothing else; the simulation order has its own slot, {@link SIM_PADDED}.
+     * Sharing one slot between the two would silently couple a camera-driven ordering to a
+     * program-driven one.
+     */
     SORTED: 3;
     /**
-     * Snapshot of the previous frame's final ALIVE — the exact length of the alive list the
-     * simulate pass consumes this frame. Written by the build-indirect pass at the end of each
-     * frame and NOT zeroed by the reset pass, so the loop stays fully GPU-driven (no CPU readback
-     * can be trusted for dispatch sizing: a stale count orphans or double-simulates slots).
+     * The exact length of the index list the simulate pass consumes this frame — the padded,
+     * program-coherent list the coherence pass built at the end of last frame, so this is
+     * {@link SIM_PADDED}'s value from then, NOT the alive count (padding makes it larger, and a
+     * multiple of the simulate workgroup size).
+     *
+     * Written by the build-indirect pass at the end of each frame, from the same value it derives
+     * the indirect dispatch args from — which is what makes the dispatch's thread count and the
+     * shader's bound agree by construction. NOT zeroed by the reset pass, so the loop stays fully
+     * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
+     * double-simulates slots).
      */
     ALIVE_IN: 4;
+    /**
+     * Length of the padded, program-coherent simulate input list the coherence pass (`../coherence/`)
+     * produced this frame — the SIMULATION order. Camera-independent; it changes only when the
+     * emitter/program set does. Read by the build-indirect pass, which turns it into next frame's
+     * {@link ALIVE_IN} and dispatch args.
+     *
+     * Zeroed by the reset pass: if the coherence passes are ever left out of a frame, simulate then
+     * reads a length of zero and does nothing, rather than re-running last frame's stale list.
+     */
+    SIM_PADDED: 5;
 }>;
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT: 8;

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD,sCAAsC;;IAEtC;;;;;OAKG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BAtCI,mCAAmC"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BA5DI,mCAAmC"}

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

@@ -13,15 +13,37 @@ export const PARTICLE_COUNTER = Object.freeze({
     DEAD: 1,
     /** number of particles requested to spawn this frame */
     SPAWN: 2,
-    /** length of the sorted index list */
+    /**
+     * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
+     * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
+     * ordering and to nothing else; the simulation order has its own slot, {@link SIM_PADDED}.
+     * Sharing one slot between the two would silently couple a camera-driven ordering to a
+     * program-driven one.
+     */
     SORTED: 3,
     /**
-     * Snapshot of the previous frame's final ALIVE — the exact length of the alive list the
-     * simulate pass consumes this frame. Written by the build-indirect pass at the end of each
-     * frame and NOT zeroed by the reset pass, so the loop stays fully GPU-driven (no CPU readback
-     * can be trusted for dispatch sizing: a stale count orphans or double-simulates slots).
+     * The exact length of the index list the simulate pass consumes this frame — the padded,
+     * program-coherent list the coherence pass built at the end of last frame, so this is
+     * {@link SIM_PADDED}'s value from then, NOT the alive count (padding makes it larger, and a
+     * multiple of the simulate workgroup size).
+     *
+     * Written by the build-indirect pass at the end of each frame, from the same value it derives
+     * the indirect dispatch args from — which is what makes the dispatch's thread count and the
+     * shader's bound agree by construction. NOT zeroed by the reset pass, so the loop stays fully
+     * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
+     * double-simulates slots).
      */
     ALIVE_IN: 4,
+    /**
+     * Length of the padded, program-coherent simulate input list the coherence pass (`../coherence/`)
+     * produced this frame — the SIMULATION order. Camera-independent; it changes only when the
+     * emitter/program set does. Read by the build-indirect pass, which turns it into next frame's
+     * {@link ALIVE_IN} and dispatch args.
+     *
+     * Zeroed by the reset pass: if the coherence passes are ever left out of a frame, simulate then
+     * reads a length of zero and does nothing, rather than re-running last frame's stale list.
+     */
+    SIM_PADDED: 5,
 });
 
 /** Number of `u32` atomic slots in the counters buffer. */

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.d.ts

@@ -42,6 +42,7 @@ export function emitter_flags_projection(flags: number): number;
  * @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: Uint32Array, f32: Float32Array, index: number, def: {
     spawn_offset: number;
@@ -58,6 +59,7 @@ export function pack_emitter(u32: Uint32Array, f32: Float32Array, index: number,
     render?: object;
     atlas_region?: number[];
     flipbook?: number[];
+    program_id?: number;
 }): void;
 /**
  * Overwrite just an emitter's world transform in a packed buffer.
@@ -104,9 +106,19 @@ export const EMITTER_FIELD: Readonly<{
     ATLAS_REGION: 33;
     FLIPBOOK: 37;
     RENDER_VELOCITY: 39;
+    /**
+     * 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: 4294967295;
 /** Sentinel for "not attached to a scene node". */

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,kCAnBW,WAAW,OACX,YAAY,SACZ,MAAM;IAEM,YAAY,EAAxB,MAAM;IACM,WAAW,EAAvB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,YAAY,EAAxB,MAAM;IACM,eAAe,EAA3B,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,KAAK,EAAjB,MAAM;IACM,UAAU,EAAtB,MAAM;IACQ,SAAS,EAAvB,MAAM,EAAE;IACO,aAAa,GAA5B,MAAM,EAAE;IACK,aAAa,GAA1B,MAAM;IACO,MAAM,GAAnB,MAAM;IACS,YAAY,GAA3B,MAAM,EAAE;IACO,QAAQ,GAAvB,MAAM,EAAE;SAwClB;AAED;;;;;;;;;;;GAWG;AACH,6CAJW,YAAY,SACZ,MAAM,UACN,UAAU,MAAM,CAAC,QAO3B;AArMD;;;;;;;;;;GAUG;AAEH,6CAA6C;AAC7C;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gDAAgD;AAChD,gCAAiC;AAEjC,uDAAuD;AACvD,kDAAmD;AAEnD,mDAAmD;AACnD,6CAA8C;AAE9C;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG"}
+{"version":3,"file":"PARTICLE_EMITTER_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AAOD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kCApBW,WAAW,OACX,YAAY,SACZ,MAAM;IAEM,YAAY,EAAxB,MAAM;IACM,WAAW,EAAvB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,YAAY,EAAxB,MAAM;IACM,eAAe,EAA3B,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,KAAK,EAAjB,MAAM;IACM,UAAU,EAAtB,MAAM;IACQ,SAAS,EAAvB,MAAM,EAAE;IACO,aAAa,GAA5B,MAAM,EAAE;IACK,aAAa,GAA1B,MAAM;IACO,MAAM,GAAnB,MAAM;IACS,YAAY,GAA3B,MAAM,EAAE;IACO,QAAQ,GAAvB,MAAM,EAAE;IACK,UAAU,GAAvB,MAAM;SA0ChB;AAED;;;;;;;;;;;GAWG;AACH,6CAJW,YAAY,SACZ,MAAM,UACN,UAAU,MAAM,CAAC,QAO3B;AAnND;;;;;;;;;;GAUG;AAEH,6CAA6C;AAC7C;;;;;;;;;;;;;;;;;;;;IA0BI;;;;;;;;OAQG;;GAEJ;AAEH,gDAAgD;AAChD,gCAAiC;AAEjC,uDAAuD;AACvD,kDAAmD;AAEnD,mDAAmD;AACnD,6CAA8C;AAE9C;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG"}

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

@@ -0,0 +1,43 @@
+/**
+ * A particle node type: a {@link NodeDescription} that additionally knows how to lower an instance
+ * of itself into VM instructions.
+ *
+ * Ports carry all the structure the compiler needs — input ports name the operands, the presence of
+ * an output port says whether the node produces a value — so nothing about the graph's shape is
+ * duplicated outside the description.
+ */
+export class ParticleNodeDescription extends NodeDescription {
+    /**
+     * Lower one instance of this node into the target instruction stream.
+     *
+     * `context` provides:
+     * - `context.in(port_name)` → the register holding that input's value (resolved by the compiler),
+     * - `context.out` → the output register (value-producing nodes only, `undefined` for sinks),
+     * - `context.parameters` → the {@link NodeInstance}'s parameters,
+     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for attribute offsets,
+     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants.
+     *
+     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     */
+    emit: (arg0: InstructionStream, arg1: {
+        in: (arg0: string) => number;
+        out: number | undefined;
+        parameters: object;
+        layout: ParticleLayout;
+        asm: ParticleAssembler;
+    }) => void;
+    /**
+     * A node with no output ports produces no value, so nothing can consume it; the only reason to
+     * emit it is its side effect (an attribute write, a kill). Such nodes are the roots the compiler
+     * traverses from.
+     * @returns {boolean}
+     */
+    get is_sink(): boolean;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleNodeDescription: boolean;
+}
+import { NodeDescription } from "../../../../core/model/node-graph/node/NodeDescription.js";
+//# sourceMappingURL=ParticleNodeDescription.d.ts.map

package/src/shade/renderer/particles/graph/ParticleNodeDescription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleNodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH;IAEI;;;;;;;;;;;OAWG;IACH,sCAFsC;QAAC,EAAE,SAAW,MAAM,KAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,GAAG,oBAAmB;KAAC,KAAE,IAAI,CAExJ;IAEZ;;;;;OAKG;IACH,uBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;CAN1D;gCApC+B,2DAA2D"}

package/src/shade/renderer/particles/graph/ParticleNodeDescription.js

@@ -0,0 +1,44 @@
+import { noop } from "../../../../core/function/noop.js";
+import { NodeDescription } from "../../../../core/model/node-graph/node/NodeDescription.js";
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+
+/**
+ * A particle node type: a {@link NodeDescription} that additionally knows how to lower an instance
+ * of itself into VM instructions.
+ *
+ * Ports carry all the structure the compiler needs — input ports name the operands, the presence of
+ * an output port says whether the node produces a value — so nothing about the graph's shape is
+ * duplicated outside the description.
+ */
+export class ParticleNodeDescription extends NodeDescription {
+
+    /**
+     * Lower one instance of this node into the target instruction stream.
+     *
+     * `context` provides:
+     * - `context.in(port_name)` → the register holding that input's value (resolved by the compiler),
+     * - `context.out` → the output register (value-producing nodes only, `undefined` for sinks),
+     * - `context.parameters` → the {@link NodeInstance}'s parameters,
+     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for attribute offsets,
+     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants.
+     *
+     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     */
+    emit = noop;
+
+    /**
+     * A node with no output ports produces no value, so nothing can consume it; the only reason to
+     * emit it is its side effect (an attribute write, a kill). Such nodes are the roots the compiler
+     * traverses from.
+     * @returns {boolean}
+     */
+    get is_sink() {
+        return !this.hasPortsByDirection(PortDirection.Out);
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleNodeDescription.prototype.isParticleNodeDescription = true;