@woosh/meep-engine 3.21.0 → 3.22.0

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

@@ -115,14 +115,6 @@ export const PARTICLE_PROGRAM_HEADER_WORDS: number;
  * @type {number}
  */
 export const PARTICLE_PROGRAM_CODE_BASE_WORD: number;
-/**
- * Bins the render-order depth sort quantises view depth into. More bins is a finer back-to-front
- * order at the cost of a longer histogram; particles that land in one bin draw in an order the
- * scatter's atomics decide.
- *
- * @type {number}
- */
-export const PARTICLE_SORT_BUCKET_COUNT: number;
 /**
  * First word index available for user-defined attributes.
  * @type {number}
@@ -258,10 +250,12 @@ export const PARTICLE_SIM_PAD_SLOT: number;
  * View-space distance, in world units, over which a soft-depth particle fades out as it approaches
  * the opaque surface behind it.
  *
- * Read by the two passes that have to agree on a fragment's coverage: the AVBOIT draw, which weights
- * the accumulators by it, and the AVBOIT splat, which records the extinction the volume then hands
- * to everything behind. A fade in one and not the other is a surface that is invisible and still
- * occludes.
+ * Above all it is what the two passes that have to agree on a fragment's coverage agree on: the
+ * AVBOIT draw, which weights the accumulators by it, and the AVBOIT splat, which records the
+ * extinction the volume then hands to everything behind. A fade in one and not the other is a
+ * surface that is invisible and still occludes. The blended billboard pipeline
+ * (`shaders/shader_particle_render.js`) reads it too, so a particle fades over the same distance
+ * whichever pipeline draws it.
  *
  * @type {number}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;GAMG;AACH,yCAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;GAYG;AACH,uCAFU,MAAM,CAE4B"}

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

@@ -129,15 +129,6 @@ export const PARTICLE_PROGRAM_HEADER_WORDS = 4;
  */
 export const PARTICLE_PROGRAM_CODE_BASE_WORD = 0;
 
-/**
- * Bins the render-order depth sort quantises view depth into. More bins is a finer back-to-front
- * order at the cost of a longer histogram; particles that land in one bin draw in an order the
- * scatter's atomics decide.
- *
- * @type {number}
- */
-export const PARTICLE_SORT_BUCKET_COUNT = 1024;
-
 /**
  * First word index available for user-defined attributes.
  * @type {number}
@@ -286,10 +277,12 @@ export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;
  * View-space distance, in world units, over which a soft-depth particle fades out as it approaches
  * the opaque surface behind it.
  *
- * Read by the two passes that have to agree on a fragment's coverage: the AVBOIT draw, which weights
- * the accumulators by it, and the AVBOIT splat, which records the extinction the volume then hands
- * to everything behind. A fade in one and not the other is a surface that is invisible and still
- * occludes.
+ * Above all it is what the two passes that have to agree on a fragment's coverage agree on: the
+ * AVBOIT draw, which weights the accumulators by it, and the AVBOIT splat, which records the
+ * extinction the volume then hands to everything behind. A fade in one and not the other is a
+ * surface that is invisible and still occludes. The blended billboard pipeline
+ * (`shaders/shader_particle_render.js`) reads it too, so a particle fades over the same distance
+ * whichever pipeline draws it.
  *
  * @type {number}
  */

package/src/shade/renderer/particles/coherence/graph_particle_bucket.d.ts

@@ -10,10 +10,10 @@
  * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
  *
  * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
- * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
- * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
- * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
- * a second place to get that wrong.
+ * engine's radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan
+ * in this codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so
+ * the pass makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here
+ * would be a second place to get that wrong.
  *
  * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
  * that is static topology — it changes when the emitter set does, never as particles are born and

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

@@ -31,10 +31,10 @@ const WORD = Uint32Array.BYTES_PER_ELEMENT;
  * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
  *
  * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
- * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
- * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
- * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
- * a second place to get that wrong.
+ * engine's radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan
+ * in this codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so
+ * the pass makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here
+ * would be a second place to get that wrong.
  *
  * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
  * that is static topology — it changes when the emitter set does, never as particles are born and
@@ -93,7 +93,7 @@ export function graph_particle_bucket({ graph, emitter_database, pool, alive, co
     let cursor = scratch?.cursor ?? BufferResourceDescriptor.from(bucket_count * WORD, GPUBufferUsage.STORAGE);
     let bucket_counts = scratch?.bucket_counts ?? BufferResourceDescriptor.from(bucket_count * WORD, GPUBufferUsage.STORAGE);
     // Indirect args this pass writes and the two per-particle passes below consume, along with the
-    // depth sort's and the bounds pass's — hence INDIRECT on top of STORAGE.
+    // bounds pass — hence INDIRECT on top of STORAGE.
     let dispatch_args = scratch?.dispatch_args ?? BufferResourceDescriptor.from(
         3 * WORD,
         GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
@@ -175,7 +175,7 @@ export function graph_particle_bucket({ graph, emitter_database, pool, alive, co
     }
 
     // `dispatch_args` goes back too: it holds one workgroup per live particle, written from the
-    // GPU's own alive count, which is exactly the shape the depth sort's per-particle passes need.
+    // GPU's own alive count, which is the shape every per-particle pass after this one needs.
     return { counters, sim_list, dispatch_args, scratch: { keys, histogram: scanned, cursor, bucket_counts, dispatch_args } };
 }
 

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts

@@ -18,7 +18,8 @@ export function particle_bucket_round_up(value: number): number;
 /**
  * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
  * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
- * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the engine's radix sort runs its spine
+ * through).
  *
  * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
  * consume a workgroup nor shift the offsets of the buckets after them.

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA5Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}
+{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAqCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA7Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}

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

@@ -2,8 +2,7 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../Part
 
 /**
  * CPU reference for the simulation-order bucketing — the readable statement of the answer the GPU
- * passes in {@link ./shader_particle_bucket.js} have to produce, the same role
- * {@link ../sort/particle_counting_sort.js} plays for the render-order depth sort.
+ * passes in {@link ./shader_particle_bucket.js} have to produce.
  *
  * ## What it is for
  *
@@ -22,11 +21,9 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../Part
  *
  * ## What it is NOT
  *
- * This is the *simulation* order: camera-independent, changing only when emitters and their
- * programs change. It is a different ordering from the *render* order in `../sort/`, which is
- * back-to-front by view depth and exists so premultiplied transparency composites correctly. The
- * two must stay in separate buffers and separate passes — reordering the render list for coherence
- * breaks transparency, and depth-sorting the simulation list destroys the coherence.
+ * This is the *simulation* list, and nothing else reads it. The draws walk the alive list, which is
+ * compacted and unpadded; this one is permuted and padded with sentinels, and drawing it would draw
+ * them. The two stay in separate buffers, with separate counter slots, for that reason.
  *
  * ## Indirection only
  *
@@ -62,7 +59,8 @@ export function particle_bucket_round_up(value) {
 /**
  * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
  * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
- * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the engine's radix sort runs its spine
+ * through).
  *
  * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
  * consume a workgroup nor shift the offsets of the buckets after them.

package/src/shade/renderer/particles/coherence/shader_particle_bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AA+GA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAuBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BA1V2B,+BAA+B"}
+{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AAgHA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAuBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BA3V2B,+BAA+B"}

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

@@ -35,7 +35,7 @@ import { chunk_particle_header } from "../data/particle_header.js";
  *
  * ## Shape
  *
- * The same three-phase shape the depth sort uses, with two small passes added for the padding:
+ * A counting sort in three phases, with two small passes added for the padding:
  *
  *   reset -> histogram -> pad -> graph_prefix_scan_csdldf -> scatter -> fill
  *
@@ -62,8 +62,9 @@ import { chunk_particle_header } from "../data/particle_header.js";
  * - **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.
+ * - **This is not the draw list.** The draws walk the compacted, unpadded alive list; this one is
+ *   permuted and padded with sentinels, and an instance per sentinel would read a garbage record.
+ *   Separate buffers, separate passes, separate counter slots.
  *
  * @see ./particle_program_buckets.js for the CPU statement of the same answer.
  */

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