@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/playground/particle_system/particle_scene.js

@@ -1,670 +1,487 @@
-import { m4_allocate } from "../../../core/geom/3d/mat4/m4_allocate.js";
-import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
-import { m4_look_at } from "../../../core/geom/3d/mat4/m4_look_at.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
-import {
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-} from "../../renderer/particles/ParticleConstants.js";
-import {
-    PREFIX_SCAN_CSDLDF_HEADER_WORDS,
-    PREFIX_SCAN_CSDLDF_PARTITION_SIZE,
-    shader_prefix_scan_csdldf,
-} from "../../renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
-import { build_indirect_compute_dispatch_command } from "../../renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
-import {
-    shader_particle_bucket_fill,
-    shader_particle_bucket_histogram,
-    shader_particle_bucket_pad,
-    shader_particle_bucket_reset,
-    shader_particle_bucket_scatter,
-} from "../../renderer/particles/coherence/shader_particle_bucket.js";
-import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
-import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
-import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
-import { VM_BUILTIN, VM_RANDOM_MODE } from "../../renderer/particles/isa/ParticleVMISA.js";
-import { ParticleLayout } from "../../renderer/particles/layout/ParticleLayout.js";
-import { GPUParticleSystem } from "../../renderer/particles/GPUParticleSystem.js";
-import { create_particle_effect } from "../../renderer/particles/runtime/create_particle_effect.js";
-import { fire_effect } from "../../renderer/particles/particle_prototype.js";
-import {
-    PARTICLE_BILLBOARD_RESOURCES,
-    create_particle_billboard_pipeline,
-} from "../../renderer/particles/shaders/shader_particle_render.js";
-import { shader_particle_emit } from "../../renderer/particles/shaders/shader_particle_emit.js";
-import {
-    shader_particle_build_indirect,
-    shader_particle_reset_counters,
-} from "../../renderer/particles/shaders/shader_particle_finalize.js";
-import { shader_particle_simulate } from "../../renderer/particles/shaders/shader_particle_simulate.js";
-
-/**
- * The scene the particle playground draws, with every reference to the page removed: it takes a
- * {@link GraphicsContext} and a colour target, and encodes one frame into a command context.
- *
- * Separate from `main.js` so the whole frame — every pass, binding, buffer usage and immediate
- * block — can be encoded against {@link ../../device/mock/SoftwareGPUDevice.js} in a vitest spec
- * (see `particle_scene.spec.js`). That is the only tier available to CI here; the mock validates
- * the WebGPU API surface but executes no shaders, so what a spec can prove is that the frame is
- * *legal*, not what it looks like. The picture is the browser's job.
- *
- * What the scene contains:
- *
- * - lit solid geometry (a ground plane + boxes) rendered into a reverse-Z depth buffer,
- * - four emitters with distinct settings — an additive fire, an alpha soft-depth smoke column,
- *   additive velocity-stretched sparks, and a wide soft-depth dust drift,
- * - a billboard pass that depth-tests against the scene, so particles are occluded by the boxes and
- *   soft-depth emitters fade as they approach surfaces.
- *
- * The loop is fully GPU-driven: the simulate dispatch runs via `dispatchWorkgroupsIndirect` and the
- * billboard draw via `drawIndirect`, both from args the build-indirect pass writes on the GPU. No
- * CPU readback participates in sizing anything — a stale CPU count would orphan alive-list entries
- * when the population grows and double-free slots when it shrinks.
- *
- * The four emitters run four distinct compiled programs, so this is also where the simulation-order
- * bucketing has something to do: without it a simulate wave holds fire, smoke, spark and dust
- * particles side by side, each wanting different opcodes out of the interpreter's switch. The
- * bucketing passes are encoded directly here rather than through `graph_particles`, which is the
- * frame-graph wiring of the same sequence.
- */
-
-/** Maximum simultaneous particles across every emitter — they share one pool. */
-const PARTICLE_CAPACITY = 1 << 15; // 32k
-
-/** Camera near plane. Also the numerator of the reverse-Z depth linearisation (see {@link write_camera}). */
-const PARTICLE_NEAR = 0.2;
-
-/**
- * The largest immediate block any of the three compute passes declares (emit's 20-byte settings
- * struct). Immediate data is an optional WebGPU capability, so callers check for it up front rather
- * than letting pipeline creation fail with an error that names neither pass nor feature.
- */
-export const PARTICLE_IMMEDIATE_BYTES = 20;
-
-/** Bytes of stats {@link ParticleScene#encode_stats_copy} writes: 8 counters, then both arg buffers. */
-export const PARTICLE_STATS_BYTES = 64;
-
-const STATS_OFFSET_DISPATCH_ARGS = 32;
-const STATS_OFFSET_DRAW_ARGS = 48;
-
-/**
- * @typedef {object} ParticleSceneStats
- * @property {number} alive particles alive at the end of the captured frame
- * @property {number} dead free slots left in the pool
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
- *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
- * @property {number} sim_padded length of the program-coherent list the coherence pass built this
- *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
- * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
- * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
- */
-
-/**
- * Build the scene against a live (or mock) device.
- *
- * @param {GraphicsContext} graphics
- * @param {object} options
- * @param {GPUTextureFormat} options.color_format format of the colour target frames are encoded into
- * @param {number} [options.capacity] particle pool size
- * @returns {object} the scene, see the returned object's own members
- */
-export function create_particle_scene(graphics, { color_format, capacity = PARTICLE_CAPACITY }) {
-    const device = graphics.device;
-
-    // --- emitters: four, each with different settings -----------------------------------------
-    const system = new GPUParticleSystem(graphics, { capacity });
-
-    // fire — additive, billboard, at the base of the tall pillar
-    system.addEmitter({
-        ...fire_effect().emitter,
-        spawn_rate: 500, flipbook: [1, 1], atlas_region: [0, 0, 1, 1],
-        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
-        transform: translation(-1, 0, 0),
-    });
-    // smoke — alpha, soft-depth, rising column above the fire
-    system.addEmitter({
-        effect: make_effect({ velocity: [0, 1.3, 0], velocityJitter: 0.35, posJitter: 0.5, accel: 0.25, life: [3, 5], size: 1.4, color: [0.45, 0.45, 0.48, 0.28] }),
-        spawn_rate: 60, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
-        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
-        render: { position: "position", size: "size", color: "color" },
-        transform: translation(-1, 2.5, 0),
-    });
-    // sparks — additive, velocity-stretched, fast, short-lived, gravity, near the box
-    system.addEmitter({
-        effect: make_effect({ velocity: [0, 5, 0], velocityJitter: 4.5, posJitter: 0.15, accel: -14, life: [0.3, 0.8], size: 0.09, color: [1.0, 0.8, 0.35, 1.0] }),
-        spawn_rate: 350, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
-        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.STRETCHED },
-        render: { position: "position", size: "size", color: "color", velocity: "velocity" },
-        transform: translation(2, 1.9, -1),
-    });
-    // dust — alpha, soft-depth, slow wide drift across the ground
-    system.addEmitter({
-        effect: make_effect({ velocity: [0.3, 0.15, 0.1], velocityJitter: 0.35, posJitter: 6, accel: 0, life: [4, 7], size: 0.7, color: [0.55, 0.5, 0.42, 0.16] }),
-        spawn_rate: 120, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
-        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
-        render: { position: "position", size: "size", color: "color" },
-        transform: translation(0, 0.3, 0),
-    });
-
-    const built = system.buildEmitterData();
-
-    // --- particle GPU buffers -----------------------------------------------------------------
-    const storage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
-    const pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * 4, usage: storage });
-    const alive_a = device.createBuffer({ label: "particles/alive_a", size: capacity * 4, usage: storage });
-    const alive_b = device.createBuffer({ label: "particles/alive_b", size: capacity * 4, usage: storage });
-    const dead = device.createBuffer({ label: "particles/dead", size: capacity * 4, usage: storage });
-    const counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * 4, usage: storage });
-    const spawn_requests = device.createBuffer({ label: "particles/spawn_requests", size: capacity * 4, usage: storage });
-    const emitters = data_buffer(device, "particles/emitters", built.emitters, storage);
-    const program = data_buffer(device, "particles/program", built.program, storage);
-    const constants = data_buffer(device, "particles/constants", built.constants, storage);
-
-    // Indirect args, written on-GPU by the build-indirect pass. Zero-initialised (WebGPU spec), so
-    // the first frame's indirect dispatch/draw are no-ops until the first snapshot lands. COPY_SRC
-    // only so the stats copy can *display* them; nothing read back here sizes a pass.
-    const args_usage = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
-    const dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: args_usage });
-    const draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: args_usage });
-
-    // --- simulation-order (coherence) buffers -------------------------------------------------
-    //
-    // A separate set from the render-order sort's, on purpose: one list is grouped by VM program and
-    // camera-independent, the other is back-to-front by view depth. Sharing a buffer between them
-    // would couple a camera-driven ordering to a program-driven one.
-    const sizes = system.bufferSizes();
-    const buckets = system.bucketCount();
-    const sim_list = device.createBuffer({ label: "particles/sim_list", size: sizes.sim_list, usage: storage });
-    const sim_keys = device.createBuffer({ label: "particles/sim_keys", size: sizes.sim_keys, usage: storage });
-    const sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: sizes.sim_histogram, usage: storage });
-    const sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: sizes.sim_bucket_counts, usage: storage });
-    const sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: sizes.sim_cursor, usage: storage });
-    const sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: sizes.sim_dispatch_args, usage: args_usage });
-
-    // Scratch the reused CSDLDF scan needs: the indirect command it is dispatched with, and its
-    // decoupled-lookback spine. One partition covers every plausible bucket count.
-    const scan_command = device.createBuffer({
-        label: "particles/sim_scan_command",
-        size: 3 * 4,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
-    });
-    // Cleared at the top of every frame, not just on creation: the spine carries per-partition
-    // flags, and a stale FLAG_INCLUSIVE left over from last frame is read as this frame's answer.
-    // The frame-graph wiring gets this for free from `BufferResourceDescriptor.empty`; encoding by
-    // hand has to ask. Rounded to a 256-byte allocation rather than the 8 bytes one partition needs.
-    const scan_spine = device.createBuffer({
-        label: "particles/sim_scan_spine",
-        size: Math.max(256, Math.ceil(buckets / PREFIX_SCAN_CSDLDF_PARTITION_SIZE) * 2 * 4),
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-    });
-
-    const initial = system.initialFreeList();
-    device.queue.writeBuffer(dead, 0, initial.dead);
-    device.queue.writeBuffer(counters, 0, initial.counters);
-
-    // --- camera + geometry --------------------------------------------------------------------
-    const camera_buffer = device.createBuffer({ label: "particles/camera", size: CAMERA_UNIFORM_STRUCT.aligned_size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-    const vp_buffer = device.createBuffer({ label: "particles/vp", size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-
-    const geometry = build_geometry();
-    const geometry_buffer = device.createBuffer({ label: "particles/geometry", size: geometry.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
-    device.queue.writeBuffer(geometry_buffer, 0, geometry);
-    const geometry_vertex_count = geometry.length / GEOMETRY_FLOATS_PER_VERTEX;
-    const { geometry_pipeline, geometry_bind_group } = make_geometry_pipeline(device, color_format, vp_buffer);
-
-    // atlas sprite — soft round falloff — and the filtering sampler the billboard shader declares
-    const atlas_view = make_sprite_texture(device).createView();
-    const atlas_sampler = device.createSampler({ magFilter: "linear", minFilter: "linear", addressModeU: "clamp-to-edge", addressModeV: "clamp-to-edge" });
-
-    // billboard pipeline: reverse-Z depth test (same compare as the geometry pass), no write;
-    // soft-depth reads the scene depth texture
-    const billboard_pipeline = create_particle_billboard_pipeline({
-        color_format,
-        depth_format: DEPTH_FORMAT,
-        depth_compare: "greater",
-    });
-
-    // reverse-Z depth buffer, recreated on resize
-    let depth_texture = null;
-    let depth_view = null;
-    let depth_width = 0;
-    let depth_height = 0;
-
-    function ensure_depth(width, height) {
-        if (depth_view !== null && depth_width === width && depth_height === height) {
-            return;
-        }
-
-        depth_texture?.destroy();
-        depth_texture = device.createTexture({
-            label: "particles/scene_depth",
-            size: [width, height],
-            format: DEPTH_FORMAT,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-        });
-        depth_view = depth_texture.createView();
-        depth_width = width;
-        depth_height = height;
-    }
-
-    let alive_read = alive_a;
-    let alive_write = alive_b;
-
-    return {
-        system,
-        capacity,
-
-        /** Buffers a harness may inspect. Not for the frame loop, which never reads them back. */
-        buffers: {
-            pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants,
-            dispatch_args, draw_args,
-            sim_list, sim_keys, sim_histogram, sim_bucket_counts, sim_cursor, sim_dispatch_args,
-            sim_scan_command: scan_command, sim_scan_spine: scan_spine,
-        },
-
-        /**
-         * Encode one whole frame: geometry, then emit + simulate + build-indirect, then the
-         * billboard draw. Does not submit — the caller finishes the context.
-         *
-         * @param {ShadeGPUCommandContext} cmd
-         * @param {object} frame
-         * @param {GPUTextureView} frame.color_view where the frame is drawn
-         * @param {number} frame.width colour target width, in texels
-         * @param {number} frame.height colour target height, in texels
-         * @param {number} frame.dt seconds since the previous frame
-         * @param {number} frame.time seconds since start, for the camera orbit and the VM's clock
-         */
-        encode_frame(cmd, { color_view, width, height, dt, time }) {
-            ensure_depth(width, height);
-            write_camera(device, camera_buffer, vp_buffer, width / height, time);
-
-            const requests = system.update(dt);
-            if (requests.length > 0) {
-                device.queue.writeBuffer(spawn_requests, 0, requests);
-            }
-
-            // --- geometry pass: clear colour + reverse-Z depth (far = 0), lit, writes depth ---
-            const geometry_pass = cmd.beginRenderPass({
-                label: "particles/geometry",
-                colorAttachments: [{ view: color_view, loadOp: "clear", storeOp: "store", clearValue: { r: 0.03, g: 0.035, b: 0.05, a: 1 } }],
-                depthStencilAttachment: { view: depth_view, depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0.0 },
-            });
-            geometry_pass.setPipeline(geometry_pipeline);
-            geometry_pass.setBindGroup(0, geometry_bind_group);
-            geometry_pass.setVertexBuffer(0, geometry_buffer);
-            geometry_pass.draw(geometry_vertex_count);
-            geometry_pass.end();
-
-            // --- emit + simulate (simulate is sized by LAST frame's GPU-written dispatch args) ---
-            shader_particle_reset_counters.dispatch({ encoder: cmd, bindings: { counters }, group_count_x: 1 });
-
-            if (requests.length > 0) {
-                shader_particle_emit.dispatchThreads({
-                    encoder: cmd,
-                    bindings: {
-                        emitters, program, vm_constants: constants, pool, spawn_requests,
-                        alive_out: alive_write, dead, counters,
-                        settings: { u_dt: dt, u_time: time, u_frame: system.frame, u_count: requests.length, u_capacity: capacity },
-                    },
-                    thread_count_x: requests.length,
-                });
-            }
-
-            shader_particle_simulate.dispatchIndirect({
-                encoder: cmd,
-                bindings: {
-                    emitters, program, vm_constants: constants, pool,
-                    sim_list, alive_out: alive_write, dead, counters,
-                    settings: { u_dt: dt, u_time: time, u_frame: system.frame },
-                },
-                command: dispatch_args,
-            });
-
-            // --- coherence: regroup the finished alive list by VM program for NEXT frame's simulate ---
-            //
-            // Reads the list emit and simulate have both finished appending to, and rewrites
-            // `sim_list` — the buffer simulate read a few lines above. Consecutive dispatches are
-            // ordered, so the read is complete before the write lands.
-            shader_particle_bucket_reset.dispatchThreads({
-                encoder: cmd,
-                bindings: { counters, histogram: sim_histogram, cursor: sim_cursor, sim_dispatch_args, u_bucket_count: buckets },
-                thread_count_x: bucket_reset_thread_count(buckets),
-            });
-
-            shader_particle_bucket_histogram.dispatchIndirect({
-                encoder: cmd,
-                bindings: { emitters, pool, alive: alive_write, keys: sim_keys, histogram: sim_histogram, counters },
-                command: sim_dispatch_args,
-            });
-
-            shader_particle_bucket_pad.dispatchThreads({
-                encoder: cmd,
-                bindings: { histogram: sim_histogram, bucket_counts: sim_bucket_counts, u_bucket_count: buckets },
-                thread_count_x: buckets,
-            });
-
-            // The same scan the radix sort runs its spine through, reused unmodified.
-            cmd.clearBuffer(scan_spine, 0, scan_spine.size);
-            build_indirect_compute_dispatch_command(
-                PREFIX_SCAN_CSDLDF_PARTITION_SIZE, cmd, sim_histogram, 0, scan_command, 0,
-            );
-            shader_prefix_scan_csdldf.dispatchIndirect({
-                encoder: cmd,
-                command: scan_command,
-                bindings: { scan_in: sim_histogram, spine: scan_spine },
-            });
-
-            shader_particle_bucket_scatter.dispatchIndirect({
-                encoder: cmd,
-                bindings: { keys: sim_keys, alive: alive_write, scanned: sim_histogram, cursor: sim_cursor, sim_list, counters },
-                command: sim_dispatch_args,
-            });
-
-            shader_particle_bucket_fill.dispatchThreads({
-                encoder: cmd,
-                bindings: { bucket_counts: sim_bucket_counts, scanned: sim_histogram, sim_list, counters, u_bucket_count: buckets },
-                thread_count_x: buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE,
-            });
-
-            // Snapshot the padded list length (next frame's simulate input) + write this frame's draw args.
-            shader_particle_build_indirect.dispatch({
-                encoder: cmd,
-                bindings: { counters, dispatch_args, draw_args, u_workgroup_size: PARTICLE_SIMULATE_WORKGROUP_SIZE },
-                group_count_x: 1,
-            });
-
-            // --- billboard pass: load colour, depth-test against the scene (read-only), indirect draw ---
-            const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
-                camera: camera_buffer, pool, sorted: alive_write, emitters,
-                atlas: atlas_view, atlas_sampler, scene_depth: depth_view,
-            }, cmd);
-
-            const billboard_pass = cmd.constructRenderPass({
-                pipeline: billboard_pipeline,
-                bindings,
-                colorAttachments: [{ view: color_view, loadOp: "load", storeOp: "store" }],
-                depthStencilAttachment: { view: depth_view, depthReadOnly: true },
-            });
-            billboard_pass.drawIndirect(draw_args, 0);
-            billboard_pass.end();
-
-            const previous = alive_read;
-            alive_read = alive_write;
-            alive_write = previous;
-        },
-
-        /**
-         * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
-         * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
-         *
-         * @param {ShadeGPUCommandContext} cmd
-         * @param {GPUBuffer} destination
-         */
-        encode_stats_copy(cmd, destination) {
-            cmd.copyBufferToBuffer(counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
-            cmd.copyBufferToBuffer(dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
-            cmd.copyBufferToBuffer(draw_args, 0, destination, STATS_OFFSET_DRAW_ARGS, 4 * 4);
-        },
-
-        /**
-         * Interpret the bytes {@link encode_stats_copy} wrote.
-         *
-         * @param {ArrayBuffer} bytes
-         * @returns {ParticleSceneStats}
-         */
-        read_stats(bytes) {
-            const words = new Uint32Array(bytes);
-            const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
-            const draw_base = STATS_OFFSET_DRAW_ARGS / 4;
-
-            return {
-                alive: words[0],
-                dead: words[1],
-                alive_in: words[4],
-                sim_padded: words[5],
-                dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
-                draw: [words[draw_base], words[draw_base + 1]],
-            };
-        },
-    };
-}
-
-// ---------------------------------------------------------------------------------------------
-// Effect authoring
-// ---------------------------------------------------------------------------------------------
-
-/**
- * A parametric point-emission effect: emit with a base velocity + jitter from a disk, integrate
- * under a vertical acceleration, and die at end of life. Only nAge.x is consumed (kill), so the
- * NaN lanes from the scalar age/lifetime divide are harmless.
- */
-function make_effect({ velocity, velocityJitter = 0, posJitter = 0, accel = 0, life = [1, 2], size = 1, color = [1, 1, 1, 1] }) {
-    const layout = new ParticleLayout([
-        { name: "position", components: 3 }, { name: "velocity", components: 3 },
-        { name: "age", components: 1 }, { name: "lifetime", components: 1 },
-        { name: "size", components: 1 }, { name: "color", components: 4 },
-    ]);
-
-    const spawn = new NodeGraph();
-    let posN = particle_node(spawn, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
-    if (posJitter > 0) {
-        const d = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIT_DISK });
-        const j = particle_node(spawn, "scale"); particle_wire(spawn, j, "v", d); particle_wire(spawn, j, "s", [posJitter]);
-        const p = particle_node(spawn, "add"); particle_wire(spawn, p, "a", posN); particle_wire(spawn, p, "b", j); posN = p;
-    }
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "position" }), "value", posN);
-
-    let velN = particle_node(spawn, "const", { value: [velocity[0], velocity[1], velocity[2], 0] });
-    if (velocityJitter > 0) {
-        const r = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
-        const rs = particle_node(spawn, "scale"); particle_wire(spawn, rs, "v", r); particle_wire(spawn, rs, "s", [velocityJitter]);
-        const vv = particle_node(spawn, "add"); particle_wire(spawn, vv, "a", velN); particle_wire(spawn, vv, "b", rs); velN = vv;
-    }
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "velocity" }), "value", velN);
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "age" }), "value", [0]);
-    const lr = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM });
-    const lm = particle_node(spawn, "mad"); particle_wire(spawn, lm, "a", lr); particle_wire(spawn, lm, "b", [life[1] - life[0]]); particle_wire(spawn, lm, "c", [life[0]]);
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "lifetime" }), "value", lm);
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "size" }), "value", [size]);
-    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "color" }), "value", color);
-
-    const update = new NodeGraph();
-    const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
-    const age = particle_node(update, "attribute", { name: "age" });
-    const nage = particle_node(update, "add"); particle_wire(update, nage, "a", age); particle_wire(update, nage, "b", dt);
-    particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", nage);
-    const lifeA = particle_node(update, "attribute", { name: "lifetime" });
-    const na = particle_node(update, "div"); particle_wire(update, na, "a", nage); particle_wire(update, na, "b", lifeA);
-    const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", na); particle_wire(update, dead, "b", [1]);
-    particle_wire(update, particle_node(update, "kill"), "condition", dead);
-    let velN2 = particle_node(update, "attribute", { name: "velocity" });
-    if (accel !== 0) {
-        const g = particle_node(update, "const", { value: [0, accel, 0, 0] });
-        const gd = particle_node(update, "scale"); particle_wire(update, gd, "v", g); particle_wire(update, gd, "s", dt);
-        const nv = particle_node(update, "add"); particle_wire(update, nv, "a", velN2); particle_wire(update, nv, "b", gd);
-        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nv); velN2 = nv;
-    }
-    const pos = particle_node(update, "attribute", { name: "position" });
-    const pd = particle_node(update, "scale"); particle_wire(update, pd, "v", velN2); particle_wire(update, pd, "s", dt);
-    const np = particle_node(update, "add"); particle_wire(update, np, "a", pos); particle_wire(update, np, "b", pd);
-    particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", np);
-
-    return create_particle_effect({ layout, spawn, update });
-}
-
-// ---------------------------------------------------------------------------------------------
-// Geometry + camera + helpers
-// ---------------------------------------------------------------------------------------------
-
-const DEPTH_FORMAT = "depth32float";
-
-/** Interleaved `[x, y, z, nx, ny, nz]`. */
-const GEOMETRY_FLOATS_PER_VERTEX = 6;
-
-const GEOM_WGSL = /* wgsl */ `
-@group(0) @binding(0) var<uniform> vp : mat4x4<f32>;
-struct VOut { @builtin(position) clip : vec4<f32>, @location(0) normal : vec3<f32> }
-@vertex fn vs(@location(0) pos : vec3<f32>, @location(1) normal : vec3<f32>) -> VOut {
-    var o : VOut;
-    o.clip = vp * vec4<f32>(pos, 1.0);
-    o.normal = normal;
-    return o;
-}
-@fragment fn fs(in : VOut) -> @location(0) vec4<f32> {
-    let N = normalize(in.normal);
-    let L = normalize(vec3<f32>(0.35, 1.0, 0.4));
-    let diffuse = max(dot(N, L), 0.0);
-    let albedo = select(vec3<f32>(0.30, 0.32, 0.36), vec3<f32>(0.22, 0.24, 0.28), N.y < 0.9);
-    let color = albedo * (0.18 + diffuse * 0.9);
-    return vec4<f32>(color, 1.0);
-}
-`;
-
-function make_geometry_pipeline(device, format, vp_buffer) {
-    const module = device.createShaderModule({ label: "particles/geometry", code: GEOM_WGSL });
-    const layout = device.createBindGroupLayout({
-        entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }],
-    });
-
-    const geometry_pipeline = device.createRenderPipeline({
-        label: "particles/geometry",
-        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
-        vertex: {
-            module,
-            entryPoint: "vs",
-            buffers: [{
-                arrayStride: GEOMETRY_FLOATS_PER_VERTEX * 4,
-                attributes: [
-                    { shaderLocation: 0, offset: 0, format: "float32x3" },
-                    { shaderLocation: 1, offset: 12, format: "float32x3" },
-                ],
-            }],
-        },
-        fragment: { module, entryPoint: "fs", targets: [{ format }] },
-        primitive: { topology: "triangle-list", cullMode: "none" },
-        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: "greater" }, // reverse-Z
-    });
-
-    const geometry_bind_group = device.createBindGroup({ layout, entries: [{ binding: 0, resource: { buffer: vp_buffer } }] });
-
-    return { geometry_pipeline, geometry_bind_group };
-}
-
-/** Ground plane + a few boxes as an interleaved `[x,y,z, nx,ny,nz]` vertex array. */
-function build_geometry() {
-    const v = [];
-    const quad = (a, b, c, d, n) => { for (const p of [a, b, c, a, c, d]) v.push(p[0], p[1], p[2], n[0], n[1], n[2]); };
-    const box = (cx, cy, cz, sx, sy, sz) => {
-        const x0 = cx - sx / 2, x1 = cx + sx / 2, y0 = cy - sy / 2, y1 = cy + sy / 2, z0 = cz - sz / 2, z1 = cz + sz / 2;
-        quad([x0, y0, z1], [x1, y0, z1], [x1, y1, z1], [x0, y1, z1], [0, 0, 1]);
-        quad([x1, y0, z0], [x0, y0, z0], [x0, y1, z0], [x1, y1, z0], [0, 0, -1]);
-        quad([x1, y0, z1], [x1, y0, z0], [x1, y1, z0], [x1, y1, z1], [1, 0, 0]);
-        quad([x0, y0, z0], [x0, y0, z1], [x0, y1, z1], [x0, y1, z0], [-1, 0, 0]);
-        quad([x0, y1, z1], [x1, y1, z1], [x1, y1, z0], [x0, y1, z0], [0, 1, 0]);
-        quad([x0, y0, z0], [x1, y0, z0], [x1, y0, z1], [x0, y0, z1], [0, -1, 0]);
-    };
-    quad([-15, 0, -15], [15, 0, -15], [15, 0, 15], [-15, 0, 15], [0, 1, 0]); // ground
-    box(-1, 1.5, 0, 1, 3, 1);        // tall pillar next to the fire
-    box(2, 0.9, -1, 1.6, 1.8, 1.6);  // block near the sparks
-    box(0, 0.6, 3.5, 7, 1.2, 0.6);   // low wall the dust drifts against
-    return new Float32Array(v);
-}
-
-// Scratch for write_camera. One scene drives one camera, and the loop runs every frame, so these
-// are reused rather than reallocated 60 times a second.
-const camera_view = m4_allocate();
-const camera_world = m4_allocate();
-const camera_projection = m4_allocate();
-const camera_view_projection = m4_allocate();
-const camera_bytes = new Float32Array(CAMERA_UNIFORM_STRUCT.aligned_size / 4);
-
-/**
- * Reverse-Z, infinite-far perspective (WebGPU 0..1 depth: near -> 1, far -> 0).
- *
- * @param {Float32Array} out column-major 4x4
- * @param {number} fov_y vertical field of view, radians
- * @param {number} aspect width / height
- * @param {number} near near plane distance
- * @returns {Float32Array} `out`
- */
-function perspective_reverse_z(out, fov_y, aspect, near) {
-    const f = 1 / Math.tan(fov_y / 2);
-
-    out.fill(0);
-    out[0] = f / aspect;
-    out[5] = f;
-    out[11] = -1;
-    out[14] = near;
-
-    return out;
-}
-
-/**
- * Orbit the camera and upload both camera buffers: the engine's full camera struct for the
- * billboard shader, and a bare view-projection for the geometry pass.
- */
-function write_camera(device, camera_buffer, vp_buffer, aspect, t) {
-    const radius = 12, height = 5.5;
-    const eye = [Math.cos(t * 0.22) * radius, height, Math.sin(t * 0.22) * radius];
-    const center = [0, 1.6, 0];
-
-    const view = m4_look_at(camera_view, eye, center, [0, 1, 0]);
-    // A look-at basis is orthonormal plus a translation, so this never reports singular.
-    m4_invert(camera_world, view);
-    const world = camera_world;
-    const projection = perspective_reverse_z(camera_projection, (58 * Math.PI) / 180, aspect, PARTICLE_NEAR);
-    const view_projection = m4_multiply(camera_view_projection, projection, view);
-
-    const put = (field, m) => camera_bytes.set(m, CAMERA_UNIFORM_STRUCT.get(field).offset / 4);
-    put("transform", world);
-    put("view_matrix", view);
-    put("projection_matrix", projection);
-    put("view_projection_matrix", view_projection);
-    // Reverse-Z infinite-far linearisation: view_depth = A / (device_depth + B), with A=near, B=0.
-    camera_bytes.set([0, PARTICLE_NEAR, 0, 0], CAMERA_UNIFORM_STRUCT.get("device_depth_to_view_space").offset / 4);
-
-    device.queue.writeBuffer(camera_buffer, 0, camera_bytes);
-    device.queue.writeBuffer(vp_buffer, 0, view_projection);
-}
-
-function translation(x, y, z) {
-    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
-}
-
-/**
- * Threads the bucket reset pass needs: enough to cover the scan's header plus its bins, rounded up
- * to the whole `vec4` the last bin lands in (the scan reads whole `vec4`s, so the tail has to be
- * cleared too or garbage joins the sums).
- *
- * @param {number} bucket_count
- * @returns {number}
- */
-function bucket_reset_thread_count(bucket_count) {
-    return PREFIX_SCAN_CSDLDF_HEADER_WORDS + ((bucket_count + 3) & ~3);
-}
-
-function data_buffer(device, label, data, usage) {
-    const buffer = device.createBuffer({ label, size: Math.max(data.byteLength, 4), usage });
-    device.queue.writeBuffer(buffer, 0, data);
-    return buffer;
-}
-
-/** A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive/alpha blobs. */
-function make_sprite_texture(device) {
-    const N = 64;
-    const px = new Uint8Array(N * N * 4);
-    for (let y = 0; y < N; y++) {
-        for (let x = 0; x < N; x++) {
-            const dx = (x + 0.5) / N * 2 - 1, dy = (y + 0.5) / N * 2 - 1;
-            const a = Math.max(0, 1 - Math.hypot(dx, dy));
-            const i = (y * N + x) * 4;
-            px[i] = 255; px[i + 1] = 255; px[i + 2] = 255; px[i + 3] = Math.round(a * a * 255);
-        }
-    }
-    const tex = device.createTexture({ label: "particles/sprite", size: [N, N], format: "rgba8unorm", usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST });
-    device.queue.writeTexture({ texture: tex }, px, { bytesPerRow: N * 4, rowsPerImage: N }, [N, N]);
-    return tex;
-}
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { make_box_geometry } from "../../renderer/geometry/primitives/make_box_geometry.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
+import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
+import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
+import {
+    particle_unit_disk,
+    particle_uniform_signed,
+} from "../../renderer/particles/graph/particle_graph_distributions.js";
+import { VM_BUILTIN } from "../../renderer/particles/isa/ParticleVMISA.js";
+import { ParticleLayout } from "../../renderer/particles/layout/ParticleLayout.js";
+import { create_particle_effect } from "../../renderer/particles/runtime/create_particle_effect.js";
+import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+import { Node3D } from "../../renderer/scene/Node3D.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
+import { fire_effect } from "./particle_prototype.js";
+
+/**
+ * The scene the particle playground shows, and the two lines of renderer configuration that make
+ * the particles part of it.
+ *
+ * The page draws through the whole {@link ../../renderer/Renderer.js} — the same one a game uses —
+ * so the particles arrive where they belong: inside the AVBOIT transparency pipeline, as a side
+ * channel of the transparent meshes, sorted against nothing and composited against everything. The
+ * page owns no pass, no pipeline, no camera buffer and no depth texture; it owns a {@link Scene}
+ * and a camera, and the renderer does the rest.
+ *
+ * Split from `main.js` so the part with no device in it can be spec'd: what emitters the scene has,
+ * what each is set to, and that {@link configure_particles} turns the feature on and hands the
+ * system its atlas. What a frame *encodes* is not this file's business any more — the renderer's
+ * own `graph_particles.spec.js` and `graph_particles_avboit.spec.js` hold that, against the
+ * software device, pass by pass.
+ *
+ * What is on screen:
+ *
+ * - opaque geometry (a floor, a pillar, a block) and one transparent pane, so the particles have
+ *   both something to be occluded by and something to composite with,
+ * - five emitters sharing one pool, each set up to exercise a different path: additive billboards,
+ *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding a
+ *   node that orbits, so a moving emitter is on screen,
+ * - a sunlight and (from the page) the default environment, because the meshes are lit.
+ */
+
+/** Bytes {@link encode_stats_copy} writes: 8 counters, then both indirect arg buffers. */
+export const PARTICLE_STATS_BYTES = 64;
+
+const STATS_OFFSET_DISPATCH_ARGS = 32;
+const STATS_OFFSET_DRAW_ARGS = 48;
+
+/**
+ * @typedef {object} ParticleSceneStats
+ * @property {number} alive particles alive at the end of the captured frame
+ * @property {number} dead free slots left in the pool
+ * @property {number} spawn_budget free slots the frame's emitters left unclaimed
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
+ *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
+ * @property {number} sim_padded length of the program-coherent list the coherence pass built this
+ *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
+ * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
+ * @property {number[]} draw the draw's indirect args, `[vertices, instances]`
+ */
+
+/**
+ * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
+ * example next door. Exported because the bounds spheres below are authored against these numbers
+ * and a spec can check that they still hold: an emitter that travels further than its sphere
+ * occludes at the wrong depth now that the sphere is the occupancy hint.
+ *
+ * @type {Object<string, {velocity: number[], velocityJitter: number, posJitter: number, accel: number, life: number[], size: number, color: number[]}>}
+ */
+export const PARTICLE_EMITTER_MOTION = {
+    smoke: { velocity: [0, 1.3, 0], velocityJitter: 0.35, posJitter: 0.5, accel: 0.25, life: [3, 5], size: 1.4, color: [0.45, 0.45, 0.48, 0.28] },
+    sparks: { velocity: [0, 5, 0], velocityJitter: 4.5, posJitter: 0.15, accel: -14, life: [0.3, 0.8], size: 0.09, color: [1.0, 0.8, 0.35, 1.0] },
+    dust: { velocity: [0.3, 0.15, 0.1], velocityJitter: 0.35, posJitter: 6, accel: 0, life: [4, 7], size: 0.7, color: [0.55, 0.5, 0.42, 0.16] },
+    torch: { velocity: [0, 1.8, 0], velocityJitter: 0.4, posJitter: 0.08, accel: 0.5, life: [0.4, 0.9], size: 0.35, color: [1.0, 0.55, 0.2, 1.0] },
+};
+
+/**
+ * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
+ * uploaded — {@link build_particle_scene} is what places them.
+ *
+ * Every one carries a bounds sphere that holds the effect it emits. Under AVBOIT that sphere is
+ * not just the culling test it used to be: it is what marks the depth slices the emitter may
+ * occlude in, so an emitter whose particles outrun it occludes at slightly the wrong depth. The
+ * spheres are sized to hold where the effect actually goes rather than to the last reachable
+ * corner of its jitter: a sphere big enough for the worst case would mark most of the depth range
+ * and cost the adaptive slicing the very thing it is for.
+ *
+ * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
+ */
+export function create_particle_emitters() {
+    // fire — additive, billboard, flipbook, at the foot of the pillar. The effect is the worked
+    // example from particle_prototype.js next door, unchanged.
+    const fire = ParticleEmitter.from({
+        ...fire_effect().emitter,
+        name: "fire",
+        spawn_rate: 500,
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
+        position: [-1, 0, 0],
+    });
+
+    // smoke — alpha, soft-depth, a rising column above the fire
+    const smoke = ParticleEmitter.from({
+        name: "smoke",
+        effect: make_effect(PARTICLE_EMITTER_MOTION.smoke),
+        spawn_rate: 60,
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
+        render: { position: "position", size: "size", color: "color" },
+        // rising at 1.3 m/s for 3 to 5 s, with the buoyancy adding a couple of metres on top
+        bounds: { center: [0, 4, 0], radius: 7 },
+        position: [-1, 2.5, 0],
+    });
+
+    // sparks — additive, velocity-stretched, fast, short-lived, under gravity, by the block
+    const sparks = ParticleEmitter.from({
+        name: "sparks",
+        effect: make_effect(PARTICLE_EMITTER_MOTION.sparks),
+        spawn_rate: 350,
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.STRETCHED },
+        render: { position: "position", size: "size", color: "color", velocity: "velocity" },
+        // thrown a few metres up and out, and pulled back down inside a second
+        bounds: { center: [0, 0.5, 0], radius: 5 },
+        position: [2, 1.9, -1],
+    });
+
+    // dust — alpha, soft-depth, a slow wide drift across the ground
+    const dust = ParticleEmitter.from({
+        name: "dust",
+        effect: make_effect(PARTICLE_EMITTER_MOTION.dust),
+        spawn_rate: 120,
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
+        render: { position: "position", size: "size", color: "color" },
+        // emitted across a 6 m disk, then drifting slowly for up to 7 s
+        bounds: { center: [1.5, 1, 0.5], radius: 10 },
+        position: [0, 0.3, 0],
+    });
+
+    // a torch riding an orbiting node: the emitter has no idea it moves — its parent does, and the
+    // GPU hierarchy pass composes the two, with nothing copied through the CPU
+    const orbit = new Node3D();
+    orbit.name = "orbit";
+
+    const torch = ParticleEmitter.from({
+        name: "torch",
+        effect: make_effect(PARTICLE_EMITTER_MOTION.torch),
+        spawn_rate: 200,
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
+        render: { position: "position", size: "size", color: "color" },
+        bounds: { center: [0, 1, 0], radius: 2.5 },
+        position: [4, 1.2, 0],
+    });
+
+    orbit.addChild(torch);
+
+    return { fire, smoke, sparks, dust, torch, orbit };
+}
+
+/**
+ * Build the scene: geometry, a light, and the emitters as nodes of it.
+ *
+ * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
+ * import; building geometry before it is ready reads an instance that is not there yet.
+ *
+ * @returns {Promise<{scene: Scene, emitters: ReturnType<create_particle_emitters>, meshes: {floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}}>}
+ */
+export async function build_particle_scene() {
+    await MeshoptClusterizer.ready;
+
+    const scene = new Scene();
+
+    scene.lights.add(make_sunlight({
+        intensity: 1.4,
+        direction: new Vector3(0.35, -1, -0.4),
+        temperature: 5200,
+    }));
+
+    const flat = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+
+    const floor = place(
+        plane(40, 40),
+        material(new Color(0.32, 0.31, 0.29, 1), { transparent: false }),
+        new Vector3(0, 0, 0),
+        flat
+    );
+
+    // the pillar the fire burns at the foot of, and the block the sparks fly off
+    const pillar = place(
+        box(0.9, 4, 0.9),
+        material(new Color(0.42, 0.4, 0.38, 1), { transparent: false }),
+        new Vector3(-1, 2, 0)
+    );
+    const block = place(
+        box(1.4, 1.2, 1.4),
+        material(new Color(0.3, 0.31, 0.34, 1), { transparent: false }),
+        new Vector3(2, 0.6, -1)
+    );
+
+    // A transparent pane across the middle of the set. The particles and this pane are drawn by
+    // the same pipeline into the same volume, so whichever is in front occludes the other — the
+    // thing a side channel exists to get right, and the thing a separate blended pass cannot.
+    const pane = place(
+        plane(9, 5),
+        material(new Color(0.35, 0.6, 0.8, 0.35)),
+        new Vector3(0.5, 2.5, 2.5)
+    );
+
+    scene.add(floor);
+    scene.add(pillar);
+    scene.add(block);
+    scene.add(pane);
+
+    const emitters = create_particle_emitters();
+
+    for (const node of [emitters.fire, emitters.smoke, emitters.sparks, emitters.dust, emitters.orbit]) {
+        scene.add(node);
+    }
+
+    return { scene, emitters, meshes: { floor, pillar, block, pane } };
+}
+
+/**
+ * Turn the particles on for this scene and give the system its sprite.
+ *
+ * This is the whole integration. The emitters are already scene nodes, so there is nothing to
+ * register: the system finds them the next time it sweeps, gives each a row pointed at the node's
+ * `transforms` row, and the renderer records the simulation and the three AVBOIT contributions.
+ *
+ * @param {import("../../renderer/Renderer.js").Renderer} renderer initialized
+ * @param {Scene} scene the one {@link build_particle_scene} returned
+ * @returns {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem}
+ */
+export function configure_particles(renderer, scene) {
+    renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
+    renderer.feature_particles_enabled = true;
+
+    const device = renderer.graphics.device;
+    const system = renderer.particles(renderer.scenes.obtain(scene));
+
+    system.atlas = make_sprite_texture(device).createView();
+    system.atlas_sampler = device.createSampler({
+        label: "particles/sprite sampler",
+        magFilter: "linear",
+        minFilter: "linear",
+        addressModeU: "clamp-to-edge",
+        addressModeV: "clamp-to-edge",
+    });
+
+    return system;
+}
+
+/**
+ * Move what moves. One call, so the page's frame loop stays three lines and the motion is here
+ * with the scene it belongs to.
+ *
+ * @param {ReturnType<create_particle_emitters>} emitters
+ * @param {number} time seconds since start
+ */
+export function animate_particle_scene(emitters, time) {
+    const orbit = emitters.orbit;
+
+    orbit.transform_local.setTranslation(
+        Math.cos(time * 0.9) * 0.5,
+        Math.sin(time * 1.7) * 0.4,
+        Math.sin(time * 0.9) * 0.5
+    );
+    orbit.updateMatrices();
+}
+
+/**
+ * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
+ * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
+ *
+ * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system
+ * @param {GPUCommandEncoder} encoder
+ * @param {GPUBuffer} destination
+ */
+export function encode_stats_copy(system, encoder, destination) {
+    const buffers = system.buffers;
+
+    encoder.copyBufferToBuffer(buffers.counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
+    encoder.copyBufferToBuffer(buffers.dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
+    encoder.copyBufferToBuffer(buffers.draw_args, 0, destination, STATS_OFFSET_DRAW_ARGS, 4 * 4);
+}
+
+/**
+ * Interpret the bytes {@link encode_stats_copy} wrote.
+ *
+ * @param {ArrayBuffer} bytes
+ * @returns {ParticleSceneStats}
+ */
+export function read_stats(bytes) {
+    const words = new Uint32Array(bytes);
+    const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
+    const draw_base = STATS_OFFSET_DRAW_ARGS / 4;
+
+    return {
+        alive: words[0],
+        dead: words[1],
+        spawn_budget: words[2],
+        alive_in: words[4],
+        sim_padded: words[5],
+        dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
+        draw: [words[draw_base], words[draw_base + 1]],
+    };
+}
+
+/**
+ * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
+ *
+ * @param {GPUDevice} device
+ * @returns {GPUTexture}
+ */
+export function make_sprite_texture(device) {
+    const N = 64;
+    const px = new Uint8Array(N * N * 4);
+
+    for (let y = 0; y < N; y++) {
+        for (let x = 0; x < N; x++) {
+            const dx = (x + 0.5) / N * 2 - 1;
+            const dy = (y + 0.5) / N * 2 - 1;
+            const a = Math.max(0, 1 - Math.hypot(dx, dy));
+            const i = (y * N + x) * 4;
+
+            px[i] = 255;
+            px[i + 1] = 255;
+            px[i + 2] = 255;
+            px[i + 3] = Math.round(a * a * 255);
+        }
+    }
+
+    const texture = device.createTexture({
+        label: "particles/sprite",
+        size: [N, N],
+        format: "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+
+    device.queue.writeTexture({ texture }, px, { bytesPerRow: N * 4, rowsPerImage: N }, [N, N]);
+
+    return texture;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Geometry helpers
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @returns {MeshletGeometry}
+ */
+function plane(width, height) {
+    return meshlets(make_plane_geometry(width, height, 1, 1));
+}
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {number} depth
+ * @returns {MeshletGeometry}
+ */
+function box(width, height, depth) {
+    return meshlets(make_box_geometry(width, height, depth));
+}
+
+/**
+ * @param {object} geometry
+ * @returns {MeshletGeometry}
+ */
+function meshlets(geometry) {
+    const built = new MeshletGeometry();
+
+    meshlet_geometry_build_from_geometry(geometry, built);
+
+    return built;
+}
+
+/**
+ * @param {Color} diffuse rgb and alpha
+ * @param {object} [options]
+ * @param {boolean} [options.transparent]
+ * @returns {StandardShadeMaterial}
+ */
+function material(diffuse, { transparent = true } = {}) {
+    const result = new StandardShadeMaterial();
+
+    result.diffuse_color.copy(diffuse);
+    result.roughness_factor = 0.55;
+    result.metallic_factor = 0;
+    result.transparency_mode = transparent ? TransparencyMode.Transparent : TransparencyMode.Opaque;
+    result.draw_side = ShadeDrawSide.Double;
+
+    return result;
+}
+
+/**
+ * @param {MeshletGeometry} geometry
+ * @param {StandardShadeMaterial} material_instance
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ * @returns {Mesh}
+ */
+function place(geometry, material_instance, position, rotation = new Quaternion()) {
+    const mesh = Mesh.from(geometry, material_instance);
+
+    mesh.transform_local.setTranslation(position.x, position.y, position.z);
+    mesh.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    mesh.updateMatrices();
+
+    return mesh;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Effect authoring
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * A parametric point-emission effect: emit with a base velocity + jitter from a disk, integrate
+ * under a vertical acceleration, and die at end of life. Only nAge.x is consumed (kill), so the
+ * NaN lanes from the scalar age/lifetime divide are harmless.
+ */
+function make_effect({ velocity, velocityJitter = 0, posJitter = 0, accel = 0, life = [1, 2], size = 1, color = [1, 1, 1, 1] }) {
+    const layout = new ParticleLayout([
+        { name: "position", components: 3 }, { name: "velocity", components: 3 },
+        { name: "age", components: 1 }, { name: "lifetime", components: 1 },
+        { name: "size", components: 1 }, { name: "color", components: 4 },
+    ]);
+
+    const init = new NodeGraph();
+    let posN = particle_node(init, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
+    if (posJitter > 0) {
+        const d = particle_unit_disk(init);
+        const j = particle_node(init, "scale"); particle_wire(init, j, "v", d); particle_wire(init, j, "s", [posJitter]);
+        const p = particle_node(init, "add"); particle_wire(init, p, "a", posN); particle_wire(init, p, "b", j); posN = p;
+    }
+    particle_wire(init, particle_node(init, "setAttribute", { name: "position" }), "value", posN);
+
+    let velN = particle_node(init, "const", { value: [velocity[0], velocity[1], velocity[2], 0] });
+    if (velocityJitter > 0) {
+        const r = particle_uniform_signed(init);
+        const rs = particle_node(init, "scale"); particle_wire(init, rs, "v", r); particle_wire(init, rs, "s", [velocityJitter]);
+        const vv = particle_node(init, "add"); particle_wire(init, vv, "a", velN); particle_wire(init, vv, "b", rs); velN = vv;
+    }
+    particle_wire(init, particle_node(init, "setAttribute", { name: "velocity" }), "value", velN);
+    particle_wire(init, particle_node(init, "setAttribute", { name: "age" }), "value", [0]);
+    const lr = particle_node(init, "random");
+    const lm = particle_node(init, "mad"); particle_wire(init, lm, "a", lr); particle_wire(init, lm, "b", [life[1] - life[0]]); particle_wire(init, lm, "c", [life[0]]);
+    particle_wire(init, particle_node(init, "setAttribute", { name: "lifetime" }), "value", lm);
+    particle_wire(init, particle_node(init, "setAttribute", { name: "size" }), "value", [size]);
+    particle_wire(init, particle_node(init, "setAttribute", { name: "color" }), "value", color);
+
+    const update = new NodeGraph();
+    const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
+    const age = particle_node(update, "attribute", { name: "age" });
+    const nage = particle_node(update, "add"); particle_wire(update, nage, "a", age); particle_wire(update, nage, "b", dt);
+    particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", nage);
+    const lifeA = particle_node(update, "attribute", { name: "lifetime" });
+    const na = particle_node(update, "div"); particle_wire(update, na, "a", nage); particle_wire(update, na, "b", lifeA);
+    const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", na); particle_wire(update, dead, "b", [1]);
+    particle_wire(update, particle_node(update, "kill"), "condition", dead);
+    let velN2 = particle_node(update, "attribute", { name: "velocity" });
+    if (accel !== 0) {
+        const g = particle_node(update, "const", { value: [0, accel, 0, 0] });
+        const gd = particle_node(update, "scale"); particle_wire(update, gd, "v", g); particle_wire(update, gd, "s", dt);
+        const nv = particle_node(update, "add"); particle_wire(update, nv, "a", velN2); particle_wire(update, nv, "b", gd);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nv); velN2 = nv;
+    }
+    const pos = particle_node(update, "attribute", { name: "position" });
+    const pd = particle_node(update, "scale"); particle_wire(update, pd, "v", velN2); particle_wire(update, pd, "s", dt);
+    const np = particle_node(update, "add"); particle_wire(update, np, "a", pos); particle_wire(update, np, "b", pd);
+    particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", np);
+
+    return create_particle_effect({ layout, init, update });
+}