@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/object_property/chunk_write_object_property_node3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_write_object_property_node3d.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/object_property/chunk_write_object_property_node3d.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,iDAFU,SAAS,CA4Bb;0BA9DoB,iCAAiC"}
+{"version":3,"file":"chunk_write_object_property_node3d.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/object_property/chunk_write_object_property_node3d.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iDAFU,SAAS,CA6Bb;0BArEoB,iCAAiC"}

package/src/shade/renderer/object_property/chunk_write_object_property_node3d.js

@@ -31,7 +31,13 @@ import { Node3DProperty } from "./Node3DProperty.js";
  * `mask` is the per-channel write gate. Translation and Scale respect
  * it per axis (the accumulator's per-axis dirty bits ensure the
  * resolve pass only overwrites the channels that were actually
- * contributed); Rotation needs all four channels and ignores the mask.
+ * contributed); Rotation needs all four channels, and uses the mask
+ * only to tell a missing `w` curve from an authored zero.
+ *
+ * `weight` is the clip weight `value` has already been multiplied by.
+ * Rotation needs it because the identity it substitutes for a missing
+ * channel has to carry the same weight as the channels that were
+ * authored; nothing else here does.
  *
  * @type {CodeChunk}
  */
@@ -43,6 +49,7 @@ fn write_object_property_node3d(
     property: u32,
     mask: u32,
     value: vec4f,
+    weight: f32,
 ) {
     let node_index = instance & 0x00FFFFFFu;
 
@@ -51,7 +58,7 @@ fn write_object_property_node3d(
             pose_accumulator_add_translation(node_index, value.xyz, mask);
         }
         case ${Node3DProperty.Rotation}u: {
-            pose_accumulator_add_rotation(node_index, value, mask);
+            pose_accumulator_add_rotation(node_index, value, mask, weight);
         }
         case ${Node3DProperty.Scale}u: {
             pose_accumulator_add_scale(node_index, value.xyz, mask);

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

@@ -62,14 +62,23 @@ words = 128 B). Word 0 is a reserved header holding the owning **emitter row** a
 pool + single alive/dead lists means **one** emit dispatch and **one** simulate dispatch cover every
 emitter — the Destiny single-shader property.
 
-Lifecycle uses the canonical GPU dead-list / alive-list ping-pong:
-- `dead_list`: stack of free slot indices (+ atomic count).
-- `alive_list[2]`: ping-pong compact lists of live slot indices (+ counts).
+Lifecycle uses the canonical GPU dead-list / alive-list pair:
+- `dead_list`: stack of free slot indices (+ atomic count). Filled `dead[i] = i` at construction by
+  `shaders/shader_particle_init_free_list.js` — a dispatch, not a host upload, which is why the
+  buffer carries no `COPY_DST`.
+- `alive_list`: a compact list of live slot indices (+ count), rebuilt from scratch every frame.
 - `counters`: atomics {alive_count, dead_count, spawn budget, …} + derived indirect dispatch/draw args.
 
 Emit: pop dead → run INIT → append `alive_new`. Simulate: read the **coherence list** last frame's
 bucketing pass built from `alive_current` → run UPDATE → kill pushes to `dead`, survival appends to
-`alive_new`. Swap lists each frame.
+`alive_new`.
+
+There is no ping-pong pair, although the shape invites one. The frame appends to the new list from a
+counter its first pass zeroes and the draws walk that same new list, so the previous frame's list has
+exactly one reader in the whole design: the bucketing rebuild on a frame whose program assignments
+changed. So the list is taken from the graphics context's buffer allocator and given back every
+frame, before the next is asked for — the pool answers with the same memory, the reserved footprint
+is one list, and only a rebuild frame holds two. See `GPUParticleSystem#swap_alive_list`.
 
 **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
@@ -560,6 +569,13 @@ chunk (`chunk_particle_billboard_vertex`), shared by the splat, the draw and the
 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 particles are no longer the only side channel: the dynamic meshes' (`DynamicMeshAVBOITChannel`,
+which trails are drawn through) meets the same three contracts, and the two share what they have in
+common rather than each keeping a copy — the box's depth interval and the slice marking
+(`aabb3_view_depth_range`, `avboit_occupancy_mark`), the coverage clamp (`avboit_coverage`) and
+everything `chunk_particle_avboit_contribution` does after its premultiply
+(`avboit_premultiplied_contribution`). A change to any of those changes both channels.
+
 ### The ECS: `ParticleEffect` + `Transform64`
 
 `engine/graphics3/GPUParticleEmitterSystem.js` is how a game reaches this system. It is an ordinary
@@ -644,7 +660,7 @@ through `GPUTextureContext`.
 
 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
+pool, alive list, 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

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

@@ -20,7 +20,7 @@
  * ## What it owns
  *
  * 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
+ * to survive to the next frame. That is the particle pool, the alive list, 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
@@ -37,6 +37,22 @@
  * 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.
  *
+ * ## The alive list is borrowed, not reserved
+ *
+ * The alive list crosses the frame boundary and so cannot be the graph's — but it does not have to
+ * be the feature's either. It is taken from the graphics context's buffer allocator and given back
+ * every frame ({@link #swap_alive_list}), which is the difference between one list and two.
+ *
+ * Two was the obvious reading of the ping-pong: the frame builds a new list while the previous one
+ * is still there to be read. But nothing reads the previous one. Emit and simulate append to the
+ * new list from a counter the frame resets to zero, the draws walk that same new list, and the only
+ * pass that ever looks at the one before it is the bucketing rebuild on a frame whose program
+ * assignments changed — a live program edit, not a frame. So on an ordinary frame the previous list
+ * goes back to the pool BEFORE the new one is asked for, the pool answers with the same memory, and
+ * the feature's reserved footprint is one list rather than two. On the rare frame that does rebuild,
+ * the old list is held one frame longer — until the graph recorded around it has been submitted —
+ * and the feature briefly costs what it used to cost always.
+ *
  * 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
  * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
@@ -123,7 +139,7 @@ export class GPUParticleSystem {
      */
     registry: EmitterRegistry;
     /**
-     * Frames elapsed. Drives the alive-list ping-pong and the VM's frame builtin.
+     * Frames elapsed. The VM's frame builtin.
      * @type {number}
      */
     frame: number;
@@ -151,6 +167,10 @@ export class GPUParticleSystem {
      * them — never for the frame loop, which reads nothing back. Entries that grow with the
      * emitter set are replaced in place.
      *
+     * `alive` and `alive_write` are one buffer under two names — what the feature holds, and what
+     * the frame writes — and `alive_read` is the previous frame's list, present only on the frames
+     * that read one. The list itself belongs to the allocator, not here; see {@link #swap_alive_list}.
+     *
      * @type {object}
      */
     buffers: object;
@@ -178,11 +198,6 @@ export class GPUParticleSystem {
      * @returns {number}
      */
     bucketCount(): number;
-    /**
-     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
-     * @returns {number}
-     */
-    get alive_write_index(): number;
     /**
      * Ask for `count` particles from an emitter, on top of its rate, on the next frame. Goes
      * through the GPU path — the tick pass folds it into the emitter's accumulator, the budget and
@@ -330,9 +345,9 @@ export class GPUParticleSystem {
     set_transform_row(emitter: import("./runtime/ParticleEmitter.js").ParticleEmitter, transform_row: number): void;
     /**
      * 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.
+     * this is the feature's footprint and not a list of the names it binds them under.
+     * `alive_write` is `alive` under the frame's name for it and would otherwise be counted twice;
+     * `alive_read` is a second list, and appears only on the frames that hold one. Exposed for tests.
      *
      * @returns {Object<string, number>}
      */

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
 import { warn_limited } from "../../util/warn_limited.js";
 import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
 import {
@@ -19,6 +20,10 @@ import {
     particle_counters_word_count,
 } from "./data/PARTICLE_COUNTERS.js";
 import { graph_particles_simulate } from "./graph_particles.js";
+import {
+    PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE,
+    shader_particle_init_free_list,
+} from "./shaders/shader_particle_init_free_list.js";
 import {
     graph_particle_avboit_draw,
     graph_particle_avboit_occupancy,
@@ -38,7 +43,7 @@ const WORD = Uint32Array.BYTES_PER_ELEMENT;
  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. */
+/** Written only by shaders. The free list is one of these: `init_free_list` fills it on-device. */
 const STORAGE = GPUBufferUsage.STORAGE;
 /** Seeded or refilled from the host with `writeBuffer`. */
 const STORAGE_UPLOAD = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
@@ -76,7 +81,7 @@ const DEFAULT_CAPACITY = 524288;
  * ## What it owns
  *
  * 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
+ * to survive to the next frame. That is the particle pool, the alive list, 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
@@ -93,6 +98,22 @@ const DEFAULT_CAPACITY = 524288;
  * 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.
  *
+ * ## The alive list is borrowed, not reserved
+ *
+ * The alive list crosses the frame boundary and so cannot be the graph's — but it does not have to
+ * be the feature's either. It is taken from the graphics context's buffer allocator and given back
+ * every frame ({@link #swap_alive_list}), which is the difference between one list and two.
+ *
+ * Two was the obvious reading of the ping-pong: the frame builds a new list while the previous one
+ * is still there to be read. But nothing reads the previous one. Emit and simulate append to the
+ * new list from a counter the frame resets to zero, the draws walk that same new list, and the only
+ * pass that ever looks at the one before it is the bucketing rebuild on a frame whose program
+ * assignments changed — a live program edit, not a frame. So on an ordinary frame the previous list
+ * goes back to the pool BEFORE the new one is asked for, the pool answers with the same memory, and
+ * the feature's reserved footprint is one list rather than two. On the rare frame that does rebuild,
+ * the old list is held one frame longer — until the graph recorded around it has been submitted —
+ * and the feature briefly costs what it used to cost always.
+ *
  * 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
  * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
@@ -173,7 +194,7 @@ export class GPUParticleSystem {
     registry;
 
     /**
-     * Frames elapsed. Drives the alive-list ping-pong and the VM's frame builtin.
+     * Frames elapsed. The VM's frame builtin.
      * @type {number}
      */
     frame = 0;
@@ -206,6 +227,10 @@ export class GPUParticleSystem {
      * them — never for the frame loop, which reads nothing back. Entries that grow with the
      * emitter set are replaced in place.
      *
+     * `alive` and `alive_write` are one buffer under two names — what the feature holds, and what
+     * the frame writes — and `alive_read` is the previous frame's list, present only on the frames
+     * that read one. The list itself belongs to the allocator, not here; see {@link #swap_alive_list}.
+     *
      * @type {object}
      */
     buffers = {};
@@ -216,6 +241,32 @@ export class GPUParticleSystem {
      */
     #sim_bucket_capacity = 0;
 
+    /**
+     * What the alive list is asked for under: one `u32` per pool slot, touched by nothing but
+     * shaders, and deliberately not cleared — every entry a reader sees was appended this frame,
+     * from a counter the frame's first pass resets to zero, so whatever the last borrower left in
+     * it is unreadable by construction. One instance, reused: the pool reads a descriptor and does
+     * not keep it.
+     *
+     * @type {BufferResourceDescriptor}
+     */
+    #alive_descriptor;
+
+    /**
+     * The alive list the last recorded frame built — the next frame's `alive_read`. Borrowed from
+     * `graphics.buffer_allocator_main`, so it is released rather than destroyed.
+     * @type {GPUBuffer|null}
+     */
+    #alive = null;
+
+    /**
+     * An alive list a recorded frame still reads: the bucketing rebuild's input on a frame whose
+     * program assignments changed. Handed back on the next {@link execute}, by which point that
+     * frame's graph has been executed and submitted.
+     * @type {GPUBuffer|null}
+     */
+    #alive_retired = null;
+
     /**
      * The spawn-command ring: `[row, count]` pairs, filled by {@link spawn}, merged and uploaded on
      * the next {@link execute}.
@@ -355,14 +406,6 @@ export class GPUParticleSystem {
         return Math.max(1, this.registry.program_id_capacity);
     }
 
-    /**
-     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
-     * @returns {number}
-     */
-    get alive_write_index() {
-        return 1 - (this.frame % 2);
-    }
-
     /**
      * Ask for `count` particles from an emitter, on top of its rate, on the next frame. Goes
      * through the GPU path — the tick pass folds it into the emitter's accumulator, the budget and
@@ -444,8 +487,9 @@ export class GPUParticleSystem {
         emitters.group_count = table.dispatch_group_count(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE);
 
         const buffers = this.buffers;
-        buffers.alive_write = buffers.alive[this.alive_write_index];
-        buffers.alive_read = buffers.alive[1 - this.alive_write_index];
+
+        this.#swap_alive_list(frame.rebucket);
+
         // The table's database owns and grows its own buffer; it is re-read every frame for that
         // reason.
         buffers.emitter_database = this.registry.database.buffer;
@@ -907,6 +951,107 @@ export class GPUParticleSystem {
         this.#sim_bucket_capacity = buckets;
     }
 
+    /**
+     * Give this frame its alive list, and hand back the ones nothing reads any more.
+     *
+     * The list is the allocator's memory on loan rather than a pair of buffers reserved here — see
+     * the class doc. Three things happen, in this order:
+     *
+     *  1. A list an earlier frame retired goes back. That frame's graph has been recorded, executed
+     *     and submitted since, so the bucketing pass that was reading it is done.
+     *  2. The previous frame's list goes back too — BEFORE the new one is asked for, so that the
+     *     pool can answer with the same memory and the steady-state footprint is one list. Skipped
+     *     when this frame rebuilds the buckets, because that pass reads it; it is retired instead
+     *     and goes back on the next call, one step behind.
+     *  3. The new list is taken. Uncleared: the frame appends to it from a counter its first pass
+     *     zeroes, so no reader can reach what the last borrower left.
+     *
+     * The pool may answer with a larger buffer than asked for, which changes nothing — every
+     * reader is bounded by a count, never by the buffer's length.
+     *
+     * @param {boolean} rebucket whether this frame's bucketing rebuild reads the previous list
+     */
+    #swap_alive_list(rebucket) {
+        const allocator = this.graphics.buffer_allocator_main;
+        const buffers = this.buffers;
+        const previous = this.#alive;
+
+        // One is taken at construction and none is ever let go without another taking its place, so
+        // there is always a previous list — including on the first frame, which can already be a
+        // rebucket if a program was edited before it.
+        assert.notNull(previous, "the previous alive list");
+
+        if (this.#alive_retired !== null) {
+            allocator.release(this.#alive_retired);
+            this.#alive_retired = null;
+        }
+
+        if (rebucket) {
+            this.#alive_retired = previous;
+        } else {
+            allocator.release(previous);
+        }
+
+        const alive = allocator.get(this.#alive_descriptor);
+
+        this.#alive = alive;
+
+        buffers.alive = alive;
+        buffers.alive_write = alive;
+        // Named only on the frames that read one: on every other frame `previous` has already gone
+        // back to the pool, and may be somebody else's by the time the graph runs.
+        buffers.alive_read = rebucket ? previous : undefined;
+    }
+
+    /**
+     * Hand every alive list back to the allocator and stop naming them.
+     *
+     * {@link destroy} cannot simply destroy them with the rest: the memory is the pool's, and a
+     * pooled buffer destroyed behind the pool's back is a handle it will hand to the next caller.
+     */
+    #release_alive_lists() {
+        const allocator = this.graphics.buffer_allocator_main;
+
+        if (this.#alive !== null) {
+            allocator.release(this.#alive);
+            this.#alive = null;
+        }
+
+        if (this.#alive_retired !== null) {
+            allocator.release(this.#alive_retired);
+            this.#alive_retired = null;
+        }
+
+        delete this.buffers.alive;
+        delete this.buffers.alive_write;
+        delete this.buffers.alive_read;
+    }
+
+    /**
+     * Fill the free list with every slot, on the GPU — see `shaders/shader_particle_init_free_list.js`
+     * for why this is a dispatch and not a host write.
+     *
+     * The launch is clamped to what a dispatch dimension holds and the shader strides through the
+     * rest: at the default capacity this is a couple of thousand workgroups, but the capacity is
+     * the caller's to choose and a dispatch past `maxComputeWorkgroupsPerDimension` is refused.
+     */
+    #init_free_list() {
+        const device = this.graphics.device;
+
+        const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/free list init");
+
+        shader_particle_init_free_list.dispatch({
+            encoder: cmd,
+            group_count_x: Math.min(
+                Math.ceil(this.capacity / PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE),
+                device.limits.maxComputeWorkgroupsPerDimension,
+            ),
+            bindings: { dead: this.buffers.dead, u_capacity: this.capacity },
+        });
+
+        cmd.finish();
+    }
+
     /**
      * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
      */
@@ -916,11 +1061,12 @@ export class GPUParticleSystem {
         const buffers = this.buffers;
 
         buffers.pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * WORD, usage: STORAGE });
-        buffers.alive = [
-            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_UPLOAD });
+
+        this.#alive_descriptor = BufferResourceDescriptor.from(capacity * WORD, STORAGE);
+        this.#alive = this.graphics.buffer_allocator_main.get(this.#alive_descriptor);
+        buffers.alive = this.#alive;
+
+        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
         // 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_GROWABLE });
@@ -936,16 +1082,14 @@ export class GPUParticleSystem {
         // 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_UPLOAD });
 
-        // Every slot free, and the counters saying so.
-        const dead = new Uint32Array(capacity);
-        for (let i = 0; i < capacity; i++) {
-            dead[i] = i;
-        }
+        // The counters say every slot is free; the pass below makes it so. A handful of words is
+        // the whole of what the host ever writes into either — the list itself is the GPU's.
         const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
         counters[PARTICLE_COUNTER.DEAD] = capacity;
 
-        device.queue.writeBuffer(buffers.dead, 0, dead);
         device.queue.writeBuffer(buffers.counters, 0, counters);
+
+        this.#init_free_list();
     }
 
     /**
@@ -978,9 +1122,9 @@ export class GPUParticleSystem {
 
     /**
      * 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.
+     * this is the feature's footprint and not a list of the names it binds them under.
+     * `alive_write` is `alive` under the frame's name for it and would otherwise be counted twice;
+     * `alive_read` is a second list, and appears only on the frames that hold one. Exposed for tests.
      *
      * @returns {Object<string, number>}
      */
@@ -988,15 +1132,13 @@ export class GPUParticleSystem {
         const sizes = {};
         const counted = new Set();
 
-        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;
+        for (const [name, buffer] of Object.entries(this.buffers)) {
+            if (buffer === undefined || buffer === null || counted.has(buffer)) {
+                continue;
             }
+
+            counted.add(buffer);
+            sizes[name] = buffer.size;
         }
 
         return sizes;
@@ -1061,10 +1203,12 @@ export class GPUParticleSystem {
             this.registry.remove(emitter);
         }
 
+        // Before the loop below, and not in it: the alive lists are the allocator's and go back to
+        // it. Destroying one would leave the pool holding a handle it will hand to the next caller.
+        this.#release_alive_lists();
+
         for (const buffer of Object.values(this.buffers)) {
-            if (Array.isArray(buffer)) {
-                buffer.forEach((b) => b.destroy());
-            } else if (buffer !== undefined && buffer !== null) {
+            if (buffer !== undefined && buffer !== null) {
                 buffer.destroy();
             }
         }

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,yCAFU,MAAM,CAEwC;AAExD;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D,uEAAuE;AACvE,gDAAiD;AAEjD,uFAAuF;AACvF,2DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,qBAAqB,CAKA;AAE/B;;;;;;GAMG;AACH,kEAA8F;AAE9F;;;;;GAKG;AACH,wEAA0G;sCAlEpE,6CAA6C"}
+{"version":3,"file":"PARTICLE_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,yCAFU,MAAM,CAEwC;AAExD;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D,uEAAuE;AACvE,gDAAiD;AAEjD,uFAAuF;AACvF,2DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,qBAAqB,CAKA;AAc/B;;;;;;GAMG;AACH,kEAA8F;AAE9F;;;;;GAKG;AACH,wEAA0G;sCA/EpE,6CAA6C"}