@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -17,20 +17,90 @@
  */
 export const PARTICLE_RECORD_WORD_COUNT: number;
 /**
- * Word index (within a record) that stores the owning emitter's index.
+ * Word index (within a record) of the header word: the owning emitter's row and that row's
+ * generation, packed as {@link ./data/particle_header.js} describes.
  * @type {number}
  */
 export const PARTICLE_RECORD_HEADER_EMITTER: number;
+/**
+ * Threads per workgroup in the emitter tick dispatch, which walks the emitter table a page group at
+ * a time through the table's page iterator. That iterator caches one occupancy word per 32 lanes,
+ * so this has to be a multiple of 32.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE: number;
+/**
+ * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
+ * @type {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.
+ *
+ * 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.
+ *
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_HEADER_WORDS: number;
+/**
+ * Header word holding the instruction section's first word index.
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_CODE_BASE_WORD: number;
+/**
+ * Bins the render-order depth sort quantises view depth into. More bins is a finer back-to-front
+ * order at the cost of a longer histogram; particles that land in one bin draw in an order the
+ * scatter's atomics decide.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SORT_BUCKET_COUNT: number;
 /**
  * First word index available for user-defined attributes.
  * @type {number}
  */
 export const PARTICLE_RECORD_USER_WORD_START: number;
 /**
- * Number of vec4f registers in the VM register file. Each register is 4 lanes; scalars live in `.x`.
+ * Size of the VM register file, in `f32` slots. A register IS a slot: a `vec3` value is three
+ * consecutive ones, and an instruction's width says how many its operands span.
+ *
+ * This is the interpreter's single largest cost and it is paid by every program, not just the ones
+ * that need it: `vm_reg` is a `var<private>` array the VM indexes dynamically, which lands in
+ * registers rather than scratch, so the file's size sets the shader's register footprint outright.
+ * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs against a 16-wave occupancy cap that
+ * anything at or below 64 VGPRs reaches. Sixteen `vec4` registers — what this was — cost 81 and
+ * held the shader to 10 waves.
+ *
+ * Scalar slots are also what makes the number go further than the same count of floats did as
+ * `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32 slots hold ten
+ * `vec3`s or 32 scalars. The playground's fire effect, the most involved in the tree, peaks at 11
+ * slots live.
+ *
+ * A graph that needs more gets a clear error out of `compile_particle_graph.js` rather than silent
+ * corruption, and the fix for it is to raise this number and re-measure — not to assume the headroom
+ * was free.
+ *
+ * ## Why 48 and not 32
+ *
+ * The node library gained {@link ./graph/ParticleNodeGroup.js groups}, and with them simplex and curl
+ * noise. Those are hundreds of instructions with a wide working set, and 32 slots is not enough for
+ * any of them: measured peaks are 26 for `simplex3`, 33 for `simplex4`, 32 for `curl3` and 40 for
+ * `curl4` — the last with a whole effect's worth of arithmetic still to fit around it.
+ *
+ * 48 is the largest number that the measurement above says is free. At 32 slots the shader compiled
+ * to 47 VGPRs, and a slot is about a VGPR, so 48 lands around 63 — still at or under the 64 that
+ * reaches the 16-wave occupancy cap. **That arithmetic has not been re-measured against a real
+ * driver.** It is the model the paragraphs above were written from, and it is a model; anyone
+ * changing this number again, or wanting to be sure of this one, should compile the simulate shader
+ * offline and read the register count rather than trust it.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_REGISTER_COUNT: number;
+export const PARTICLE_VM_REGISTER_SLOTS: number;
 /**
  * Number of `u32` words per VM instruction: `[op, dst, s0, s1, s2]`.
  * @type {number}
@@ -39,6 +109,17 @@ export const PARTICLE_VM_INSTRUCTION_WORDS: number;
 /**
  * Hard cap on instructions executed by a single VM program invocation. A safety bound so a malformed
  * program can never spin the GPU; the interpreter's loop is `for (i in 0..LIMIT)`.
+ *
+ * A bound and not a cost: the loop runs `min(instruction_count, LIMIT)` times, so a program of forty
+ * instructions costs forty whatever this says. What it does cost is the refusal — a program past it
+ * does not assemble — and the effects that library groups make possible are far past what 256 was.
+ * `curl4` alone is about six thousand instructions, being twelve four-dimensional simplex samples
+ * with no loop to put them in.
+ *
+ * Which is worth saying plainly rather than only in a constant: an effect built on curl noise runs
+ * thousands of VM instructions per particle per frame. That is not a budget anyone should spend
+ * without meaning to, and it is why the expensive groups say what they cost in their own help text.
+ *
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS: number;
@@ -73,4 +154,16 @@ export const PARTICLE_SIMULATE_WORKGROUP_SIZE: number;
  * @type {number}
  */
 export const PARTICLE_SIM_PAD_SLOT: number;
+/**
+ * View-space distance, in world units, over which a soft-depth particle fades out as it approaches
+ * the opaque surface behind it.
+ *
+ * Read by the two passes that have to agree on a fragment's coverage: the AVBOIT draw, which weights
+ * the accumulators by it, and the AVBOIT splat, which records the extinction the volume then hands
+ * to everything behind. A fade in one and not the other is a surface that is invisible and still
+ * occludes.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SOFT_FADE_RANGE: number;
 //# sourceMappingURL=ParticleConstants.d.ts.map

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;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC"}
+{"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;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;GAMG;AACH,yCAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;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

@@ -19,11 +19,54 @@
 export const PARTICLE_RECORD_WORD_COUNT = 32;
 
 /**
- * Word index (within a record) that stores the owning emitter's index.
+ * Word index (within a record) of the header word: the owning emitter's row and that row's
+ * generation, packed as {@link ./data/particle_header.js} describes.
  * @type {number}
  */
 export const PARTICLE_RECORD_HEADER_EMITTER = 0;
 
+/**
+ * Threads per workgroup in the emitter tick dispatch, which walks the emitter table a page group at
+ * a time through the table's page iterator. That iterator caches one occupancy word per 32 lanes,
+ * so this has to be a multiple of 32.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE = 64;
+
+/**
+ * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
+ * @type {number}
+ */
+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.
+ *
+ * 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.
+ *
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_HEADER_WORDS = 4;
+
+/**
+ * Header word holding the instruction section's first word index.
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_CODE_BASE_WORD = 0;
+
+/**
+ * Bins the render-order depth sort quantises view depth into. More bins is a finer back-to-front
+ * order at the cost of a longer histogram; particles that land in one bin draw in an order the
+ * scatter's atomics decide.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SORT_BUCKET_COUNT = 1024;
+
 /**
  * First word index available for user-defined attributes.
  * @type {number}
@@ -31,10 +74,42 @@ export const PARTICLE_RECORD_HEADER_EMITTER = 0;
 export const PARTICLE_RECORD_USER_WORD_START = 1;
 
 /**
- * Number of vec4f registers in the VM register file. Each register is 4 lanes; scalars live in `.x`.
+ * Size of the VM register file, in `f32` slots. A register IS a slot: a `vec3` value is three
+ * consecutive ones, and an instruction's width says how many its operands span.
+ *
+ * This is the interpreter's single largest cost and it is paid by every program, not just the ones
+ * that need it: `vm_reg` is a `var<private>` array the VM indexes dynamically, which lands in
+ * registers rather than scratch, so the file's size sets the shader's register footprint outright.
+ * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs against a 16-wave occupancy cap that
+ * anything at or below 64 VGPRs reaches. Sixteen `vec4` registers — what this was — cost 81 and
+ * held the shader to 10 waves.
+ *
+ * Scalar slots are also what makes the number go further than the same count of floats did as
+ * `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32 slots hold ten
+ * `vec3`s or 32 scalars. The playground's fire effect, the most involved in the tree, peaks at 11
+ * slots live.
+ *
+ * A graph that needs more gets a clear error out of `compile_particle_graph.js` rather than silent
+ * corruption, and the fix for it is to raise this number and re-measure — not to assume the headroom
+ * was free.
+ *
+ * ## Why 48 and not 32
+ *
+ * The node library gained {@link ./graph/ParticleNodeGroup.js groups}, and with them simplex and curl
+ * noise. Those are hundreds of instructions with a wide working set, and 32 slots is not enough for
+ * any of them: measured peaks are 26 for `simplex3`, 33 for `simplex4`, 32 for `curl3` and 40 for
+ * `curl4` — the last with a whole effect's worth of arithmetic still to fit around it.
+ *
+ * 48 is the largest number that the measurement above says is free. At 32 slots the shader compiled
+ * to 47 VGPRs, and a slot is about a VGPR, so 48 lands around 63 — still at or under the 64 that
+ * reaches the 16-wave occupancy cap. **That arithmetic has not been re-measured against a real
+ * driver.** It is the model the paragraphs above were written from, and it is a model; anyone
+ * changing this number again, or wanting to be sure of this one, should compile the simulate shader
+ * offline and read the register count rather than trust it.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_REGISTER_COUNT = 16;
+export const PARTICLE_VM_REGISTER_SLOTS = 48;
 
 /**
  * Number of `u32` words per VM instruction: `[op, dst, s0, s1, s2]`.
@@ -45,9 +120,20 @@ export const PARTICLE_VM_INSTRUCTION_WORDS = 5;
 /**
  * Hard cap on instructions executed by a single VM program invocation. A safety bound so a malformed
  * program can never spin the GPU; the interpreter's loop is `for (i in 0..LIMIT)`.
+ *
+ * A bound and not a cost: the loop runs `min(instruction_count, LIMIT)` times, so a program of forty
+ * instructions costs forty whatever this says. What it does cost is the refusal — a program past it
+ * does not assemble — and the effects that library groups make possible are far past what 256 was.
+ * `curl4` alone is about six thousand instructions, being twelve four-dimensional simplex samples
+ * with no loop to put them in.
+ *
+ * Which is worth saying plainly rather than only in a constant: an effect built on curl noise runs
+ * thousands of VM instructions per particle per frame. That is not a budget anyone should spend
+ * without meaning to, and it is why the expensive groups say what they cost in their own help text.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_MAX_INSTRUCTIONS = 256;
+export const PARTICLE_VM_MAX_INSTRUCTIONS = 8192;
 
 /**
  * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
@@ -81,3 +167,16 @@ export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
  * @type {number}
  */
 export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;
+
+/**
+ * View-space distance, in world units, over which a soft-depth particle fades out as it approaches
+ * the opaque surface behind it.
+ *
+ * Read by the two passes that have to agree on a fragment's coverage: the AVBOIT draw, which weights
+ * the accumulators by it, and the AVBOIT splat, which records the extinction the volume then hands
+ * to everything behind. A fade in one and not the other is a surface that is invisible and still
+ * occludes.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SOFT_FADE_RANGE = 0.5;

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

@@ -27,7 +27,7 @@
  * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
  * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
  * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
- * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
  * @param {number} params.counters graph handle of the atomic counters
@@ -36,9 +36,9 @@
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }: {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }: {
     graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     gpu: {
         sim_list: GPUBuffer;
@@ -48,7 +48,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         sim_cursor: GPUBuffer;
         sim_dispatch_args: GPUBuffer;
     };
-    emitters: number;
+    emitter_database: number;
     pool: number;
     alive: number;
     counters: number;
@@ -57,5 +57,6 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
 }): {
     counters: number;
     sim_list: number;
+    dispatch_args: number;
 };
 //# sourceMappingURL=graph_particle_bucket.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAnBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,QAAQ,EAAvB,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;IACJ;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAqGhD"}
+{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAnBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;;cACO,MAAM;cAAY,MAAM;mBAAiB,MAAM;EAwGtE"}

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { align_4 } from "../../../../core/binary/align_4.js";
 import { graph_compute_indirect_pass } from "../../shader/graph/compute/graph_compute_indirect_pass.js";
 import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
 import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
@@ -44,7 +45,7 @@ import {
  * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
  * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
  * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
- * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
  * @param {number} params.counters graph handle of the atomic counters
@@ -53,16 +54,17 @@ import {
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }) {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }) {
     assert.defined(graph, "graph");
     assert.isPositiveInteger(bucket_count, "bucket_count");
     assert.isNonNegativeInteger(sim_list, "sim_list");
 
     // Sized from the bucket count, which only changes when the emitter set does — so a caller that
     // added an emitter and did not reallocate gets told here rather than scattering out of bounds.
-    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    // Aligned up because the scan reads whole `vec4`s, so the last bin's tail is part of the buffer.
+    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
     assert.greaterThanOrEqual(gpu.sim_histogram.size, bin_words * Uint32Array.BYTES_PER_ELEMENT, "sim_histogram is too small for the bucket count");
     assert.greaterThanOrEqual(gpu.sim_cursor.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_cursor is too small for the bucket count");
     assert.greaterThanOrEqual(gpu.sim_bucket_counts.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_bucket_counts is too small for the bucket count");
@@ -98,7 +100,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         const out = graph_compute_indirect_pass({
             graph,
             shader: shader_particle_bucket_histogram,
-            bindings: { emitters, pool, alive, keys, histogram, counters },
+            bindings: { emitter_database, pool, alive, keys, histogram, counters },
             command: dispatch_args,
         });
         keys = out.keys;
@@ -153,7 +155,9 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         counters = out.counters;
     }
 
-    return { counters, sim_list };
+    // `dispatch_args` goes back too: it holds one workgroup per live particle, written from the
+    // GPU's own alive count, which is exactly the shape the depth sort's per-particle passes need.
+    return { counters, sim_list, dispatch_args };
 }
 
 /**
@@ -165,15 +169,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
  * @returns {number}
  */
 function reset_group_count(bucket_count) {
-    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
 
     return Math.ceil(words / PARTICLE_SIMULATE_WORKGROUP_SIZE);
 }
-
-/**
- * @param {number} value
- * @returns {number} `value` rounded up to a multiple of four — the scan reads whole `vec4`s
- */
-function round_up_4(value) {
-    return (value + 3) & ~3;
-}

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

@@ -12,8 +12,8 @@ export const shader_particle_bucket_reset: ComputeShader;
  * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
  * emitter index would split a run that was already coherent into one padded bucket per emitter.
  *
- * The emitter's program id is read by direct indexing rather than through
- * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * The program id is read through the table's single-FIELD accessor rather than
+ * `particle_emitter_read` — decoding a whole emitter record, transform matrix included, to reach one
  * word would be pure waste in a pass that touches every live particle.
  *
  * @type {ComputeShader}

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AAwGA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAyBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BArV2B,+BAA+B"}
+{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AA+GA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAuBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BA1V2B,+BAA+B"}

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

@@ -11,7 +11,9 @@ import {
     PARTICLE_SIM_PAD_SLOT,
 } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { PARTICLE_EMITTER_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_emitter_program_id } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_header } from "../data/particle_header.js";
 
 /**
  * Simulation-order bucketing — the passes that make each simulate wave run ONE VM program.
@@ -26,6 +28,11 @@ import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.j
  * a waterfall loop whose trip count is the number of DISTINCT register indices live in the wave.
  * Grouping the wave by program collapses both at once.
  *
+ * It is also load-bearing, not only a speed-up: the simulate pass reads its section parameters
+ * from the wave's first lane (`particle_wave_uniform` in `../shaders/shader_particle_simulate.js`),
+ * so a wave holding two programs would run one of them over the other's particles. The grouping is
+ * the contract that pass compiles against.
+ *
  * ## Shape
  *
  * The same three-phase shape the depth sort uses, with two small passes added for the padding:
@@ -82,7 +89,7 @@ const PAD_MASK = (~(WG - 1)) >>> 0;
 const WG_LOG = Math.log2(WG);
 
 /** Constants every pass in this file interpolates. */
-const COMMON = /* wgsl */ `
+const COMMON = /* language=wgsl */ `
 const BUCKET_HEADER_WORDS : u32 = ${HEADER}u;
 const BUCKET_ALIGNMENT : u32 = ${WG}u;
 const BUCKET_PAD_MASK : u32 = ${PAD_MASK}u;
@@ -113,7 +120,7 @@ reset_resources.createGroup()
 export const shader_particle_bucket_reset = ComputeShader.from({
     label: "Particle Bucket Reset",
     resources: reset_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -156,7 +163,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 const histogram_resources = new ShaderResourceSetDescriptor();
 
 histogram_resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, false)
     .addStorageBuffer("alive", WebGPUArray.u32, false)
     .addStorageBuffer("keys", WebGPUArray.u32, true)
@@ -168,8 +175,8 @@ histogram_resources.createGroup()
  * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
  * emitter index would split a run that was already coherent into one padded bucket per emitter.
  *
- * The emitter's program id is read by direct indexing rather than through
- * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * The program id is read through the table's single-FIELD accessor rather than
+ * `particle_emitter_read` — decoding a whole emitter record, transform matrix included, to reach one
  * word would be pure waste in a pass that touches every live particle.
  *
  * @type {ComputeShader}
@@ -177,12 +184,10 @@ histogram_resources.createGroup()
 export const shader_particle_bucket_histogram = ComputeShader.from({
     label: "Particle Bucket Histogram",
     resources: histogram_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_EMITTER_RECORD_WORDS : u32 = ${EMITTER_STRIDE}u;
-const EMITTER_WORD_PROGRAM_ID : u32 = ${EMITTER_FIELD.PROGRAM_ID}u;
 
 @compute @workgroup_size(${WG}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
@@ -190,13 +195,13 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
 
     let slot = alive[i];
-    let emitter_index = pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER];
-    let program = emitters[emitter_index * PARTICLE_EMITTER_RECORD_WORDS + EMITTER_WORD_PROGRAM_ID];
+    let emitter_index = particle_header_emitter(pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER]);
+    let program = ${PARTICLE_EMITTER_DESCRIPTOR.marshalling_method_read_field('program_id')}(&emitter_database, emitter_index);
 
     keys[i] = program;
     atomicAdd(&histogram[BUCKET_HEADER_WORDS + program], 1u);
 }
-`),
+`, [chunk_particle_emitter_program_id, chunk_particle_header]),
 });
 
 // --- 2. pad -----------------------------------------------------------------------------------
@@ -223,7 +228,7 @@ pad_resources.createGroup()
 export const shader_particle_bucket_pad = ComputeShader.from({
     label: "Particle Bucket Pad",
     resources: pad_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -264,7 +269,7 @@ scatter_resources.createGroup()
 export const shader_particle_bucket_scatter = ComputeShader.from({
     label: "Particle Bucket Scatter",
     resources: scatter_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -313,7 +318,7 @@ fill_resources.createGroup()
 export const shader_particle_bucket_fill = ComputeShader.from({
     label: "Particle Bucket Fill",
     resources: fill_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
 

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.d.ts

@@ -8,8 +8,13 @@ export const PARTICLE_COUNTER: Readonly<{
     ALIVE: 0;
     /** length of the dead (free) list */
     DEAD: 1;
-    /** number of particles requested to spawn this frame */
-    SPAWN: 2;
+    /**
+     * Free slots not yet promised to a spawn this frame. The reset pass seeds it from
+     * {@link DEAD}; the emitter tick pass takes from it as it decides each emitter's spawn count,
+     * so an emitter is only ever debited for particles the pool can actually hold. What is left at
+     * the end of the frame is the headroom the frame had.
+     */
+    SPAWN_BUDGET: 2;
     /**
      * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
      * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
@@ -44,10 +49,4 @@ export const PARTICLE_COUNTER: Readonly<{
 }>;
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT: 8;
-/**
- * Per-dispatch uniform for the simulate/emit passes.
- * @type {WebGPUStruct}
- */
-export const PARTICLE_SIM_UNIFORM_STRUCT: WebGPUStruct;
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 //# sourceMappingURL=PARTICLE_COUNTERS.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BA5DI,mCAAmC"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC"}

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.js

@@ -1,6 +1,3 @@
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-
 /**
  * Indices into the particle counters buffer (an `array<atomic<u32>>`). The simulate/emit passes use
  * atomics on these slots to append to the alive/dead lists; a finalize pass turns the counts into
@@ -11,8 +8,13 @@ export const PARTICLE_COUNTER = Object.freeze({
     ALIVE: 0,
     /** length of the dead (free) list */
     DEAD: 1,
-    /** number of particles requested to spawn this frame */
-    SPAWN: 2,
+    /**
+     * Free slots not yet promised to a spawn this frame. The reset pass seeds it from
+     * {@link DEAD}; the emitter tick pass takes from it as it decides each emitter's spawn count,
+     * so an emitter is only ever debited for particles the pool can actually hold. What is left at
+     * the end of the frame is the headroom the frame had.
+     */
+    SPAWN_BUDGET: 2,
     /**
      * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
      * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
@@ -48,15 +50,3 @@ export const PARTICLE_COUNTER = Object.freeze({
 
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT = 8;
-
-/**
- * Per-dispatch uniform for the simulate/emit passes.
- * @type {WebGPUStruct}
- */
-export const PARTICLE_SIM_UNIFORM_STRUCT = WebGPUStruct.from({
-    dt: f32,
-    time: f32,
-    frame: u32,
-    /** number of items in the input list (alive-in for simulate, spawn requests for emit) */
-    count: u32,
-}, "ParticleSimUniform");

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

@@ -0,0 +1,56 @@
+/**
+ * Emitters are counted in tens, not thousands, so the engine-wide default page (128 KB) would
+ * reserve two orders of magnitude more than a scene ever fills. 16 KB still holds ~140 emitters per
+ * page and the table grows a page at a time past that.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_PAGE_SIZE: number;
+/**
+ * How big an emitter database's buffer starts out. The page address table takes 32 KB (two tables'
+ * worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each table —
+ * around a hundred and forty emitters — before the database grows itself.
+ *
+ * @type {number}
+ */
+export const PARTICLE_DATABASE_INITIAL_SIZE: number;
+/** Name of the emitter table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_EMITTER_TABLE: "emitters";
+/** Name of the GPU-owned emitter state table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_EMITTER_STATE_TABLE: "emitter_state";
+/**
+ * Schema of the particle system's GPU database. Two tables, one row per emitter in each, at the
+ * same row index:
+ *
+ * - `emitters` — CPU-authored and low-churn, exactly the shape `GPUDatabase` is for. Adding or
+ *   removing one emitter queues that one record for upload; the rest of the table is not touched,
+ *   and the pass shaders address rows by a stable id that survives its neighbours coming and going.
+ * - `emitter_state` — GPU-owned ({@link ./PARTICLE_EMITTER_STATE.js}): claimed with a zero record
+ *   when the emitter's row is, then written only by the tick and spawn-command passes.
+ *
+ * One buffer for both is what keeps every pass that reads an emitter at one binding for the pair.
+ *
+ * Programs and their constant pools are NOT here: they are variable-length and shared between
+ * emitters, so they live in the packed {@link ../runtime/ProgramArena.js} buffer, referenced by the
+ * offsets each emitter record carries.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const PARTICLE_DATABASE_SPEC: GPUDatabaseDefinition;
+/**
+ * Descriptor for the emitter table — the source of the WGSL reader every emitter-consuming pass
+ * pulls in ({@link GPUTypedTableDescriptor#chunk_read}, and
+ * {@link GPUTypedTableDescriptor#chunk_read_field} for the passes that want a single field).
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_EMITTER_DESCRIPTOR: GPUTypedTableDescriptor;
+/**
+ * Descriptor for the state table — the tick pass reads and writes whole rows through it, the
+ * spawn-command pass adds to one, and the emit / simulate passes read the age off it.
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_EMITTER_STATE_DESCRIPTOR: GPUTypedTableDescriptor;
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+//# sourceMappingURL=PARTICLE_DATABASE_SPEC.d.ts.map