@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,197 +1,132 @@
-import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { ColorTargetState } from "../../../descriptor/pipeline/render/ColorTargetState.js";
-import { DepthStencilState } from "../../../descriptor/pipeline/render/DepthStencilState.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_WORD_COUNT,
-} from "../ParticleConstants.js";
-import { EMITTER_ATTRIBUTE_ABSENT, EMITTER_FLAG } from "../data/PARTICLE_EMITTER_LAYOUT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
-import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
-
-/**
- * The billboard renderer.
- *
- * One instanced draw covers every visible particle: `instance_index` indexes the depth-`sorted` slot
- * list, `vertex_index` (0..5) picks a quad corner. The vertex stage reads the particle's render-bound
- * attributes (position / size / colour / rotation / flipbook frame), expands the corner per the
- * emitter's projection mode, and projects with the camera. The fragment stage samples the atlas
- * sub-rect + flipbook cell, applies an optional soft-depth fade against the scene depth, runs the
- * pluggable lighting hook (unlit by default; the feature swaps in the shading-chunk-backed one when
- * an emitter enables lighting), and emits premultiplied colour.
- *
- * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
- * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
- * the whole draw stays GPU-driven with no pipeline switches.
- *
- * The math (billboard expansion, atlas/flipbook UV, soft fade, premultiply) is unit-tested in
- * {@link ./chunk_particle_render_math.spec.js}; this module assembles it into a render pipeline.
- */
-
-/** Premultiplied blend: additive when a=0 (dst preserved, colour adds), over-blend when a=srcAlpha. */
-export const PARTICLE_BILLBOARD_BLEND = {
-    color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-    alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-};
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("sorted", WebGPUArray.u32, false)
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    // Sampled with a filtering sampler, so the atlas must be a filterable float texture.
-    .addTexture("atlas", "float")
-    .addSampler("atlas_sampler", "filtering")
-    // Only textureLoad-ed (soft depth), so it can be unfilterable — matches an r32float scene depth.
-    .addTexture("scene_depth", "unfilterable-float");
-
-const 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 PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
-const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
-const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
-const PARTICLE_SOFT_FADE_RANGE : f32 = 0.5;
-
-struct ParticleVertexOut {
-    @builtin(position) clip : vec4<f32>,
-    @location(0) uv : vec2<f32>,
-    @location(1) color : vec4<f32>,
-    @location(2) world_position : vec3<f32>,
-    @location(3) normal : vec3<f32>,
-    @location(4) view_depth : f32,
-    @location(5) @interpolate(flat) flags : u32,
-    @location(6) @interpolate(flat) blend : u32,
-}
-
-fn particle_read_vec(base : u32, offset : u32, count : u32) -> vec4<f32> {
-    var v = vec4<f32>(0.0);
-    if (count > 0u) { v.x = bitcast<f32>(pool[base + offset]); }
-    if (count > 1u) { v.y = bitcast<f32>(pool[base + offset + 1u]); }
-    if (count > 2u) { v.z = bitcast<f32>(pool[base + offset + 2u]); }
-    if (count > 3u) { v.w = bitcast<f32>(pool[base + offset + 3u]); }
-    return v;
-}
-
-@vertex
-fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
-    var corners = array<vec2<f32>, 6>(
-        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
-        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(-1.0, 1.0),
-    );
-    let corner = corners[vi];
-
-    let slot = sorted[ii];
-    let base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    var world_center = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
-    var size = 1.0;
-    if (em.render_size != PARTICLE_ATTRIBUTE_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
-    var color = vec4<f32>(1.0);
-    if (em.render_color != PARTICLE_ATTRIBUTE_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
-    var rotation = 0.0;
-    if (em.render_rotation != PARTICLE_ATTRIBUTE_ABSENT) { rotation = bitcast<f32>(pool[base + em.render_rotation]); }
-    var frame = 0.0;
-    if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
-    var velocity = vec3<f32>(0.0);
-    if (em.render_velocity != PARTICLE_ATTRIBUTE_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
-
-    let cam_right = camera.transform[0].xyz;
-    let cam_up = camera.transform[1].xyz;
-    let cam_forward = -camera.transform[2].xyz;
-
-    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, particle_emitter_projection(em.flags));
-    let world = world_center + offset;
-
-    var out : ParticleVertexOut;
-    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
-    out.uv = particle_atlas_uv(corner * 0.5 + vec2<f32>(0.5), em.atlas_region, em.flipbook, frame);
-    out.color = color;
-    out.world_position = world;
-    out.normal = -cam_forward;
-    out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
-    out.flags = em.flags;
-    out.blend = particle_emitter_blend(em.flags);
-    return out;
-}
-
-@fragment
-fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
-    let sampled = textureSample(atlas, atlas_sampler, in.uv);
-    var color = sampled * in.color;
-
-    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
-        let scene_dev = textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r;
-        // Reverse-Z hyperbolic linearisation: view_depth = A / (device_depth + B).
-        let A = camera.device_depth_to_view_space.y;
-        let B = camera.device_depth_to_view_space.x;
-        let scene_vd = select(A / (scene_dev + B), 1e9, scene_dev <= 0.0);
-        color.a = color.a * particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE);
-    }
-
-    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
-        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
-    }
-
-    return particle_premultiply(color, in.blend);
-}
-`, [chunk_particle_emitter, chunk_particle_render_math, chunk_particle_lighting_unlit]);
-
-/**
- * The shader itself. One compilation, shared by every pipeline built from it — the options below
- * vary the pipeline state, never the WGSL.
- *
- * @type {ShaderDescriptor}
- */
-const descriptor = ShaderDescriptor.from({ label: "Particle Billboard", body, resources });
-
-/**
- * Build the billboard render pipeline descriptor.
- * @param {object} [options]
- * @param {string} [options.color_format] colour target format
- * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
- *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
- * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
- *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
- * @returns {RenderPipelineDescriptor}
- */
-export function create_particle_billboard_pipeline({
-                                                       color_format = "rgba16float",
-                                                       depth_format = "depth32float",
-                                                       depth_compare = "greater"
-} = {}) {
-
-    const code = descriptor.source;
-
-    return RenderPipelineDescriptor.from({
-        label: "Particle Billboard",
-        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: {
-            module: { code },
-            entryPoint: "fs_main",
-            targets: [ColorTargetState.from({ format: color_format, blend: PARTICLE_BILLBOARD_BLEND })],
-        },
-        // Depth-test against the scene, but never write (transparent). Omitted entirely when no depth
-        // attachment is bound.
-        depthStencil: depth_format == null
-            ? undefined
-            : DepthStencilState.from({ format: depth_format, depthWriteEnabled: false, depthCompare: depth_compare }),
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-
-}
-
-/** The billboard shader's resource set (for building bind groups + the draw command). */
-export const PARTICLE_BILLBOARD_RESOURCES = resources;
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { ColorTargetState } from "../../../descriptor/pipeline/render/ColorTargetState.js";
+import { DepthStencilState } from "../../../descriptor/pipeline/render/DepthStencilState.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
+import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
+
+/**
+ * The standalone billboard renderer: particles drawn straight over the scene colour, back to
+ * front, with fixed-function blending. This is the path a page without the renderer's transparency
+ * pipeline uses; under the renderer the particles go through AVBOIT instead
+ * (`../graph_particles_avboit.js`), where order does not matter and they composite against the
+ * transparent meshes.
+ *
+ * One instanced draw covers every visible particle: `instance_index` indexes the depth-sorted
+ * `draw_list`, `vertex_index` (0..5) picks a quad corner. The vertex stage is `chunk_particle_billboard_vertex`,
+ * shared with the AVBOIT particle passes. The fragment stage samples the atlas sub-rect + flipbook
+ * cell, applies an optional soft-depth fade against the scene depth, runs the pluggable lighting hook
+ * (unlit by default; the feature swaps in the shading-chunk-backed one when an emitter enables
+ * lighting), and emits premultiplied colour.
+ *
+ * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
+ * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
+ * the whole draw stays GPU-driven with no pipeline switches.
+ *
+ * The math (billboard expansion, atlas/flipbook UV, soft fade, premultiply) is unit-tested in
+ * {@link ./chunk_particle_render_math.spec.js}; this module assembles it into a render pipeline.
+ */
+
+/** Premultiplied blend: additive when a=0 (dst preserved, colour adds), over-blend when a=srcAlpha. */
+export const PARTICLE_BILLBOARD_BLEND = {
+    color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+    alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+};
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("draw_list", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    // Sampled with a filtering sampler, so the atlas must be a filterable float texture.
+    .addTexture("atlas", "float")
+    .addSampler("atlas_sampler", "filtering")
+    // Only textureLoad-ed (soft depth), so it can be unfilterable — matches an r32float scene depth.
+    .addTexture("scene_depth", "unfilterable-float");
+
+const body = CodeChunk.from(
+    /* language=wgsl */ `
+const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
+const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
+const PARTICLE_SOFT_FADE_RANGE : f32 = 0.5;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
+    return particle_billboard_vertex(vi, ii);
+}
+
+@fragment
+fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
+    let sampled = textureSample(atlas, atlas_sampler, in.uv);
+    var color = sampled * in.color;
+
+    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
+        let scene_dev = textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r;
+        // Reverse-Z hyperbolic linearisation: view_depth = A / (device_depth + B).
+        let A = camera.device_depth_to_view_space.y;
+        let B = camera.device_depth_to_view_space.x;
+        let scene_vd = select(A / (scene_dev + B), 1e9, scene_dev <= 0.0);
+        color.a = color.a * particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE);
+    }
+
+    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
+        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
+    }
+
+    return particle_premultiply(color, in.blend);
+}
+`, [chunk_particle_billboard_vertex, chunk_particle_lighting_unlit]);
+
+/**
+ * The shader itself. One compilation, shared by every pipeline built from it — the options below
+ * vary the pipeline state, never the WGSL.
+ *
+ * @type {ShaderDescriptor}
+ */
+const descriptor = ShaderDescriptor.from({ label: "Particle Billboard", body, resources });
+
+/**
+ * Build the billboard render pipeline descriptor.
+ * @param {object} [options]
+ * @param {string} [options.color_format] colour target format
+ * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
+ *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
+ * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
+ *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
+ * @returns {RenderPipelineDescriptor}
+ */
+export function create_particle_billboard_pipeline({
+                                                       color_format = "rgba16float",
+                                                       depth_format = "depth32float",
+                                                       depth_compare = "greater"
+} = {}) {
+
+    const code = descriptor.source;
+
+    return RenderPipelineDescriptor.from({
+        label: "Particle Billboard",
+        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+        vertex: { module: { code }, entryPoint: "vs_main" },
+        fragment: {
+            module: { code },
+            entryPoint: "fs_main",
+            targets: [ColorTargetState.from({ format: color_format, blend: PARTICLE_BILLBOARD_BLEND })],
+        },
+        // Depth-test against the scene, but never write (transparent). Omitted entirely when no depth
+        // attachment is bound.
+        depthStencil: depth_format == null
+            ? undefined
+            : DepthStencilState.from({ format: depth_format, depthWriteEnabled: false, depthCompare: depth_compare }),
+        primitive: { topology: "triangle-list", cullMode: "none" },
+    });
+
+}
+
+/** The billboard shader's resource set (for building bind groups + the draw command). */
+export const PARTICLE_BILLBOARD_RESOURCES = resources;

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AAyIA,qDAIG;iDAjII,yBAAyB;8BATF,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AA+LA,qDAIG;iDAtLI,yBAAyB;8BATF,+BAA+B"}

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

@@ -1,3 +1,4 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
@@ -12,7 +13,10 @@ import {
     PARTICLE_VM_INSTRUCTION_WORDS,
 } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_particle_context.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_curve_disabled } from "./chunk_particle_curve_disabled.js";
+import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
+import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
 
 /**
  * The particle simulate pass — Destiny-style single execution shader.
@@ -28,9 +32,10 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
  * `sim_list` is NOT the raw alive list. It is the program-coherent indirection list the coherence
  * pass (`../coherence/`) built at the end of last frame: the same pool slots, reordered so that
  * particles running one VM program sit together, each run padded out to a whole workgroup. That is
- * what keeps a wave from spanning two programs, which would make the interpreter's opcode `switch`
- * diverge and multiply the register file's `v_movrels` waterfall by the number of distinct register
- * indices in the wave.
+ * what keeps a wave from spanning two programs — and this shader leans on it rather than merely
+ * benefiting from it: the section parameters are read from the wave's first lane
+ * (`particle_wave_uniform` below), so a wave that held two programs would run one of them over the
+ * other's particles. The coherence pass is part of this shader's correctness, not only of its speed.
  *
  * Padding entries carry {@link PARTICLE_SIM_PAD_SLOT} and are dropped BEFORE the compaction
  * atomics, so a padding lane never appends to the alive list and never pushes a slot onto the free
@@ -39,6 +44,13 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
  * the tail of a bucket, and every real lane in that wave belongs to that one bucket, so the `switch`
  * the survivors execute is uniform regardless.
  *
+ * ## Orphans
+ *
+ * A particle whose header generation is not its emitter row's current generation belongs to an
+ * emitter that has been removed — the row is either zero-filled or already someone else's. It is
+ * killed here, the frame the mismatch appears, before it can run a stranger's program or follow a
+ * stranger's node. See `../data/particle_header.js`.
+ *
  * ## Sizing
  *
  * The input length is read from `counters[ALIVE_IN]` — the padded length of that list, snapshotted
@@ -75,9 +87,9 @@ const resources = new ShaderResourceSetDescriptor();
 resources.setImmediate('settings', SIMULATE_SETTINGS);
 
 resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
-    .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, true)
     .addStorageBuffer("sim_list", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
@@ -94,6 +106,26 @@ const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
 const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
 
+// 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 register file is
+// indexed through M0 directly instead of through a waterfall loop over the lanes' indices. The VM
+// chunk is unchanged, and emit keeps its per-lane decode, because its waves span emitters.
+//
+// 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);
+}
+
 @compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
@@ -109,23 +141,38 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     if (slot == PARTICLE_SIM_PAD_SLOT) { return; }
 
     let record_base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
-
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    particle_vm_reset();
-    particle_setup_context(em, slot, settings.u_dt, settings.u_time, 0.0, 0.0, settings.u_frame);
-    particle_vm_execute(
-        &program,
-        em.update_offset * PARTICLE_INSTRUCTION_WORDS,
-        em.update_count,
-        &vm_constants,
-        em.constant_offset,
-        &pool,
-        record_base,
-    );
-
-    if (vm_killed) {
+    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.
+    var killed = particle_header_generation(header) != em.generation;
+
+    if (!killed) {
+        let node = scene_read_node(&scene_database, em.node);
+
+        particle_vm_reset();
+        particle_setup_context(
+            em, node, slot,
+            settings.u_dt, settings.u_time,
+            particle_emitter_age(&emitter_database, emitter_index),
+            0.0, settings.u_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,
+        );
+
+        killed = vm_killed;
+    }
+
+    if (killed) {
         let d = atomicAdd(&counters[COUNTER_DEAD], 1u);
         dead[d] = slot;
     } else {
@@ -133,7 +180,14 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
         alive_out[a] = slot;
     }
 }
-`, [chunk_particle_context, chunk_particle_curve_disabled]);
+`, [
+    chunk_particle_setup_context,
+    chunk_particle_emitter_age,
+    chunk_particle_curve_disabled,
+    chunk_particle_header,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
 
 export const shader_particle_simulate = ComputeShader.from({
     label: "Particle Simulate",

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

@@ -0,0 +1,26 @@
+/**
+ * The CPU's way in to GPU spawning: a list of `(emitter row, particle count)` pairs the host
+ * authored this frame, each added to that emitter's `pending` in the GPU-owned state table. The
+ * tick pass, which runs next, folds `pending` into the emitter's accumulator and decides the actual
+ * spawn count along with everything else.
+ *
+ * Deliberately a facade over the GPU path rather than a second path: a burst asked for here goes
+ * through the same budget, the same expansion and the same INIT program as the emitter's own rate,
+ * and is subject to the same culling. It is also the channel a VM opcode would use to spawn from
+ * the GPU — a sub-emitter or a trail would add to its target's `pending` the same way, with an
+ * atomic binding of its own since many threads would race one row.
+ *
+ * **One command per row.** The state table shares its buffer with the emitter table, bound as a
+ * plain `array<u32>`, so the add here is a read-modify-write and two commands naming one row would
+ * lose one of them. The host merges duplicates before upload ({@link GPUParticleSystem#spawn}),
+ * which is a few dozen entries at most and costs it nothing.
+ *
+ * The dispatch is sized by the host, because the host wrote the list and knows its length exactly;
+ * it is the one host-provided count in the frame that is not stale by construction.
+ *
+ * @type {ComputeShader}
+ */
+export const PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE: ComputeShader;
+export const shader_particle_spawn_commands: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_spawn_commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_spawn_commands.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_spawn_commands.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oDAHU,aAAa,CAGiC;AA8BxD,2DAIG;8BA/D2B,+BAA+B"}

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

@@ -0,0 +1,66 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_SPAWN_COMMAND_WORDS } from "../ParticleConstants.js";
+import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+
+/**
+ * The CPU's way in to GPU spawning: a list of `(emitter row, particle count)` pairs the host
+ * authored this frame, each added to that emitter's `pending` in the GPU-owned state table. The
+ * tick pass, which runs next, folds `pending` into the emitter's accumulator and decides the actual
+ * spawn count along with everything else.
+ *
+ * Deliberately a facade over the GPU path rather than a second path: a burst asked for here goes
+ * through the same budget, the same expansion and the same INIT program as the emitter's own rate,
+ * and is subject to the same culling. It is also the channel a VM opcode would use to spawn from
+ * the GPU — a sub-emitter or a trail would add to its target's `pending` the same way, with an
+ * atomic binding of its own since many threads would race one row.
+ *
+ * **One command per row.** The state table shares its buffer with the emitter table, bound as a
+ * plain `array<u32>`, so the add here is a read-modify-write and two commands naming one row would
+ * lose one of them. The host merges duplicates before upload ({@link GPUParticleSystem#spawn}),
+ * which is a few dozen entries at most and costs it nothing.
+ *
+ * The dispatch is sized by the host, because the host wrote the list and knows its length exactly;
+ * it is the one host-provided count in the frame that is not stale by construction.
+ *
+ * @type {ComputeShader}
+ */
+
+export const PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE = 64;
+
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+resources.setImmediate("u_count", u32);
+
+resources.createGroup()
+    .addStorageBuffer("commands", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true);
+
+const body = CodeChunk.from(/* language=wgsl */ `
+const COMMAND_WORDS : u32 = ${PARTICLE_SPAWN_COMMAND_WORDS}u;
+
+@compute @workgroup_size(${PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= u_count) { return; }
+
+    let row = commands[i * COMMAND_WORDS];
+    let count = commands[i * COMMAND_WORDS + 1u];
+
+    var state = ${STATE.marshalling_method_read_rw}(&emitter_database, row);
+    state.pending = state.pending + count;
+    ${STATE.marshalling_method_write}(&emitter_database, row, state);
+}
+`, [STATE.chunk_read_rw, STATE.chunk_write]);
+
+export const shader_particle_spawn_commands = ComputeShader.from({
+    label: "Particle Spawn Commands",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts

@@ -1,6 +1,6 @@
 export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 /**
- * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count)` threads, not over
  * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
  * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
  * and the scan adds them in.

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAsDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AA0EH,2DAIG;AAyCH,yDAIG;8BA1O2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAyDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AAgEH,2DAIG;AAiCH,yDAIG;8BA3N2B,+BAA+B"}