@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -38,14 +38,6 @@ export const PARTICLE_COUNTER: Readonly<{
      * the end of the frame is the headroom the frame had.
      */
     SPAWN_BUDGET: 2;
-    /**
-     * 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;
     /**
      * 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
@@ -58,19 +50,23 @@ export const PARTICLE_COUNTER: Readonly<{
      * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
      * double-simulates slots).
      */
-    ALIVE_IN: 4;
+    ALIVE_IN: 3;
     /**
      * 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.
+     * produced this frame — longer than {@link ALIVE}, because padding each program's run out to a
+     * whole workgroup adds sentinels. 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;
+    SIM_PADDED: 4;
 }>;
-/** Number of `u32` atomic slots the counters themselves occupy — the head of the buffer. */
+/**
+ * `u32` atomic slots reserved for the counters at the head of the buffer — more than
+ * {@link PARTICLE_COUNTER} names, so a counter can be added without moving the bounds section that
+ * starts right after them.
+ */
 export const PARTICLE_COUNTER_COUNT: 8;
 /**
  * First word of the per-emitter bounds accumulator, which occupies the rest of the counters buffer:

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":"AAqFA;;;;;;GAMG;AACH,+DAHW,MAAM,GACJ,MAAM,CAIlB;AAQD;;;;;;;;;;GAUG;AACH,uDAHW,MAAM,GACJ,WAAW,CAevB;AA9HD;;;;;;;GAOG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,4FAA4F;AAC5F,uCAAwC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,mCAFU,MAAM,CAE2C;AAE3D;;;;;;GAMG;AACH,oCAFU,MAAM,CAEuB;AAavC,0EAA0E;AAC1E,kDAAmD;AAEnD,0EAA0E;AAC1E,mDAAoD"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAiFA;;;;;;GAMG;AACH,+DAHW,MAAM,GACJ,MAAM,CAIlB;AAQD;;;;;;;;;;GAUG;AACH,uDAHW,MAAM,GACJ,WAAW,CAevB;AA1HD;;;;;;;GAOG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH;;;;GAIG;AACH,uCAAwC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,mCAFU,MAAM,CAE2C;AAE3D;;;;;;GAMG;AACH,oCAFU,MAAM,CAEuB;AAavC,0EAA0E;AAC1E,kDAAmD;AAEnD,0EAA0E;AAC1E,mDAAoD"}

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

@@ -18,14 +18,6 @@ export const PARTICLE_COUNTER = Object.freeze({
      * the end of the frame is the headroom the frame had.
      */
     SPAWN_BUDGET: 2,
-    /**
-     * 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,
     /**
      * 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
@@ -38,20 +30,24 @@ export const PARTICLE_COUNTER = Object.freeze({
      * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
      * double-simulates slots).
      */
-    ALIVE_IN: 4,
+    ALIVE_IN: 3,
     /**
      * 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.
+     * produced this frame — longer than {@link ALIVE}, because padding each program's run out to a
+     * whole workgroup adds sentinels. 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,
+    SIM_PADDED: 4,
 });
 
-/** Number of `u32` atomic slots the counters themselves occupy — the head of the buffer. */
+/**
+ * `u32` atomic slots reserved for the counters at the head of the buffer — more than
+ * {@link PARTICLE_COUNTER} names, so a counter can be added without moving the bounds section that
+ * starts right after them.
+ */
 export const PARTICLE_COUNTER_COUNT = 8;
 
 /**

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

@@ -3,16 +3,14 @@
  * @param {object} options
  * @param {boolean} [options.lighting]
  * @param {boolean} [options.soft_depth]
- * @param {boolean} [options.sort]
  * @param {boolean} [options.cull]
  * @param {number} [options.blend] see {@link EMITTER_BLEND}
  * @param {number} [options.projection] see {@link EMITTER_PROJECTION}
  * @returns {number}
  */
-export function make_emitter_flags({ lighting, soft_depth, sort, cull, blend, projection }?: {
+export function make_emitter_flags({ lighting, soft_depth, cull, blend, projection }?: {
     lighting?: boolean;
     soft_depth?: boolean;
-    sort?: boolean;
     cull?: boolean;
     blend?: number;
     projection?: number;
@@ -24,7 +22,7 @@ export function emitter_flags_projection(flags: number): number;
 /**
  * One emitter's GPU record: which compiled program it runs and where that program's code and
  * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
- * tick / emit / simulate / sort / render passes read — the scene node it hangs off, spawn rate,
+ * tick / emit / simulate / render passes read — the scene node it hangs off, spawn rate,
  * feature flags, render-attribute bindings, atlas region and flipbook grid.
  *
  * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
@@ -53,11 +51,14 @@ export const PARTICLE_EMITTER_STRUCT: WebGPUStruct;
 export const EMITTER_ATTRIBUTE_ABSENT: 4294967295;
 /**
  * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
+ *
+ * Bit 2 is unassigned and stays that way. The whole word is written to saved data verbatim by
+ * {@link ../../../../engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.js}, so a bit
+ * a retired feature gave back cannot be handed to a new one without changing what old data means.
  */
 export const EMITTER_FLAG: Readonly<{
     LIGHTING: number;
     SOFT_DEPTH: number;
-    SORT: number;
     CULL: number;
 }>;
 /** Blend modes (stored in flag bits [4,6)). All expressed by one premultiplied blend pipeline. */

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAgIA;;;;;;;;;;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;AA3JD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CA+DO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG;6BAlK0B,mCAAmC"}
+{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAmIA;;;;;;;;;GASG;AACH;IAP6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAUlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AA5JD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CA+DO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;;;;;GAMG;AACH;;;;GAIG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAmCH,uEAAuE;AACvE;;;;;GAEG;6BAnK0B,mCAAmC"}

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

@@ -4,7 +4,7 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 /**
  * One emitter's GPU record: which compiled program it runs and where that program's code and
  * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
- * tick / emit / simulate / sort / render passes read — the scene node it hangs off, spawn rate,
+ * tick / emit / simulate / render passes read — the scene node it hangs off, spawn rate,
  * feature flags, render-attribute bindings, atlas region and flipbook grid.
  *
  * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
@@ -96,11 +96,14 @@ export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
 
 /**
  * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
+ *
+ * Bit 2 is unassigned and stays that way. The whole word is written to saved data verbatim by
+ * {@link ../../../../engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.js}, so a bit
+ * a retired feature gave back cannot be handed to a new one without changing what old data means.
  */
 export const EMITTER_FLAG = Object.freeze({
     LIGHTING: 1 << 0,      // forward-shade billboards with scene lighting
     SOFT_DEPTH: 1 << 1,    // fade against scene depth
-    SORT: 1 << 2,          // depth-sort this emitter's particles for correct transparency
     CULL: 1 << 3,          // frustum + occlusion simulation culling (sleep when culled)
 });
 
@@ -131,17 +134,15 @@ const PROJECTION_MASK = 0b111 << PROJECTION_SHIFT;
  * @param {object} options
  * @param {boolean} [options.lighting]
  * @param {boolean} [options.soft_depth]
- * @param {boolean} [options.sort]
  * @param {boolean} [options.cull]
  * @param {number} [options.blend] see {@link EMITTER_BLEND}
  * @param {number} [options.projection] see {@link EMITTER_PROJECTION}
  * @returns {number}
  */
-export function make_emitter_flags({ lighting = false, soft_depth = false, sort = false, cull = false, blend = EMITTER_BLEND.ALPHA, projection = EMITTER_PROJECTION.BILLBOARD } = {}) {
+export function make_emitter_flags({ lighting = false, soft_depth = false, cull = false, blend = EMITTER_BLEND.ALPHA, projection = EMITTER_PROJECTION.BILLBOARD } = {}) {
     let flags = 0;
     if (lighting) flags |= EMITTER_FLAG.LIGHTING;
     if (soft_depth) flags |= EMITTER_FLAG.SOFT_DEPTH;
-    if (sort) flags |= EMITTER_FLAG.SORT;
     if (cull) flags |= EMITTER_FLAG.CULL;
     flags |= (blend << BLEND_SHIFT) & BLEND_MASK;
     flags |= (projection << PROJECTION_SHIFT) & PROJECTION_MASK;

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

@@ -9,11 +9,9 @@
  *   -> bucket -> bounds -> build indirect
  *
  * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
- * whoever draws. Nothing here depends on how they will be drawn, which is why the render mode
- * ({@link ParticleRenderMode}) selects only what `execute` records AFTER this: the depth sort and
- * the billboard draw (`sort/graph_particle_sort.js`, `graph_particles_billboard.js`), or nothing at
- * all, because the AVBOIT orchestrator will draw them later off these same handles
- * (`graph_particles_avboit.js`).
+ * the draw. That draw is not here and is not recorded by `execute` either: the AVBOIT transparency
+ * orchestrator makes it later in the frame, off these same handles, through the side channels in
+ * `graph_particles_avboit.js`.
  *
  * ## Spawning is decided here, on the GPU
  *
@@ -33,26 +31,25 @@
  * into emit and simulate would union this frame's newborns with last frame's survivors, and would
  * pay six atomics per particle inside the pass whose register pressure sets the system's occupancy.
  *
- * ## Two orderings, kept apart
+ * ## Two lists, 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.
+ * regrouped so each wave runs one VM program, with every run padded out to a whole workgroup. Its
+ * arrangement changes only when emitters or their programs do.
  *
- * 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 standalone billboard draw is the only
- * thing that consumes it, so it is built only in that mode. 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 alive list is the other one, and it is the draw's: compacted, unpadded, one entry per live
+ * particle. Drawing the padded coherence list instead would draw its sentinels. Neither list is
+ * ordered by view depth and neither needs to be — the AVBOIT volume and its accumulators are sums,
+ * so no arrangement of the draw changes a pixel.
  *
  * ## Nothing is sized from the CPU
  *
  * Simulate's workgroup count comes from `dispatch_args` (written by LAST frame's build-indirect
  * pass) via `dispatchWorkgroupsIndirect`, and its element bound from the `ALIVE_IN` counter
- * snapshot; the draw, and the sort's two per-particle passes when there is a sort, are sized the
- * same way, from this frame's alive count. A CPU count is inevitably stale and corrupts the pool
- * (orphaned slots when the population grows, double-freed slots when it shrinks).
+ * snapshot; the draw is sized the same way, from this frame's alive count. A CPU count is inevitably
+ * stale and corrupts the pool (orphaned slots when the population grows, double-freed slots when it
+ * shrinks).
  *
  * 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
@@ -67,8 +64,8 @@
  * produced and consumed inside one graph, so the pass that first writes it declares it with a
  * {@link BufferResourceDescriptor} in place of a handle and the graph allocates it just in time and
  * releases it after its last reader — into the pool every other feature draws from. That is the
- * spawn counts and the emit command, the VM's wide register file, the draw args, the bucketing
- * scratch (`coherence/`) and the whole depth sort (`sort/`).
+ * spawn counts and the emit command, the VM's wide register file, the draw args and the bucketing
+ * scratch (`coherence/`).
  *
  * On the very first frame `dispatch_args` must be zero-initialised (WebGPU zero-fills new buffers)
  * and the `ALIVE_IN` counter 0, so simulate is a no-op until the first build-indirect has run.
@@ -76,10 +73,8 @@
 /**
  * @typedef {object} ParticleSimulationHandles
  * @property {number} pool the particle pool, after this frame's INIT and UPDATE
- * @property {number} alive this frame's compacted alive list — the render order's input
- * @property {number} counters the atomic counters, after build-indirect
- * @property {number} draw_args the billboard draw's indirect args: six vertices, one instance per live particle
- * @property {number} sim_dispatch_args one workgroup per live particle, for a per-particle pass
+ * @property {number} alive this frame's compacted alive list — what the draw walks
+ * @property {number} draw_args the draw's indirect args: six vertices, one instance per live particle
  * @property {number} emitter_database the emitter database, after the bounds pass published the
  *   measured box into each emitter's state row
  */
@@ -146,21 +141,13 @@ export type ParticleSimulationHandles = {
      */
     pool: number;
     /**
-     * this frame's compacted alive list — the render order's input
+     * this frame's compacted alive list — what the draw walks
      */
     alive: number;
     /**
-     * the atomic counters, after build-indirect
-     */
-    counters: number;
-    /**
-     * the billboard draw's indirect args: six vertices, one instance per live particle
+     * the draw's indirect args: six vertices, one instance per live particle
      */
     draw_args: number;
-    /**
-     * one workgroup per live particle, for a per-particle pass
-     */
-    sim_dispatch_args: number;
     /**
      * the emitter database, after the bounds pass published the
      * measured box into each emitter's state row

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":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA7BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACS,GAAG,EAAlB,MAAM;IACS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACiB,QAAQ,GAA/B,OAAO;QACc,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;QACe,YAAY,EAAjC,MAAM;QAGe,eAAe,EAApC,MAAM;QAC6D,eAAe,EAAlF,OAAO,6BAA6B,EAAE,cAAc;;IAElD,yBAAyB,CA8TrC;;;;;UAtWa,MAAM;;;;WACN,MAAM;;;;cACN,MAAM;;;;eACN,MAAM;;;;uBACN,MAAM;;;;;sBACN,MAAM"}
+{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA7BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACS,GAAG,EAAlB,MAAM;IACS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACiB,QAAQ,GAA/B,OAAO;QACc,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;QACe,YAAY,EAAjC,MAAM;QAGe,eAAe,EAApC,MAAM;QAC6D,eAAe,EAAlF,OAAO,6BAA6B,EAAE,cAAc;;IAElD,yBAAyB,CA4TrC;;;;;UAlWa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;;sBACN,MAAM"}

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

@@ -48,11 +48,9 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  *   -> bucket -> bounds -> build indirect
  *
  * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
- * whoever draws. Nothing here depends on how they will be drawn, which is why the render mode
- * ({@link ParticleRenderMode}) selects only what `execute` records AFTER this: the depth sort and
- * the billboard draw (`sort/graph_particle_sort.js`, `graph_particles_billboard.js`), or nothing at
- * all, because the AVBOIT orchestrator will draw them later off these same handles
- * (`graph_particles_avboit.js`).
+ * the draw. That draw is not here and is not recorded by `execute` either: the AVBOIT transparency
+ * orchestrator makes it later in the frame, off these same handles, through the side channels in
+ * `graph_particles_avboit.js`.
  *
  * ## Spawning is decided here, on the GPU
  *
@@ -72,26 +70,25 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  * into emit and simulate would union this frame's newborns with last frame's survivors, and would
  * pay six atomics per particle inside the pass whose register pressure sets the system's occupancy.
  *
- * ## Two orderings, kept apart
+ * ## Two lists, 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.
+ * regrouped so each wave runs one VM program, with every run padded out to a whole workgroup. Its
+ * arrangement changes only when emitters or their programs do.
  *
- * 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 standalone billboard draw is the only
- * thing that consumes it, so it is built only in that mode. 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 alive list is the other one, and it is the draw's: compacted, unpadded, one entry per live
+ * particle. Drawing the padded coherence list instead would draw its sentinels. Neither list is
+ * ordered by view depth and neither needs to be — the AVBOIT volume and its accumulators are sums,
+ * so no arrangement of the draw changes a pixel.
  *
  * ## Nothing is sized from the CPU
  *
  * Simulate's workgroup count comes from `dispatch_args` (written by LAST frame's build-indirect
  * pass) via `dispatchWorkgroupsIndirect`, and its element bound from the `ALIVE_IN` counter
- * snapshot; the draw, and the sort's two per-particle passes when there is a sort, are sized the
- * same way, from this frame's alive count. A CPU count is inevitably stale and corrupts the pool
- * (orphaned slots when the population grows, double-freed slots when it shrinks).
+ * snapshot; the draw is sized the same way, from this frame's alive count. A CPU count is inevitably
+ * stale and corrupts the pool (orphaned slots when the population grows, double-freed slots when it
+ * shrinks).
  *
  * 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
@@ -106,8 +103,8 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  * produced and consumed inside one graph, so the pass that first writes it declares it with a
  * {@link BufferResourceDescriptor} in place of a handle and the graph allocates it just in time and
  * releases it after its last reader — into the pool every other feature draws from. That is the
- * spawn counts and the emit command, the VM's wide register file, the draw args, the bucketing
- * scratch (`coherence/`) and the whole depth sort (`sort/`).
+ * spawn counts and the emit command, the VM's wide register file, the draw args and the bucketing
+ * scratch (`coherence/`).
  *
  * On the very first frame `dispatch_args` must be zero-initialised (WebGPU zero-fills new buffers)
  * and the `ALIVE_IN` counter 0, so simulate is a no-op until the first build-indirect has run.
@@ -116,10 +113,8 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
 /**
  * @typedef {object} ParticleSimulationHandles
  * @property {number} pool the particle pool, after this frame's INIT and UPDATE
- * @property {number} alive this frame's compacted alive list — the render order's input
- * @property {number} counters the atomic counters, after build-indirect
- * @property {number} draw_args the billboard draw's indirect args: six vertices, one instance per live particle
- * @property {number} sim_dispatch_args one workgroup per live particle, for a per-particle pass
+ * @property {number} alive this frame's compacted alive list — what the draw walks
+ * @property {number} draw_args the draw's indirect args: six vertices, one instance per live particle
  * @property {number} emitter_database the emitter database, after the bounds pass published the
  *   measured box into each emitter's state row
  */
@@ -222,7 +217,7 @@ export function graph_particles_simulate({
         gr_draw = indirect.draw_args;
     }
 
-    // 1. Reset the alive/sorted/sim-padded counters (dead count + ALIVE_IN snapshot persist) and
+    // 1. Reset the alive/sim-padded counters (dead count + ALIVE_IN snapshot persist) and
     //    seed the frame's spawn budget from the free count.
     counters = graph_compute_pass({
         graph,
@@ -468,9 +463,7 @@ export function graph_particles_simulate({
     return {
         pool,
         alive: alive_write,
-        counters: indirect.counters,
         draw_args: indirect.draw_args,
-        sim_dispatch_args: bucketed.dispatch_args,
         emitter_database,
     };
 }

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

@@ -6,9 +6,9 @@ import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../rasterize/native/avboit/sha
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { shader_particle_avboit_occupancy } from "./shaders/shader_particle_avboit_occupancy.js";
 import {
-    PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
-    PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE,
-    PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE,
+    PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE,
     PARTICLE_AVBOIT_DRAW_RESOURCES,
 } from "./shaders/shader_particle_avboit_draw.js";
 import {
@@ -26,9 +26,9 @@ import {
  * GPU-driven: the draws are `drawIndirect` over the GPU's own alive count, and the occupancy walks
  * the emitter table's pages. Nothing here knows how many particles there are.
  *
- * Order does not matter to any of them — the volume and the accumulators are order-independent — so
- * the depth sort the standalone billboard draw needs is not run for this path, and its buffers are
- * never made. That is what {@link ParticleRenderMode.AVBOIT} means.
+ * Order does not matter to any of them: the volume and the accumulators are sums, so no arrangement
+ * of the draw changes a pixel. That is why the particles are never depth-sorted — the alive list
+ * comes off the simulation compacted, and it is drawn as it stands.
  */
 
 /** The accumulators' view: one mip, the one the frame draws into. */
@@ -270,7 +270,7 @@ export function graph_particle_avboit_draw({
         // allowed because the attachment is read-only.
         const pass_encoder = encoder.constructRenderPass({
             label: "Particle AVBOIT Draw",
-            pipeline: PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
+            pipeline: PARTICLE_AVBOIT_DRAW_ALPHA_PIPELINE,
             bindings,
             colorAttachments: [
                 attachment(data.color),
@@ -283,15 +283,15 @@ export function graph_particle_avboit_draw({
                 depthReadOnly: true,
             },
         });
-        // All three use the alive list; their vertex stages select disjoint particle groups.
-        // Premultiplied particles can both cover and emit, so they retain the general pipeline.
-        const args = resources.get(data.draw_args);
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE));
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE));
-        pass_encoder.drawIndirect(args, 0);
-        pass_encoder.end();
+        // All three use the alive list; their vertex stages select disjoint particle groups.
+        // Premultiplied particles can both cover and emit, so they retain the general pipeline.
+        const args = resources.get(data.draw_args);
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_ADDITIVE_PIPELINE));
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.setPipeline(graphics.render_pipelines.obtain(PARTICLE_AVBOIT_DRAW_GENERAL_PIPELINE));
+        pass_encoder.drawIndirect(args, 0);
+        pass_encoder.end();
     }
 
     const pass_data = {};

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

@@ -75,13 +75,13 @@ export class EmitterRegistry {
      * The emitter table.
      * @returns {GPUTypedTable}
      */
-    get table(): GPUTypedTable;
+    get table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
     /**
      * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
      * here and otherwise the GPU's.
      * @returns {GPUTypedTable}
      */
-    get state_table(): GPUTypedTable;
+    get state_table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
     /**
      * @returns {number} number of live emitters
      */
@@ -214,6 +214,7 @@ export class EmitterRegistry {
     build_program(): Uint32Array;
     #private;
 }
+export type GPUTypedTable = import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
 import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
 import { ProgramHeap } from "./ProgramHeap.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";

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":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;4BAzc2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BA7c2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}

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

@@ -13,6 +13,10 @@ import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
 import { ProgramHeap } from "./ProgramHeap.js";
 
+/**
+ * @typedef {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
+ */
+
 /**
  * Staging for one emitter row. Reused across every write — the table serializes it into its page
  * shadow synchronously, so nothing outlives the call. This is what keeps a frame's flush free of
@@ -61,13 +65,13 @@ export class EmitterRegistry {
      * Packed instruction + constant buffers for every distinct program in the set.
      * @type {ProgramHeap}
      */
-    programs = new ProgramHeap();
-
-    /**
-     * Changes when a live emitter moves to different bytecode; invalidates simulation grouping.
-     * @type {number}
-     */
-    program_assignment_version = 0;
+    programs = new ProgramHeap();
+
+    /**
+     * Changes when a live emitter moves to different bytecode; invalidates simulation grouping.
+     * @type {number}
+     */
+    program_assignment_version = 0;
 
     /**
      * The live emitters, in no particular order — the row in {@link context} is the identity.
@@ -226,8 +230,8 @@ export class EmitterRegistry {
 
         const context = new GPUParticleEmitterContext();
 
-        context.placement = this.programs.acquire(emitter.program);
-        context.program = emitter.program;
+        context.placement = this.programs.acquire(emitter.program);
+        context.program = emitter.program;
 
         context.generation = this.#generation;
         this.#generation = particle_generation_next(this.#generation);
@@ -287,8 +291,8 @@ export class EmitterRegistry {
 
         this.programs.release(context.placement);
 
-        context.placement = null;
-        context.program = null;
+        context.placement = null;
+        context.program = null;
 
         this.#contexts.delete(emitter);
     }
@@ -323,12 +327,12 @@ export class EmitterRegistry {
         // unpacks it nor gives it a new id
         context.placement = this.programs.acquire(program);
 
-        emitter.program = program;
-        context.program = program;
-
-        if (context.placement !== previous) {
-            this.program_assignment_version++;
-        }
+        emitter.program = program;
+        context.program = program;
+
+        if (context.placement !== previous) {
+            this.program_assignment_version++;
+        }
 
         this.programs.release(previous);
 
@@ -411,16 +415,16 @@ export class EmitterRegistry {
      * Stages through the one module-static record, so a frame's restaging allocates nothing however
      * many rows it touches.
      */
-    flush() {
-        const table = this.table;
-
-        // Reconcile plain-field edits before checking relocation: an acquire can repack the heap
-        // and move placements of rows we would otherwise have already staged.
-        for (const [emitter, context] of this.#contexts) {
-            if (emitter.program !== context.program) {
-                this.set_program(emitter, emitter.program);
-            }
-        }
+    flush() {
+        const table = this.table;
+
+        // Reconcile plain-field edits before checking relocation: an acquire can repack the heap
+        // and move placements of rows we would otherwise have already staged.
+        for (const [emitter, context] of this.#contexts) {
+            if (emitter.program !== context.program) {
+                this.set_program(emitter, emitter.program);
+            }
+        }
 
         const placement_version = this.programs.placement_version;
 

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

@@ -198,11 +198,11 @@ export class ParticleEmitter extends Node3D {
      * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
      * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
-     * being at the origin.
+     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * particle as being at the origin.
      *
-     * The record stores word offsets rather than names because that is what the render and sort
-     * passes index a particle record with; resolving here is the only place a name is involved.
+     * The record stores word offsets rather than names because that is what those passes index a
+     * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
      *        attribute name in the effect's layout

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

@@ -192,11 +192,11 @@ export class ParticleEmitter extends Node3D {
      * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
      * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
-     * being at the origin.
+     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * particle as being at the origin.
      *
-     * The record stores word offsets rather than names because that is what the render and sort
-     * passes index a particle record with; resolving here is the only place a name is involved.
+     * The record stores word offsets rather than names because that is what those passes index a
+     * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
      *        attribute name in the effect's layout