@woosh/meep-engine 3.29.0 → 3.30.0

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
@@ -644,7 +653,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/graph/groups/simplex_reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simplex_reference.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/simplex_reference.js"],"names":[],"mappings":"AAyGA;;;;;GAKG;AACH,0CAHW,MAAM,EAAE,GACN,MAAM,CA2ElB"}
+{"version":3,"file":"simplex_reference.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/simplex_reference.js"],"names":[],"mappings":"AA+GA;;;;;GAKG;AACH,0CAHW,MAAM,EAAE,GACN,MAAM,CA2ElB"}

package/src/shade/renderer/particles/graph/groups/simplex_reference.js

@@ -18,8 +18,14 @@
  * double-precision oracle takes the other branch there and disagrees with the VM about a third of the
  * time, and it would be the one that was wrong: a GPU is `f32` too.
  *
- * So `fr` is applied wherever the VM would have stored a register, and nowhere else. Sums inside a
- * dot product are not rounded per term, because the opcode accumulates and stores once.
+ * So `fr` is applied wherever the VM would have stored a register — and inside `DOT` and
+ * `NORMALIZE` as well, because the shader computes those entirely in f32 and the reference executor
+ * now does the same. This file used to say the sum was accumulated wide and rounded once, which was
+ * a faithful transcription of a reference VM that summed in f64: f32 results without f32 range.
+ *
+ * The one place `fr` is deliberately absent from an intermediate is a product the group spells as a
+ * `MAD` — `row * ns_x + ns_y`, and the two reflections below it. `MAD` models the fused form, so
+ * its product is not rounded on either executor; see the opcode in {@link ../../vm/ParticleVMReference.js}.
  */
 
 /** @type {function(number):number} */
@@ -34,16 +40,16 @@ const G3 = 1 / 6;
 /**
  * @param {number[]} a
  * @param {number[]} b
- * @returns {number} the dot product, accumulated wide and rounded once, as `DOT` does
+ * @returns {number} the dot product, every step of it in f32, as `DOT` does
  */
 function dot(a, b) {
     let sum = 0;
 
     for (let i = 0; i < a.length; i++) {
-        sum += a[i] * b[i];
+        sum = fr(sum + fr(a[i] * b[i]));
     }
 
-    return fr(sum);
+    return sum;
 }
 
 /**
@@ -58,8 +64,8 @@ function step(edge, x) {
 }
 
 /**
- * `NORMALIZE`, as the opcode does it: the length is accumulated and taken wide and only the lanes
- * are rounded, and a zero vector normalises to zero rather than to nothing.
+ * `NORMALIZE`, as the opcode does it: every step of the length in f32, and a zero vector normalises
+ * to zero rather than to nothing.
  *
  * The group used to spell this as Gustavson's `taylorInvSqrt` — a line through the band the gradient
  * table's squared lengths fall in — and now calls the opcode, which is one instruction rather than
@@ -73,12 +79,12 @@ function normalize(v) {
     let sum = 0;
 
     for (const component of v) {
-        sum += component * component;
+        sum = fr(sum + fr(component * component));
     }
 
-    const length = Math.sqrt(sum);
+    const length = fr(Math.sqrt(sum));
 
-    const inverse = length > 0 ? 1 / length : 0;
+    const inverse = length > 0 ? fr(1 / length) : 0;
 
     return v.map(component => fr(component * inverse));
 }

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

@@ -59,7 +59,7 @@
  * ## 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),
+ * counters, the alive list, `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
@@ -85,7 +85,9 @@
  * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
  * @param {number} params.camera graph handle of the view's camera uniform (`CAMERA_UNIFORM_STRUCT`)
  * @param {number} params.scene_database graph handle of the scene database — the emitters' nodes
- * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}
+ * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}. `gpu.alive_read`
+ *   is the exception: it is the previous frame's alive list and is present only when
+ *   `frame.rebucket` says this frame reads one
  * @param {object} params.emitters the emitter table's shape this frame
  * @param {number} params.emitters.capacity the table's element capacity — the length of the count
  *   list the scan consumes

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA7BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACS,GAAG,EAAlB,MAAM;IACS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACiB,QAAQ,GAA/B,OAAO;QACc,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;QACe,YAAY,EAAjC,MAAM;QAGe,eAAe,EAApC,MAAM;QAC6D,eAAe,EAAlF,OAAO,6BAA6B,EAAE,cAAc;;IAElD,yBAAyB,CA4TrC;;;;;UAlWa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;;sBACN,MAAM"}
+{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IA/BkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACS,GAAG,EAAlB,MAAM;IAGS,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,CAgUrC;;;;;UAxWa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;;sBACN,MAAM"}

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

@@ -98,7 +98,7 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  * ## 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),
+ * counters, the alive list, `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
@@ -126,7 +126,9 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
  * @param {number} params.camera graph handle of the view's camera uniform (`CAMERA_UNIFORM_STRUCT`)
  * @param {number} params.scene_database graph handle of the scene database — the emitters' nodes
- * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}
+ * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}. `gpu.alive_read`
+ *   is the exception: it is the previous frame's alive list and is present only when
+ *   `frame.rebucket` says this frame reads one
  * @param {object} params.emitters the emitter table's shape this frame
  * @param {number} params.emitters.capacity the table's element capacity — the length of the count
  *   list the scan consumes
@@ -197,6 +199,10 @@ export function graph_particles_simulate({
     if (frame.rebucket) {
         // Live program edits can split a previously uniform wave. Rebuild from the previous
         // compact alive list BEFORE reset discards its count and before simulate broadcasts code.
+        //
+        // `gpu.alive_read` exists only here. It is the one reader the previous frame's list ever
+        // has, which is why the feature holds one list rather than a ping-pong pair and keeps the
+        // old one only across a frame that rebuckets — see `GPUParticleSystem#swap_alive_list`.
         const bucketed = graph_particle_bucket({
             graph, emitter_database, pool, counters, capacity, bucket_count,
             alive: graph_import_buffer(graph, gpu.alive_read, "particles/alive_read"),

package/src/shade/renderer/particles/optimizer/particle_vm_semantics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_vm_semantics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_vm_semantics.js"],"names":[],"mappings":"AA4IA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAW/B;AA1JD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBA1BxB,OAAO;;;;;cAGP,OAAO;;;;;;gBAEP,OAAO;;;;;;eAGP,OAAO;;;;;;;;cAGP,OAAO;;;;;;;;;;sBAKP,OAAO"}
+{"version":3,"file":"particle_vm_semantics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_vm_semantics.js"],"names":[],"mappings":"AAkJA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAW/B;AAhKD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBA1BxB,OAAO;;;;;cAGP,OAAO;;;;;;gBAEP,OAAO;;;;;;eAGP,OAAO;;;;;;;;cAGP,OAAO;;;;;;;;;;sBAKP,OAAO"}

package/src/shade/renderer/particles/optimizer/particle_vm_semantics.js

@@ -89,11 +89,17 @@ semantics(VM_OP.ADD, EXACT);
 semantics(VM_OP.SUB, EXACT);
 semantics(VM_OP.MUL, EXACT);
 semantics(VM_OP.DIV, EXACT);
-// `a * b + c` is one rounding on hardware that contracts it into an FMA and two in the reference.
+// The reference leaves the product unrounded — it models the fused form — and the shader spells
+// `a * b + c`, which a driver may contract into an FMA or may round in between. The two executors
+// agree exactly on the first reading and not on the second, and nothing in WGSL says which one a
+// device takes.
 semantics(VM_OP.MAD, INEXACT);
 semantics(VM_OP.MIN, EXACT);
 semantics(VM_OP.MAX, EXACT);
-// The reference spells it `a + (b - a) * t`; WGSL's `mix` is free to round it differently.
+// The reference now spells it as WGSL defines it, `a * (1 - t) + b * t`, rather than as the lerp
+// `a + (b - a) * t` — those are different numbers, not different roundings, wherever the span
+// `b - a` overflows or swallows an end. What is left is that a driver may contract either product
+// with the sum, which is the same slack `MAD` has.
 semantics(VM_OP.MIX, INEXACT);
 semantics(VM_OP.CLAMP, EXACT);
 

package/src/shade/renderer/particles/optimizer/pass_fold_constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pass_fold_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_fold_constants.js"],"names":[],"mappings":"AAyF4B,sJAEwD;AAuJpF;;;;;;;;;;GAUG;AACH,gDANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAmElB;AA9SD,qBAAqB;AACrB,2CADW,MAAM,CAC4C;AAE7D;;;;;GAKG;AACH,0CAFU,IAAI,MAAM,CAAC,CAE2C"}
+{"version":3,"file":"pass_fold_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_fold_constants.js"],"names":[],"mappings":"AAyF4B,sJAEwD;AAuJpF;;;;;;;;;;GAUG;AACH,gDANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAyElB;AApTD,qBAAqB;AACrB,2CADW,MAAM,CAC4C;AAE7D;;;;;GAKG;AACH,0CAFU,IAAI,MAAM,CAAC,CAE2C"}