@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/runtime/ProgramPlacement.js

@@ -0,0 +1,106 @@
+/**
+ * Where one program sits in the {@link ./ProgramHeap.js ProgramHeap}, and what an emitter record
+ * carries to find it.
+ *
+ * A placement is the heap's, not the caller's: {@link ./ProgramHeap.js#acquire} hands one out and
+ * {@link ./ProgramHeap.js#release} takes it back, and every field here is written by the heap. It is
+ * shared — every emitter running the same bytecode holds the same placement object, which is what
+ * puts them in one simulation bucket — and it is MUTATED IN PLACE when the heap repacks. Holders
+ * therefore see the new offsets without being handed a new object, and only have to restage the
+ * record they wrote the old ones into.
+ *
+ * The offsets are section-relative, which is what lets the heap move a program without the shader
+ * knowing: instruction offsets count instructions from the code section's base, and
+ * {@link ProgramPlacement#constant_offset} counts words from the constant section's base. The one
+ * absolute address in the whole buffer is the header word saying where the code section starts.
+ */
+export class ProgramPlacement {
+
+    /**
+     * Dense-ish id of this program: the value the emitter record carries and the simulation-order
+     * pass histograms on. Stable for the life of the placement, repacks included — the offsets move,
+     * the id does not.
+     *
+     * Ids are handed out lowest-free-first and a released one is reused, so they stay inside
+     * `[0, ProgramHeap#program_id_capacity)` however many programs come and go.
+     *
+     * @type {number}
+     */
+    program_id = -1;
+
+    /**
+     * First instruction of the INIT section, counted in instructions from the code base.
+     * @type {number}
+     */
+    init_offset = 0;
+
+    /**
+     * Instructions in the INIT section.
+     * @type {number}
+     */
+    init_count = 0;
+
+    /**
+     * First instruction of the UPDATE section, counted in instructions from the code base. Directly
+     * after INIT — the two sections of a program are allocated as one contiguous range.
+     * @type {number}
+     */
+    update_offset = 0;
+
+    /**
+     * Instructions in the UPDATE section.
+     * @type {number}
+     */
+    update_count = 0;
+
+    /**
+     * First word of this program's constant pool, counted in words from the constant base. The VM
+     * adds it to every program-local constant reference.
+     * @type {number}
+     */
+    constant_offset = 0;
+
+    /**
+     * The heap's own copy of the bytecode — the key it is filed under, and what a repack rewrites
+     * into the moved range.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    program = null;
+
+    /**
+     * How many emitters hold this placement. The heap frees the ranges and releases the id when it
+     * reaches zero, so one emitter of a shared effect going away does not take the effect with it.
+     *
+     * @type {number}
+     */
+    references = 0;
+
+    /**
+     * The code range, in instructions, as {@link ../../../../core/binary/allocator/OffsetAllocator.js}
+     * handed it out. `null` for a program with no instructions at all.
+     *
+     * @type {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation|null}
+     */
+    code_allocation = null;
+
+    /**
+     * The constant-pool range, in words. `null` for a program with an empty pool.
+     * @type {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation|null}
+     */
+    constant_allocation = null;
+
+    /**
+     * @returns {number} instructions this program occupies in the code section, both sections summed
+     */
+    get instruction_count() {
+        return this.init_count + this.update_count;
+    }
+
+    /**
+     * @returns {number} words this program occupies in the constant section
+     */
+    get constant_word_count() {
+        return this.program === null ? 0 : this.program.constant_word_count;
+    }
+}

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts

@@ -2,8 +2,11 @@
  * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
+ * The two halves come back together because they are compiled together, and an emitter takes both:
+ * the layout is what a render binding resolves a name against, the program is what the heap packs.
+ * They are not a value in their own right, so they go into an emitter by being spread —
+ * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
+ * the emitter keeps them as two fields rather than as one bag.
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}

package/src/shade/renderer/particles/runtime/create_particle_effect.js

@@ -1,19 +1,22 @@
-import { compile_particle_effect } from "../graph/compile_particle_graph.js";
-
-/**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
- * and UPDATE node graphs, lowered to VM bytecode.
- *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
- *
- * @param {object} params
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {NodeGraph} [params.init]
- * @param {NodeGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
- */
-export function create_particle_effect({ layout, init, update }) {
-    const program = compile_particle_effect({ init, update, layout });
-    return { layout, program };
-}
+import { compile_particle_effect } from "../graph/compile_particle_graph.js";
+
+/**
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
+ * and UPDATE node graphs, lowered to VM bytecode.
+ *
+ * The two halves come back together because they are compiled together, and an emitter takes both:
+ * the layout is what a render binding resolves a name against, the program is what the heap packs.
+ * They are not a value in their own right, so they go into an emitter by being spread —
+ * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
+ * the emitter keeps them as two fields rather than as one bag.
+ *
+ * @param {object} params
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @param {NodeGraph} [params.init]
+ * @param {NodeGraph} [params.update]
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ */
+export function create_particle_effect({ layout, init, update }) {
+    const program = compile_particle_effect({ init, update, layout });
+    return { layout, program };
+}

package/src/shade/renderer/particles/shaders/chunk_particle_emit_step.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the emit pass does for one particle born this frame — which emitter it belongs to, and what
+ * its record holds once it exists.
+ *
+ * Shared by {@link ./shader_particle_emit.js} and {@link ./shader_particle_emit_wide.js} for the
+ * same reason {@link ./chunk_particle_simulate_step.js} is shared: two register backings, one
+ * meaning, and the difference between the shaders is how they get an index and nothing else.
+ *
+ * ## What stays in the entry points
+ *
+ * Both atomic sections: popping a free slot off the dead-list stack, and appending the newborn to
+ * the alive list. They bracket `particle_emit_one` rather than living inside it, because the pop
+ * has to fail before any record is touched, and because an atomic array behind a pointer parameter
+ * is a shape nothing else in the engine uses.
+ *
+ * The pop is the delicate one, and its guard must catch WRAPPED values rather than just zero. When
+ * many threads race an empty stack, the first over-pop wraps the counter to `0xFFFFFFFF` before its
+ * undo lands, and a concurrent thread then observes a huge old value. Checking only `== 0` would let
+ * it index `dead[old - 1]` with garbage and hand out a bogus slot, corrupting a live record. The
+ * dead count can never legitimately exceed the pool capacity, so `> capacity` identifies every
+ * wrapped state; each thread that subtracted also adds back exactly once, so the counter converges
+ * to 0. Both entry points spell that out; this paragraph is where it is explained.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emit_step: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emit_step.d.ts.map

package/src/shade/renderer/particles/shaders/chunk_particle_emit_step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_emit_step.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_emit_step.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,uCAFU,SAAS,CAoGhB;0BAvIuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_emit_step.js

@@ -0,0 +1,136 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_lower_bound_branchless } from "../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_USER_WORD_START,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
+import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
+
+/**
+ * What the emit pass does for one particle born this frame — which emitter it belongs to, and what
+ * its record holds once it exists.
+ *
+ * Shared by {@link ./shader_particle_emit.js} and {@link ./shader_particle_emit_wide.js} for the
+ * same reason {@link ./chunk_particle_simulate_step.js} is shared: two register backings, one
+ * meaning, and the difference between the shaders is how they get an index and nothing else.
+ *
+ * ## What stays in the entry points
+ *
+ * Both atomic sections: popping a free slot off the dead-list stack, and appending the newborn to
+ * the alive list. They bracket `particle_emit_one` rather than living inside it, because the pop
+ * has to fail before any record is touched, and because an atomic array behind a pointer parameter
+ * is a shape nothing else in the engine uses.
+ *
+ * The pop is the delicate one, and its guard must catch WRAPPED values rather than just zero. When
+ * many threads race an empty stack, the first over-pop wraps the counter to `0xFFFFFFFF` before its
+ * undo lands, and a concurrent thread then observes a huge old value. Checking only `== 0` would let
+ * it index `dead[old - 1]` with garbage and hand out a bogus slot, corrupting a live record. The
+ * dead count can never legitimately exceed the pool capacity, so `> capacity` identifies every
+ * wrapped state; each thread that subtracted also adds back exactly once, so the counter converges
+ * to 0. Both entry points spell that out; this paragraph is where it is explained.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emit_step = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
+
+// Which emitter newborn i belongs to, and where in that emitter's batch it sits.
+struct ParticleEmitAssignment {
+    valid : bool,
+    emitter_row : u32,
+    // This particle's place in its emitter's batch this frame, n / count — the SPAWN_FRACTION
+    // contract, for spreading a batch along a spawn curve.
+    spawn_fraction : f32,
+}
+
+// Locate newborn i in the prefix scan of the tick pass's per-row spawn counts.
+//
+// The emitter is the first row whose inclusive sum exceeds i; its batch starts at the sum before,
+// which is the exclusive sum. Rows that spawned nothing this frame have equal sums and the search
+// steps over them. That is the meshes-to-meshlets expansion applied to particles: the per-emitter
+// count is unbounded and no thread loops over it.
+fn particle_emit_assignment(
+    prefix : ptr<storage, array<u32>>,
+    emitter_count : u32,
+    i : u32,
+) -> ParticleEmitAssignment {
+    var r : ParticleEmitAssignment;
+    r.valid = false;
+    r.emitter_row = 0u;
+    r.spawn_fraction = 0.0;
+
+    // The scan's last inclusive sum is the number of particles born this frame. An empty list has
+    // no last element to read; it also has no particles.
+    if (emitter_count == 0u) { return r; }
+    if (i >= (*prefix)[emitter_count - 1u]) { return r; }
+
+    let emitter_row = lower_bound_branchless(prefix, i + 1u, emitter_count);
+    var batch_start = 0u;
+    if (emitter_row > 0u) {
+        batch_start = (*prefix)[emitter_row - 1u];
+    }
+    let batch_size = (*prefix)[emitter_row] - batch_start;
+
+    r.valid = true;
+    r.emitter_row = emitter_row;
+    r.spawn_fraction = f32(i - batch_start) / f32(batch_size);
+
+    return r;
+}
+
+// Give a freshly popped slot its particle: clear what the last occupant left, stamp the header with
+// the emitter row and its generation, and run that emitter's INIT program over the record. The
+// emitter's position and axes come from its scene node, so a particle born of an emitter riding a
+// bone starts where the bone is this frame.
+fn particle_emit_one(
+    scene_database : ptr<storage, array<u32>>,
+    emitter_database : ptr<storage, array<u32>>,
+    program : ptr<storage, array<u32>>,
+    pool : ptr<storage, array<u32>, read_write>,
+    emitter_row : u32,
+    slot : u32,
+    spawn_fraction : f32,
+    dt : f32,
+    time : f32,
+    frame : u32,
+) {
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+
+    let em = particle_emitter_read(emitter_database, emitter_row);
+    let node = scene_read_node(scene_database, em.node);
+
+    // Clear stale user state from a recycled slot (each write targets a distinct word).
+    for (var w = PARTICLE_USER_WORD_START; w < PARTICLE_RECORD_WORDS; w = w + 1u) {
+        (*pool)[record_base + w] = 0u;
+    }
+    (*pool)[record_base + PARTICLE_HEADER_EMITTER] = particle_header_pack(emitter_row, em.generation);
+
+    particle_vm_reset();
+    particle_setup_context(
+        em, node, slot,
+        dt, time,
+        particle_emitter_age(emitter_database, emitter_row),
+        spawn_fraction, frame,
+    );
+    particle_vm_execute(
+        program,
+        em.init_offset * PARTICLE_INSTRUCTION_WORDS,
+        em.init_count,
+        em.constant_offset,
+        pool,
+        record_base,
+    );
+}
+`, [
+    chunk_particle_setup_context,
+    chunk_particle_emitter_age,
+    chunk_particle_header,
+    chunk_lower_bound_branchless,
+]);

package/src/shade/renderer/particles/shaders/chunk_particle_simulate_step.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What the simulate pass does to one particle — everything between reading its slot out of the
+ * coherence list and deciding whether it lives.
+ *
+ * It is a chunk rather than the body of a shader because there are two simulate shaders and only one
+ * simulation. {@link ./shader_particle_simulate.js} runs one invocation per particle over the fast
+ * register file; {@link ./shader_particle_simulate_wide.js} runs a bounded launch with a grid-stride
+ * loop over the wide one. They differ in how they get an index and in nothing else, and everything
+ * that is not "how do I get an index" lives here so it cannot drift between them.
+ *
+ * ## What stays in the entry points
+ *
+ * The compaction atomics. `particle_simulate_one` returns a verdict and the caller acts on it, so
+ * the two `atomicAdd`s and the list appends sit in `main` where the dispatch shape can be seen next
+ * to them. That is also why this chunk takes no pointer to `counters`: an atomic array behind a
+ * pointer parameter is a shape nothing else in the engine uses, and the seam is not worth being the
+ * first.
+ *
+ * ## The padding verdict is a verdict, not an early exit
+ *
+ * A lane the coherence pass padded a bucket out with returns {@link PARTICLE_SIM_SKIP}, and the
+ * caller then does nothing at all with it. Getting this wrong is not subtle in its consequences:
+ * appending a padding lane would put {@link PARTICLE_SIM_PAD_SLOT} — `0xffffffff` — on the alive
+ * list or the free list, and a later emit would take it off the free list and use it as a record
+ * base.
+ *
+ * Returning early from this function leaves the lane inactive for the rest of it, which is exactly
+ * what the wave-uniform read below needs, and is the same active set the old inline early-`return`
+ * produced.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_simulate_step: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_simulate_step.d.ts.map

package/src/shade/renderer/particles/shaders/chunk_particle_simulate_step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_simulate_step.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_simulate_step.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,2CAFU,SAAS,CA2FhB;0BApIuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_simulate_step.js

@@ -0,0 +1,133 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIM_PAD_SLOT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
+import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
+
+/**
+ * What the simulate pass does to one particle — everything between reading its slot out of the
+ * coherence list and deciding whether it lives.
+ *
+ * It is a chunk rather than the body of a shader because there are two simulate shaders and only one
+ * simulation. {@link ./shader_particle_simulate.js} runs one invocation per particle over the fast
+ * register file; {@link ./shader_particle_simulate_wide.js} runs a bounded launch with a grid-stride
+ * loop over the wide one. They differ in how they get an index and in nothing else, and everything
+ * that is not "how do I get an index" lives here so it cannot drift between them.
+ *
+ * ## What stays in the entry points
+ *
+ * The compaction atomics. `particle_simulate_one` returns a verdict and the caller acts on it, so
+ * the two `atomicAdd`s and the list appends sit in `main` where the dispatch shape can be seen next
+ * to them. That is also why this chunk takes no pointer to `counters`: an atomic array behind a
+ * pointer parameter is a shape nothing else in the engine uses, and the seam is not worth being the
+ * first.
+ *
+ * ## The padding verdict is a verdict, not an early exit
+ *
+ * A lane the coherence pass padded a bucket out with returns {@link PARTICLE_SIM_SKIP}, and the
+ * caller then does nothing at all with it. Getting this wrong is not subtle in its consequences:
+ * appending a padding lane would put {@link PARTICLE_SIM_PAD_SLOT} — `0xffffffff` — on the alive
+ * list or the free list, and a later emit would take it off the free list and use it as a record
+ * base.
+ *
+ * Returning early from this function leaves the lane inactive for the rest of it, which is exactly
+ * what the wave-uniform read below needs, and is the same active set the old inline early-`return`
+ * produced.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_simulate_step = 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 PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
+const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
+
+// Verdicts particle_simulate_one returns. SKIP is a lane that never held a particle.
+const PARTICLE_SIM_SKIP : u32 = 0u;
+const PARTICLE_SIM_ALIVE : u32 = 1u;
+const PARTICLE_SIM_KILLED : u32 = 2u;
+
+// The value the wave's first live lane holds, in every lane.
+//
+// Everything that reaches the interpreter in one wave belongs to one bucket of sim_list: the
+// coherence pass grouped the list by program and padded each group to a whole workgroup, and the
+// padding and orphan lanes have left by the time a program runs. So the three numbers that pick a
+// section are the same in every lane. The compiler cannot see that — they come out of a table row
+// found through a per-lane header, which is as divergent as a value gets — and reading them from
+// the first lane is what tells it. The rest follows on its own: the instruction words are then
+// fetched through the scalar unit, the opcode switch branches on a scalar, and the fast register
+// file is indexed through M0 directly instead of through a waterfall loop over the lanes' indices.
+// (The wide file is indexed per-lane whatever happens, and keeps the other two.) Emit keeps its
+// per-lane decode, because its waves span emitters.
+//
+// The grid-stride caller preserves this: its stride is a whole number of workgroups, so an
+// iteration covers a workgroup-aligned span of the list and a wave still sees one bucket.
+//
+// The uniformity diagnostic is off because the call sits behind per-lane early returns. That is the
+// situation the builtin is defined for — it reads the first ACTIVE lane — and the one WGSL's
+// analysis over-approximates.
+@diagnostic(off, subgroup_uniformity)
+fn particle_wave_uniform(value : u32) -> u32 {
+    return subgroupBroadcastFirst(value);
+}
+
+// Run one particle's UPDATE program and say what became of it. Everything the caller then has to do
+// is atomic.
+fn particle_simulate_one(
+    scene_database : ptr<storage, array<u32>>,
+    emitter_database : ptr<storage, array<u32>>,
+    program : ptr<storage, array<u32>>,
+    pool : ptr<storage, array<u32>, read_write>,
+    slot : u32,
+    dt : f32,
+    time : f32,
+    frame : u32,
+) -> u32 {
+    // A lane the coherence pass padded the bucket out with. It owns no slot, so it has no verdict
+    // and the caller must not book one for it. Padding only ever appears in the tail of a bucket, so
+    // every real lane in this wave still belongs to the one bucket, and the switch the survivors
+    // execute is uniform regardless.
+    if (slot == PARTICLE_SIM_PAD_SLOT) { return PARTICLE_SIM_SKIP; }
+
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+    let header = (*pool)[record_base + PARTICLE_HEADER_EMITTER];
+    let emitter_index = particle_header_emitter(header);
+
+    let em = particle_emitter_read(emitter_database, emitter_index);
+
+    // An orphan: its emitter is gone and the row is free or somebody else's. Freed without running
+    // a program — there is no program of its own left to run.
+    if (particle_header_generation(header) != em.generation) { return PARTICLE_SIM_KILLED; }
+
+    let node = scene_read_node(scene_database, em.node);
+
+    particle_vm_reset();
+    particle_setup_context(
+        em, node, slot,
+        dt, time,
+        particle_emitter_age(emitter_database, emitter_index),
+        0.0, frame,
+    );
+    particle_vm_execute(
+        program,
+        particle_wave_uniform(em.update_offset) * PARTICLE_INSTRUCTION_WORDS,
+        particle_wave_uniform(em.update_count),
+        particle_wave_uniform(em.constant_offset),
+        pool,
+        record_base,
+    );
+
+    if (vm_killed) { return PARTICLE_SIM_KILLED; }
+
+    return PARTICLE_SIM_ALIVE;
+}
+`, [
+    chunk_particle_setup_context,
+    chunk_particle_emitter_age,
+    chunk_particle_header,
+]);

package/src/shade/renderer/particles/shaders/shader_particle_emit.d.ts

@@ -1,16 +1,14 @@
 /**
  * The particle emit pass: one thread per particle born this frame.
  *
- * Its input is the prefix scan of the emitter tick pass's per-row spawn counts. Thread `i` finds
- * the emitter it belongs to by binary search over the inclusive sums — the first row whose sum
- * exceeds `i` — and its place within that emitter's batch from the sum before. That is the
- * meshes-to-meshlets expansion applied to particles: the per-emitter count is unbounded, no thread
- * loops, and the dispatch is sized on the GPU from the scan's total.
+ * Its input is the prefix scan of the emitter tick pass's per-row spawn counts; thread `i` finds the
+ * emitter it belongs to by binary search over the inclusive sums, and its place within that
+ * emitter's batch from the sum before. Then: pop a free slot from the dead list, clear the record,
+ * stamp the header, run the emitter's INIT program, and append the slot to the new alive list.
  *
- * Then, as ever: pop a free slot from the dead list, clear the record, stamp the header with the
- * emitter row and its generation, run the emitter's INIT program to give the particle its state,
- * and append the slot to the new alive list. The emitter's position and axes come from its scene
- * node, so a particle born of an emitter riding a bone starts where the bone is this frame.
+ * The per-newborn work is {@link ./chunk_particle_emit_step.js}, shared with
+ * {@link ./shader_particle_emit_wide.js}. What this file is, is the *fast* register backing plus the
+ * one-lane-per-newborn dispatch that suits it.
  *
  * Runs before simulate in the frame so newborns join the same alive list survivors are compacted
  * into. Shares the VM + context + emitter chunks with simulate.
@@ -22,6 +20,17 @@
  * size — so the two must agree, and the constant it uses is the one it is.
  */
 export const PARTICLE_EMIT_WORKGROUP_SIZE: number;
+/**
+ * Per-dispatch, 16 bytes, read-only.
+ *
+ * These were separate uniforms, which meant a transient buffer, a staging copy and a bind group
+ * entry each for a few bytes of frame state. WGSL allows one immediate per entry point, so carrying
+ * them as immediate data means carrying them together.
+ *
+ * @type {WebGPUStruct}
+ */
+export const EMIT_SETTINGS: WebGPUStruct;
 export const shader_particle_emit: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_particle_emit.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,kDAA8E;AAuH9E,iDAIG;8BAnK2B,+BAA+B"}
+{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,kDAA8E;AAE9E;;;;;;;;GAQG;AACH,4BAFU,YAAY,CAOK;AAqD3B,iDAIG;6BA1G0B,mCAAmC;8BAGlC,+BAA+B"}