@woosh/meep-engine 3.14.3 → 3.14.5

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

@@ -0,0 +1,553 @@
+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 } from "../../renderer/particles/ParticleConstants.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 {
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    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.
+ */
+
+/** 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
+ * @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 });
+
+    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 },
+
+        /**
+         * 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,
+                    alive_in: alive_read, alive_out: alive_write, dead, counters,
+                    settings: { u_dt: dt, u_time: time, u_frame: system.frame },
+                },
+                command: dispatch_args,
+            });
+
+            // Snapshot the final alive count (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],
+                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];
+}
+
+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;
+}