@woosh/meep-engine 3.21.0 → 3.22.0

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
@@ -17,12 +31,11 @@
  * ReSTIR's reservoirs follow the resolution.
  *
  * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
- * whole depth sort, 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 six megabytes at the default
- * capacity that no other feature could ever borrow, and four of them are cleared by a reset pass
- * every frame regardless.
+ * 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
@@ -57,21 +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. Under `AVBOIT` none of those passes is recorded, so the graph never allocates
- * their buffers either.
+ * 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
  *
@@ -126,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.
@@ -142,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}
      */
@@ -187,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'
@@ -214,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.
      *
@@ -330,9 +325,59 @@ export class GPUParticleSystem {
     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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"}

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

@@ -6,7 +6,6 @@ import {
     PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
     PARTICLE_RECORD_WORD_COUNT,
     PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    PARTICLE_SORT_BUCKET_COUNT,
     PARTICLE_SPAWN_COMMAND_WORDS,
     PARTICLE_VM_FAST_REGISTER_SLOTS,
     PARTICLE_WARMUP_EMITTER_JITTER,
@@ -25,14 +24,11 @@ import {
     graph_particle_avboit_occupancy,
     graph_particle_avboit_splat,
 } from "./graph_particles_avboit.js";
-import { graph_particles_billboard } from "./graph_particles_billboard.js";
-import { ParticleRenderMode } from "./ParticleRenderMode.js";
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
-import { graph_particle_sort } from "./sort/graph_particle_sort.js";
 import { WARMUP_QUEUE } from "./warmup/shader_particle_warmup.js";
 import { warmup_schedule } from "./warmup/warmup_schedule.js";
 import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { inspect_gpu_buffer } from "../buffer/inspect_gpu_buffer.js";
 
 const WORD = Uint32Array.BYTES_PER_ELEMENT;
 
@@ -49,14 +45,29 @@ const STORAGE_UPLOAD = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
 /** Uploaded, and copied forward into its replacement when the emitter set outgrows it. */
 const STORAGE_GROWABLE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
 /**
- * An indirect command the GPU writes and the GPU consumes. COPY_SRC is for the playground's HUD,
- * which reads the args back to show that the dispatch really is sized on-device — twelve bytes, and
- * the only thing in this file read back at all.
+ * An indirect command the GPU writes and the GPU consumes. COPY_SRC is for {@link
+ * GPUParticleSystem#read_stats}, which reads the args back to show that the dispatch really is
+ * sized on-device — twelve bytes.
  */
 const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
 
 const DEFAULT_CAPACITY = 524288;
 
+/**
+ * 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
@@ -76,12 +87,11 @@ const DEFAULT_CAPACITY = 524288;
  * ReSTIR's reservoirs follow the resolution.
  *
  * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
- * whole depth sort, 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 six megabytes at the default
- * capacity that no other feature could ever borrow, and four of them are cleared by a reset pass
- * every frame regardless.
+ * 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
@@ -116,21 +126,18 @@ const DEFAULT_CAPACITY = 524288;
  * 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. Under `AVBOIT` none of those passes is recorded, so the graph never allocates
- * their buffers either.
+ * 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
  *
@@ -182,13 +189,6 @@ export class GPUParticleSystem {
      */
     max_catchup_seconds = 1;
 
-    /**
-     * 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 = new Float32Array([0.1, 100]);
-
     /**
      * 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.
@@ -201,8 +201,9 @@ export class GPUParticleSystem {
 
     /**
      * 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}
      */
@@ -285,12 +286,6 @@ export class GPUParticleSystem {
      */
     #program_assignment_version = 0;
 
-    /** @type {object|null} */
-    #pipeline = null;
-
-    /** @type {string} */
-    #pipeline_key = "";
-
     /**
      * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
      * @type {object}
@@ -305,19 +300,13 @@ export class GPUParticleSystem {
     #emitters = { capacity: 0, group_count: 0 };
 
     /**
-     * This frame's simulation, for the draw that follows it: the graph it was recorded into, the
-     * scene database handle it read, and the handles it produced. Reused, never reallocated.
+     * This frame's simulation, for the side channels that draw it later in the frame: the graph it
+     * was recorded into, the scene database handle it read, and the handles it produced. Reused,
+     * never reallocated.
      * @type {{graph: object|null, scene_database: number, emitter_group_count: number, handles: object|null}}
      */
     #simulated = { graph: null, scene_database: -1, emitter_group_count: 0, handles: null };
 
-    /** @type {object} */
-    #render = {
-        atlas: null,
-        atlas_sampler: null,
-        obtain_pipeline: (color_format, depth_format) => this.#obtain_pipeline(color_format, depth_format),
-    };
-
     /**
      * @param {object} graphics engine GraphicsContext (has `.device`)
      * @param {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
@@ -419,18 +408,37 @@ export class GPUParticleSystem {
     }
 
     /**
-     * The simulation half of the 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.
-     * What it leaves as graph handles is what a draw consumes, whichever draw that turns out to be.
+     * 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.
+     *
+     * 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.
      *
-     * @param {object} params see {@link execute}
+     * 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'
+     * `global` matrices are this frame's.
+     *
+     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
+     * handles into the graph it recorded into; a second view of the same scene records a second
+     * graph and would step the simulation twice. The renderer has one view per `render` call today,
+     * so this holds by construction; a second view of one scene needs the step and the handles
+     * separated — record the passes for the first graph, import the same buffers into the rest.
+     *
+     * @param {object} params
      * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
-     * @param {number} params.camera
-     * @param {number} params.scene_database
-     * @param {number} params.dt
+     * @param {number} params.camera graph handle of the camera uniform buffer
+     * @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
      * @returns {import("./graph_particles.js").ParticleSimulationHandles}
      */
-    #simulate({ graph, camera, scene_database, dt }) {
+    execute({ graph, camera, scene_database, dt }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+
         this.sync_membership();
         this.#upload();
 
@@ -471,7 +479,7 @@ export class GPUParticleSystem {
             frame,
         });
 
-        // Kept for the draw that follows, whichever it is, and for nothing past this frame.
+        // Kept for the side channels that draw later in this frame, and for nothing past it.
         const current = this.#simulated;
         current.graph = graph;
         current.scene_database = scene_database;
@@ -489,101 +497,7 @@ export class GPUParticleSystem {
     }
 
     /**
-     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
-     * it.
-     *
-     * {@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.
-     *
-     * 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'
-     * `global` matrices are this frame's.
-     *
-     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
-     * handles into the graph it recorded into; a second view of the same scene records a second
-     * graph and would step the simulation twice. The renderer has one view per `render` call today,
-     * so this holds by construction; a second view of one scene needs the step and the handles
-     * separated — record the passes for the first graph, import the same buffers into the rest.
-     *
-     * @param {object} params
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
-     * @param {number} params.camera graph handle of the camera uniform buffer
-     * @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
-     */
-    execute({ graph, camera, scene_database, color, depth, dt, mode = ParticleRenderMode.BILLBOARD }) {
-        assert.defined(graph, "graph");
-        assert.isNumber(dt, "dt");
-        assert.enum(mode, ParticleRenderMode, "mode");
-
-        const billboard = mode === ParticleRenderMode.BILLBOARD;
-
-        // Checked before the simulation rather than at the draw: the simulation advances `frame` and
-        // `time` and writes the pool, and a throw after that leaves a frame half-stepped.
-        if (billboard) {
-            assert.isNonNegativeInteger(color, "color");
-            assert.isNonNegativeInteger(depth, "depth");
-        }
-
-        const simulated = this.#simulate({ graph, camera, scene_database, dt });
-
-        if (!billboard) {
-            // AVBOIT: the side channels draw these handles later in the frame, and the colour target
-            // is not this call's to touch.
-            return color;
-        }
-
-        // The render order: back-to-front by view depth, so premultiplied transparency composites
-        // correctly. Its two per-particle passes take the dispatch the coherence reset wrote from
-        // the GPU's own alive count, and every buffer it needs is the graph's — a system the
-        // renderer drives through AVBOIT records none of these passes and so pays for none of them.
-        const sorted = graph_particle_sort({
-            graph,
-            camera,
-            emitter_database: simulated.emitter_database,
-            pool: simulated.pool,
-            alive: simulated.alive,
-            counters: simulated.counters,
-            dispatch_args: simulated.sim_dispatch_args,
-            capacity: this.capacity,
-            bucket_count: PARTICLE_SORT_BUCKET_COUNT,
-            near: this.sort_depth_range[0],
-            far: this.sort_depth_range[1],
-        });
-
-        const render = this.#render;
-        render.atlas = this.atlas;
-        render.atlas_sampler = this.atlas_sampler;
-
-        // One instanced billboard draw over the sorted list, sized by the draw args this frame's
-        // build-indirect wrote.
-        return graph_particles_billboard({
-            graph,
-            camera,
-            color,
-            depth,
-            pool: simulated.pool,
-            draw_list: sorted,
-            emitter_database: simulated.emitter_database,
-            draw_args: simulated.draw_args,
-            render,
-        });
-    }
-
-    /**
-     * What this frame's {@link simulate} left, checked against the graph a side-channel call names:
+     * What this frame's {@link execute} left, checked against the graph a side-channel call names:
      * the AVBOIT orchestrator records its passes into the same graph, later in the same frame.
      *
      * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
@@ -1096,27 +1010,6 @@ export class GPUParticleSystem {
         });
     }
 
-    /**
-     * @param {string} color_format
-     * @param {string} depth_format
-     * @returns {object} the billboard pipeline descriptor for these attachment formats
-     */
-    #obtain_pipeline(color_format, depth_format) {
-        const key = `${color_format}/${depth_format}`;
-
-        if (this.#pipeline === null || this.#pipeline_key !== key) {
-            this.#pipeline = create_particle_billboard_pipeline({
-                color_format,
-                depth_format,
-                // reverse-Z, the engine convention
-                depth_compare: "greater",
-            });
-            this.#pipeline_key = key;
-        }
-
-        return this.#pipeline;
-    }
-
     /**
      * 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.
@@ -1143,6 +1036,54 @@ export class GPUParticleSystem {
         return sizes;
     }
 
+    /**
+     * 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>}
+     */
+    async read_stats() {
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+
+        const read = (buffer, words) => inspect_gpu_buffer({
+            device,
+            buffer,
+            buffer_size: words * WORD,
+            // The mapped range is only valid for the length of the callback, so the decode either
+            // happens inside it or takes a copy. A copy, so one `Promise.all` sees both buffers.
+            callback: bytes => new Uint32Array(bytes.slice(0)),
+        });
+
+        const [counters, dispatch] = await Promise.all([
+            // The head of the buffer only: what follows the counters is the per-emitter bounds
+            // accumulator, which is boxes rather than counts and grows with the emitter table.
+            read(buffers.counters, PARTICLE_COUNTER_COUNT),
+            read(buffers.dispatch_args, 3),
+        ]);
+
+        return {
+            alive: counters[PARTICLE_COUNTER.ALIVE],
+            dead: counters[PARTICLE_COUNTER.DEAD],
+            spawn_budget: counters[PARTICLE_COUNTER.SPAWN_BUDGET],
+            alive_in: counters[PARTICLE_COUNTER.ALIVE_IN],
+            sim_padded: counters[PARTICLE_COUNTER.SIM_PADDED],
+            sim_workgroups: dispatch[0],
+        };
+    }
+
     destroy() {
         /*
          The emitters go first, and they matter more than the buffers: they are the scene's nodes,