@woosh/meep-engine 3.20.0 → 3.22.0

package/src/shade/renderer/particles/DESIGN.md

@@ -10,7 +10,8 @@ the decision to spawn is the GPU's.
 
 - Single simulation execution shader (data-driven VM, not one-pipeline-per-effect).
 - Projection modes: camera-facing billboard (+ velocity-stretched, axis-locked, world-oriented).
-- Depth sorting for correct transparency, built on the `csdldf` prefix scan.
+- Order-independent transparency: the particles are a side channel of the AVBOIT pipeline, so they
+  composite against the transparent meshes with no depth ordering of any kind.
 - Node-based composition → shader VM (compile graph → bytecode).
 - Frustum culling of spawning (optional, flagged, sleep-when-culled + bounded catch-up).
 - Flipbooks (atlas sub-rect + frame grid).
@@ -20,9 +21,9 @@ the decision to spawn is the GPU's.
 - Scene-node / bone attachment: an emitter **is** a `Node3D`; its world matrix is its row of the
   scene's `transforms` table, composed by the GPU hierarchy pass.
 - Distinct per-particle lifecycle: **no** built-in age/position — the schema + program define state.
-- Billboard renderer reuses engine shader chunks incl. lighting (forward-shaded, optional per emitter).
+- Billboard drawing reuses engine shader chunks incl. lighting (forward-shaded, optional per emitter).
 - Blend modes (alpha + additive) via a **single** premultiplied blend setup.
-- Authored curves and RGB/RGBA gradients compiled into arithmetic for simulation.
+- Authored curves and RGB/RGBA gradients compiled into arithmetic for simulation.
 - Spawning decided on the GPU, per emitter, with the CPU able to ask for bursts through the same path.
 - No per-frame allocation on the CPU beyond the frame graph's own records.
 
@@ -45,9 +46,12 @@ runtime GPU: particle pool (array<u32>, uniform stride) + alive/dead lists + cou
              ├─ simulate (VM UPDATE program) ── update → (kill|orphan→dead | keep→alive_new)
              ├─ bucket (histogram → csdldf scan → scatter)  ── alive → program-coherent sim list
              ├─ bounds (per particle → per emitter box, published to the state row)
-             ├─ build indirect (dispatch + draw args)
-             ├─ sort  (histogram → csdldf scan → scatter)    [render order]
-             └─ render (instanced billboard quads, forward + optional lighting + soft depth)
+             └─ build indirect (dispatch + draw args)
+
+             the AVBOIT transparency pipeline then draws the alive list through the side channel:
+             ├─ occupancy (per emitter box → depth slices)
+             ├─ splat     (extinction into the voxel volume)
+             └─ draw      (instanced billboard quads → the four accumulators)
 ```
 
 ### Particle storage — single shared pool, uniform stride
@@ -69,11 +73,11 @@ bucketing pass built from `alive_current` → run UPDATE → kill pushes to `dea
 
 **The loop is strictly GPU-driven.** The build-indirect pass snapshots the padded length of the
 coherence list into `counters[ALIVE_IN]` and writes the indirect dispatch args next frame's simulate
-consumes (`dispatchWorkgroupsIndirect`) plus the indirect draw args this frame's render consumes
+consumes (`dispatchWorkgroupsIndirect`) plus the indirect draw args this frame's draws consume
 (`drawIndirect`, sized by the *unpadded* alive count); simulate bound-checks against the ALIVE_IN
-snapshot. The sort's per-particle passes take the dispatch the bucket reset writes from the alive
-count. Sizing any of this from a CPU readback is a correctness bug, not a shortcut: the readback is
-inevitably stale, so a growing population orphans the tail of the alive list (slots leak into limbo)
+snapshot. The bounds pass takes the dispatch the bucket reset writes from the alive count. Sizing
+any of this from a CPU readback is a correctness bug, not a shortcut: the readback is inevitably
+stale, so a growing population orphans the tail of the alive list (slots leak into limbo)
 and a shrinking one re-simulates stale entries — double-freeing slots so two live particles later
 share one record. The emit pass's dead-list pop guards against wrapped counters
 (`old == 0 || old > capacity`), so racing an exhausted pool drops spawns cleanly instead of handing
@@ -159,7 +163,7 @@ recursion, no data-dependent jumps — conditionals are predicated via CMP/SELEC
   Word 0 packs the opcode (bits 0..7), the lane count (8..10), each source's `VM_KIND` (two bits per
   slot at 16..21) and the destination slot (24..31). A source word means what its kind says: `REG`
   is a base slot plus a swizzle, `IMM` is an `f32` bit pattern read in every lane, and `NONE` is a
-  raw field the opcode reads for itself (attribute word-offset+comp / builtin id /
+  raw field the opcode reads for itself (attribute word-offset+comp / builtin id /
   pool index).
 - Constant pool: `array<vec4f>` per program, referenced by `LOAD_CONST`.
 - Two entry sections per program: **INIT** and **UPDATE** (offsets in the emitter record). INIT
@@ -210,13 +214,13 @@ A core `NodeGraph` holds particle nodes (ports + parameters) for INIT and UPDATE
 2. lowers each node to VM ops (nodes emit via a small builder that allocates result registers),
 3. linear-scan register allocation with liveness,
 4. interns constants into the pool,
-5. resolves attribute references,
-6. emits `Program { init, update, constants, reg_count, attributes }`.
+5. resolves attribute references,
+6. emits `Program { init, update, constants, reg_count, attributes }`.
 
 Standard node library: constants, attribute get/set, arithmetic/vector/math, random (uniform/sphere/
-disk/cone), authored curves and RGB/RGBA gradients, noise (curl), integrate, gravity, emit-shapes,
-compare/select, kill-if. Curves and gradients expand into graph nodes that emit ordinary VM
-arithmetic; no animation-table binding or sampling opcode is needed.
+disk/cone), authored curves and RGB/RGBA gradients, noise (curl), integrate, gravity, emit-shapes,
+compare/select, kill-if. Curves and gradients expand into graph nodes that emit ordinary VM
+arithmetic; no animation-table binding or sampling opcode is needed.
 
 ### Emitters are scene nodes
 
@@ -251,7 +255,7 @@ was staged from. An author who edits an emitter says so the way they say it for
 
 One `emitters` table (CPU-managed, low churn). Row = `PARTICLE_EMITTER_STRUCT`: program
 offsets+lengths, constant-pool offset, seed, spawn rate, **node** (transforms row), **generation**,
-flags (lighting/soft/sort/cull/blend/projection), render binding (attr offsets for
+flags (lighting/soft/cull/blend/projection), render binding (attr offsets for
 position/size/color/rotation/frame/velocity), atlas region + flipbook grid, and the program id
 the coherence pass buckets on. The atlas region is resolved, not authored: the emitter names an
 image and the system packs it, the way `ShaderManager` packs the old engine's sprites, so a repack
@@ -311,11 +315,15 @@ or simulation, the previous compact alive list is bucketed again and its padded
 are rebuilt. This prevents a previously shared wave from executing one emitter's newly edited program
 over another emitter's particles. Ordinary frames keep the existing end-of-frame bucketing only;
 content-identical replacements need no repair. Both bucket runs on an edit frame reuse the latest
-graph handles for their scratch buffers, so each persistent buffer is imported once.
+graph handles for their scratch, so it is created once and both runs share one dependency chain.
 
-The coherence list is persistent GPU state, including its padding. Growing the bucket capacity copies
-it to the replacement buffer before destroying the old one. The old count and indirect dispatch
-remain valid across growth; only the per-frame histogram/cursor/key scratch may be discarded.
+The coherence list is persistent GPU state, including its padding — the one thing the bucketing
+leaves behind. Growing the bucket capacity copies it to the replacement buffer before destroying the
+old one; the old count and indirect dispatch remain valid across growth. The histogram, cursors, keys
+and dispatch args beside it live and die inside one frame graph, so the passes that write them
+declare them (a `BufferResourceDescriptor` in place of a handle) and the graph allocates and releases
+them around their users. None asks for a clear: the reset pass already covers every word it will
+read, and `keys` is written by the same indirect dispatch that reads it.
 
 Every row of a frame is staged through one module-static record (`EmitterRegistry`), so a flush
 allocates nothing however many rows it restages.
@@ -480,42 +488,47 @@ programs again. Padding entries carry `PARTICLE_SIM_PAD_SLOT` and the simulate s
 It is an **indirection** list. Particle records never move: slots are referenced by the dead list and
 across frames, so relocating a record would leave both pointing at the wrong particle.
 
-The three-phase shape is the depth sort's, with the padding added: histogram (atomic per bucket) →
+It is a counting sort in three phases, with the padding added: histogram (atomic per bucket) →
 round each bin up to a whole workgroup → `graph_prefix_scan_csdldf` (reused as-is — the one scan here
 whose only cross-workgroup wait is CSDLDF's bounded spin-then-fallback) → scatter → fill the tails
 with the sentinel. Nothing reads back to the CPU; the only host-supplied number is the bucket count,
 which is static topology.
 
-**Render order** (`sort/`) — per-frame, particles sorted back-to-front by view depth so
-premultiplied transparency composites correctly. Counting sort on a quantised view depth
-(`PARTICLE_SORT_BUCKET_COUNT` bins over `GPUParticleSystem#sort_depth_range`): histogram from the
-camera uniform's view matrix, `graph_prefix_scan_csdldf` the bin counts to offsets, scatter (index
-payload). The sorted index list feeds the instanced draw. Both per-particle passes are bounded by
-the alive counter and dispatched by the args the bucket reset wrote from it.
+**There is no render order.** The draws walk the alive list exactly as compaction left it, because
+everything downstream of them is a sum: the AVBOIT volume accumulates extinction and the four
+accumulators accumulate colour, coverage and emission, and no arrangement of the instances changes
+any of those. So the system spends nothing on ordering: no key pass, no scan, no scatter, and no
+per-particle key and index lists to hold them in.
 
-Reordering the render list for program coherence would break transparency; depth-sorting the
-simulation list would destroy the coherence. They share no buffer and no counter slot —
-`PARTICLE_COUNTER.SORTED` belongs to the render order, `SIM_PADDED` to the simulation order.
+The two lists are still distinct and must stay so: the simulation list is permuted and padded with
+sentinels, so drawing it would draw them, and depth-ordering it would destroy the coherence. They
+share no buffer and no counter slot — `SIM_PADDED` is the simulation list's length, `ALIVE` the
+draw's.
 
 ### Rendering
 
-One render pipeline, one blend state = premultiplied: `color: (one, one-minus-src-alpha)`,
-`alpha: (one, one-minus-src-alpha)`. Additive vs. alpha is chosen by the shader emitting premultiplied
-RGB with alpha 0 (additive) vs. alpha a (normal) — GPU-driven, no pipeline switch. A 6-vertex quad is
-expanded per instance (billboard/velocity-stretch/axis-lock/world modes). Fragment: sample atlas
-(region + flipbook frame), optional forward lighting via `chunk_shade_standard_material_direct` +
-IBL, optional soft-depth fade. Depth-tested, no depth write. Draws into the HDR color target.
-Soft-depth fading scales both RGB and alpha for premultiplied inputs; straight-alpha and additive
-inputs have alpha scaled before premultiplication. Both draw paths share `particle_fade_color`.
-
-### Drawing under the renderer: an AVBOIT side channel
-
-Under `Renderer` the particles are not drawn by the billboard pass above. They go through the AVBOIT
-transparency pipeline (`rasterize/native/avboit/`) as a **side channel** — the contract in
-`AVBOITSideChannel.js` — so they composite order-independently with the transparent meshes and
-against the opaque scene, through the same volume and the same accumulators. Quads are not packed
-into meshlets; the orchestrator asks the channel for its contribution at the three points where the
-meshlet buckets have just made theirs:
+A 6-vertex quad is expanded per instance (billboard/velocity-stretch/axis-lock/world modes) by
+`chunk_particle_billboard_vertex`. Fragment: sample atlas (region + flipbook frame), optional forward
+lighting via `chunk_shade_standard_material_direct` + IBL, optional soft-depth fade. Soft-depth
+fading scales both RGB and alpha for premultiplied inputs; straight-alpha and additive inputs have
+alpha scaled before premultiplication.
+
+Additive vs. alpha is never a pipeline switch: the shader emits premultiplied RGB with alpha 0
+(additive) or alpha a (normal), so one setup covers both and the choice stays per particle and
+GPU-driven. Under AVBOIT that choice picks which accumulators the fragment writes; in the blended
+pipeline `shaders/shader_particle_render.js` builds it is one blend state,
+`(one, one-minus-src-alpha)` on both channels. That pipeline is not this system's — it is what
+`GPUParticularRenderer` draws `particular`'s CPU-simulated particles with, over a draw list it sorts
+back to front on the CPU — but it shares this vertex stage, this atlas and flipbook math, and
+`particle_fade_color`, so a sprite looks the same whichever draws it.
+
+### Drawing: an AVBOIT side channel
+
+The particles are drawn by the AVBOIT transparency pipeline (`rasterize/native/avboit/`) as a
+**side channel** — the contract in `AVBOITSideChannel.js` — so they composite order-independently
+with the transparent meshes and against the opaque scene, through the same volume and the same
+accumulators. Quads are not packed into meshlets; the orchestrator asks the channel for its
+contribution at the three points where the meshlet buckets have just made theirs:
 
 1. **occupancy** (`shader_particle_avboit_occupancy`): one thread per emitter row, the emitter's
    measured box (the culling box, off the state row) as a view-depth interval, dilated and OR-ed
@@ -542,12 +555,11 @@ meshlet buckets have just made theirs:
    scene behind already has it. That accumulator is the one addition to AVBOIT's resolve for this.
    The whole decision is `chunk_particle_avboit_contribution`, and it is spec'd on the emulator.
 
-No sort: the volume makes order irrelevant, so this path reads the alive list and the draw args
-straight from `simulate`. The billboard vertex stage is one chunk
-(`chunk_particle_billboard_vertex`) shared by the standalone renderer and both AVBOIT passes.
-`GPUParticleSystem` implements the three methods; `Renderer.feature_particles_enabled` runs
-`simulate` before the transparency pass and hands the system to the orchestrator. MBOIT is legacy
-and gets no particle path.
+All three read the alive list and the draw args straight from `simulate`; the vertex stage is one
+chunk (`chunk_particle_billboard_vertex`), shared by the splat, the draw and the blended pipeline
+`particular` uses. `GPUParticleSystem` implements the three methods; `Renderer.feature_particles_enabled`
+runs `execute` before the transparency pass and hands the system to the orchestrator. MBOIT is legacy
+and gets no particle path, so under it the particles simulate and are not drawn.
 
 ### The ECS: `ParticleEffect` + `Transform64`
 
@@ -627,13 +639,26 @@ through `GPUTextureContext`.
 
 ### Ownership: `GPUParticleSystem`
 
-Constructed once against a `GPUSceneContext`, in the mould of `ReSTIRDI`. It owns every persistent
-buffer — pool, alive lists, dead list, counters, both indirect-args buffers, the coherence and sort
-scratch, the emitter database (both tables), the packed program buffer, the spawn-command ring — and grows the ones that depend on the emitter set inside `execute`. The
-default atlas is a 1x1 white texel. `execute({graph, camera, scene_database, color, depth, dt})`
-sweeps the scene, pushes what changed (on a command context opened only when something needs
-one), and records the whole frame through `graph_particles`, returning the colour handle after
-the draw. An integrator does not encode a particle pass by hand.
+Constructed once against a `GPUSceneContext`, in the mould of `ReSTIRDI`. It owns persistent buffers
+and only those — a buffer is reserved here if and only if its contents cross the frame boundary:
+pool, alive lists, dead list, counters, the coherence list, simulate's indirect dispatch args, the
+emitter database (both tables), the packed program buffer, the spawn-command ring and the warm-up
+queue — and grows the ones that depend on the emitter set inside `execute`. Everything else a frame
+touches is the frame graph's, declared by the pass that first writes it: the bucketing scratch, the
+draw args, the spawn counts and the wide register file. The default atlas is a 1x1 white texel.
+`execute({graph, camera, scene_database, dt})` sweeps the scene, pushes what changed (on a command
+context opened only when something needs one), and records the simulation through `graph_particles`,
+returning the handles the side channels draw from. It touches no colour target — the drawing is the
+transparency pipeline's — and an integrator does not encode a particle pass by hand.
+
+The frame reads nothing back, but a HUD or an inspector wants to: `read_stats()` copies the counters
+and the dispatch args out and returns them named — alive, free, the spawn budget, both list lengths
+and the workgroups the next simulate will launch. That is the whole of the readback, and the only
+reason the dispatch args carry `COPY_SRC` (the counters and the coherence list carry it to be copied
+forward when they grow). Nothing it returns may size a pass: the numbers describe a frame already
+submitted, and what sizing from a stale count costs is set out under the finalize pass above. The
+draw args are not among them and cannot be — they are the graph's, released after the last draw that
+reads them — and their instance count is the alive count regardless.
 
 ## File layout
 
@@ -675,7 +700,7 @@ src/shade/renderer/particles/
   shaders/shader_particle_emit.js            per-newborn INIT, sized by the scan
   shaders/shader_particle_simulate.js        per-particle UPDATE + compaction + orphan kill
   shaders/shader_particle_finalize.js        reset counters (+ budget) / build indirect args
-  shaders/shader_particle_render.js          billboard pipeline
+  shaders/shader_particle_render.js          blended billboard pipeline (GPUParticularRenderer's)
   shaders/chunk_particle_setup_context.js    VM builtins from the emitter's node, + the RNG seed
   shaders/chunk_particle_emitter_age.js      the tick pass's running age, off the emitter_state table
   shaders/chunk_particle_spawn_budget.js     take from the frame's spawn budget; both ticks spend it
@@ -687,8 +712,7 @@ src/shade/renderer/particles/
   shaders/chunk_particle_billboard_vertex.js the billboard vertex stage, shared by every draw
   shaders/shader_particle_avboit_*.js        occupancy / splat / draw through AVBOIT
   bounds/*                           the measured emitter box: accumulate, publish
-  sort/*                             render-order depth sort
-  graph_particles.js                 simulate (to the draw args) + the standalone sort and draw
+  graph_particles.js                 the simulation, to the draw args
   graph_particles_avboit.js          the AVBOIT side channel: occupancy, splat, draw
   GPUParticleSystem.js               the feature: owns the buffers, sweeps the scene, execute()
   *.spec.js                          co-located tests (JS + emulator + software device)
@@ -698,19 +722,19 @@ src/shade/renderer/particles/
 
 - Pure JS: layout packing, assembler, register allocator, node compiler, heap/emitter/registry
   bookkeeping (via `SoftwareGPUDevice`), the header encoding.
-- WGSL via emulator: VM opcode parity (JS vs WGSL), curve sampling, sort key/depth, atlas+flipbook
-  UV math, billboard expansion, soft-depth fade, and every compute pass on small fixtures — the tick
+- WGSL via emulator: VM opcode parity (JS vs WGSL), curve sampling, atlas+flipbook UV math,
+  billboard expansion, soft-depth fade, and every compute pass on small fixtures — the tick
   (rate integration, generations, pending, budget, culling, page-group walk), emit (expansion over
-  the scan, node position, orphans), simulate, spawn commands, finalize, bucket, sort. Each such spec
+  the scan, node position, orphans), simulate, spawn commands, finalize, bucket. Each such spec
   carries its own copy of the scaffolding: a real scene with a `GPUSceneContext` and a real registry,
   laid out by `gpu_database_words` the way the GPU holds both databases, so the shaders read rows the
   real writers wrote.
 - Multi-frame capstone (`particle_lifecycle.spec`): reset → commands → tick → (JS scan) → emit →
   simulate across frames, with the GPU deciding to spawn, a CPU burst, the budget, and death.
 - Orchestration on `SoftwareGPUDevice`: `GPUParticleSystem.spec` (scene sweep, growth, uploads only
-  when needed, the ring), `graph_particles.spec` (pass sequence, indirect sizing, the two orderings,
-  every persistent buffer imported exactly once), and the playground's `particle_scene.spec` (the
-  integration: geometry → hierarchy → particles → draw).
+  when needed, the ring, the `read_stats` decode), `graph_particles.spec` (pass sequence, indirect
+  sizing, the two lists, every persistent buffer imported exactly once), and the playground's
+  `particle_scene.spec` (the integration: geometry → hierarchy → particles → draw).
 - Cross-parity meta-tests: every ISA opcode implemented by both executors.
 
 Regression checks use the existing tools: seeded software-device buffer copies for list growth,
@@ -742,5 +766,5 @@ was seeded.
 Done: `Renderer.feature_particles_enabled` (off by default), `Renderer.particles(scene_ctx)` creating
 one system per scene context on first use, `simulate` recorded before the transparency pass and the
 system passed to the AVBOIT orchestrator as its side channel. Remaining:
-1. For lit emitters, compile a render variant that swaps the disabled lighting hook for a
-   shading-chunk-backed lighting hook (+ the `SHADING_LIGHT_RESOURCE_GROUP`).
+1. For lit emitters, compile a render variant that swaps the disabled lighting hook for a
+   shading-chunk-backed lighting hook (+ the `SHADING_LIGHT_RESOURCE_GROUP`).

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

@@ -1,3 +1,17 @@
+/**
+ * What {@link GPUParticleSystem#read_stats} decodes: the counts the GPU keeps between frames, named.
+ *
+ * @typedef {object} ParticleSystemStats
+ * @property {number} alive live particles the frame ended with
+ * @property {number} dead length of the free list
+ * @property {number} spawn_budget free slots the frame never promised to a spawn — its headroom
+ * @property {number} alive_in entries the frame's simulate consumed — the padded, program-coherent
+ *   list the frame before it built, so never fewer than that frame's `alive`
+ * @property {number} sim_padded length of the padded, program-coherent simulate list built this
+ *   frame; the gap to `alive` is what keeping each wave on one VM program costs in lanes
+ * @property {number} sim_workgroups workgroups the NEXT simulate will dispatch — read out of the
+ *   indirect args rather than derived, so it is what the GPU will actually launch
+ */
 /**
  * The GPU particle system: a feature of a scene, in the mould of `ReSTIRDI` — construct once
  * against a {@link GPUSceneContext}, and contribute the frame's passes through
@@ -5,15 +19,23 @@
  *
  * ## What it owns
  *
- * Every piece of persistent GPU state: the particle pool, the ping-pong alive lists, the dead
- * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) scratch,
- * the emitter database (the emitter table and the GPU-owned state table, one buffer), the packed
- * program buffer, and the spawn-command ring. Buffers that depend on the emitter set — the
- * coherence scratch on the number of distinct programs, the program buffer on the heap, the
+ * Persistent GPU state, and only that: a buffer is reserved here if and only if its contents have
+ * to survive to the next frame. That is the particle pool, the ping-pong alive lists, the dead
+ * free-list, the counters, the simulation-order (coherence) list, simulate's indirect dispatch args
+ * (written at the end of one frame, read by the next), the emitter database (the emitter table and
+ * the GPU-owned state table, one buffer), the packed program buffer, and the two CPU-uploaded
+ * queues — the spawn-command ring and the warm-up queue. Buffers that depend on the emitter set —
+ * the coherence list on the number of distinct programs, the program buffer on the heap, the
  * database on its own pages, the counters on the emitter table's element capacity (they carry the
- * per-emitter bounds accumulator, see `bounds/`) — are grown inside
- * {@link execute}, the way ReSTIR's reservoirs follow the resolution. The render-order (sort)
- * scratch is not in that list because it is not unconditional: see below.
+ * per-emitter bounds accumulator, see `bounds/`) — are grown inside {@link execute}, the way
+ * ReSTIR's reservoirs follow the resolution.
+ *
+ * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
+ * draw args, the spawn counts and the VM's wide register file are produced and consumed inside one
+ * graph, so the pass that first writes each one declares it and the graph allocates it just in time
+ * and releases it after its last reader — into the pool the rest of the renderer allocates from.
+ * Reserving them here instead would be megabytes at the default capacity that no other feature
+ * could ever borrow, and most of them are cleared by a reset pass every frame regardless.
  *
  * Every pass stays within the eight storage buffers a stage gets by default: the emitter record
  * and the GPU-owned state are two tables of one database buffer, and the VM's constants and code
@@ -48,20 +70,18 @@
  * command list that a pass adds to the emitter's pending spawns, on the same path as everything
  * else. See `graph_particles.js` for the frame.
  *
- * ## Drawing, and the one thing the mode changes
+ * ## Drawing
  *
- * {@link execute} is the whole per-frame call, once per frame. It always records everything that
- * moves particles and leaves the alive list and the indirect draw args as graph handles; what it
- * records after that is the {@link ParticleRenderMode} it was given.
+ * {@link execute} is the whole per-frame call, once per frame, and it records only the simulation:
+ * everything that moves particles, leaving the alive list and the indirect draw args as graph
+ * handles. It draws nothing.
  *
- * `BILLBOARD` sorts the alive list back-to-front and draws it over a colour target, because
- * premultiplied over-blending is order-dependent. `AVBOIT` records neither: under the renderer the
- * system is an `AVBOITSideChannel`, and the transparency orchestrator asks it for its occupancy, its
- * extinction and its draw at the three points where the transparent meshes have contributed theirs
- * ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}). Those read the same handles
- * and composite into a volume and a set of accumulators that are sums, so an ordering would buy
- * nothing — and the sort is four passes and a scan over every live particle, plus two lists a word
- * per particle each, which is why the mode also decides whether those buffers exist at all.
+ * The drawing is the transparency pipeline's. The system is an `AVBOITSideChannel`, and the AVBOIT
+ * orchestrator asks it for its occupancy, its extinction and its draw at the three points where the
+ * transparent meshes have contributed theirs ({@link avboit_occupancy}, {@link avboit_splat},
+ * {@link avboit_draw}). Those read the handles `execute` produced and composite into a voxel volume
+ * and a set of accumulators that are sums — so the particles need no depth ordering at all, and
+ * none is ever built.
  *
  * ## Allocation
  *
@@ -116,12 +136,6 @@ export class GPUParticleSystem {
      * @type {number}
      */
     max_catchup_seconds: number;
-    /**
-     * View-depth range the render sort quantises: particles nearer than `[0]` share the front bin,
-     * farther than `[1]` the back one. Read only by {@link ParticleRenderMode.BILLBOARD}.
-     * @type {Float32Array}
-     */
-    sort_depth_range: Float32Array;
     /**
      * Sprite atlas the billboards sample, and the sampler they sample it with. A 1x1 white texel by
      * default, so an emitter with no art draws as a plain quad rather than nothing.
@@ -132,8 +146,9 @@ export class GPUParticleSystem {
     atlas_sampler: GPUSampler;
     /**
      * The persistent GPU buffers, by the names the graph functions bind them under. Exposed for
-     * inspection — a harness copying the counters out to display them — never for the frame loop,
-     * which reads nothing back. Entries that grow with the emitter set are replaced in place.
+     * inspection — {@link bufferSizes} measures them, {@link read_stats} reads the counts out of
+     * them — never for the frame loop, which reads nothing back. Entries that grow with the
+     * emitter set are replaced in place.
      *
      * @type {object}
      */
@@ -177,16 +192,14 @@ export class GPUParticleSystem {
      */
     spawn(emitter: import("./runtime/ParticleEmitter.js").ParticleEmitter, count: number): void;
     /**
-     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
-     * it.
+     * The system's whole contribution to the frame, once per frame: reconcile the emitter set with
+     * the scene, push what changed to the GPU, and record every pass that moves particles — through
+     * to the indirect draw args.
      *
-     * {@link ParticleRenderMode.BILLBOARD} adds the depth sort and one billboard draw over `color`
-     * with fixed-function blending, for a page with no transparency pipeline of its own.
-     * {@link ParticleRenderMode.AVBOIT} adds nothing: the orchestrator draws the particles later in
-     * the frame through {@link avboit_occupancy}, {@link avboit_splat} and {@link avboit_draw}, off
-     * the handles this just produced, and its accumulators are order-independent — so the sort is
-     * skipped and its buffers are never allocated. `color` comes straight back either way, so a
-     * caller can assign the result unconditionally and let the mode be the only difference.
+     * It draws nothing and touches no colour target. The handles it returns are what the AVBOIT
+     * side channels ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}) consume
+     * later in the same frame, off this same graph, once the transparent meshes have contributed
+     * theirs.
      *
      * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
      * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
@@ -204,22 +217,14 @@ export class GPUParticleSystem {
      * @param {number} params.scene_database graph handle of the scene database — the one the
      *   hierarchy pass returned, so this reads the matrices it composed
      * @param {number} params.dt seconds since the previous frame
-     * @param {ParticleRenderMode} [params.mode] who draws, and so whether there is a sort
-     * @param {number} [params.color] graph handle of the colour target to draw over. Required by
-     *   `BILLBOARD`; returned untouched by `AVBOIT`
-     * @param {number} [params.depth] graph handle of the scene depth (tested, never written).
-     *   Required by `BILLBOARD`
-     * @returns {number|undefined} the colour handle after the particle draw, or `color` unchanged
+     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
      */
-    execute({ graph, camera, scene_database, color, depth, dt, mode }: {
+    execute({ graph, camera, scene_database, dt }: {
         graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
         camera: number;
         scene_database: number;
         dt: number;
-        mode?: ParticleRenderMode;
-        color?: number;
-        depth?: number;
-    }): number | undefined;
+    }): import("./graph_particles.js").ParticleSimulationHandles;
     /**
      * `AVBOITSideChannel#avboit_occupancy`: the emitters' measured bounding boxes, as depth slices.
      *
@@ -310,15 +315,69 @@ export class GPUParticleSystem {
      */
     sync_membership(): void;
     /**
-     * Sizes of the persistent buffers, in bytes, as they stand. Exposed for tests.
+     * Sizes of the persistent buffers, in bytes, as they stand — one entry per distinct buffer, so
+     * this is the feature's reserved footprint and not a list of the names it binds them under.
+     * `alive_read` and `alive_write` are the two `alive` entries under the frame's names for them,
+     * and would otherwise be counted a second time each. Exposed for tests.
+     *
      * @returns {Object<string, number>}
      */
     bufferSizes(): {
         [x: string]: number;
     };
+    /**
+     * Copy the counts the GPU keeps back to the host and decode them, for display and diagnostics.
+     *
+     * Read back to *look at*: nothing here may size a pass. Every number describes a frame that has
+     * already been submitted, so by the time one arrives it is at best one frame stale — and sizing
+     * a dispatch or a draw from a stale count is a correctness bug, not an inaccuracy, for the
+     * reasons `shader_particle_build_indirect` sets out. This is the whole of what the feature ever
+     * reads back, and the only reason {@link INDIRECT} carries `COPY_SRC` at all.
+     *
+     * The draw args are not here and cannot be: they never leave the frame graph, which allocates
+     * them at the build-indirect pass and releases them after the last draw that reads them. Their
+     * instance count is {@link ParticleSystemStats#alive}, which the counters carry anyway.
+     *
+     * Two copies, two submissions and a map round trip, so a caller polling this for an overlay
+     * wants to rate-limit itself and to hold off while a previous read is still outstanding.
+     *
+     * @returns {Promise<ParticleSystemStats>}
+     */
+    read_stats(): Promise<ParticleSystemStats>;
     destroy(): void;
     #private;
 }
+/**
+ * What {@link GPUParticleSystemread_stats } decodes: the counts the GPU keeps between frames, named.
+ */
+export type ParticleSystemStats = {
+    /**
+     * live particles the frame ended with
+     */
+    alive: number;
+    /**
+     * length of the free list
+     */
+    dead: number;
+    /**
+     * free slots the frame never promised to a spawn — its headroom
+     */
+    spawn_budget: number;
+    /**
+     * entries the frame's simulate consumed — the padded, program-coherent
+     * list the frame before it built, so never fewer than that frame's `alive`
+     */
+    alive_in: number;
+    /**
+     * length of the padded, program-coherent simulate list built this
+     * frame; the gap to `alive` is what keeping each wave on one VM program costs in lanes
+     */
+    sim_padded: number;
+    /**
+     * workgroups the NEXT simulate will dispatch — read out of the
+     * indirect args rather than derived, so it is what the GPU will actually launch
+     */
+    sim_workgroups: number;
+};
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { ParticleRenderMode } from "./ParticleRenderMode.js";
 //# sourceMappingURL=GPUParticleSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}