@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -20,6 +20,7 @@ import {
     particle_counters_word_count,
 } from "./data/PARTICLE_COUNTERS.js";
 import { graph_particles_simulate } from "./graph_particles.js";
+import { PARTICLE_FIELD_BIND_WORKGROUP_SIZE } from "./shaders/shader_particle_field_bind.js";
 import {
     SLOT_STACK_FILL_WORKGROUP_SIZE,
     shader_slot_stack_fill,
@@ -83,8 +84,9 @@ const DEFAULT_CAPACITY = 65536;
  * 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 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
+ * (written at the end of one frame, read by the next), the emitter database (the emitter table, the
+ * GPU-owned state table and the transform binding table, one buffer), the packed program buffer
+ * (code, constants and field values), 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
@@ -338,6 +340,9 @@ export class GPUParticleSystem {
     /** @type {{capacity: number, group_count: number}} */
     #emitters = { capacity: 0, group_count: 0 };
 
+    /** @type {{group_count: number}} */
+    #field_bindings = { group_count: 0 };
+
     /**
      * This frame's simulation, for the side channels that draw it later in the frame: the graph it
      * was recorded into, the scene database handle it read, and the handles it produced. Reused,
@@ -389,6 +394,16 @@ export class GPUParticleSystem {
         return this.registry.emitters;
     }
 
+    /**
+     * The system's global fields — the static members every effect may read by name. Setting one is
+     * a word write and a span upload on the next frame; nothing is restaged and no program changes.
+     *
+     * @returns {import("./runtime/ParticleGlobalFields.js").ParticleGlobalFields}
+     */
+    get global_fields() {
+        return this.registry.programs.global_fields;
+    }
+
     /**
      * Number of simulation-order buckets — one per program id the registry can hand out, which is
      * its peak number of distinct compiled programs rather than its current one.
@@ -486,6 +501,12 @@ export class GPUParticleSystem {
         emitters.capacity = table.element_capacity;
         emitters.group_count = table.dispatch_group_count(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE);
 
+        const field_bindings = this.#field_bindings;
+        const binding_table = this.registry.binding_table;
+        field_bindings.group_count = binding_table.count === 0
+            ? 0
+            : binding_table.dispatch_group_count(PARTICLE_FIELD_BIND_WORKGROUP_SIZE);
+
         const buffers = this.buffers;
 
         this.#swap_alive_list(frame.rebucket);
@@ -511,6 +532,7 @@ export class GPUParticleSystem {
             // or unregistering the one hungry effect — can flip it either way.
             wide_registers: this.registry.max_register_count > PARTICLE_VM_FAST_REGISTER_SLOTS,
             frame,
+            field_bindings,
         });
 
         // Kept for the side channels that draw later in this frame, and for nothing past it.
@@ -687,9 +709,9 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Push everything the CPU changed to the GPU: dirty emitter rows, the state buffer's growth,
-     * rebuilt program buffers, the spawn-command ring, and the coherence scratch's growth. A
-     * command context is opened only if something needs one.
+     * Push everything the CPU changed to the GPU: dirty emitter and binding rows, the state buffer's
+     * growth, the program buffer rebuilt or its changed field span, the spawn-command ring, and the
+     * coherence scratch's growth. A command context is opened only if something needs one.
      */
     #upload() {
         const registry = this.registry;
@@ -697,10 +719,11 @@ export class GPUParticleSystem {
 
         registry.flush();
 
-        // Both tables stage into the one database: the emitter rows the author changed, and the
-        // state rows claimed or released with them.
+        // All three tables stage into the one database: the emitter rows the author changed, the
+        // state rows claimed or released with them, and the binding rows.
         const rows_staged = registry.table.element_upload_buffer.position > 0
-            || registry.state_table.element_upload_buffer.position > 0;
+            || registry.state_table.element_upload_buffer.position > 0
+            || registry.binding_table.element_upload_buffer.position > 0;
 
         if (rows_staged) {
             const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/upload");
@@ -710,8 +733,23 @@ export class GPUParticleSystem {
             cmd.finish();
         }
 
+        const heap = registry.programs;
+
         if (registry.programs_dirty) {
             this.buffers.program = replace_data_buffer(device, this.buffers.program, "particles/program", registry.build_program());
+        } else if (heap.fields_dirty) {
+            // field values change while the code does not: the span goes out from the heap's words
+            // into the buffer already on the device
+            const words = heap.field_words;
+            const begin = heap.fields_dirty_begin;
+
+            device.queue.writeBuffer(
+                this.buffers.program, (heap.field_base_word + begin) * WORD,
+                words.buffer, words.byteOffset + begin * WORD,
+                (heap.fields_dirty_end - begin) * WORD,
+            );
+
+            heap.clear_fields_dirty();
         }
 
         this.#merge_spawn_commands();

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

@@ -8,7 +8,7 @@
 /**
  * Number of `u32` words in a single particle record in the shared pool.
  *
- * Word 0 is reserved as the record header (owning emitter index). User attributes occupy words
+ * Word 0 is reserved as the record header (owning emitter index). User particle fields occupy words
  * `1 .. PARTICLE_RECORD_WORD_COUNT`. All emitters share one pool with this uniform stride, which is
  * what lets a single simulate dispatch process every emitter's particles (Destiny-style).
  *
@@ -101,11 +101,12 @@ export const PARTICLE_WARMUP_WORKGROUP_SIZE: number;
 export const PARTICLE_SPAWN_COMMAND_WORDS: number;
 /**
  * Words in front of the packed program buffer: word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} holds
- * the word index the instruction section starts at; the constant pool follows the header, so the
- * one buffer is `[header][constants][code]` — data, then code, and one binding for both.
+ * the word index the instruction section starts at, and word {@link PARTICLE_PROGRAM_FIELD_BASE_WORD}
+ * the one the field section starts at. The constant pool follows the header, so the one buffer is
+ * `[header][constants][code][fields]` — and one binding for all of it.
  *
- * Four words is now just room to grow the header: the pool is addressed by word, so nothing after
- * it needs a `vec4` boundary to land on. That was the original reason for the number.
+ * Two of the four words are spare. Every section is addressed by word, so nothing after the header
+ * needs a `vec4` boundary to land on.
  *
  * @type {number}
  */
@@ -116,7 +117,23 @@ export const PARTICLE_PROGRAM_HEADER_WORDS: number;
  */
 export const PARTICLE_PROGRAM_CODE_BASE_WORD: number;
 /**
- * First word index available for user-defined attributes.
+ * Header word holding the field section's first word index: global fields from there, then every
+ * emitter's block of emitter fields.
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_FIELD_BASE_WORD: number;
+/**
+ * Words reserved for global fields at the start of the field section, so a global field is addressed
+ * from zero and never moves while the emitter blocks after it are allocated, freed and repacked.
+ *
+ * 16 KiB, reserved whether or not anything is declared. The global layout packs into it and refuses
+ * a declaration that would run past it; 4,096 words is more global state than a scene has names for.
+ *
+ * @type {number}
+ */
+export const PARTICLE_GLOBAL_FIELD_WORDS: number;
+/**
+ * First word index available for user-defined particle fields.
  * @type {number}
  */
 export const PARTICLE_RECORD_USER_WORD_START: number;

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;GAUG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;GAIG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}

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

@@ -9,7 +9,7 @@
 /**
  * Number of `u32` words in a single particle record in the shared pool.
  *
- * Word 0 is reserved as the record header (owning emitter index). User attributes occupy words
+ * Word 0 is reserved as the record header (owning emitter index). User particle fields occupy words
  * `1 .. PARTICLE_RECORD_WORD_COUNT`. All emitters share one pool with this uniform stride, which is
  * what lets a single simulate dispatch process every emitter's particles (Destiny-style).
  *
@@ -113,11 +113,12 @@ export const PARTICLE_SPAWN_COMMAND_WORDS = 2;
 
 /**
  * Words in front of the packed program buffer: word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} holds
- * the word index the instruction section starts at; the constant pool follows the header, so the
- * one buffer is `[header][constants][code]` — data, then code, and one binding for both.
+ * the word index the instruction section starts at, and word {@link PARTICLE_PROGRAM_FIELD_BASE_WORD}
+ * the one the field section starts at. The constant pool follows the header, so the one buffer is
+ * `[header][constants][code][fields]` — and one binding for all of it.
  *
- * Four words is now just room to grow the header: the pool is addressed by word, so nothing after
- * it needs a `vec4` boundary to land on. That was the original reason for the number.
+ * Two of the four words are spare. Every section is addressed by word, so nothing after the header
+ * needs a `vec4` boundary to land on.
  *
  * @type {number}
  */
@@ -130,7 +131,25 @@ export const PARTICLE_PROGRAM_HEADER_WORDS = 4;
 export const PARTICLE_PROGRAM_CODE_BASE_WORD = 0;
 
 /**
- * First word index available for user-defined attributes.
+ * Header word holding the field section's first word index: global fields from there, then every
+ * emitter's block of emitter fields.
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_FIELD_BASE_WORD = 1;
+
+/**
+ * Words reserved for global fields at the start of the field section, so a global field is addressed
+ * from zero and never moves while the emitter blocks after it are allocated, freed and repacked.
+ *
+ * 16 KiB, reserved whether or not anything is declared. The global layout packs into it and refuses
+ * a declaration that would run past it; 4,096 words is more global state than a scene has names for.
+ *
+ * @type {number}
+ */
+export const PARTICLE_GLOBAL_FIELD_WORDS = 4096;
+
+/**
+ * First word index available for user-defined particle fields.
  * @type {number}
  */
 export const PARTICLE_RECORD_USER_WORD_START = 1;

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.js

@@ -8,7 +8,7 @@ import {
     PARTICLE_BOUNDS_PLUS_INF,
     PARTICLE_BOUNDS_WORDS,
 } from "../data/PARTICLE_COUNTERS.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_FIELD_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
 import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
 import { chunk_particle_render_math } from "../shaders/chunk_particle_render_math.js";
 
@@ -138,7 +138,7 @@ fn particle_bounds_is_empty(box : ${AABB3_STRUCT.wgsl_ref}) -> bool {
  * @type {CodeChunk}
  */
 export const chunk_particle_bounds_of_record = CodeChunk.from(/* language=wgsl */ `
-const PARTICLE_BOUNDS_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+const PARTICLE_BOUNDS_FIELD_ABSENT : u32 = ${PARTICLE_FIELD_ABSENT}u;
 
 struct ParticleBoundsSample {
     center : vec3<f32>,
@@ -159,17 +159,17 @@ fn particle_bounds_of_record(
     record_base : u32,
 ) -> ParticleBoundsSample {
     var center = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+    if (em.render_position != PARTICLE_BOUNDS_FIELD_ABSENT) {
         center = particle_bounds_read_vec3(pool, record_base, em.render_position);
     }
 
     var size = 1.0;
-    if (em.render_size != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+    if (em.render_size != PARTICLE_BOUNDS_FIELD_ABSENT) {
         size = bitcast<f32>((*pool)[record_base + em.render_size]);
     }
 
     var velocity = vec3<f32>(0.0);
-    if (em.render_velocity != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+    if (em.render_velocity != PARTICLE_BOUNDS_FIELD_ABSENT) {
         velocity = particle_bounds_read_vec3(pool, record_base, em.render_velocity);
     }
 

package/src/shade/renderer/particles/bounds/shader_particle_bounds.js

@@ -1,187 +1,187 @@
-import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-} from "../ParticleConstants.js";
-import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
-import { chunk_particle_header } from "../data/particle_header.js";
-import { chunk_particle_bounds_of_record, chunk_particle_bounds_store } from "./chunk_particle_bounds.js";
-
-/**
- * The two passes that measure every emitter's bounding box, at the end of the frame that produced
- * the particles.
- *
- * - {@link shader_particle_bounds_accumulate} — one thread per live particle: read where its quad
- *   is and merge it into its emitter's accumulator.
- * - {@link shader_particle_bounds_publish} — one thread per emitter row: hand the accumulation to
- *   the state row the culling and occupancy passes read, and start the next frame's measurement.
- *
- * ## Why this is not a tail on the simulate pass
- *
- * It was, briefly. Two things are wrong with booking the box from inside emit and simulate. The
- * measurement is not of one population: simulate sees last frame's survivors and emit sees this
- * frame's newborns, so the union spans two frames and is looser than either. And the merge is six
- * atomics in the pass whose register pressure decides the whole system's occupancy — the interpreter
- * — paid to compute something that needs none of the VM, none of the scene, and five words of the
- * record.
- *
- * Run over the alive list instead and the measurement is of exactly the set that is alive and about
- * to be drawn, taken by a pass that reads a header, an emitter row and three attributes.
- *
- * ## Sizing
- *
- * The accumulate pass is dispatched indirectly from `sim_dispatch_args`, which the coherence reset
- * wrote from the GPU's own alive count — the same args the render sort's two per-particle passes
- * take, and the reason its workgroup size must stay {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, which
- * is what those args were divided by. Its element bound is `counters[ALIVE]`, read in the shader.
- * Nothing here is sized from the host.
- *
- * The publish pass walks the emitter table with the table's page iterator, one page group per
- * workgroup, like the tick.
- */
-
-export { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_EMITTER_TICK_WORKGROUP_SIZE };
-
-// --- accumulate -------------------------------------------------------------------------------
-
-const accumulate_resources = new ShaderResourceSetDescriptor();
-
-accumulate_resources.createGroup()
-    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-/**
- * One thread per live particle: merge its quad into its emitter's accumulator.
- *
- * The alive list holds real slots only — the padding sentinel belongs to the simulation-order list,
- * and an orphan was killed by the simulate pass that built this list — so every entry is a particle
- * whose emitter row is live and whose record has this frame's values in it.
- *
- * It decodes a whole emitter record to reach four of its fields, which the bucketing histogram
- * deliberately does not (`chunk_particle_emitter_program_id`). The difference is what is being paid
- * for: emitters are counted in tens, so the records are a working set that stays resident for the
- * whole dispatch, while the pool reads are a gather over the free list and are what this pass costs.
- * The billboard vertex stage reads a record the same way, per vertex.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_bounds_accumulate = ComputeShader.from({
-    label: "Particle Bounds Accumulate",
-    resources: accumulate_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-
-@compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-
-    // This frame's alive count, as emit and simulate left it. The indirect dispatch was built from
-    // the same number, so the excess is at most a workgroup's tail.
-    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
-
-    let slot = alive[i];
-    let record_base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_row = particle_header_emitter(pool[record_base + PARTICLE_HEADER_EMITTER]);
-
-    let em = particle_emitter_read(&emitter_database, emitter_row);
-    let sample = particle_bounds_of_record(em, &pool, record_base);
-
-    particle_bounds_contribute(emitter_row, sample.center, sample.radius);
-}
-`, [
-        chunk_particle_bounds_of_record,
-        chunk_particle_bounds_store,
-        chunk_particle_header,
-    ]),
-});
-
-// --- publish ----------------------------------------------------------------------------------
-
-const PG = PARTICLE_EMITTER_DESCRIPTOR.page_iterator_symbol_prefix(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true);
-const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
-
-// Generated once and held, because each call builds a fresh chunk declaring the same function: two
-// calls for one field would be two declarations of it in the assembled shader.
-const WRITE_BOUNDS_MIN = STATE.wgsl_gen_write_field_code("bounds_min");
-const WRITE_BOUNDS_MAX = STATE.wgsl_gen_write_field_code("bounds_max");
-
-const publish_resources = new ShaderResourceSetDescriptor();
-
-publish_resources.createGroup()
-    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-/**
- * One thread per emitter table row: publish what the accumulate pass measured into
- * `bounds_min` / `bounds_max` of the emitter's state row, and reset the accumulator.
- *
- * The state row rather than the accumulator directly, because the readers — the tick's frustum test
- * next frame, the AVBOIT occupancy later in this one — should not each have to know the
- * accumulator's layout or repeat the empty case below. It is also where the rest of an emitter's
- * GPU-owned state lives, for the reason {@link ../data/PARTICLE_EMITTER_STATE.js} gives.
- *
- * ## The empty case
- *
- * No measured particles means unknown bounds, represented by an infinite box. The tick lets such
- * an emitter spawn until a finite population can be measured; occupancy skips it because there is
- * nothing to splat. This also lets an exhausted effect restart without requiring authored bounds
- * or prewarm. Readers recognize the sentinel before doing geometry arithmetic on infinities.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_bounds_publish = ComputeShader.from({
-    label: "Particle Bounds Publish",
-    resources: publish_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-@compute @workgroup_size(${PARTICLE_EMITTER_TICK_WORKGROUP_SIZE}, 1, 1)
-fn main(
-    @builtin(workgroup_id) wg_id : vec3<u32>,
-    @builtin(local_invocation_index) local_id : u32,
-) {
-    // page_address is uniform across the workgroup, so this branch is uniform.
-    if (!${PG}_setup(&emitter_database, wg_id.x, local_id)) {
-        return;
-    }
-
-    let slot_in_page = ${PG}_slot_in_page(local_id);
-
-    if (slot_in_page >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot_in_page)) {
-        return;
-    }
-
-    let row = ${PG}_slot_to_index(slot_in_page);
-
-    var box = particle_bounds_read(row);
-
-    if (particle_bounds_is_empty(box)) {
-        // The empty accumulator already holds [+inf, -inf]. Swap the loaded endpoints to
-        // publish unknown bounds without constructing forbidden infinite constant expressions.
-        box = ${AABB3_STRUCT.make({ min: "box.max", max: "box.min" })};
-    }
-
-    particle_bounds_reset(row);
-
-    // Two field writes rather than a whole-row read-modify-write: the tick wrote this row earlier in
-    // the frame, and there is no reason for this pass to carry the rest of it through registers.
-    ${STATE.marshalling_method_write_field("bounds_min")}(&emitter_database, row, box.min);
-    ${STATE.marshalling_method_write_field("bounds_max")}(&emitter_database, row, box.max);
-}
-`, [
-        PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true),
-        WRITE_BOUNDS_MIN,
-        WRITE_BOUNDS_MAX,
-        chunk_particle_bounds_store,
-    ]),
-});
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_bounds_of_record, chunk_particle_bounds_store } from "./chunk_particle_bounds.js";
+
+/**
+ * The two passes that measure every emitter's bounding box, at the end of the frame that produced
+ * the particles.
+ *
+ * - {@link shader_particle_bounds_accumulate} — one thread per live particle: read where its quad
+ *   is and merge it into its emitter's accumulator.
+ * - {@link shader_particle_bounds_publish} — one thread per emitter row: hand the accumulation to
+ *   the state row the culling and occupancy passes read, and start the next frame's measurement.
+ *
+ * ## Why this is not a tail on the simulate pass
+ *
+ * It was, briefly. Two things are wrong with booking the box from inside emit and simulate. The
+ * measurement is not of one population: simulate sees last frame's survivors and emit sees this
+ * frame's newborns, so the union spans two frames and is looser than either. And the merge is six
+ * atomics in the pass whose register pressure decides the whole system's occupancy — the interpreter
+ * — paid to compute something that needs none of the VM, none of the scene, and five words of the
+ * record.
+ *
+ * Run over the alive list instead and the measurement is of exactly the set that is alive and about
+ * to be drawn, taken by a pass that reads a header, an emitter row and three particle fields.
+ *
+ * ## Sizing
+ *
+ * The accumulate pass is dispatched indirectly from `sim_dispatch_args`, which the coherence reset
+ * wrote from the GPU's own alive count — the same args the render sort's two per-particle passes
+ * take, and the reason its workgroup size must stay {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, which
+ * is what those args were divided by. Its element bound is `counters[ALIVE]`, read in the shader.
+ * Nothing here is sized from the host.
+ *
+ * The publish pass walks the emitter table with the table's page iterator, one page group per
+ * workgroup, like the tick.
+ */
+
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_EMITTER_TICK_WORKGROUP_SIZE };
+
+// --- accumulate -------------------------------------------------------------------------------
+
+const accumulate_resources = new ShaderResourceSetDescriptor();
+
+accumulate_resources.createGroup()
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per live particle: merge its quad into its emitter's accumulator.
+ *
+ * The alive list holds real slots only — the padding sentinel belongs to the simulation-order list,
+ * and an orphan was killed by the simulate pass that built this list — so every entry is a particle
+ * whose emitter row is live and whose record has this frame's values in it.
+ *
+ * It decodes a whole emitter record to reach four of its fields, which the bucketing histogram
+ * deliberately does not (`chunk_particle_emitter_program_id`). The difference is what is being paid
+ * for: emitters are counted in tens, so the records are a working set that stays resident for the
+ * whole dispatch, while the pool reads are a gather over the free list and are what this pass costs.
+ * The billboard vertex stage reads a record the same way, per vertex.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bounds_accumulate = ComputeShader.from({
+    label: "Particle Bounds Accumulate",
+    resources: accumulate_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+
+@compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    // This frame's alive count, as emit and simulate left it. The indirect dispatch was built from
+    // the same number, so the excess is at most a workgroup's tail.
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let slot = alive[i];
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_row = particle_header_emitter(pool[record_base + PARTICLE_HEADER_EMITTER]);
+
+    let em = particle_emitter_read(&emitter_database, emitter_row);
+    let sample = particle_bounds_of_record(em, &pool, record_base);
+
+    particle_bounds_contribute(emitter_row, sample.center, sample.radius);
+}
+`, [
+        chunk_particle_bounds_of_record,
+        chunk_particle_bounds_store,
+        chunk_particle_header,
+    ]),
+});
+
+// --- publish ----------------------------------------------------------------------------------
+
+const PG = PARTICLE_EMITTER_DESCRIPTOR.page_iterator_symbol_prefix(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true);
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+// Generated once and held, because each call builds a fresh chunk declaring the same function: two
+// calls for one field would be two declarations of it in the assembled shader.
+const WRITE_BOUNDS_MIN = STATE.wgsl_gen_write_field_code("bounds_min");
+const WRITE_BOUNDS_MAX = STATE.wgsl_gen_write_field_code("bounds_max");
+
+const publish_resources = new ShaderResourceSetDescriptor();
+
+publish_resources.createGroup()
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per emitter table row: publish what the accumulate pass measured into
+ * `bounds_min` / `bounds_max` of the emitter's state row, and reset the accumulator.
+ *
+ * The state row rather than the accumulator directly, because the readers — the tick's frustum test
+ * next frame, the AVBOIT occupancy later in this one — should not each have to know the
+ * accumulator's layout or repeat the empty case below. It is also where the rest of an emitter's
+ * GPU-owned state lives, for the reason {@link ../data/PARTICLE_EMITTER_STATE.js} gives.
+ *
+ * ## The empty case
+ *
+ * No measured particles means unknown bounds, represented by an infinite box. The tick lets such
+ * an emitter spawn until a finite population can be measured; occupancy skips it because there is
+ * nothing to splat. This also lets an exhausted effect restart without requiring authored bounds
+ * or prewarm. Readers recognize the sentinel before doing geometry arithmetic on infinities.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bounds_publish = ComputeShader.from({
+    label: "Particle Bounds Publish",
+    resources: publish_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(${PARTICLE_EMITTER_TICK_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // page_address is uniform across the workgroup, so this branch is uniform.
+    if (!${PG}_setup(&emitter_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot_in_page = ${PG}_slot_in_page(local_id);
+
+    if (slot_in_page >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot_in_page)) {
+        return;
+    }
+
+    let row = ${PG}_slot_to_index(slot_in_page);
+
+    var box = particle_bounds_read(row);
+
+    if (particle_bounds_is_empty(box)) {
+        // The empty accumulator already holds [+inf, -inf]. Swap the loaded endpoints to
+        // publish unknown bounds without constructing forbidden infinite constant expressions.
+        box = ${AABB3_STRUCT.make({ min: "box.max", max: "box.min" })};
+    }
+
+    particle_bounds_reset(row);
+
+    // Two field writes rather than a whole-row read-modify-write: the tick wrote this row earlier in
+    // the frame, and there is no reason for this pass to carry the rest of it through registers.
+    ${STATE.marshalling_method_write_field("bounds_min")}(&emitter_database, row, box.min);
+    ${STATE.marshalling_method_write_field("bounds_max")}(&emitter_database, row, box.max);
+}
+`, [
+        PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true),
+        WRITE_BOUNDS_MIN,
+        WRITE_BOUNDS_MAX,
+        chunk_particle_bounds_store,
+    ]),
+});