@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/particles.js

@@ -0,0 +1,1533 @@
+import { auxSuffix, motionVariant, ScenePipelineCache, sceneVariant, velocityLocation, } from '../render/scene-pipelines.js';
+import { createShaderModule } from '../render/wgsl.js';
+import { buildEmitSurface } from './emit-surface.js';
+import { COLOR_CURVE_FLOATS, FX_PARTICLE_FLOATS, FX_REQUEST_FLOATS, FX_SIM_FLOATS, FX_SPAWN_FLOATS, fxRenderWgsl, MAX_FORCES, PARTICLE_COLLIDE_WGSL, PARTICLE_COMPUTE_WGSL, PARTICLE_COUNT_WGSL, PARTICLE_DEPTH_COPY_WGSL, PARTICLE_EXT_COMPUTE_WGSL, PARTICLE_EXT_RENDER_WGSL, PARTICLE_RENDER_WGSL, PARTICLE_WORLD_COMPUTE_WGSL, PARTICLE_WORLD_RENDER_WGSL, SIZE_CURVE_FLOATS, SURFACE_TRI_FLOATS, } from './particles-wgsl.js';
+import { defaultFxRandom, SPAWN_SEED_MAX } from './random.js';
+const PARTICLE_BYTES = 80;
+const SPAWN_FLOATS = 28;
+const SIM_FLOATS = 8;
+const FX_PARTICLE_BYTES = FX_PARTICLE_FLOATS * 4;
+/** Floats of the collision uniform: two mat4, viewport, params. */
+const COLLIDE_FLOATS = 40;
+/** The soft-particle depth copy's format (sampleable as `texture_depth_2d`). */
+const SOFT_DEPTH_FORMAT = 'depth32float';
+/** Most stops a `sizeCurve`/`colorCurve` may have. */
+export const MAX_CURVE_STOPS = 8;
+const POINT = { kind: 'point' };
+/** 2D maps `box` to `rect` and `sphere` to `circle`, so the 2D shader is unchanged. */
+const SHAPE_ID = { point: 0, circle: 1, rect: 2, line: 3, box: 2, sphere: 1, mesh: 6 };
+const WORLD_SHAPE_ID = {
+    point: 0,
+    circle: 1,
+    rect: 2,
+    line: 3,
+    box: 4,
+    sphere: 5,
+    mesh: 6,
+};
+const WORLD_GRAVITY = [0, -9.8, 0];
+const GRAVITY_2D = [0, 400];
+const ZERO2 = [0, 0];
+const ZERO3 = [0, 0, 0];
+const SPEED_2D = [80, 300];
+const WORLD_SPEED = [0.5, 2];
+const SIZE_2D = [6, 1];
+const WORLD_SIZE = [0.1, 0.02];
+const LIFE = [0.5, 1.2];
+const FORCE_ID = { attract: 0, vortex: 1, turbulence: 2, drag: 3 };
+const FALLOFF_ID = { constant: 0, linear: 1, 'inverse-square': 2 };
+const ADDITIVE = {
+    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+};
+const PREMULTIPLIED = {
+    color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+};
+/**
+ * GPU particles: spawn + integrate in compute, rendered as additive (or alpha) quads into both
+ * scene targets (colour + emissive → bloom). Draw with `frame.drawable(system)`.
+ *
+ * In 2D (`space: '2d'`, the default) quads are velocity-stretched in the XY plane. In world
+ * space they face the camera, stretch along the velocity's projection on the view plane,
+ * test depth, fade by distance and near scene geometry, and may be lit.
+ *
+ * The extended kernel (world space, or 2D with `extended`) adds sprite sheets, spin, curves,
+ * `forces`, depth collision, sub-emission and mesh emission; the plain 2D kernel stays what it
+ * was, pixel for pixel.
+ *
+ * Particles live in a ring buffer: when full, the oldest are overwritten.
+ */
+export class ParticleSystem {
+    capacity;
+    space;
+    /** Whether this system runs the extended kernel. */
+    extended;
+    /** Multiplier on every emit count (set < 1 for prefers-reduced-motion). */
+    spawnScale = 1;
+    floorY;
+    bounce;
+    stretch;
+    /** World space only: see `ParticleSystemOptions.lit`. */
+    lit;
+    /** World space only: see `ParticleSystemOptions.fade` (null = no distance fade). */
+    fade;
+    /** World space only: see `ParticleSystemOptions.softness`. */
+    softness;
+    /** World space only: the target soft particles read depth from (null = `renderer.target`). */
+    depthTarget;
+    /** See `ParticleSystemOptions.readsDepth`. Live. */
+    readsDepth;
+    /** Live particles at the last readback (`countAlive` only; -1 before the first). */
+    alive = -1;
+    /** Live particles below `countBelowY` at the last readback (`countAlive` only; -1 before the first). */
+    below = -1;
+    /** Live: the forces applied each frame (extended kernel; the first `MAX_FORCES` count). */
+    forces;
+    /** Live: depth collision parameters (world, `readsDepth`; null = off). */
+    collide;
+    /** Live: the stream `emit` draws spawn seeds from (see `ParticleSystemOptions.random`). */
+    random;
+    renderer;
+    device;
+    particleBuffer;
+    spawnBuffer;
+    simBuffer;
+    spawnData;
+    simData;
+    spawnFloats;
+    maxSpawns;
+    spawnPipeline;
+    updatePipeline;
+    /**
+     * Render pipelines per depth format (null: none; a depth one tests without writing) × the
+     * view target's aux key, made on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    pipelines = new ScenePipelineCache();
+    renderDesc;
+    blend;
+    /** World space: the velocity builds of the render shader by fragment location (ws/render-11). */
+    motionModules = [];
+    computeGroup;
+    renderGroup;
+    soft = null;
+    counter = null;
+    fx = null;
+    collider = null;
+    /** `debug`: the staging buffer `debugReadback` copies the particles into. */
+    debugRead = null;
+    /** The copy in flight, shared by `debugReadback` and `readbackFields` calls made meanwhile. */
+    debugJob = null;
+    /** Whether this frame's `prepare` copied scene depth (world space). */
+    softActive = false;
+    /** The renderer's `depthCopy` view `hookGroup` was made for (`readsDepth`). */
+    hookView = null;
+    hookGroup = null;
+    /** The group `draw` binds: own copy, the renderer's copy, or the stand-in. */
+    depthGroup = null;
+    spawnCount = 0;
+    maxSpawnInCmd = 0;
+    head = 0;
+    pendingDt = 0;
+    time = 0;
+    warnedOverflow = false;
+    warnedExtended = false;
+    clearPending = false;
+    constructor(renderer, opts = {}) {
+        const device = renderer.device;
+        this.renderer = renderer;
+        this.device = device;
+        const world = opts.space === 'world';
+        const fx = world ||
+            !!opts.extended ||
+            !!opts.texture ||
+            !!opts.collide ||
+            !!opts.atlas ||
+            (opts.forces?.length ?? 0) > 0;
+        this.space = world ? 'world' : '2d';
+        this.extended = fx;
+        this.capacity = Math.max(64, Math.floor(opts.capacity ?? 65536));
+        this.maxSpawns = opts.maxSpawnsPerFrame ?? 256;
+        this.floorY = opts.floorY ?? (world ? -1e9 : 1e9);
+        this.bounce = opts.bounce ?? 0.35;
+        this.stretch = opts.stretch ?? 0.02;
+        this.lit = opts.lit ?? false;
+        this.fade = opts.fade ? { near: opts.fade.near, far: opts.fade.far } : null;
+        this.softness = opts.softness ?? 0.25;
+        this.depthTarget = opts.depthTarget ?? null;
+        this.readsDepth = opts.readsDepth ?? false;
+        this.forces = opts.forces ?? [];
+        this.collide = world && opts.collide ? opts.collide : null;
+        this.random = opts.random ?? defaultFxRandom('particles');
+        this.spawnFloats = fx ? FX_SPAWN_FLOATS : SPAWN_FLOATS;
+        this.simData = new Float32Array(fx ? FX_SIM_FLOATS : SIM_FLOATS);
+        this.particleBuffer = device.createBuffer({
+            label: 'particles',
+            size: this.capacity * (fx ? FX_PARTICLE_BYTES : PARTICLE_BYTES),
+            // COPY_DST: `clear()` zeroes it with `encoder.clearBuffer`. COPY_SRC only for `debug`.
+            usage: GPUBufferUsage.STORAGE |
+                GPUBufferUsage.COPY_DST |
+                (opts.debug ? GPUBufferUsage.COPY_SRC : 0),
+        });
+        if (opts.debug) {
+            this.debugRead = device.createBuffer({
+                label: 'particles-debug-read',
+                size: this.particleBuffer.size,
+                usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+            });
+        }
+        this.spawnData = new Float32Array(this.maxSpawns * this.spawnFloats);
+        this.spawnBuffer = device.createBuffer({
+            label: 'particle-spawns',
+            size: this.spawnData.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.simBuffer = device.createBuffer({
+            label: 'particle-sim',
+            size: this.simData.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        const computeEntries = [
+            { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } },
+            { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } },
+            { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: {} },
+        ];
+        if (fx) {
+            computeEntries.push({ binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, { binding: 4, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } }, { binding: 5, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } });
+        }
+        const computeLayout = device.createBindGroupLayout({
+            label: 'particles-compute-layout',
+            entries: computeEntries,
+        });
+        const cmod = createShaderModule(device, world ? PARTICLE_WORLD_COMPUTE_WGSL : fx ? PARTICLE_EXT_COMPUTE_WGSL : PARTICLE_COMPUTE_WGSL, world ? 'particles-world-compute' : fx ? 'particles-ext-compute' : 'particles-compute');
+        const cpl = device.createPipelineLayout({ bindGroupLayouts: [computeLayout] });
+        this.spawnPipeline = device.createComputePipeline({
+            label: 'particles-spawn',
+            layout: cpl,
+            compute: { module: cmod, entryPoint: 'spawn' },
+        });
+        this.updatePipeline = device.createComputePipeline({
+            label: 'particles-update',
+            layout: cpl,
+            compute: { module: cmod, entryPoint: 'update' },
+        });
+        if (fx) {
+            this.fx = this.makeFx(computeLayout, cmod, cpl, opts);
+            this.computeGroup = this.fx.computeGroup;
+        }
+        else {
+            this.computeGroup = device.createBindGroup({
+                label: 'particles-compute',
+                layout: computeLayout,
+                entries: [
+                    { binding: 0, resource: { buffer: this.particleBuffer } },
+                    { binding: 1, resource: { buffer: this.spawnBuffer } },
+                    { binding: 2, resource: { buffer: this.simBuffer } },
+                ],
+            });
+        }
+        const renderEntries = [
+            { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+            { binding: 1, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: {} },
+        ];
+        if (world) {
+            renderEntries.push({
+                binding: 2,
+                visibility: GPUShaderStage.FRAGMENT,
+                texture: { sampleType: 'depth' },
+            });
+        }
+        if (fx) {
+            renderEntries.push({ binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } }, { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: {} }, { binding: 5, visibility: GPUShaderStage.FRAGMENT, sampler: {} });
+        }
+        const renderLayout = device.createBindGroupLayout({
+            label: world ? 'particles-world-render-layout' : 'particles-render-layout',
+            entries: renderEntries,
+        });
+        const rmod = createShaderModule(device, world ? PARTICLE_WORLD_RENDER_WGSL : fx ? PARTICLE_EXT_RENDER_WGSL : PARTICLE_RENDER_WGSL, world ? 'particles-world-render' : fx ? 'particles-ext-render' : 'particles-render');
+        const blend = opts.blend === 'alpha' ? PREMULTIPLIED : ADDITIVE;
+        this.renderDesc = {
+            label: world ? 'particles-world' : 'particles-render',
+            layout: device.createPipelineLayout({
+                bindGroupLayouts: [renderer.globalsLayout, renderLayout],
+            }),
+            vertex: { module: rmod, entryPoint: 'vs' },
+            fragment: {
+                module: rmod,
+                entryPoint: 'fs',
+                targets: renderer.sceneTargets(blend),
+            },
+            primitive: { topology: 'triangle-list' },
+        };
+        this.blend = blend;
+        this.pipelineFor(null, renderer.target.auxKey);
+        if (world)
+            this.soft = this.makeSoftDepth(renderLayout);
+        this.renderGroup = this.makeRenderGroup(world ? 'particles-world-render' : 'particles-render', renderLayout, this.soft ? this.soft.dummy.createView() : null);
+        if (world && opts.collide)
+            this.collider = this.makeCollider();
+        if (opts.countAlive)
+            this.counter = this.makeCounter(fx, opts.countBelowY ?? -Infinity);
+    }
+    /** A render bind group: the particles and sim, the depth view (world), the fx table/sheet. */
+    makeRenderGroup(label, layout, depth) {
+        const entries = [
+            { binding: 0, resource: { buffer: this.particleBuffer } },
+            { binding: 1, resource: { buffer: this.simBuffer } },
+        ];
+        if (depth)
+            entries.push({ binding: 2, resource: depth });
+        const fx = this.fx;
+        if (fx) {
+            entries.push({ binding: 3, resource: { buffer: fx.curves } }, { binding: 4, resource: fx.sheet }, { binding: 5, resource: fx.sampler });
+        }
+        return this.device.createBindGroup({ label, layout, entries });
+    }
+    makeFx(computeLayout, cmod, cpl, opts) {
+        const device = this.device;
+        const maxSubs = Math.max(1, Math.floor(opts.maxSubEmitters ?? 16));
+        const maxCurves = Math.max(1, Math.floor(opts.maxCurves ?? 32));
+        const state = device.createBuffer({
+            label: 'particles-state',
+            size: 16 + this.maxSpawns * FX_REQUEST_FLOATS * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        const subData = new Float32Array(maxSubs * FX_SPAWN_FLOATS);
+        const subs = device.createBuffer({
+            label: 'particles-subs',
+            size: subData.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        const curveData = new Float32Array(maxCurves * (SIZE_CURVE_FLOATS + COLOR_CURVE_FLOATS));
+        const curves = device.createBuffer({
+            label: 'particles-curves',
+            size: curveData.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        const surfaceData = new Float32Array(SURFACE_TRI_FLOATS);
+        const surface = device.createBuffer({
+            label: 'particles-surface',
+            size: surfaceData.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        let white = null;
+        let sheet;
+        if (opts.texture) {
+            sheet = opts.texture.view;
+        }
+        else {
+            white = device.createTexture({
+                label: 'particles-sheet-none',
+                size: [1, 1],
+                format: 'rgba8unorm',
+                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+            });
+            device.queue.writeTexture({ texture: white }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
+            sheet = white.createView();
+        }
+        const sampler = device.createSampler({
+            label: 'particles-sheet',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+        const fx = {
+            computeLayout,
+            computeGroup: null,
+            advancePipeline: device.createComputePipeline({
+                label: 'particles-advance',
+                layout: cpl,
+                compute: { module: cmod, entryPoint: 'advance' },
+            }),
+            subPipeline: device.createComputePipeline({
+                label: 'particles-subspawn',
+                layout: cpl,
+                compute: { module: cmod, entryPoint: 'subspawn' },
+            }),
+            state,
+            subs,
+            subData,
+            subSlots: new WeakMap(),
+            subNext: 0,
+            subUsed: 0,
+            subDirty: false,
+            curves,
+            curveData,
+            sizeSlots: new WeakMap(),
+            colorSlots: new WeakMap(),
+            sizeNext: 0,
+            colorNext: 0,
+            curveDirty: false,
+            surface,
+            surfaceData,
+            surfaceUsed: 0,
+            surfaceSlots: new WeakMap(),
+            surfaceDirty: false,
+            sheet,
+            sampler,
+            white,
+            textured: !!opts.texture,
+            columns: Math.max(1, Math.floor(opts.atlas?.columns ?? 1)),
+            rows: Math.max(1, Math.floor(opts.atlas?.rows ?? 1)),
+            spawnTotal: 0,
+            warnedSubs: false,
+            warnedCurves: false,
+        };
+        fx.computeGroup = this.makeComputeGroup(fx);
+        const s = this.simData;
+        s[17] = maxCurves * SIZE_CURVE_FLOATS;
+        s[18] = this.maxSpawns;
+        return fx;
+    }
+    makeComputeGroup(fx) {
+        return this.device.createBindGroup({
+            label: 'particles-compute',
+            layout: fx.computeLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.particleBuffer } },
+                { binding: 1, resource: { buffer: this.spawnBuffer } },
+                { binding: 2, resource: { buffer: this.simBuffer } },
+                { binding: 3, resource: { buffer: fx.state } },
+                { binding: 4, resource: { buffer: fx.subs } },
+                { binding: 5, resource: { buffer: fx.surface } },
+            ],
+        });
+    }
+    makeSoftDepth(renderLayout) {
+        const device = this.device;
+        const copyLayout = device.createBindGroupLayout({
+            label: 'particles-depth-copy-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
+            ],
+        });
+        const mod = createShaderModule(device, PARTICLE_DEPTH_COPY_WGSL, 'particles-depth-copy');
+        const copyPipeline = device.createRenderPipeline({
+            label: 'particles-depth-copy',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [copyLayout] }),
+            vertex: { module: mod, entryPoint: 'vs' },
+            fragment: { module: mod, entryPoint: 'fs', targets: [] },
+            primitive: { topology: 'triangle-list' },
+            depthStencil: {
+                format: SOFT_DEPTH_FORMAT,
+                depthWriteEnabled: true,
+                depthCompare: 'always',
+            },
+        });
+        const dummy = device.createTexture({
+            label: 'particles-depth-none',
+            size: [1, 1],
+            format: SOFT_DEPTH_FORMAT,
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const att = {
+            view: undefined,
+            depthClearValue: 1,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+        };
+        return {
+            copyLayout,
+            copyPipeline,
+            renderLayout,
+            dummy,
+            copy: null,
+            copyGroup: null,
+            src: null,
+            srcGroup: null,
+            att,
+            passDesc: {
+                label: 'particles-depth-copy',
+                colorAttachments: [],
+                depthStencilAttachment: att,
+            },
+        };
+    }
+    makeCollider() {
+        const device = this.device;
+        const layout = device.createBindGroupLayout({
+            label: 'particles-collide-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: {} },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: 'depth' } },
+            ],
+        });
+        const pipeline = device.createComputePipeline({
+            label: 'particles-collide',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            compute: {
+                module: createShaderModule(device, PARTICLE_COLLIDE_WGSL, 'particles-collide'),
+                entryPoint: 'collide',
+            },
+        });
+        const data = new Float32Array(COLLIDE_FLOATS);
+        const uniform = device.createBuffer({
+            label: 'particles-collide-params',
+            size: data.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        return { pipeline, layout, uniform, data, group: null, view: null };
+    }
+    makeCounter(fx, belowY) {
+        const device = this.device;
+        const count = device.createBuffer({
+            label: 'particles-alive',
+            size: 8,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+        const read = device.createBuffer({
+            label: 'particles-alive-read',
+            size: 8,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+        const params = device.createBuffer({
+            label: 'particles-alive-params',
+            size: 32,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // capacity, vec4s per particle, index of the `life` vec4, index of the position vec4, belowY.
+        const p = new ArrayBuffer(32);
+        new Uint32Array(p, 0, 4).set([this.capacity, fx ? 10 : 5, fx ? 4 : 3, 0]);
+        new Float32Array(p, 16, 1)[0] = belowY;
+        device.queue.writeBuffer(params, 0, p);
+        const layout = device.createBindGroupLayout({
+            label: 'particles-alive-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: {} },
+            ],
+        });
+        const pipeline = device.createComputePipeline({
+            label: 'particles-alive',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            compute: {
+                module: createShaderModule(device, PARTICLE_COUNT_WGSL, 'particles-alive'),
+                entryPoint: 'count',
+            },
+        });
+        const group = device.createBindGroup({
+            label: 'particles-alive',
+            layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.particleBuffer } },
+                { binding: 1, resource: { buffer: count } },
+                { binding: 2, resource: { buffer: params } },
+            ],
+        });
+        return { pipeline, group, count, read, params, state: 'idle' };
+    }
+    /**
+     * Queue `count` new particles. Cheap: one small record, spawned on the GPU next frame. The
+     * record's seed (every per-particle random on the GPU derives from it) is drawn from `random`,
+     * default the system's own stream.
+     */
+    emit(p, count, random = this.random) {
+        const n = Math.min(Math.floor(count * this.spawnScale), this.capacity);
+        if (n <= 0)
+            return;
+        if (this.spawnCount >= this.maxSpawns) {
+            if (!this.warnedOverflow) {
+                console.warn(`[particles] more than ${this.maxSpawns} emits in one frame; dropping`);
+                this.warnedOverflow = true;
+            }
+            return;
+        }
+        const o = this.spawnCount++ * this.spawnFloats;
+        const fx = this.fx;
+        if (fx) {
+            this.writeFxSpawn(this.spawnData, p, n, fx.spawnTotal, o, 0, random);
+            fx.spawnTotal += n;
+        }
+        else {
+            this.writeSpawn(p, n, o, random);
+            this.head = (this.head + n) % this.capacity;
+        }
+        if (n > this.maxSpawnInCmd)
+            this.maxSpawnInCmd = n;
+    }
+    writeSpawn(p, n, at, random) {
+        const d = this.spawnData;
+        let o = at;
+        const shape = p.shape ?? POINT;
+        let sa = 0;
+        let sb = 0;
+        if (shape.kind === 'circle' || shape.kind === 'sphere')
+            sa = shape.radius;
+        else if (shape.kind === 'rect' || shape.kind === 'box') {
+            sa = shape.width;
+            sb = shape.height;
+        }
+        else if (shape.kind === 'line') {
+            sa = shape.dx;
+            sb = shape.dy;
+        }
+        if (!this.warnedExtended &&
+            (shape.kind === 'mesh' ||
+                p.tile !== undefined ||
+                p.rotation ||
+                p.spin ||
+                p.sizeCurve ||
+                p.colorCurve ||
+                p.onDeath ||
+                p.onLife)) {
+            console.warn('[particles] sprite, spin, curve, mesh and sub-emission fields need `extended`');
+            this.warnedExtended = true;
+        }
+        const speed = p.speed ?? [80, 300];
+        const life = p.life ?? [0.5, 1.2];
+        const size = p.size ?? [6, 1];
+        const c0 = p.colorStart;
+        const c1 = p.colorEnd;
+        const g = p.gravity ?? [0, 400];
+        // a
+        d[o++] = p.x;
+        d[o++] = p.y;
+        d[o++] = sa;
+        d[o++] = sb;
+        // b
+        d[o++] = p.angle ?? -Math.PI / 2;
+        d[o++] = p.spread ?? Math.PI * 2;
+        d[o++] = speed[0];
+        d[o++] = speed[1];
+        // c
+        d[o++] = life[0];
+        d[o++] = life[1];
+        d[o++] = size[0];
+        d[o++] = size[1];
+        // c0, c1
+        o = writeColors(d, o, c0, c1);
+        // d
+        d[o++] = g[0];
+        d[o++] = g[1];
+        d[o++] = p.drag ?? 1;
+        d[o++] = shape.kind === 'mesh' ? 0 : SHAPE_ID[shape.kind];
+        // e
+        d[o++] = this.head;
+        d[o++] = n;
+        d[o++] = random.int(0, SPAWN_SEED_MAX);
+        d[o++] = p.emissive ?? 1;
+    }
+    /**
+     * An extended spawn record at `at` of `d`: `n` particles from `start` (relative to the
+     * frame's ring head). `depth` 1 writes a sub-emitter record (no sub-emitters of its own).
+     */
+    writeFxSpawn(d, p, n, start, at, depth, random) {
+        const world = this.space === 'world';
+        const fx = this.fx;
+        let o = at;
+        const shape = p.shape ?? POINT;
+        let sa = 0;
+        let sb = 0;
+        let sc = 0;
+        let meshOffset = 0;
+        let meshCount = 0;
+        let flags = p.alignToVelocity === false ? 0 : 1;
+        if (shape.kind === 'circle' || shape.kind === 'sphere')
+            sa = shape.radius;
+        else if (shape.kind === 'rect') {
+            sa = shape.width;
+            sb = shape.height;
+        }
+        else if (shape.kind === 'box') {
+            sa = shape.width;
+            sb = shape.height;
+            sc = world ? shape.depth : 0;
+        }
+        else if (shape.kind === 'line') {
+            sa = shape.dx;
+            sb = shape.dy;
+            sc = world ? (shape.dz ?? 0) : 0;
+        }
+        else if (shape.kind === 'mesh') {
+            const m = this.internSurface(shape);
+            meshOffset = m.offset;
+            meshCount = m.count;
+            if (shape.alongNormal)
+                flags |= 2;
+        }
+        const speed = p.speed ?? (world ? WORLD_SPEED : SPEED_2D);
+        const life = p.life ?? LIFE;
+        const size = p.size ?? (world ? WORLD_SIZE : SIZE_2D);
+        const g = p.gravity ?? (world ? WORLD_GRAVITY : GRAVITY_2D);
+        const w = p.wind ?? ZERO3;
+        const tile = p.tile ?? 0;
+        const rot = p.rotation ?? ZERO2;
+        const spin = p.spin ?? ZERO2;
+        const sizeSlot = p.sizeCurve ? this.internCurve(fx, p.sizeCurve, false) : -1;
+        const colorSlot = p.colorCurve ? this.internCurve(fx, p.colorCurve, true) : -1;
+        let deathSlot = -1;
+        let lifeSlot = -1;
+        if (depth === 0) {
+            if (p.onDeath && p.onDeath.count > 0) {
+                deathSlot = this.internSub(fx, p.onDeath, p.onDeath.params, p.inherit ?? 0, random);
+            }
+            if (p.onLife && p.onLife.rate > 0) {
+                lifeSlot = this.internSub(fx, p.onLife, p.onLife.params, p.inherit ?? 0, random);
+            }
+        }
+        // a
+        d[o++] = p.x;
+        d[o++] = p.y;
+        d[o++] = world ? (p.z ?? 0) : 0;
+        d[o++] = world ? WORLD_SHAPE_ID[shape.kind] : SHAPE_ID[shape.kind];
+        // b
+        d[o++] = sa;
+        d[o++] = sb;
+        d[o++] = sc;
+        d[o++] = p.spread ?? Math.PI * 2;
+        // c
+        d[o++] = p.angle ?? (world ? Math.PI / 2 : -Math.PI / 2);
+        d[o++] = world ? (p.vz ?? 0) : 0;
+        d[o++] = speed[0];
+        d[o++] = speed[1];
+        // d
+        d[o++] = life[0];
+        d[o++] = life[1];
+        d[o++] = size[0];
+        d[o++] = size[1];
+        // c0, c1
+        o = writeColors(d, o, p.colorStart, p.colorEnd);
+        // e
+        d[o++] = g[0];
+        d[o++] = g[1];
+        d[o++] = world ? (g[2] ?? 0) : 0;
+        d[o++] = p.drag ?? 1;
+        // f
+        d[o++] = world ? w[0] : 0;
+        d[o++] = world ? w[1] : 0;
+        d[o++] = world ? w[2] : 0;
+        d[o++] = p.emissive ?? 1;
+        // g
+        d[o++] = start;
+        d[o++] = n;
+        d[o++] = random.int(0, SPAWN_SEED_MAX);
+        d[o++] = p.inherit ?? 0;
+        // h
+        d[o++] = typeof tile === 'number' ? tile : tile[0];
+        d[o++] = typeof tile === 'number' ? tile : tile[1];
+        d[o++] = p.tileRate ?? 0;
+        d[o++] = flags;
+        // i
+        d[o++] = rot[0];
+        d[o++] = rot[1];
+        d[o++] = spin[0];
+        d[o++] = spin[1];
+        // j
+        d[o++] = sizeSlot;
+        d[o++] = colorSlot;
+        d[o++] = deathSlot;
+        d[o++] = lifeSlot;
+        // k
+        d[o++] = p.onDeath?.count ?? 0;
+        d[o++] = p.onLife?.rate ?? 0;
+        d[o++] = meshOffset;
+        d[o++] = meshCount;
+    }
+    /** The curve table slot of `stops` (by identity; rewritten on every emit, so edits are live). */
+    internCurve(fx, stops, color) {
+        const n = stops.length;
+        if (n < 2 || n > MAX_CURVE_STOPS) {
+            throw new Error(`[particles] a curve needs 2..${MAX_CURVE_STOPS} stops, got ${n}`);
+        }
+        const slots = color ? fx.colorSlots : fx.sizeSlots;
+        const maxCurves = this.simData[17] / SIZE_CURVE_FLOATS;
+        let slot = slots.get(stops);
+        if (slot === undefined) {
+            const next = color ? fx.colorNext : fx.sizeNext;
+            slot = next % maxCurves;
+            if (next >= maxCurves && !fx.warnedCurves) {
+                console.warn(`[particles] more than ${maxCurves} distinct curves; reusing slots`);
+                fx.warnedCurves = true;
+            }
+            if (color)
+                fx.colorNext = next + 1;
+            else
+                fx.sizeNext = next + 1;
+            slots.set(stops, slot);
+        }
+        const t = fx.curveData;
+        if (color) {
+            const base = maxCurves * SIZE_CURVE_FLOATS + slot * COLOR_CURVE_FLOATS;
+            t[base] = n;
+            for (let i = 0; i < n; i++) {
+                const c = stops[i];
+                t[base + 4 + i * 4] = c[0];
+                t[base + 5 + i * 4] = c[1];
+                t[base + 6 + i * 4] = c[2];
+                t[base + 7 + i * 4] = c[3] ?? 1;
+            }
+        }
+        else {
+            const base = slot * SIZE_CURVE_FLOATS;
+            t[base] = n;
+            for (let i = 0; i < n; i++)
+                t[base + 1 + i] = stops[i];
+        }
+        fx.curveDirty = true;
+        return slot;
+    }
+    /** The sub-emitter record slot of `key` (by identity; rewritten on every parent emit). */
+    internSub(fx, key, params, inherit, random) {
+        const maxSubs = fx.subData.length / FX_SPAWN_FLOATS;
+        let slot = fx.subSlots.get(key);
+        if (slot === undefined) {
+            slot = fx.subNext % maxSubs;
+            if (fx.subNext >= maxSubs && !fx.warnedSubs) {
+                console.warn(`[particles] more than ${maxSubs} distinct sub-emitters; reusing slots`);
+                fx.warnedSubs = true;
+            }
+            fx.subNext++;
+            fx.subUsed = Math.min(fx.subNext, maxSubs);
+            fx.subSlots.set(key, slot);
+        }
+        this.writeFxSpawn(fx.subData, params, 0, 0, slot * FX_SPAWN_FLOATS, 1, random);
+        fx.subData[slot * FX_SPAWN_FLOATS + 35] = inherit;
+        fx.subDirty = true;
+        return slot;
+    }
+    /** The surface table range of a mesh shape (built and appended on first sight). */
+    internSurface(shape) {
+        const fx = this.fx;
+        let m = fx.surfaceSlots.get(shape);
+        if (m)
+            return m;
+        const surface = 'table' in shape ? shape : buildEmitSurface(shape, shape);
+        const floats = surface.triangles * SURFACE_TRI_FLOATS;
+        if (fx.surfaceUsed + floats > fx.surfaceData.length) {
+            const grown = new Float32Array(Math.max(fx.surfaceUsed + floats, fx.surfaceData.length * 2));
+            grown.set(fx.surfaceData.subarray(0, fx.surfaceUsed));
+            fx.surfaceData = grown;
+        }
+        fx.surfaceData.set(surface.table.subarray(0, floats), fx.surfaceUsed);
+        m = { offset: fx.surfaceUsed / 4, count: surface.triangles };
+        fx.surfaceUsed += floats;
+        fx.surfaceDirty = true;
+        fx.surfaceSlots.set(shape, m);
+        return m;
+    }
+    /** Advance simulation time. Call from fixed update; integration happens on the GPU. */
+    update(dt) {
+        this.pendingDt += dt;
+    }
+    prepare(encoder, frame) {
+        const dt = Math.min(this.pendingDt, 0.1);
+        this.pendingDt = 0;
+        this.time += dt;
+        const s = this.simData;
+        const fx = this.fx;
+        s[0] = dt;
+        s[1] = this.floorY;
+        s[2] = this.bounce;
+        s[3] = this.time;
+        s[4] = this.capacity;
+        s[5] = this.stretch;
+        s[6] = this.spawnCount;
+        s[7] = fx ? fx.spawnTotal : 0;
+        if (this.soft) {
+            // With `readsDepth` the renderer's hook (`afterOpaque`) supplies this frame's depth.
+            this.softActive = this.readsDepth ? false : this.copyDepth(encoder, frame);
+            this.depthGroup = this.softActive ? this.soft.copyGroup : null;
+            const f = this.fade;
+            s[8] = f ? f.near : 0;
+            s[9] = f ? f.far : 0;
+            s[10] = this.softness;
+            s[11] = this.softActive ? 1 : 0;
+            s[12] = this.lit ? 1 : 0;
+        }
+        if (fx) {
+            s[13] = fx.textured ? 1 : 0;
+            s[14] = fx.columns;
+            s[15] = fx.rows;
+            s[16] = this.writeForces(s);
+        }
+        const q = this.device.queue;
+        q.writeBuffer(this.simBuffer, 0, s);
+        if (this.clearPending) {
+            encoder.clearBuffer(this.particleBuffer);
+            if (fx)
+                encoder.clearBuffer(fx.state);
+            this.clearPending = false;
+        }
+        if (fx)
+            this.uploadTables(fx);
+        const counter = this.counter;
+        if (counter?.state === 'copied')
+            this.readAlive(counter);
+        const count = counter?.state === 'idle';
+        if (count)
+            encoder.clearBuffer(counter.count);
+        const pass = encoder.beginComputePass({ label: 'particles' });
+        pass.setBindGroup(0, this.computeGroup);
+        if (this.spawnCount > 0) {
+            q.writeBuffer(this.spawnBuffer, 0, this.spawnData.buffer, 0, this.spawnCount * this.spawnFloats * 4);
+            pass.setPipeline(this.spawnPipeline);
+            pass.dispatchWorkgroups(Math.ceil(this.maxSpawnInCmd / 64), this.spawnCount);
+        }
+        if (fx) {
+            pass.setPipeline(fx.advancePipeline);
+            pass.dispatchWorkgroups(1);
+        }
+        if (dt > 0) {
+            pass.setPipeline(this.updatePipeline);
+            pass.dispatchWorkgroups(Math.ceil(this.capacity / 64));
+            if (fx && fx.subUsed > 0) {
+                pass.setPipeline(fx.subPipeline);
+                pass.dispatchWorkgroups(Math.ceil(this.maxSpawns / 64));
+            }
+        }
+        if (count) {
+            pass.setPipeline(counter.pipeline);
+            pass.setBindGroup(0, counter.group);
+            pass.dispatchWorkgroups(Math.ceil(this.capacity / 64));
+        }
+        pass.end();
+        if (count) {
+            encoder.copyBufferToBuffer(counter.count, 0, counter.read, 0, 8);
+            counter.state = 'copied';
+        }
+        this.spawnCount = 0;
+        this.maxSpawnInCmd = 0;
+        if (fx)
+            fx.spawnTotal = 0;
+        this.warnedOverflow = false;
+    }
+    /** Pack `forces` (the first `MAX_FORCES`) into the sim block; returns how many. */
+    writeForces(s) {
+        const forces = this.forces;
+        const n = Math.min(forces.length, MAX_FORCES);
+        for (let i = 0; i < n; i++) {
+            const f = forces[i];
+            const o = 20 + i * 12;
+            s[o] = FORCE_ID[f.kind];
+            for (let k = 1; k < 12; k++)
+                s[o + k] = 0;
+            if (f.kind === 'attract' || f.kind === 'vortex') {
+                s[o + 1] = f.x;
+                s[o + 2] = f.y;
+                s[o + 3] = f.z ?? 0;
+                s[o + 4] = f.strength;
+                s[o + 5] = f.radius ?? 0;
+                if (f.kind === 'vortex') {
+                    s[o + 8] = f.axis[0];
+                    s[o + 9] = f.axis[1];
+                    s[o + 10] = f.axis[2];
+                }
+                else {
+                    s[o + 8] = FALLOFF_ID[f.falloff ?? 'constant'];
+                    s[o + 9] = f.deadZone ?? 0;
+                }
+            }
+            else if (f.kind === 'turbulence') {
+                s[o + 4] = f.strength;
+                s[o + 6] = f.frequency;
+                s[o + 7] = f.seed ?? 0;
+            }
+            else {
+                s[o + 11] = f.amount;
+            }
+        }
+        return n;
+    }
+    /** Upload the dirty curve, sub-emitter and surface tables (the surface buffer may grow). */
+    uploadTables(fx) {
+        const q = this.device.queue;
+        if (fx.curveDirty) {
+            q.writeBuffer(fx.curves, 0, fx.curveData);
+            fx.curveDirty = false;
+        }
+        if (fx.subDirty) {
+            q.writeBuffer(fx.subs, 0, fx.subData.buffer, 0, fx.subUsed * FX_SPAWN_FLOATS * 4);
+            fx.subDirty = false;
+        }
+        if (fx.surfaceDirty) {
+            const bytes = fx.surfaceUsed * 4;
+            if (bytes > fx.surface.size) {
+                fx.surface.destroy();
+                fx.surface = this.device.createBuffer({
+                    label: 'particles-surface',
+                    size: fx.surfaceData.byteLength,
+                    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+                });
+                fx.computeGroup = this.makeComputeGroup(fx);
+                this.computeGroup = fx.computeGroup;
+            }
+            q.writeBuffer(fx.surface, 0, fx.surfaceData.buffer, 0, bytes);
+            fx.surfaceDirty = false;
+        }
+    }
+    /**
+     * Map last frame's count (its commands were submitted by now). This frame records nothing
+     * into the readback buffer, so mapping it while this frame is encoded is valid.
+     */
+    readAlive(c) {
+        c.state = 'mapping';
+        c.read.mapAsync(GPUMapMode.READ).then(() => {
+            if (c.state !== 'mapping')
+                return;
+            const counts = new Uint32Array(c.read.getMappedRange(0, 8));
+            this.alive = counts[0];
+            this.below = counts[1] ?? 0;
+            c.read.unmap();
+            c.state = 'idle';
+        }, () => {
+            c.state = 'dead';
+        });
+    }
+    /**
+     * World space: copy the scene's depth into this system's own depth32float texture, which the
+     * fragment shader samples for the soft fade. It runs before this frame's scene pass, so it
+     * holds what the target's depth held then: the previous frame's, or that of an earlier
+     * `render` call this frame (draw the particles on their own layer in a second view of the
+     * same camera for a same-frame fade). Returns false (soft fade off) without depth.
+     */
+    copyDepth(encoder, frame) {
+        const sd = this.soft;
+        if (this.softness <= 0 || !frame?.depthFormat)
+            return false;
+        const src = (this.depthTarget ?? this.renderer.target).depth;
+        if (!src)
+            return false;
+        const device = this.device;
+        if (!sd.copy || sd.copy.width !== src.width || sd.copy.height !== src.height) {
+            sd.copy?.destroy();
+            sd.copy = device.createTexture({
+                label: 'particles-depth',
+                size: [src.width, src.height],
+                format: SOFT_DEPTH_FORMAT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            });
+            const view = sd.copy.createView();
+            sd.att.view = view;
+            sd.copyGroup = this.makeRenderGroup('particles-world-render-soft', sd.renderLayout, view);
+        }
+        if (sd.src !== src) {
+            sd.src = src;
+            sd.srcGroup = device.createBindGroup({
+                label: 'particles-depth-copy',
+                layout: sd.copyLayout,
+                entries: [{ binding: 0, resource: src.view }],
+            });
+        }
+        const pass = encoder.beginRenderPass(sd.passDesc);
+        pass.setPipeline(sd.copyPipeline);
+        pass.setBindGroup(0, sd.srcGroup);
+        pass.draw(3);
+        pass.end();
+        return true;
+    }
+    /**
+     * Draw inside the scene pass. With a depth camera (`frame.depthFormat` set) the pipeline
+     * tests against depth without writing it, like any blended material.
+     */
+    draw(pass, frame) {
+        const fmt = frame?.depthFormat ?? null;
+        pass.setPipeline(this.pipelineFor(fmt, frame ? frame.auxKey : this.renderer.target.auxKey));
+        pass.setBindGroup(1, this.depthGroup ?? this.renderGroup);
+        pass.draw(6, this.capacity);
+    }
+    /**
+     * The renderer's depth hook (`readsDepth`, world space): with `softness` > 0 bind this
+     * frame's opaque depth copy and flip the shader's soft flag on (a 4-byte write that lands
+     * before the frame's commands run); with `collide` run the collision kernel against the same
+     * depth. New bind groups only when the copy texture changed.
+     */
+    afterOpaque(encoder, view) {
+        const sd = this.soft;
+        if (!sd)
+            return;
+        if (this.softness > 0) {
+            if (view.depthView !== this.hookView) {
+                this.hookView = view.depthView;
+                this.hookGroup = this.makeRenderGroup('particles-world-render-hook', sd.renderLayout, view.depthView);
+            }
+            this.softActive = true;
+            this.depthGroup = this.hookGroup;
+            const s = this.simData;
+            s[11] = 1;
+            this.device.queue.writeBuffer(this.simBuffer, 11 * 4, s.buffer, 11 * 4, 4);
+        }
+        const col = this.collider;
+        const params = this.collide;
+        if (col && params) {
+            if (view.depthView !== col.view) {
+                col.view = view.depthView;
+                col.group = this.device.createBindGroup({
+                    label: 'particles-collide',
+                    layout: col.layout,
+                    entries: [
+                        { binding: 0, resource: { buffer: this.particleBuffer } },
+                        { binding: 1, resource: { buffer: col.uniform } },
+                        { binding: 2, resource: view.depthView },
+                    ],
+                });
+            }
+            const d = col.data;
+            d.set(view.camera.viewProjection, 0);
+            d.set(view.camera.invViewProj, 16);
+            const vp = view.viewport;
+            d[32] = vp.x;
+            d[33] = vp.y;
+            d[34] = vp.width;
+            d[35] = vp.height;
+            d[36] = params.bounce;
+            d[37] = params.friction;
+            d[38] = params.thickness ?? 1;
+            // The last advance's dt: the swept test steps back along the velocity by it.
+            d[39] = this.simData[0];
+            this.device.queue.writeBuffer(col.uniform, 0, d);
+            const pass = encoder.beginComputePass({ label: 'particles-collide' });
+            pass.setPipeline(col.pipeline);
+            pass.setBindGroup(0, col.group);
+            pass.dispatchWorkgroups(Math.ceil(this.capacity / 64));
+            pass.end();
+        }
+    }
+    pipelineFor(format, aux) {
+        const p = this.pipelines.get(format, aux);
+        if (p)
+            return p;
+        const desc = this.renderDesc;
+        const targets = this.renderer.sceneTargets(this.blend, aux);
+        const label = `${desc.label}${format ? `:${format}` : ''}${auxSuffix(aux)}`;
+        const depth = format
+            ? { format, depthWriteEnabled: false, depthCompare: 'less-equal' }
+            : undefined;
+        // World particles write their own motion into a velocity attachment (ws/render-11); 2D
+        // ones (screen space, no camera history) keep it masked.
+        const at = this.space === 'world' ? velocityLocation(aux) : 0;
+        return this.pipelines.set(format, aux, this.device.createRenderPipeline(at === 0
+            ? sceneVariant(desc, targets, label, depth)
+            : motionVariant(desc, this.motionModule(at), targets, aux, `${label}:motion`, depth)));
+    }
+    motionModule(at) {
+        let m = this.motionModules[at];
+        if (!m) {
+            m = createShaderModule(this.device, fxRenderWgsl(true, at), 'particles-world-render-motion');
+            this.motionModules[at] = m;
+        }
+        return m;
+    }
+    /**
+     * Kill every particle (e.g. on scene change), including emits queued earlier this frame.
+     * The buffer is zeroed on the GPU at the start of the next `prepare` (no CPU allocation);
+     * particles emitted after `clear()` survive.
+     */
+    clear() {
+        this.clearPending = true;
+        this.spawnCount = 0;
+        this.maxSpawnInCmd = 0;
+        this.head = 0;
+        if (this.fx)
+            this.fx.spawnTotal = 0;
+    }
+    /**
+     * Copy the particle buffer into the staging buffer, map it and return the live particles
+     * (`debug: true` only; rejects otherwise). Never runs on its own. The copy is submitted at
+     * once, so call it outside a frame (after `endFrame`): it then holds every frame submitted so
+     * far. A call while one is in flight returns that one's promise.
+     */
+    debugReadback() {
+        const job = this.debugCopy('debugReadback');
+        if (!job) {
+            return Promise.reject(new Error('ParticleSystem.debugReadback needs `debug: true`'));
+        }
+        if (!job.packed) {
+            job.wantPacked = true;
+            job.packed = job.done.then((r) => r.packed);
+        }
+        return job.packed;
+    }
+    /**
+     * As `debugReadback`, but resolves to every field of the live particles by name
+     * (`ParticleFields`), unpacked from the kernel's layout (ws/fx-7). `debug: true` only. Calls
+     * made while a copy is in flight share it with each other and with `debugReadback`, so both
+     * forms called back to back describe the same copy.
+     */
+    readbackFields() {
+        const job = this.debugCopy('readbackFields');
+        if (!job) {
+            return Promise.reject(new Error('ParticleSystem.readbackFields needs `debug: true`'));
+        }
+        if (!job.fields) {
+            job.wantFields = true;
+            job.fields = job.done.then((r) => r.fields);
+        }
+        return job.fields;
+    }
+    /** The copy in flight, or a new one submitted now; null without `debug`. */
+    debugCopy(label) {
+        const read = this.debugRead;
+        if (!read)
+            return null;
+        if (this.debugJob)
+            return this.debugJob;
+        const enc = this.device.createCommandEncoder({ label: `particles-${label}` });
+        enc.copyBufferToBuffer(this.particleBuffer, 0, read, 0, read.size);
+        this.device.queue.submit([enc.finish()]);
+        const time = this.time;
+        const job = {
+            wantPacked: false,
+            wantFields: false,
+            packed: null,
+            fields: null,
+            done: read.mapAsync(GPUMapMode.READ).then(() => {
+                const d = new Float32Array(read.getMappedRange(0, read.size));
+                const out = {
+                    packed: job.wantPacked ? parseParticles(d, this.capacity, this.extended, time) : null,
+                    fields: job.wantFields ? this.parseFields(d, time) : null,
+                };
+                read.unmap();
+                this.debugJob = null;
+                return out;
+            }, (err) => {
+                this.debugJob = null;
+                throw err;
+            }),
+        };
+        this.debugJob = job;
+        return job;
+    }
+    /** `parseFields` with this system's layout and curve table. */
+    parseFields(d, time) {
+        const fx = this.fx;
+        return parseFields(d, this.capacity, this.extended, time, fx ? fx.curveData : null);
+    }
+    destroy() {
+        this.debugRead?.destroy();
+        this.particleBuffer.destroy();
+        this.spawnBuffer.destroy();
+        this.simBuffer.destroy();
+        if (this.soft) {
+            this.soft.dummy.destroy();
+            this.soft.copy?.destroy();
+            this.soft.copy = null;
+        }
+        if (this.counter) {
+            this.counter.state = 'dead';
+            this.counter.count.destroy();
+            this.counter.read.destroy();
+            this.counter.params.destroy();
+        }
+        const fx = this.fx;
+        if (fx) {
+            fx.state.destroy();
+            fx.subs.destroy();
+            fx.curves.destroy();
+            fx.surface.destroy();
+            fx.white?.destroy();
+        }
+        this.collider?.uniform.destroy();
+    }
+}
+/**
+ * The live particles of a particle buffer's floats. Layouts: the original kernel's 20 floats
+ * (`posVel`, c0, c1, `life` at 12), the extended kernel's 40 (`pos` at 0, `vel` at 4, `life`
+ * at 16). Live means age < lifetime, as `PARTICLE_COUNT_WGSL` counts.
+ */
+function parseParticles(d, capacity, extended, time) {
+    const stride = extended ? FX_PARTICLE_FLOATS : PARTICLE_BYTES / 4;
+    const lifeAt = extended ? 16 : 12;
+    let alive = 0;
+    for (let i = 0; i < capacity; i++) {
+        const o = i * stride + lifeAt;
+        if (d[o] < d[o + 1])
+            alive++;
+    }
+    const positions = new Float32Array(alive * 3);
+    const velocities = new Float32Array(alive * 3);
+    const slots = new Uint32Array(alive);
+    let n = 0;
+    for (let i = 0; i < capacity; i++) {
+        const o = i * stride;
+        if (!(d[o + lifeAt] < d[o + lifeAt + 1]))
+            continue;
+        slots[n] = i;
+        const k = n * 3;
+        positions[k] = d[o];
+        positions[k + 1] = d[o + 1];
+        if (extended) {
+            positions[k + 2] = d[o + 2];
+            velocities[k] = d[o + 4];
+            velocities[k + 1] = d[o + 5];
+            velocities[k + 2] = d[o + 6];
+        }
+        else {
+            velocities[k] = d[o + 2];
+            velocities[k + 1] = d[o + 3];
+        }
+        n++;
+    }
+    return { alive, positions, velocities, slots, time };
+}
+/**
+ * Every field of the live particles of a particle buffer's floats (ws/fx-7). The original
+ * kernel's 20 floats: `posVel` (pos.xy, vel.xy), c0, c1, `life` (age, lifetime, size at birth,
+ * size at death), `phys` (gravity.xy, drag, emissive). The extended kernel's 40: `pos` (xyz,
+ * rotation), `vel` (xyz, spin), c0, c1, `life`, `phys` (gravity xyz, drag), `wind` (xyz,
+ * emissive), `tile`, `curve` (slots), `sub`. `curves` is the curve table (extended only) for
+ * `radius`, read as the kernel's `size_at` does.
+ */
+function parseFields(d, capacity, extended, time, curves) {
+    const stride = extended ? FX_PARTICLE_FLOATS : PARTICLE_BYTES / 4;
+    const lifeAt = extended ? 16 : 12;
+    let alive = 0;
+    for (let i = 0; i < capacity; i++) {
+        const o = i * stride + lifeAt;
+        if (d[o] < d[o + 1])
+            alive++;
+    }
+    const f = {
+        alive,
+        slots: new Uint32Array(alive),
+        time,
+        position: new Float32Array(alive * 3),
+        velocity: new Float32Array(alive * 3),
+        age: new Float32Array(alive),
+        life: new Float32Array(alive),
+        radius: new Float32Array(alive),
+        sizeStart: new Float32Array(alive),
+        sizeEnd: new Float32Array(alive),
+        color0: new Float32Array(alive * 4),
+        color1: new Float32Array(alive * 4),
+        gravity: new Float32Array(alive * 3),
+        drag: new Float32Array(alive),
+        emissive: new Float32Array(alive),
+        rotation: new Float32Array(alive),
+        spin: new Float32Array(alive),
+        wind: new Float32Array(alive * 3),
+        tile: new Float32Array(alive * 4),
+        curveSlots: new Int32Array(alive * 4).fill(-1),
+        sub: new Float32Array(alive * 3),
+    };
+    let n = 0;
+    for (let i = 0; i < capacity; i++) {
+        const o = i * stride;
+        const age = d[o + lifeAt];
+        const life = d[o + lifeAt + 1];
+        if (!(age < life))
+            continue;
+        const s0 = d[o + lifeAt + 2];
+        const s1 = d[o + lifeAt + 3];
+        const t = age / life;
+        const k3 = n * 3;
+        const k4 = n * 4;
+        f.slots[n] = i;
+        f.age[n] = age;
+        f.life[n] = life;
+        f.sizeStart[n] = s0;
+        f.sizeEnd[n] = s1;
+        // c0 then c1 straight before `life` in both layouts.
+        f.color0.set(d.subarray(o + lifeAt - 8, o + lifeAt - 4), k4);
+        f.color1.set(d.subarray(o + lifeAt - 4, o + lifeAt), k4);
+        f.position[k3] = d[o];
+        f.position[k3 + 1] = d[o + 1];
+        let size = s0 + (s1 - s0) * t;
+        if (extended) {
+            f.position[k3 + 2] = d[o + 2];
+            f.rotation[n] = d[o + 3];
+            f.velocity.set(d.subarray(o + 4, o + 7), k3);
+            f.spin[n] = d[o + 7];
+            f.gravity.set(d.subarray(o + 20, o + 23), k3);
+            f.drag[n] = d[o + 23];
+            f.wind.set(d.subarray(o + 24, o + 27), k3);
+            f.emissive[n] = d[o + 27];
+            f.tile.set(d.subarray(o + 28, o + 32), k4);
+            for (let c = 0; c < 4; c++)
+                f.curveSlots[k4 + c] = d[o + 32 + c];
+            f.sub.set(d.subarray(o + 36, o + 39), k3);
+            const slot = d[o + 32];
+            if (slot >= 0 && curves) {
+                // size_at: piecewise-linear over the slot's stops, times the size at birth.
+                const base = Math.floor(slot) * SIZE_CURVE_FLOATS;
+                const stops = curves[base];
+                const x = Math.min(Math.max(t, 0), 1) * (stops - 1);
+                const j = Math.min(Math.floor(x), stops - 2);
+                const a = curves[base + 1 + j];
+                size = (a + (curves[base + 2 + j] - a) * (x - j)) * s0;
+            }
+        }
+        else {
+            f.velocity[k3] = d[o + 2];
+            f.velocity[k3 + 1] = d[o + 3];
+            f.gravity[k3] = d[o + 16];
+            f.gravity[k3 + 1] = d[o + 17];
+            f.drag[n] = d[o + 18];
+            f.emissive[n] = d[o + 19];
+        }
+        f.radius[n] = Math.max(size, 0) * 0.5;
+        n++;
+    }
+    return f;
+}
+/** Write `c0` and `c1` (default: `c0` with alpha 0) at `o`; returns the next offset. */
+function writeColors(d, at, c0, c1) {
+    let o = at;
+    d[o++] = c0[0];
+    d[o++] = c0[1];
+    d[o++] = c0[2];
+    d[o++] = c0[3] ?? 1;
+    d[o++] = c1 ? c1[0] : c0[0];
+    d[o++] = c1 ? c1[1] : c0[1];
+    d[o++] = c1 ? c1[2] : c0[2];
+    d[o++] = c1 ? (c1[3] ?? 1) : 0;
+    return o;
+}
+/**
+ * The CPU reference of the kernel's curve lookup: piecewise-linear over `stops` (2..8) spread
+ * evenly on 0..1, each stop `stride` numbers (1 for a size curve, 4 for RGBA), written to `out`.
+ */
+export function evaluateCurve(stops, stride, t, out) {
+    const n = Math.floor(stops.length / stride);
+    const x = Math.min(Math.max(t, 0), 1) * (n - 1);
+    const i = Math.min(Math.floor(x), n - 2);
+    const f = x - i;
+    for (let k = 0; k < stride; k++) {
+        const a = stops[i * stride + k];
+        const b = stops[(i + 1) * stride + k];
+        out[k] = a + (b - a) * f;
+    }
+    return out;
+}
+function pcg(v) {
+    const s = (Math.imul(v, 747796405) + 2891336453) >>> 0;
+    const w = Math.imul(((s >>> ((s >>> 28) + 4)) ^ s) >>> 0, 277803737) >>> 0;
+    return ((w >>> 22) ^ w) >>> 0;
+}
+function lattice(x, y, z, seed) {
+    const h = pcg((Math.imul(x, 73856093) ^ Math.imul(y, 19349663) ^ Math.imul(z, 83492791) ^ seed) >>> 0);
+    return h / 4294967295;
+}
+function vnoise(x, y, z, seed) {
+    const ix = Math.floor(x);
+    const iy = Math.floor(y);
+    const iz = Math.floor(z);
+    const fx = x - ix;
+    const fy = y - iy;
+    const fz = z - iz;
+    const ux = fx * fx * (3 - 2 * fx);
+    const uy = fy * fy * (3 - 2 * fy);
+    const uz = fz * fz * (3 - 2 * fz);
+    const l = (dx, dy, dz) => lattice(ix + dx, iy + dy, iz + dz, seed);
+    const x00 = l(0, 0, 0) + (l(1, 0, 0) - l(0, 0, 0)) * ux;
+    const x10 = l(0, 1, 0) + (l(1, 1, 0) - l(0, 1, 0)) * ux;
+    const x01 = l(0, 0, 1) + (l(1, 0, 1) - l(0, 0, 1)) * ux;
+    const x11 = l(0, 1, 1) + (l(1, 1, 1) - l(0, 1, 1)) * ux;
+    const y0 = x00 + (x10 - x00) * uy;
+    const y1 = x01 + (x11 - x01) * uy;
+    return y0 + (y1 - y0) * uz;
+}
+/**
+ * The CPU reference of the kernel's force step: accelerate `vel` (xyz) by `forces` at `pos`
+ * over `dt` and apply the extra drag (the particle's own gravity, drag and wind are not
+ * included). For tests and shadow simulations; the GPU does the real work.
+ */
+export function applyForces(forces, pos, vel, dt) {
+    let ax = 0;
+    let ay = 0;
+    let az = 0;
+    let drag = 0;
+    const px = pos[0];
+    const py = pos[1];
+    const pz = pos[2] ?? 0;
+    for (const f of forces) {
+        if (f.kind === 'attract') {
+            const dx = f.x - px;
+            const dy = f.y - py;
+            const dz = (f.z ?? 0) - pz;
+            const r = Math.hypot(dx, dy, dz);
+            const radius = f.radius ?? 0;
+            let w = radius > 0 ? Math.max(1 - r / radius, 0) : 1;
+            if (f.falloff === 'linear')
+                w *= r;
+            else if (f.falloff === 'inverse-square')
+                w /= Math.max(r * r, 1e-4);
+            if (r > 1e-4 && r >= (f.deadZone ?? 0)) {
+                ax += (dx / r) * f.strength * w;
+                ay += (dy / r) * f.strength * w;
+                az += (dz / r) * f.strength * w;
+            }
+        }
+        else if (f.kind === 'vortex') {
+            const al = Math.hypot(f.axis[0], f.axis[1], f.axis[2]) || 1;
+            const nx = f.axis[0] / al;
+            const ny = f.axis[1] / al;
+            const nz = f.axis[2] / al;
+            const rx = px - f.x;
+            const ry = py - f.y;
+            const rz = pz - (f.z ?? 0);
+            const d = rx * nx + ry * ny + rz * nz;
+            const qx = rx - nx * d;
+            const qy = ry - ny * d;
+            const qz = rz - nz * d;
+            const r = Math.hypot(qx, qy, qz);
+            const radius = f.radius ?? 0;
+            const w = radius > 0 ? Math.max(1 - r / radius, 0) : 1;
+            if (r > 1e-4) {
+                const s = (f.strength * w) / r;
+                ax += (ny * qz - nz * qy) * s;
+                ay += (nz * qx - nx * qz) * s;
+                az += (nx * qy - ny * qx) * s;
+            }
+        }
+        else if (f.kind === 'turbulence') {
+            const e = 0.05;
+            const s = (f.seed ?? 0) >>> 0;
+            const x = px * f.frequency;
+            const y = py * f.frequency;
+            const z = pz * f.frequency;
+            const dzdy = vnoise(x, y + e, z, s + 2) - vnoise(x, y - e, z, s + 2);
+            const dydz = vnoise(x, y, z + e, s + 1) - vnoise(x, y, z - e, s + 1);
+            const dxdz = vnoise(x, y, z + e, s) - vnoise(x, y, z - e, s);
+            const dzdx = vnoise(x + e, y, z, s + 2) - vnoise(x - e, y, z, s + 2);
+            const dydx = vnoise(x + e, y, z, s + 1) - vnoise(x - e, y, z, s + 1);
+            const dxdy = vnoise(x, y + e, z, s) - vnoise(x, y - e, z, s);
+            const k = f.strength / (2 * e);
+            ax += (dzdy - dydz) * k;
+            ay += (dxdz - dzdx) * k;
+            az += (dydx - dxdy) * k;
+        }
+        else {
+            drag += f.amount;
+        }
+    }
+    const damp = Math.exp(-drag * dt);
+    vel[0] = (vel[0] + ax * dt) * damp;
+    vel[1] = (vel[1] + ay * dt) * damp;
+    if (vel.length > 2)
+        vel[2] = (vel[2] + az * dt) * damp;
+}
+/**
+ * Continuous emission at `rate` particles/second, plus bursts. Mutate `params` freely. With
+ * `random` the emitter's spawn seeds come from that stream instead of the system's (ws/fx-4).
+ */
+export class ParticleEmitter {
+    system;
+    params;
+    rate;
+    active = true;
+    /** Live: the stream this emitter's emits draw from; null uses the system's `random`. */
+    random;
+    carry = 0;
+    constructor(system, params, rate = 0, random) {
+        this.system = system;
+        this.params = params;
+        this.rate = rate;
+        this.random = random ?? null;
+    }
+    update(dt) {
+        if (!this.active || this.rate <= 0)
+            return;
+        this.carry += this.rate * dt;
+        const n = Math.floor(this.carry);
+        if (n > 0) {
+            this.carry -= n;
+            this.system.emit(this.params, n, this.random ?? this.system.random);
+        }
+    }
+    burst(count, overrides) {
+        this.system.emit(overrides ? { ...this.params, ...overrides } : this.params, count, this.random ?? this.system.random);
+    }
+}