@woosh/meep-engine 3.14.4 → 3.14.6

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

@@ -1 +1 @@
-{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/particle_prototype.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA2GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAcpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,0CALW,OAAO,wBAAwB,EAAE,iBAAiB;IAEjC,IAAI,GAArB,MAAM;;UACG,MAAM;WAAS,MAAM;EAWxC;+BAhL8B,4BAA4B"}
+{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/particle_prototype.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA2GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAcpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,0CALW,OAAO,wBAAwB,EAAE,iBAAiB;IAEjC,IAAI,GAArB,MAAM;;UACG,MAAM;WAAS,MAAM;EAWxC;+BAhL8B,4BAA4B"}

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

@@ -1,180 +1,181 @@
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
-import { ParticleGraph } from "./graph/ParticleGraph.js";
-import { VM_BUILTIN, VM_RANDOM_MODE } from "./isa/ParticleVMISA.js";
-import { ParticleLayout } from "./layout/ParticleLayout.js";
-import { create_particle_effect } from "./runtime/create_particle_effect.js";
-
-/**
- * Worked examples of authoring particle effects with the node graph + wiring them into a
- * {@link GPUParticleSystem}. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
- * additive vs alpha blending, projection modes, soft depth and lighting toggles.
- *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
- */
-
-/**
- * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
- * follow curves over their lifetime and whose flipbook advances with age.
- *
- * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
- * @param {number} [options.flipbook_frames]
- * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
- */
-export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } = {}) {
-    const layout = new ParticleLayout([
-        { name: "position", components: 3 },
-        { name: "velocity", components: 3 },
-        { name: "age", components: 1 },
-        { name: "lifetime", components: 1 },
-        { name: "size", components: 1 },
-        { name: "color", components: 4 },
-        { name: "frame", components: 1 },
-    ]);
-
-    // --- SPAWN: seed each particle's state ---
-    const spawn = new ParticleGraph();
-    {
-        // position = emitter position + a small disk of jitter on the ground
-        const ep = spawn.add("builtin", { id: VM_BUILTIN.EMITTER_POSITION });
-        const disk = spawn.add("random", { mode: VM_RANDOM_MODE.UNIT_DISK });
-        const jitter = spawn.add("scale"); spawn.wire(jitter, "v", disk); spawn.wire(jitter, "s", [0.2]);
-        const p0 = spawn.add("add"); spawn.wire(p0, "a", ep); spawn.wire(p0, "b", jitter);
-        spawn.wire(spawn.add("setAttribute", { name: "position" }), "value", p0);
-
-        // velocity = upward buoyancy + signed turbulence
-        const up = spawn.add("const", { value: [0, 2.0, 0, 0] });
-        const turb = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
-        const turbS = spawn.add("scale"); spawn.wire(turbS, "v", turb); spawn.wire(turbS, "s", [0.5]);
-        const v0 = spawn.add("add"); spawn.wire(v0, "a", up); spawn.wire(v0, "b", turbS);
-        spawn.wire(spawn.add("setAttribute", { name: "velocity" }), "value", v0);
-
-        spawn.wire(spawn.add("setAttribute", { name: "age" }), "value", [0]);
-        // lifetime 1.2..1.8s
-        const lr = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM });
-        const ls = spawn.add("mad"); spawn.wire(ls, "a", lr); spawn.wire(ls, "b", [0.6]); spawn.wire(ls, "c", [1.2]);
-        spawn.wire(spawn.add("setAttribute", { name: "lifetime" }), "value", ls);
-
-        spawn.wire(spawn.add("setAttribute", { name: "size" }), "value", [0.4]);
-        spawn.wire(spawn.add("setAttribute", { name: "color" }), "value", [1.0, 0.6, 0.2, 1.0]);
-        spawn.wire(spawn.add("setAttribute", { name: "frame" }), "value", [0]);
-    }
-
-    // --- UPDATE: advance + destroy ---
-    const update = new ParticleGraph();
-    {
-        const dt = update.add("builtin", { id: VM_BUILTIN.DELTA_TIME });
-
-        // age += dt
-        const age = update.add("attribute", { name: "age" });
-        const newAge = update.add("add"); update.wire(newAge, "a", age); update.wire(newAge, "b", dt);
-        update.wire(update.add("setAttribute", { name: "age" }), "value", newAge);
-
-        // normalizedAge = age / lifetime
-        const lifetime = update.add("attribute", { name: "lifetime" });
-        const nAge = update.add("div"); update.wire(nAge, "a", newAge); update.wire(nAge, "b", lifetime);
-
-        // kill when normalizedAge >= 1
-        const dead = update.add("compare", { op: "ge" }); update.wire(dead, "a", nAge); update.wire(dead, "b", [1]);
-        update.wire(update.add("kill"), "condition", dead);
-
-        // buoyant rise + drift: velocity += (0, 1, 0)*dt ; position += velocity*dt
-        const vel = update.add("attribute", { name: "velocity" });
-        const buoy = update.add("const", { value: [0, 1.0, 0, 0] });
-        const buoyDt = update.add("scale"); update.wire(buoyDt, "v", buoy); update.wire(buoyDt, "s", dt);
-        const nVel = update.add("add"); update.wire(nVel, "a", vel); update.wire(nVel, "b", buoyDt);
-        update.wire(update.add("setAttribute", { name: "velocity" }), "value", nVel);
-        const pos = update.add("attribute", { name: "position" });
-        const velDt = update.add("scale"); update.wire(velDt, "v", nVel); update.wire(velDt, "s", dt);
-        const nPos = update.add("add"); update.wire(nPos, "a", pos); update.wire(nPos, "b", velDt);
-        update.wire(update.add("setAttribute", { name: "position" }), "value", nPos);
-
-        // size + alpha from curves over life (or constants if no curve provided)
-        if (size_curve !== undefined) {
-            const sc = update.add("curve", { handle: size_curve }); update.wire(sc, "t", nAge);
-            update.wire(update.add("setAttribute", { name: "size" }), "value", sc);
-        }
-        const color = update.add("attribute", { name: "color" });
-        if (alpha_curve !== undefined) {
-            const ac = update.add("curve", { handle: alpha_curve }); update.wire(ac, "t", nAge);
-            // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
-            // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
-            const alphaVec = update.add("mul");
-            update.wire(alphaVec, "a", color);
-            update.wire(alphaVec, "b", ac); // broadcasts ac to all lanes (rgb also fades — a warm ember look)
-            update.wire(update.add("setAttribute", { name: "color" }), "value", alphaVec);
-        }
-
-        // flipbook frame = floor(normalizedAge * frames)
-        const framesN = update.add("const", { value: [flipbook_frames, 0, 0, 0] });
-        const fscaled = update.add("mul"); update.wire(fscaled, "a", nAge); update.wire(fscaled, "b", framesN);
-        const fframe = update.add("floor"); update.wire(fframe, "x", fscaled);
-        update.wire(update.add("setAttribute", { name: "frame" }), "value", fframe);
-    }
-
-    const effect = create_particle_effect({ layout, spawn, update });
-
-    const emitter = {
-        effect,
-        spawn_rate: 120,
-        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
-        render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 1.5, 0], radius: 2.5 },
-        // A 4x4 flipbook packed as the whole atlas here; a real atlas would use a sub-rect.
-        atlas_region: [0, 0, 1, 1],
-        flipbook: [4, 4],
-    };
-
-    return { layout, effect, emitter };
-}
-
-/**
- * A smoke effect: slow, expanding, alpha-blended, lit, soft-depth billboards. Same authoring
- * surface as fire; the differences are all data (blend/lighting/soft flags, rates, colours).
- * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
- */
-export function smoke_effect() {
-    const { layout, effect } = fire_effect({ flipbook_frames: 8 });
-    const emitter = {
-        effect,
-        spawn_rate: 25,
-        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true, lighting: true, sort: true },
-        render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 3, 0], radius: 5 },
-        atlas_region: [0, 0, 1, 1],
-        flipbook: [1, 1],
-    };
-    return { layout, effect, emitter };
-}
-
-/**
- * Register a fire + smoke plume on a particle system, optionally attaching the fire to a bone.
- *
- * The per-frame loop the integrator runs:
- * ```js
- * const spawn_requests = system.update(dt, { is_visible });     // CPU: bone transforms + spawn counts
- * system.uploadFrame(spawn_requests);                           // upload emitters (if dirty) + requests
- * graph_particles({ graph, gpu: system.gpuHandles(), frame });  // reset -> emit -> simulate -> indirect
- * // caller appends the depth sort + billboard render into its own graph
- * ```
- *
- * @param {import("./GPUParticleSystem.js").GPUParticleSystem} system
- * @param {object} [options]
- * @param {object} [options.bone] a Node3D to attach the fire emitter to
- * @returns {{fire: number, smoke: number}} emitter indices
- */
-export function register_campfire(system, { bone } = {}) {
-    const fire = system.addEmitter(fire_effect().emitter);
-    const smoke = system.addEmitter(smoke_effect().emitter);
-    if (bone !== undefined) {
-        system.attachToNode(fire, bone);
-        system.attachToNode(smoke, bone);
-    }
-    system.buildEmitterData();
-    return { fire, smoke };
-}
+import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
+import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
+import { particle_node, particle_wire } from "./graph/particle_graph_authoring.js";
+import { VM_BUILTIN, VM_RANDOM_MODE } from "./isa/ParticleVMISA.js";
+import { ParticleLayout } from "./layout/ParticleLayout.js";
+import { create_particle_effect } from "./runtime/create_particle_effect.js";
+
+/**
+ * Worked examples of authoring particle effects with the node graph + wiring them into a
+ * {@link GPUParticleSystem}. Demonstrates: distinct per-particle lifecycle (no built-in age — the
+ * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * additive vs alpha blending, projection modes, soft depth and lighting toggles.
+ *
+ * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
+ * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
+ * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
+ * disabled provider), which is handy for the headless tests.
+ */
+
+/**
+ * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
+ * follow curves over their lifetime and whose flipbook advances with age.
+ *
+ * @param {object} [options]
+ * @param {number} [options.size_curve] curve handle for size(normalizedAge)
+ * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {number} [options.flipbook_frames]
+ * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
+ */
+export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } = {}) {
+    const layout = new ParticleLayout([
+        { name: "position", components: 3 },
+        { name: "velocity", components: 3 },
+        { name: "age", components: 1 },
+        { name: "lifetime", components: 1 },
+        { name: "size", components: 1 },
+        { name: "color", components: 4 },
+        { name: "frame", components: 1 },
+    ]);
+
+    // --- SPAWN: seed each particle's state ---
+    const spawn = new NodeGraph();
+    {
+        // position = emitter position + a small disk of jitter on the ground
+        const ep = particle_node(spawn, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
+        const disk = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIT_DISK });
+        const jitter = particle_node(spawn, "scale"); particle_wire(spawn, jitter, "v", disk); particle_wire(spawn, jitter, "s", [0.2]);
+        const p0 = particle_node(spawn, "add"); particle_wire(spawn, p0, "a", ep); particle_wire(spawn, p0, "b", jitter);
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "position" }), "value", p0);
+
+        // velocity = upward buoyancy + signed turbulence
+        const up = particle_node(spawn, "const", { value: [0, 2.0, 0, 0] });
+        const turb = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
+        const turbS = particle_node(spawn, "scale"); particle_wire(spawn, turbS, "v", turb); particle_wire(spawn, turbS, "s", [0.5]);
+        const v0 = particle_node(spawn, "add"); particle_wire(spawn, v0, "a", up); particle_wire(spawn, v0, "b", turbS);
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "velocity" }), "value", v0);
+
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "age" }), "value", [0]);
+        // lifetime 1.2..1.8s
+        const lr = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM });
+        const ls = particle_node(spawn, "mad"); particle_wire(spawn, ls, "a", lr); particle_wire(spawn, ls, "b", [0.6]); particle_wire(spawn, ls, "c", [1.2]);
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "lifetime" }), "value", ls);
+
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "size" }), "value", [0.4]);
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "color" }), "value", [1.0, 0.6, 0.2, 1.0]);
+        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "frame" }), "value", [0]);
+    }
+
+    // --- UPDATE: advance + destroy ---
+    const update = new NodeGraph();
+    {
+        const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
+
+        // age += dt
+        const age = particle_node(update, "attribute", { name: "age" });
+        const newAge = particle_node(update, "add"); particle_wire(update, newAge, "a", age); particle_wire(update, newAge, "b", dt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", newAge);
+
+        // normalizedAge = age / lifetime
+        const lifetime = particle_node(update, "attribute", { name: "lifetime" });
+        const nAge = particle_node(update, "div"); particle_wire(update, nAge, "a", newAge); particle_wire(update, nAge, "b", lifetime);
+
+        // kill when normalizedAge >= 1
+        const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", nAge); particle_wire(update, dead, "b", [1]);
+        particle_wire(update, particle_node(update, "kill"), "condition", dead);
+
+        // buoyant rise + drift: velocity += (0, 1, 0)*dt ; position += velocity*dt
+        const vel = particle_node(update, "attribute", { name: "velocity" });
+        const buoy = particle_node(update, "const", { value: [0, 1.0, 0, 0] });
+        const buoyDt = particle_node(update, "scale"); particle_wire(update, buoyDt, "v", buoy); particle_wire(update, buoyDt, "s", dt);
+        const nVel = particle_node(update, "add"); particle_wire(update, nVel, "a", vel); particle_wire(update, nVel, "b", buoyDt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nVel);
+        const pos = particle_node(update, "attribute", { name: "position" });
+        const velDt = particle_node(update, "scale"); particle_wire(update, velDt, "v", nVel); particle_wire(update, velDt, "s", dt);
+        const nPos = particle_node(update, "add"); particle_wire(update, nPos, "a", pos); particle_wire(update, nPos, "b", velDt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", nPos);
+
+        // size + alpha from curves over life (or constants if no curve provided)
+        if (size_curve !== undefined) {
+            const sc = particle_node(update, "curve", { handle: size_curve }); particle_wire(update, sc, "t", nAge);
+            particle_wire(update, particle_node(update, "setAttribute", { name: "size" }), "value", sc);
+        }
+        const color = particle_node(update, "attribute", { name: "color" });
+        if (alpha_curve !== undefined) {
+            const ac = particle_node(update, "curve", { handle: alpha_curve }); particle_wire(update, ac, "t", nAge);
+            // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
+            // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
+            const alphaVec = particle_node(update, "mul");
+            particle_wire(update, alphaVec, "a", color);
+            particle_wire(update, alphaVec, "b", ac); // broadcasts ac to all lanes (rgb also fades — a warm ember look)
+            particle_wire(update, particle_node(update, "setAttribute", { name: "color" }), "value", alphaVec);
+        }
+
+        // flipbook frame = floor(normalizedAge * frames)
+        const framesN = particle_node(update, "const", { value: [flipbook_frames, 0, 0, 0] });
+        const fscaled = particle_node(update, "mul"); particle_wire(update, fscaled, "a", nAge); particle_wire(update, fscaled, "b", framesN);
+        const fframe = particle_node(update, "floor"); particle_wire(update, fframe, "x", fscaled);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "frame" }), "value", fframe);
+    }
+
+    const effect = create_particle_effect({ layout, spawn, update });
+
+    const emitter = {
+        effect,
+        spawn_rate: 120,
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
+        render: { position: "position", size: "size", color: "color", frame: "frame" },
+        bounds: { center: [0, 1.5, 0], radius: 2.5 },
+        // A 4x4 flipbook packed as the whole atlas here; a real atlas would use a sub-rect.
+        atlas_region: [0, 0, 1, 1],
+        flipbook: [4, 4],
+    };
+
+    return { layout, effect, emitter };
+}
+
+/**
+ * A smoke effect: slow, expanding, alpha-blended, lit, soft-depth billboards. Same authoring
+ * surface as fire; the differences are all data (blend/lighting/soft flags, rates, colours).
+ * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
+ */
+export function smoke_effect() {
+    const { layout, effect } = fire_effect({ flipbook_frames: 8 });
+    const emitter = {
+        effect,
+        spawn_rate: 25,
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true, lighting: true, sort: true },
+        render: { position: "position", size: "size", color: "color", frame: "frame" },
+        bounds: { center: [0, 3, 0], radius: 5 },
+        atlas_region: [0, 0, 1, 1],
+        flipbook: [1, 1],
+    };
+    return { layout, effect, emitter };
+}
+
+/**
+ * Register a fire + smoke plume on a particle system, optionally attaching the fire to a bone.
+ *
+ * The per-frame loop the integrator runs:
+ * ```js
+ * const spawn_requests = system.update(dt, { is_visible });     // CPU: bone transforms + spawn counts
+ * system.uploadFrame(spawn_requests);                           // upload emitters (if dirty) + requests
+ * graph_particles({ graph, gpu: system.gpuHandles(), frame });  // reset -> emit -> simulate -> indirect
+ * // caller appends the depth sort + billboard render into its own graph
+ * ```
+ *
+ * @param {import("./GPUParticleSystem.js").GPUParticleSystem} system
+ * @param {object} [options]
+ * @param {object} [options.bone] a Node3D to attach the fire emitter to
+ * @returns {{fire: number, smoke: number}} emitter indices
+ */
+export function register_campfire(system, { bone } = {}) {
+    const fire = system.addEmitter(fire_effect().emitter);
+    const smoke = system.addEmitter(smoke_effect().emitter);
+    if (bone !== undefined) {
+        system.attachToNode(fire, bone);
+        system.attachToNode(smoke, bone);
+    }
+    system.buildEmitterData();
+    return { fire, smoke };
+}

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),
         };
     }