@woosh/meep-engine 3.20.0 → 3.21.0

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

@@ -1,8 +1,6 @@
 import { assert } from "../../../core/assert.js";
-import { align_4 } from "../../../core/binary/align_4.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { warn_limited } from "../../util/warn_limited.js";
-import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
 import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
 import {
     PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
@@ -38,7 +36,23 @@ import { GPUTextureContext } from "../texture/GPUTextureContext.js";
 
 const WORD = Uint32Array.BYTES_PER_ELEMENT;
 
-const STORAGE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+/*
+ A wide usage mask costs bandwidth: the driver places a buffer by what it was told the buffer might
+ have to do, and the flags below are what each one actually does. `pool` and the alive lists are the
+ big ones and are touched by nothing but shaders. Adding a flag "just in case" moves 64 MiB onto a
+ slower path for a copy nobody makes — see `BufferResourceDescriptor`.
+*/
+/** Written only by shaders. */
+const STORAGE = GPUBufferUsage.STORAGE;
+/** Seeded or refilled from the host with `writeBuffer`. */
+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.
+ */
 const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
 
 const DEFAULT_CAPACITY = 524288;
@@ -50,15 +64,24 @@ const DEFAULT_CAPACITY = 524288;
  *
  * ## 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
+ * 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.
  *
  * 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
@@ -106,7 +129,8 @@ const DEFAULT_CAPACITY = 524288;
  * ({@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.
+ * per particle each. Under `AVBOIT` none of those passes is recorded, so the graph never allocates
+ * their buffers either.
  *
  * ## Allocation
  *
@@ -521,22 +545,19 @@ export class GPUParticleSystem {
             return color;
         }
 
-        // Allocated here rather than in the constructor: they are two words per particle plus the
-        // bins, and only this mode ever reads them. A system the renderer drives never makes them.
-        this.#ensure_sort_buffers();
-
         // 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.
+        // 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,
-            gpu: this.buffers,
             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],
@@ -854,7 +875,7 @@ export class GPUParticleSystem {
 
         if (this.buffers.warmup_queue.size < bytes) {
             this.buffers.warmup_queue.destroy();
-            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE });
+            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE_UPLOAD });
         }
 
         device.queue.writeBuffer(this.buffers.warmup_queue, 0, words.buffer, words.byteOffset, bytes);
@@ -948,7 +969,7 @@ export class GPUParticleSystem {
         }
 
         const device = this.graphics.device;
-        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE });
+        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE_GROWABLE });
 
         const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/counters grow");
 
@@ -968,8 +989,14 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Scratch follows the peak number of program ids. The coherence list itself is persistent:
-     * the next simulate consumes its entries and padding with the previous frame's saved count.
+     * The coherence list follows the peak number of program ids. It is the one thing the bucketing
+     * leaves behind: the next simulate consumes its entries and padding with the previous frame's
+     * saved count, so it cannot be a transient and it cannot be reallocated empty. Growth copies it
+     * forward; the old count and dispatch stay valid because the entries keep their places.
+     *
+     * The bins, cursors, keys and dispatch args the bucketing needs alongside it live and die inside
+     * one frame graph, so `coherence/` declares them on the passes that write them and the graph
+     * owns them.
      *
      * @param {number} buckets
      */
@@ -980,56 +1007,26 @@ export class GPUParticleSystem {
 
         const device = this.graphics.device;
         const buffers = this.buffers;
-        const capacity = this.capacity;
-
-        for (const name of ["sim_keys", "sim_histogram", "sim_bucket_counts", "sim_cursor"]) {
-            buffers[name]?.destroy();
-        }
 
         // Padding rounds each bucket up to a whole workgroup, so it can add at most `workgroup - 1`
         // entries per bucket; one whole workgroup per bucket is the bound.
         const previous = buffers.sim_list;
-        buffers.sim_list = device.createBuffer({ label: "particles/sim_list", size: (capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD, usage: STORAGE });
+        buffers.sim_list = device.createBuffer({
+            label: "particles/sim_list",
+            size: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD,
+            usage: STORAGE_GROWABLE,
+        });
+
         if (previous !== undefined) {
             const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/coherence grow");
             cmd.gpu_encoder.copyBufferToBuffer(previous, 0, buffers.sim_list, 0, previous.size);
             cmd.finish();
             previous.destroy();
         }
-        buffers.sim_keys = device.createBuffer({ label: "particles/sim_keys", size: capacity * WORD, usage: STORAGE });
-        // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
-        // rounded up to a multiple of four.
-        buffers.sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(buckets)) * WORD, usage: STORAGE });
-        buffers.sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: buckets * WORD, usage: STORAGE });
-        buffers.sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: buckets * WORD, usage: STORAGE });
 
         this.#sim_bucket_capacity = buckets;
     }
 
-    /**
-     * The render-order scratch, made on the first frame that actually sorts.
-     *
-     * Only {@link ParticleRenderMode.BILLBOARD} reads any of it, and the two per-particle lists are
-     * a word per particle each — at the renderer's default capacity, half a megabyte that AVBOIT
-     * would never touch. Nothing in them outlives a frame, so there is nothing to carry over and the
-     * first sorted frame is as correct as any later one.
-     */
-    #ensure_sort_buffers() {
-        const buffers = this.buffers;
-
-        if (buffers.sorted !== undefined) {
-            return;
-        }
-
-        const device = this.graphics.device;
-        const capacity = this.capacity;
-
-        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
-        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
-    }
-
     /**
      * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
      */
@@ -1043,21 +1040,21 @@ export class GPUParticleSystem {
             device.createBuffer({ label: "particles/alive_a", size: capacity * WORD, usage: STORAGE }),
             device.createBuffer({ label: "particles/alive_b", size: capacity * WORD, usage: STORAGE }),
         ];
-        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
+        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE_UPLOAD });
         // Just the counters to begin with. The per-emitter bounds accumulator that shares this
         // buffer follows the emitter table's capacity, and there is no table yet.
-        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE });
+        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE_GROWABLE });
 
-        // Indirect args, written on-GPU. Zero-initialised (WebGPU spec), so the first frame's
-        // indirect dispatch/draw are no-ops until the first build-indirect has run.
+        // Simulate's workgroup count, written by the END of one frame's build-indirect and read by
+        // the NEXT frame's dispatch — the one indirect buffer that crosses the boundary, and so the
+        // one the graph cannot own. Zero-initialised (WebGPU spec), so the first frame's indirect
+        // dispatch is a no-op until the first build-indirect has run.
         buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
-        buffers.draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * WORD, usage: INDIRECT });
-        buffers.sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: 3 * WORD, usage: INDIRECT });
 
-        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE });
+        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE_UPLOAD });
 
         // The warm-up queue: one entry to start with, grown on upload to what a frame registers.
-        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE });
+        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE_UPLOAD });
 
         // Every slot free, and the counters saying so.
         const dead = new Uint32Array(capacity);
@@ -1121,16 +1118,24 @@ export class GPUParticleSystem {
     }
 
     /**
-     * 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() {
         const sizes = {};
+        const counted = new Set();
 
-        for (const [name, buffer] of Object.entries(this.buffers)) {
-            if (Array.isArray(buffer)) {
-                sizes[name] = buffer[0].size;
-            } else if (buffer !== undefined && buffer !== null) {
+        for (const [name, value] of Object.entries(this.buffers)) {
+            for (const buffer of Array.isArray(value) ? value : [value]) {
+                if (buffer === undefined || buffer === null || counted.has(buffer)) {
+                    continue;
+                }
+
+                counted.add(buffer);
                 sizes[name] = buffer.size;
             }
         }
@@ -1183,7 +1188,7 @@ export class GPUParticleSystem {
 function replace_data_buffer(device, previous, label, data) {
     previous?.destroy();
 
-    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE });
+    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE_UPLOAD });
 
     device.queue.writeBuffer(buffer, 0, data);
 

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

@@ -21,15 +21,22 @@
  * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
  * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
  *
+ * ## The list is the feature's, the scratch is the graph's
+ *
+ * `sim_list` is the one thing here that crosses the frame boundary — this frame writes it, next
+ * frame's simulate reads it — so the feature owns it and hands it in. Everything else (the keys,
+ * the bins, the cursors, the dispatch args) is produced and consumed inside this call, so the pass
+ * that first writes each one declares it with a {@link BufferResourceDescriptor} in place of a
+ * handle, and the graph allocates and releases it around the passes that use it. `keys` is a word
+ * per particle: at the renderer's default capacity, 2 MiB the feature no longer reserves.
+ *
+ * None of them asks for a clear. The reset pass covers the histogram (header, padding and the bins
+ * up to the whole `vec4` the last one lands in), the cursors and all three dispatch words; `keys`
+ * is written by the same indirect dispatch that later reads it, and `bucket_counts` by the same
+ * `bucket_count` threads.
+ *
  * @param {object} params
  * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
- * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
- * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
- * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
- * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
- * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
- * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
- * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
  * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
@@ -38,25 +45,19 @@
  *   imported here because the simulate pass reads it earlier in the same frame: importing the same
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
+ * @param {number} params.capacity pool capacity in particles — the length of the key list
  * @param {number} params.bucket_count number of distinct compiled programs
  * @param {ParticleBucketScratch} [params.scratch] latest handles when bucketing again in this graph
  * @returns {{counters: number, sim_list: number, dispatch_args: number, scratch: ParticleBucketScratch}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count, scratch }: {
+export function graph_particle_bucket({ graph, emitter_database, pool, alive, counters, sim_list, capacity, bucket_count, scratch }: {
     graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
-    gpu: {
-        sim_list: GPUBuffer;
-        sim_keys: GPUBuffer;
-        sim_histogram: GPUBuffer;
-        sim_bucket_counts: GPUBuffer;
-        sim_cursor: GPUBuffer;
-        sim_dispatch_args: GPUBuffer;
-    };
     emitter_database: number;
     pool: number;
     alive: number;
     counters: number;
     sim_list: number;
+    capacity: number;
     bucket_count: number;
     scratch?: ParticleBucketScratch;
 }): {

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

@@ -1 +1 @@
-{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAkBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IApBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;IACyB,OAAO,GAAtC,qBAAqB;;cACR,MAAM;cAAY,MAAM;mBAAiB,MAAM;aAAW,qBAAqB;EAyGtG;oCAnJY;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC"}
+{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAoBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAdqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACyB,OAAO,GAAtC,qBAAqB;IACnB;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAC,CA4GvG;oCA9JY;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC"}

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

@@ -1,8 +1,8 @@
 import { assert } from "../../../../core/assert.js";
 import { align_4 } from "../../../../core/binary/align_4.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { graph_compute_indirect_pass } from "../../shader/graph/compute/graph_compute_indirect_pass.js";
 import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
-import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
 import {
     PREFIX_SCAN_CSDLDF_HEADER_WORDS,
 } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
@@ -16,6 +16,8 @@ import {
     shader_particle_bucket_scatter,
 } from "./shader_particle_bucket.js";
 
+const WORD = Uint32Array.BYTES_PER_ELEMENT;
+
 /**
  * @typedef {{keys: number, histogram: number, cursor: number, bucket_counts: number, dispatch_args: number}} ParticleBucketScratch
  */
@@ -40,15 +42,22 @@ import {
  * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
  * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
  *
+ * ## The list is the feature's, the scratch is the graph's
+ *
+ * `sim_list` is the one thing here that crosses the frame boundary — this frame writes it, next
+ * frame's simulate reads it — so the feature owns it and hands it in. Everything else (the keys,
+ * the bins, the cursors, the dispatch args) is produced and consumed inside this call, so the pass
+ * that first writes each one declares it with a {@link BufferResourceDescriptor} in place of a
+ * handle, and the graph allocates and releases it around the passes that use it. `keys` is a word
+ * per particle: at the renderer's default capacity, 2 MiB the feature no longer reserves.
+ *
+ * None of them asks for a clear. The reset pass covers the histogram (header, padding and the bins
+ * up to the whole `vec4` the last one lands in), the cursors and all three dispatch words; `keys`
+ * is written by the same indirect dispatch that later reads it, and `bucket_counts` by the same
+ * `bucket_count` threads.
+ *
  * @param {object} params
  * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
- * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
- * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
- * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
- * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
- * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
- * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
- * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
  * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
@@ -57,34 +66,38 @@ import {
  *   imported here because the simulate pass reads it earlier in the same frame: importing the same
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
+ * @param {number} params.capacity pool capacity in particles — the length of the key list
  * @param {number} params.bucket_count number of distinct compiled programs
  * @param {ParticleBucketScratch} [params.scratch] latest handles when bucketing again in this graph
  * @returns {{counters: number, sim_list: number, dispatch_args: number, scratch: ParticleBucketScratch}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count, scratch }) {
+export function graph_particle_bucket({ graph, emitter_database, pool, alive, counters, sim_list, capacity, bucket_count, scratch }) {
     assert.defined(graph, "graph");
+    assert.isPositiveInteger(capacity, "capacity");
     assert.isPositiveInteger(bucket_count, "bucket_count");
     assert.isNonNegativeInteger(sim_list, "sim_list");
 
-    // Sized from the bucket count, which only changes when the emitter set does — so a caller that
-    // added an emitter and did not reallocate gets told here rather than scattering out of bounds.
-    // Aligned up because the scan reads whole `vec4`s, so the last bin's tail is part of the buffer.
+    // Sized from the bucket count, which only changes when the emitter set does. Aligned up because
+    // the scan reads whole `vec4`s, so the last bin's tail is part of the buffer.
     const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
-    assert.greaterThanOrEqual(gpu.sim_histogram.size, bin_words * Uint32Array.BYTES_PER_ELEMENT, "sim_histogram is too small for the bucket count");
-    assert.greaterThanOrEqual(gpu.sim_cursor.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_cursor is too small for the bucket count");
-    assert.greaterThanOrEqual(gpu.sim_bucket_counts.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_bucket_counts is too small for the bucket count");
 
     // Every buffer a pass WRITES must be THREADED: the write returns a renamed (versioned) handle
-    // and the next pass must read THAT one. Reading the original import instead leaves the ordering
+    // and the next pass must read THAT one. Reading the original handle instead leaves the ordering
     // between the two passes unexpressed — the graph's own validator rejects it, because both
     // versions name one piece of memory and the stale-looking read silently returns the new
     // contents.
-    // An edit frame buckets twice. Reuse the latest handles so both runs share one dependency chain.
-    let keys = scratch?.keys ?? graph_import_buffer(graph, gpu.sim_keys, "particles/sim_keys");
-    let histogram = scratch?.histogram ?? graph_import_buffer(graph, gpu.sim_histogram, "particles/sim_histogram");
-    let cursor = scratch?.cursor ?? graph_import_buffer(graph, gpu.sim_cursor, "particles/sim_cursor");
-    let bucket_counts = scratch?.bucket_counts ?? graph_import_buffer(graph, gpu.sim_bucket_counts, "particles/sim_bucket_counts");
-    let dispatch_args = scratch?.dispatch_args ?? graph_import_buffer(graph, gpu.sim_dispatch_args, "particles/sim_dispatch_args");
+    // An edit frame buckets twice. The second run is handed the first's handles, so the transients
+    // are created once and both runs share one dependency chain.
+    let keys = scratch?.keys ?? BufferResourceDescriptor.from(capacity * WORD, GPUBufferUsage.STORAGE);
+    let histogram = scratch?.histogram ?? BufferResourceDescriptor.from(bin_words * WORD, GPUBufferUsage.STORAGE);
+    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.
+    let dispatch_args = scratch?.dispatch_args ?? BufferResourceDescriptor.from(
+        3 * WORD,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    );
 
     // 0. Clear the bins and cursors, write the scan's {count} header, and size the two per-particle
     //    passes below from the GPU's own alive count.

package/src/shade/renderer/particles/graph/ParticleGroupBuilder.d.ts

@@ -58,10 +58,10 @@ export class ParticleGroupBuilder {
      * @param {object} [parameters] overrides on top of the type's defaults
      * @returns {{node: NodeInstance, port: Port}} the node's `out` port
      */
-    op(type: string, args?: (number | {
+    op(type: string, args?: Array<{
         node: NodeInstance;
         port: Port;
-    })[], parameters?: object): {
+    } | number>, parameters?: object): {
         node: NodeInstance;
         port: Port;
     };
@@ -76,10 +76,10 @@ export class ParticleGroupBuilder {
      * @returns {Object<string, {node: NodeInstance, port: Port}>} a reference per output port name
      */
     call(group: ParticleNodeGroup, args?: {
-        [x: string]: number | {
+        [x: string]: {
             node: NodeInstance;
             port: Port;
-        };
+        } | number;
     }): {
         [x: string]: {
             node: NodeInstance;
@@ -159,10 +159,10 @@ export class ParticleGroupBuilder {
      * @param {{node: NodeInstance, port: Port}|number} value
      * @returns {void}
      */
-    out(name: string, value: number | {
+    out(name: string, value: {
         node: NodeInstance;
         port: Port;
-    }): void;
+    } | number): void;
     /**
      * Finish the group, having checked that it is one.
      *

package/src/shade/renderer/particles/graph/ParticleGroupBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleGroupBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleGroupBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAaI;;OAEG;IACH,qBAFW,MAAM,EAoBhB;IAjCD;;;OAGG;IACH,OAFU,iBAAiB,CAErB;IAEN;;;OAGG;IACH;YAFiB,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC;MAEjD;IAyBR;;;;;;;;;;;OAWG;IACH,SALW,MAAM;;;uBAEN,MAAM;;;MAoBhB;IAED;;;;;;;;;OASG;IACH,YAJW,iBAAiB;;;;;;;;;;MA0B3B;IAED;;;;;OAKG;IACH,iBAHc,MAAM,KACP;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,WAJW;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,WACvC,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAU5C;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,UAJW,MAAM;;;QAEJ,IAAI,CAehB;IAED;;;;;;;;OAQG;IACH,SAFa,iBAAiB,CA+B7B;;CAgDJ;kCA7SiC,wBAAwB"}
+{"version":3,"file":"ParticleGroupBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleGroupBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAaI;;OAEG;IACH,qBAFW,MAAM,EAoBhB;IAjCD;;;OAGG;IACH,OAFU,iBAAiB,CAErB;IAEN;;;OAGG;IACH;YAFiB,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC;MAEjD;IAyBR;;;;;;;;;;;OAWG;IACH,SALW,MAAM,SACN,MAAM;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,CAAC,eAC9C,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAmB5C;IAED;;;;;;;;;OASG;IACH,YAJW,iBAAiB;YACV,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC,GAAC,MAAM;;YAC7C,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC;MAwB3D;IAED;;;;;OAKG;IACH,iBAHc,MAAM,KACP;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,WAJW;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,WACvC,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAU5C;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,UAJW,MAAM,SACN;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GACrC,IAAI,CAehB;IAED;;;;;;;;OAQG;IACH,SAFa,iBAAiB,CA+B7B;;CAgDJ;kCA7SiC,wBAAwB"}

package/src/shade/renderer/particles/graph/ParticleNodeGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleNodeGroup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js"],"names":[],"mappings":"AAiWA;;;;;GAKG;AACH,6CAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;GAKG;AACH,iDAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,6EAFa,OAAO,CAKnB;AA3XD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;GAEG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH;IA2EI;;;;;;;;;;;;;;;OAeG;IACH;QAT2B,IAAI,EAApB,MAAM;QACW,KAAK,GAAtB,MAAM;QACW,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACmF,MAAM,GAAhG,MAAM;YAAC,MAAM,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QACW,OAAO,GAAjG,MAAM;YAAC,MAAM,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QAC7E,iBAAiB,CA2B7B;IAnHD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,OAAO,CAEH;IAEd;;;;OAIG;IACH,QAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAElF;IAEZ;;;OAGG;IACH,SAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAEjF;IAEb;;;OAGG;IACH,OAFU,SAAS,CAEK;IAExB;;;OAGG;IACH,QAFU,mBAAmB,CAEM;IAEnC;;;OAGG;IACH,aAFU,4BAA4B,CAEnB;IAEnB;;;OAGG;IACH,WAFU,YAAY,CAEL;IAEjB;;;OAGG;IACH,YAFU,YAAY,CAEJ;IA6ClB;;;;;;OAMG;IACH,oBAJW,MAAM,aACN,aAAa,GACX,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAMnE;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CAN9C;AAQD;;;;;;;GAOG;AACH;IACI;;OAEG;IACH,mBAFW,iBAAiB,EAwD3B;IAnDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAwBlB;;;;;;;;;;MAeC;IAED,kBAKC;IAIT;;;OAGG;IACH,yCAFU,OAAO,CAEoD;CANpE;AAQD;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,mBAHW,iBAAiB,QACjB,MAAM,EAqDhB;IAhDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAElB;;;;OAIG;IACH,eAFU,MAAM,CAEA;IAoBhB;;;;;;;;;;;;MASM;IAEN,kBAKC;IAIT;;;OAGG;IACH,6CAFU,OAAO,CAE4D;CAN5E;6BAxV4B,wDAAwD;0BAD3D,gDAAgD;oCAGtC,iEAAiE;8BADvE,yDAAyD;wCAE/C,8BAA8B"}
+{"version":3,"file":"ParticleNodeGroup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js"],"names":[],"mappings":"AAiWA;;;;;GAKG;AACH,6CAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;GAKG;AACH,iDAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,6EAFa,OAAO,CAKnB;AA3XD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;GAEG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH;IA2EI;;;;;;;;;;;;;;;OAeG;IACH;QAT2B,IAAI,EAApB,MAAM;QACW,KAAK,GAAtB,MAAM;QACW,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACmF,MAAM,GAAhG,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QACW,OAAO,GAAjG,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QAC7E,iBAAiB,CA2B7B;IAnHD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,OAAO,CAEH;IAEd;;;;OAIG;IACH,QAFU,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAElF;IAEZ;;;OAGG;IACH,SAFU,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAEjF;IAEb;;;OAGG;IACH,OAFU,SAAS,CAEK;IAExB;;;OAGG;IACH,QAFU,mBAAmB,CAEM;IAEnC;;;OAGG;IACH,aAFU,4BAA4B,CAEnB;IAEnB;;;OAGG;IACH,WAFU,YAAY,CAEL;IAEjB;;;OAGG;IACH,YAFU,YAAY,CAEJ;IA6ClB;;;;;;OAMG;IACH,oBAJW,MAAM,aACN,aAAa,GACX,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAMnE;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CAN9C;AAQD;;;;;;;GAOG;AACH;IACI;;OAEG;IACH,mBAFW,iBAAiB,EAwD3B;IAnDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAwBlB;;;;;;;;;;MAeC;IAED,kBAKC;IAIT;;;OAGG;IACH,yCAFU,OAAO,CAEoD;CANpE;AAQD;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,mBAHW,iBAAiB,QACjB,MAAM,EAqDhB;IAhDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAElB;;;;OAIG;IACH,eAFU,MAAM,CAEA;IAoBhB;;;;;;;;;;;;MASM;IAEN,kBAKC;IAIT;;;OAGG;IACH,6CAFU,OAAO,CAE4D;CAN5E;6BAxV4B,wDAAwD;0BAD3D,gDAAgD;oCAGtC,iEAAiE;8BADvE,yDAAyD;wCAE/C,8BAA8B"}

package/src/shade/renderer/particles/graph/ParticleValueType.d.ts

@@ -58,7 +58,7 @@ export function particle_type_conversion(from: ParticleValueType, to: ParticleVa
     dropped?: string;
     zeroed?: string;
     message: string;
-};
+} | null;
 /**
  * The types a value in a particle graph can have: a float vector of one to four lanes, and the
  * types that say what such a vector *means*.

package/src/shade/renderer/particles/graph/ParticleValueType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleValueType.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleValueType.js"],"names":[],"mappings":"AAqKA;;;;;;;;;;GAUG;AACH,mDAFa,iBAAiB,GAAC,IAAI,CAQlC;AAED;;;;;;;;;GASG;AACH,gDAJW,MAAM,GACJ,iBAAiB,CAW7B;AAED;;;;;;;GAOG;AACH,8DAFa,iBAAiB,GAAC,IAAI,CAQlC;AAED;;;;;;;;;;;;GAYG;AACH,4CAHW,SAAS,iBAAiB,GAAC,IAAI,GAAC,SAAS,CAAC,GACxC,iBAAiB,GAAC,IAAI,CAkBlC;AAKD;;;;;;;;;GASG;AACH,+CALW,iBAAiB,MACjB,iBAAiB;cACJ,MAAM;aAAW,MAAM;aAAW,MAAM;EAyB/D;AA3RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAwBI;;;;;;;OAOG;IACH,gBAPW,MAAM,QACN,MAAM,cACN,MAAM;QAEY,QAAQ,GAA1B,OAAO;QACL,iBAAiB,CAU7B;IAvCD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;OAOG;IACH,UAFU,OAAO,CAEA;IAEjB;;OAEG;IACH,yBAEC;IAqBL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CAN9C;AAQD,gCAAgC;AAChC,gCADW,iBAAiB,CACyC;AAErE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;GASG;AACH,kCAFU,iBAAiB,CAE0F;AAErH;;;GAGG;AACH,mCAFU,cAAc,iBAAiB,CAAC,CAOvC;AAEH;;;GAGG;AACH,sCAFU,cAAc,iBAAiB,CAAC,CAIvC;AAEH;;;GAGG;AACH,uCAFU,cAAc,iBAAiB,CAAC,CAKvC;yBA9JsB,oDAAoD"}
+{"version":3,"file":"ParticleValueType.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleValueType.js"],"names":[],"mappings":"AAqKA;;;;;;;;;;GAUG;AACH,mDAFa,iBAAiB,GAAC,IAAI,CAQlC;AAED;;;;;;;;;GASG;AACH,gDAJW,MAAM,GACJ,iBAAiB,CAW7B;AAED;;;;;;;GAOG;AACH,8DAFa,iBAAiB,GAAC,IAAI,CAQlC;AAED;;;;;;;;;;;;GAYG;AACH,4CAHW,SAAS,iBAAiB,GAAC,IAAI,GAAC,SAAS,CAAC,GACxC,iBAAiB,GAAC,IAAI,CAkBlC;AAKD;;;;;;;;;GASG;AACH,+CALW,iBAAiB,MACjB,iBAAiB,GACf;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAyBrE;AA3RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH;IAwBI;;;;;;;OAOG;IACH,gBAPW,MAAM,QACN,MAAM,cACN,MAAM;QAEY,QAAQ,GAA1B,OAAO;QACL,iBAAiB,CAU7B;IAvCD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;OAOG;IACH,UAFU,OAAO,CAEA;IAEjB;;OAEG;IACH,yBAEC;IAqBL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CAN9C;AAQD,gCAAgC;AAChC,gCADW,iBAAiB,CACyC;AAErE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE,gCAAgC;AAChC,iCADW,iBAAiB,CAC2C;AAEvE;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;GASG;AACH,kCAFU,iBAAiB,CAE0F;AAErH;;;GAGG;AACH,mCAFU,cAAc,iBAAiB,CAAC,CAOvC;AAEH;;;GAGG;AACH,sCAFU,cAAc,iBAAiB,CAAC,CAIvC;AAEH;;;GAGG;AACH,uCAFU,cAAc,iBAAiB,CAAC,CAKvC;yBA9JsB,oDAAoD"}

package/src/shade/renderer/particles/graph/make_particle_group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_particle_group.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/make_particle_group.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB6B,KAAK;IACE,KAAK,EAA9B,SAAS,MAAM,CAAC;IACD,IAAI,EAAnB,MAAM;IACU,KAAK,GAArB,MAAM;IACU,IAAI,GAApB,MAAM;IACU,IAAI,GAApB,MAAM;IACuB,MAAM;IAII,cAAc;IAES,MAAM,GAApE,OAAO,6BAA6B,EAAE,cAAc;;WAGnD,iBAAiB;YAChB,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;aACxD,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;KAAC,CAAC;EAgE3E;kCAnI6D,wBAAwB"}
+{"version":3,"file":"make_particle_group.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/make_particle_group.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB6B,KAAK;IACE,KAAK,EAA9B,SAAS,MAAM,CAAC;IACD,IAAI,EAAnB,MAAM;IACU,KAAK,GAArB,MAAM;IACU,IAAI,GAApB,MAAM;IACU,IAAI,GAApB,MAAM;IACuB,MAAM;IAII,cAAc;IAES,MAAM,GAApE,OAAO,6BAA6B,EAAE,cAAc;IAElD;IACZ,KAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAU,EAAE,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC,CAAC;IACtE,OAAW,EAAE,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;KAAC,CAAC,CAAA;CACxE,CA+DH;kCAnI6D,wBAAwB"}

package/src/shade/renderer/particles/graph/particle_graph_authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,sDALW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM;UACiB,MAAM;WAAS,MAAM;IAC1C,MAAM,CA2BlB;AA2BD;;;;;GAKG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}
+{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,sDALW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM,UACN,MAAM,GAAC,MAAM,EAAE,GAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,GAC3C,MAAM,CA2BlB;AA2BD;;;;;GAKG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}

package/src/shade/renderer/particles/graph/particle_group_json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_group_json.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_group_json.js"],"names":[],"mappings":"AA+CA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,gDAHW,OAAO,wBAAwB,EAAE,iBAAiB,GAChD,iBAAiB,CAmC7B;AAED;;;;;;;;;;GAUG;AACH;IAPqC,IAAI,EAA9B,iBAAiB;IACsB,cAAc;IAES,OAAO,UAA5D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;IAElD,OAAO,wBAAwB,EAAE,iBAAiB,CAiD9D;AAED;;;;;;;GAOG;AACH,mDAHW,OAAO,wBAAwB,EAAE,iBAAiB,GAChD,OAAO,8BAA8B,EAAE,uBAAuB,EAAE,CAI5E;AA9JD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AACH,wCAFU,MAAM,CAEwC;AAExD;;GAEG;AACH,yCAFU,MAAM,CAE0C;;UAS5C,MAAM;WACN,MAAM;UACN,MAAM;UACN,MAAM;YACN,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC;aACxC,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC;UACxC,OAAO,0BAA0B,EAAE,iBAAiB"}
+{"version":3,"file":"particle_group_json.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_group_json.js"],"names":[],"mappings":"AA+CA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,gDAHW,OAAO,wBAAwB,EAAE,iBAAiB,GAChD,iBAAiB,CAmC7B;AAED;;;;;;;;;;GAUG;AACH;IAPqC,IAAI,EAA9B,iBAAiB;IACsB,cAAc;IAES,OAAO,UAA5D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;IAElD,OAAO,wBAAwB,EAAE,iBAAiB,CAiD9D;AAED;;;;;;;GAOG;AACH,mDAHW,OAAO,wBAAwB,EAAE,iBAAiB,GAChD,OAAO,8BAA8B,EAAE,uBAAuB,EAAE,CAI5E;AA9JD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AACH,wCAFU,MAAM,CAEwC;AAExD;;GAEG;AACH,yCAFU,MAAM,CAE0C;;UAS5C,MAAM;WACN,MAAM;UACN,MAAM;UACN,MAAM;YACN,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC;aACxC,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC;UACxC,OAAO,0BAA0B,EAAE,iBAAiB"}

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

@@ -59,6 +59,17 @@
  * passes must read — exactly the ReSTIR reservoir pattern. Every persistent buffer is imported
  * exactly once: two imports of one buffer are two resource entries the graph cannot tell apart.
  *
+ * ## What is imported, and what the graph owns
+ *
+ * A buffer is imported only if its contents cross the frame boundary: the pool, the free list, the
+ * counters, the alive lists, `sim_list` (written here, read by next frame's simulate),
+ * `dispatch_args` (the same), the program blob and the two CPU-uploaded queues. Everything else is
+ * 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/`).
+ *
  * 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.
  */

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;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,CAuTrC;;;;;UA/Va,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}