@driftengine/core 4.9.0 → 4.11.0

package/dist/render/backend/webgpu/gpuClothSet.js

@@ -0,0 +1,462 @@
+/**
+ * Skinned cloth solved on the device, a set of garments at a time: `ClothControl`'s schedule for
+ * each garment, over one set of buffers, in one compute pass and one submit a frame.
+ *
+ * **The CPU solver's steps, as dispatches.** A step is `clothBegin`, then per substep
+ * `clothPredict`, every colour of every kind of constraint per iteration, `clothLimit` and
+ * `clothFinish`; then `clothBlend` while a reset blends back in. The particles never leave the
+ * device: a frame ends with `clothPublish` writing each garment's, at the frame's `alpha`, into the
+ * particle texture its bound meshes' vertex stage reads — so a garment costs no upload a frame.
+ *
+ * **A round is one kind of work for every garment that has it next.** Each garment's control asks
+ * for poses, resets and steps as it always did; they wait in its queue (`clothOps.ts`) until the
+ * set records them a round at a time — the poses of every garment with a pose next, in one
+ * dispatch, then the rests, then a step for every garment with a step next, each colour of each kind
+ * one dispatch across the set (`clothSetPack.ts`). A garment with nothing of that kind sits the round
+ * out. So a step costs one garment's dispatches whatever the set holds: fifteen garments of nine
+ * colours at four iterations are about a hundred a step, where a pass a garment was some fourteen
+ * hundred.
+ *
+ * **One submit a frame, everything it needs written before it.** `queue.writeBuffer` lands ahead of
+ * the whole submit rather than between two dispatches, which is the trap `AGENTS.md` (2026-08-27)
+ * records for draws and is no different here. So every round's records take a slot of their own, a
+ * frame that runs out of slots submits what it has and goes on, and a garment posed while work
+ * against its last pose is still unsent sends that work first, since its matrices are one region.
+ *
+ * **What it gives up**: single precision; a colour dispatched over the most records any garment has
+ * in it; and garments of one set step together, so they share a step, substeps, iterations and most
+ * steps a frame, refused by name otherwise. Self-collision is accepted and not simulated, as on the
+ * CPU.
+ */
+import { ClothControl, exactExp, validateClothSetup } from '@driftengine/physics';
+import { clothKernelsFor } from './clothKernels.js';
+import { CLOTH_OP_POSE, CLOTH_OP_REST, CLOTH_OP_STEP, ClothOps, PACE_HEAD_WORDS, PACE_WORDS, } from './clothOps.js';
+import { CLOTH_CONSTANT_BYTES, clothBatchSlots, clothConstants, clothRoundOffsets, writeClothCarry, } from './clothSetLayout.js';
+import { packClothSet } from './clothSetPack.js';
+import { packCloth } from './clothSolvePack.js';
+import { GpuClothParticles } from './clothTextures.js';
+import { CLOTH_WORKGROUP } from './shaders/clothSolve.wgsl.js';
+import { DYNAMIC_ALIGNMENT } from './uniformRing.js';
+const STORAGE = 0x80;
+const UNIFORM = 0x40;
+const COPY_DST = 0x8;
+const COPY_SRC = 0x4;
+const MAP_READ = 0x1;
+/** Rounds a submit holds before it is sent and the slots start again. */
+const ROUNDS = 64;
+const KINDS = [CLOTH_OP_POSE, CLOTH_OP_REST, CLOTH_OP_STEP];
+export class GpuClothSet {
+    device;
+    garments = [];
+    packed;
+    kernels;
+    buffers = [];
+    state;
+    frameData;
+    paces;
+    group;
+    /** One round's records, every garment's: the head an op's, the rest each garment's own. */
+    staging;
+    stagingWords;
+    stagingFloats;
+    /** Each kind's first batch slot, and the first garment's publishing slot. */
+    batchSlot;
+    groups;
+    substeps;
+    iterations;
+    encoder = null;
+    pass = null;
+    round = 0;
+    constructor(device, setups) {
+        this.device = device;
+        if (setups.length === 0)
+            throw new Error('skinned cloth set: no garments');
+        for (const setup of setups)
+            validateClothSetup(setup);
+        const packed = packClothSet(setups.map(packCloth));
+        this.packed = packed;
+        const n = packed.count;
+        const count = setups.length;
+        this.kernels = clothKernelsFor(device);
+        this.groups = Math.ceil(n / CLOTH_WORKGROUP);
+        const buffer = (label, bytes, usage) => {
+            const made = device.createBuffer({
+                label: `cloth.${label}`,
+                size: Math.max(16, bytes),
+                usage,
+            });
+            this.buffers.push(made);
+            return made;
+        };
+        this.staging = new ArrayBuffer(count * PACE_WORDS * 4);
+        this.stagingWords = new Uint32Array(this.staging);
+        this.stagingFloats = new Float32Array(this.staging);
+        setups.forEach((setup, g) => this.garments.push(this.garment(setup, g)));
+        const first = this.garments[0].control.parameters;
+        this.substeps = first.substeps;
+        this.iterations = first.iterations;
+        this.refuseStrangers(first);
+        const constants = buffer('constants', CLOTH_CONSTANT_BYTES, UNIFORM | COPY_DST);
+        const rounds = buffer('rounds', ROUNDS * DYNAMIC_ALIGNMENT, UNIFORM | COPY_DST);
+        this.paces = buffer('paces', ROUNDS * this.staging.byteLength, STORAGE | COPY_DST);
+        const batchWords = clothBatchSlots(packed);
+        const batches = buffer('batches', batchWords.byteLength, UNIFORM | COPY_DST);
+        this.state = buffer('state', n * 12 * 4, STORAGE | COPY_DST | COPY_SRC);
+        const pose = buffer('pose', n * 9 * 4, STORAGE);
+        const statics = buffer('statics', packed.statics.byteLength, STORAGE | COPY_DST);
+        const constraints = buffer('constraints', packed.constraints.byteLength, STORAGE | COPY_DST);
+        const lambda = buffer('lambda', (packed.distances + packed.bendings) * 4, STORAGE);
+        this.frameData = buffer('frame', (packed.joints * 16 + packed.colliders * 8) * 4, STORAGE | COPY_DST);
+        const queue = device.queue;
+        queue.writeBuffer(constants, 0, clothConstants(packed, first.step / first.substeps));
+        queue.writeBuffer(rounds, 0, clothRoundOffsets(ROUNDS, count));
+        queue.writeBuffer(batches, 0, batchWords);
+        queue.writeBuffer(statics, 0, packed.statics);
+        if (packed.constraints.byteLength > 0) {
+            queue.writeBuffer(constraints, 0, packed.constraints);
+        }
+        /* The rest pose until the first pose, which resets each garment to its own. */
+        const state = new Float32Array(n * 12);
+        setups.forEach((setup, g) => {
+            const base = this.garments[g].range.particleBase * 3;
+            state.set(setup.positions, base);
+            state.set(setup.positions, n * 9 + base);
+        });
+        queue.writeBuffer(this.state, 0, state);
+        const slot = (of) => ({ buffer: of, size: DYNAMIC_ALIGNMENT });
+        this.group = device.createBindGroup({
+            label: 'cloth.solve',
+            layout: this.kernels.layout,
+            entries: [
+                { binding: 0, resource: { buffer: constants } },
+                { binding: 1, resource: slot(rounds) },
+                { binding: 2, resource: slot(batches) },
+                { binding: 3, resource: { buffer: this.state } },
+                { binding: 4, resource: { buffer: pose } },
+                { binding: 5, resource: { buffer: statics } },
+                { binding: 6, resource: { buffer: constraints } },
+                { binding: 7, resource: { buffer: lambda } },
+                { binding: 8, resource: { buffer: this.frameData } },
+                { binding: 9, resource: { buffer: this.paces } },
+            ],
+        });
+        const colours = (batches) => (batches.length - 1) * 2;
+        this.batchSlot = {
+            distance: 0,
+            bending: colours(packed.distanceBatches),
+            tether: colours(packed.distanceBatches) + colours(packed.bendingBatches),
+            publish: colours(packed.distanceBatches) +
+                colours(packed.bendingBatches) +
+                colours(packed.tetherBatches),
+        };
+    }
+    /** How many garments the set holds. */
+    get size() {
+        return this.garments.length;
+    }
+    /** Garment `g`'s particles, what `setCloth` draws its bound meshes by. */
+    particles(g) {
+        return this.at(g).particles;
+    }
+    /** Garment `g`'s rig for the steps to come; see `ClothControl.setPose`. */
+    setPose(g, globals, model) {
+        this.at(g).control.setPose(globals, model);
+    }
+    /** The frame's sample of the scene's wind for garment `g`. See `SkinnedCloth.setWind`. */
+    setWind(g, x, y, z) {
+        const wind = this.at(g).wind;
+        wind[0] = x;
+        wind[1] = y;
+        wind[2] = z;
+    }
+    /** Garment `g` back to its skinned pose, settled; the next `step` publishes it. */
+    reset(g) {
+        this.at(g).control.reset();
+    }
+    /**
+     * `dt` of the caller's time in whole fixed steps for every garment, and each garment's particles
+     * at its `alpha` published for the draws that follow, as the particles of `frame`.
+     */
+    step(dt, frame) {
+        const garments = this.garments;
+        for (let g = 0; g < garments.length; g++)
+            garments[g].control.advance(dt);
+        this.run();
+        const at = this.takeRound();
+        for (let g = 0; g < garments.length; g++) {
+            const base = g * PACE_WORDS;
+            const garment = garments[g];
+            this.stagingWords.fill(0, base, base + PACE_HEAD_WORDS);
+            this.stagingFloats[base + 2] = garment.control.alpha;
+            this.stagingFloats.set(garment.wind, base + 28);
+        }
+        this.device.queue.writeBuffer(this.paces, this.paceOffset(at), this.staging);
+        for (let g = 0; g < garments.length; g++) {
+            const garment = garments[g];
+            const view = garment.particles.publish(frame);
+            const slot = (this.batchSlot.publish + g) * DYNAMIC_ALIGNMENT;
+            const groups = Math.ceil(garment.range.count / CLOTH_WORKGROUP);
+            this.dispatch('clothPublish', at, slot, garment.outputs[view], groups);
+        }
+        this.flush();
+    }
+    /**
+     * Garment `g`'s particles where its last step left them, three floats each: for the parity check,
+     * which compares them with the CPU solver's positions. Not for a frame — it waits on the device.
+     */
+    async read(g) {
+        this.run();
+        this.flush();
+        const { particleBase, count } = this.at(g).range;
+        const bytes = count * 12;
+        const readback = this.device.createBuffer({
+            label: 'cloth.readback',
+            size: bytes,
+            usage: MAP_READ | COPY_DST,
+        });
+        const encoder = this.device.createCommandEncoder({ label: 'cloth.read' });
+        encoder.copyBufferToBuffer(this.state, particleBase * 12, readback, 0, bytes);
+        this.device.queue.submit([encoder.finish()]);
+        await readback.mapAsync(MAP_READ);
+        const out = new Float32Array(readback.getMappedRange().slice(0));
+        readback.unmap();
+        readback.destroy();
+        return out;
+    }
+    /** Its buffers; the particle textures are the renderer's to retire with the frame. */
+    dispose() {
+        this.flush();
+        for (const made of this.buffers)
+            made.destroy();
+    }
+    at(g) {
+        const garment = this.garments[g];
+        if (garment === undefined)
+            throw new Error(`skinned cloth set: no garment ${g}`);
+        return garment;
+    }
+    /** Garment `g`: its schedule over a device that queues, its particles and its own numbers. */
+    garment(setup, g) {
+        const range = this.packed.garments[g];
+        const particles = new GpuClothParticles(this.device, range.count, true);
+        const ops = new ClothOps();
+        const solver = {
+            targetsChanged: (change) => this.targetsChanged(garment, change),
+            rest: () => this.queueOp(garment, CLOTH_OP_REST),
+            step: (fraction, blend) => this.queueStep(garment, fraction, blend),
+        };
+        const control = new ClothControl(setup, solver, false);
+        const output = (k) => this.device.createBindGroup({
+            label: 'cloth.publish',
+            layout: this.kernels.outputLayout,
+            entries: [{ binding: 0, resource: particles.viewOf(k) }],
+        });
+        const garment = {
+            range,
+            control,
+            particles,
+            ops,
+            wind: new Float32Array(control.parameters.wind),
+            outputs: [output(0), output(1)],
+            fromAt: 0,
+            toAt: 0,
+            recorded: false,
+        };
+        this.writeOwn(garment, g);
+        return garment;
+    }
+    /**
+     * A garment's own words of its record, which every round carries: its colliders, its texture's
+     * width and its constants. Its limits ride in the head beside `live`, written as it joins a round.
+     */
+    writeOwn(garment, g) {
+        const p = garment.control.parameters;
+        const h = p.step / p.substeps;
+        const base = g * PACE_WORDS;
+        const u = this.stagingWords;
+        const f = this.stagingFloats;
+        u[base + 32] = garment.range.colliderBase;
+        u[base + 33] = garment.range.colliders;
+        u[base + 34] = garment.particles.width;
+        f[base + 36] = exactExp(p.damping * h);
+        f[base + 37] = exactExp(p.drag * h);
+        f[base + 38] = p.maxDistanceScale;
+        f[base + 39] = p.margin;
+        f.set(p.gravity, base + 40);
+    }
+    /** Garments that cannot step together, refused by the first number they disagree on. */
+    refuseStrangers(first) {
+        this.garments.forEach((garment, g) => {
+            const p = garment.control.parameters;
+            for (const name of ['step', 'substeps', 'iterations', 'maxSteps']) {
+                if (p[name] !== first[name]) {
+                    throw new Error(`skinned cloth set: garment ${g} has ${name} ${p[name]} where garment 0 has ` +
+                        `${first[name]}; a set steps its garments together, so they must agree`);
+                }
+            }
+        });
+    }
+    targetsChanged(garment, change) {
+        if (change !== 'posed') {
+            garment.fromAt = garment.toAt;
+            return;
+        }
+        /*
+         * The pose's matrices and colliders are written ahead of the next submit, so any work of this
+         * garment's still waiting or recorded — a reset's settle steps, which read the colliders — is
+         * sent first, or it would run against this pose rather than its own.
+         */
+        if (garment.ops.pending > 0 || garment.recorded) {
+            this.run();
+            this.flush();
+        }
+        this.writeFrameData(garment);
+        garment.fromAt = garment.toAt;
+        garment.toAt = garment.toAt === 0 ? this.packed.count * 3 : 0;
+        this.queueOp(garment, CLOTH_OP_POSE);
+    }
+    queueOp(garment, kind) {
+        const at = garment.ops.push(kind);
+        const words = garment.ops.headWords;
+        words[at + 4] = garment.fromAt;
+        words[at + 5] = garment.toAt;
+        garment.ops.headFloats.set(garment.wind, at + 28);
+        return at;
+    }
+    queueStep(garment, fraction, blend) {
+        const at = this.queueOp(garment, CLOTH_OP_STEP);
+        const f = garment.ops.headFloats;
+        f[at] = fraction;
+        f[at + 1] = blend;
+        const { parameters, targets } = garment.control;
+        writeClothCarry(parameters, targets.modelBefore, targets.modelNow, garment.ops.headWords, f, at);
+    }
+    /** Every op every garment is waiting on, a round of one kind at a time, in each garment's order. */
+    run() {
+        for (;;) {
+            let ran = false;
+            for (let k = 0; k < KINDS.length; k++) {
+                const kind = KINDS[k];
+                if (this.waiting(kind)) {
+                    this.runRound(kind);
+                    ran = true;
+                }
+            }
+            if (!ran)
+                return;
+        }
+    }
+    /** Whether any garment has `kind` next. */
+    waiting(kind) {
+        for (let g = 0; g < this.garments.length; g++) {
+            if (this.garments[g].ops.next === kind)
+                return true;
+        }
+        return false;
+    }
+    /** One round: every garment with `kind` next takes part, and the rest sit it out. */
+    runRound(kind) {
+        const at = this.takeRound();
+        const words = this.stagingWords;
+        let blends = false;
+        for (let g = 0; g < this.garments.length; g++) {
+            const garment = this.garments[g];
+            const base = g * PACE_WORDS;
+            words.fill(0, base, base + PACE_HEAD_WORDS);
+            if (garment.ops.next !== kind)
+                continue;
+            garment.ops.take(words, base);
+            words[base + 6] = 1;
+            words[base + 7] = garment.range.limits;
+            garment.recorded = true;
+            if (this.stagingFloats[base + 1] > 0)
+                blends = true;
+        }
+        this.device.queue.writeBuffer(this.paces, this.paceOffset(at), this.staging);
+        if (kind === CLOTH_OP_POSE)
+            this.dispatch('clothPose', at, 0, null);
+        else if (kind === CLOTH_OP_REST)
+            this.dispatch('clothRest', at, 0, null);
+        else
+            this.stepRound(at, blends);
+    }
+    stepRound(at, blends) {
+        this.dispatch('clothBegin', at, 0, null);
+        const { distanceBatches, bendingBatches, tetherBatches } = this.packed;
+        for (let s = 0; s < this.substeps; s++) {
+            this.dispatch('clothPredict', at, 0, null);
+            for (let pass = 0; pass < this.iterations; pass++) {
+                const first = pass === 0 ? 1 : 0;
+                this.batches('clothDistance', distanceBatches, this.batchSlot.distance, first, at);
+                this.batches('clothBending', bendingBatches, this.batchSlot.bending, first, at);
+                this.batches('clothTether', tetherBatches, this.batchSlot.tether, first, at);
+            }
+            this.dispatch('clothLimit', at, 0, null);
+            this.dispatch('clothFinish', at, 0, null);
+        }
+        if (blends)
+            this.dispatch('clothBlend', at, 0, null);
+    }
+    /** Every colour of one kind across the set, in colour order, each a dispatch over its range. */
+    batches(entry, batches, firstSlot, first, roundAt) {
+        for (let b = 0; b + 1 < batches.length; b++) {
+            const size = batches[b + 1] - batches[b];
+            if (size === 0)
+                continue;
+            const slot = firstSlot + b * 2 + first;
+            this.dispatch(entry, roundAt, slot * DYNAMIC_ALIGNMENT, null, Math.ceil(size / CLOTH_WORKGROUP));
+        }
+    }
+    dispatch(entry, roundAt, batchAt, output, groups = this.groups) {
+        const pass = this.passFor();
+        pass.setPipeline(this.kernels.pipelines[entry]);
+        pass.setBindGroup(0, this.group, [roundAt, batchAt]);
+        if (output !== null)
+            pass.setBindGroup(1, output);
+        pass.dispatchWorkgroups(groups);
+    }
+    passFor() {
+        if (this.pass === null) {
+            this.encoder = this.device.createCommandEncoder({ label: 'cloth' });
+            this.pass = this.encoder.beginComputePass({ label: 'cloth' });
+        }
+        return this.pass;
+    }
+    /** A round's slot, sending what is recorded first where the slots are spent: its byte offset. */
+    takeRound() {
+        if (this.round === ROUNDS)
+            this.flush();
+        return this.round++ * DYNAMIC_ALIGNMENT;
+    }
+    /** Where the records of the round at `roundAt` sit in `paces`. */
+    paceOffset(roundAt) {
+        return (roundAt / DYNAMIC_ALIGNMENT) * this.staging.byteLength;
+    }
+    /** Send what has been recorded: every slot it reads was written ahead of it on the queue. */
+    flush() {
+        const { pass, encoder } = this;
+        if (pass === null || encoder === null)
+            return;
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        this.pass = null;
+        this.encoder = null;
+        this.round = 0;
+        for (let g = 0; g < this.garments.length; g++)
+            this.garments[g].recorded = false;
+    }
+    /** A garment's skin matrices — or its model, with no rig — and its colliders, into the set's. */
+    writeFrameData(garment) {
+        const targets = garment.control.targets;
+        const { jointBase, joints, colliderBase, colliders, rigged } = garment.range;
+        const queue = this.device.queue;
+        const matrices = (rigged && targets.skin !== null ? targets.skin : targets.model);
+        queue.writeBuffer(this.frameData, jointBase * 64, matrices, 0, joints * 16);
+        if (colliders === 0)
+            return;
+        const ends = this.packed.joints * 16;
+        const radii = ends + this.packed.colliders * 6;
+        queue.writeBuffer(this.frameData, (ends + colliderBase * 6) * 4, targets.colliderEnds, 0, colliders * 6);
+        queue.writeBuffer(this.frameData, (radii + colliderBase * 2) * 4, targets.colliderRadii, 0, colliders * 2);
+    }
+}

package/dist/render/backend/webgpu/instanced.d.ts

@@ -1,6 +1,7 @@
 import type { CullSlot } from './instanceCullPass.ts';
 import type { MeshInstances } from '../../instances.ts';
 import type { GpuMesh } from './buffers.ts';
+import { GpuInstanceClocks, type GpuBoneAnimation } from './boneAnimations.ts';
 /**
  * One mesh's per-instance buffer on the device.
  *
@@ -25,7 +26,19 @@ export declare class GpuInstancedBatch {
     /** The frame the slots were last taken in, and how many were taken. */
     slotFrame: number;
     slotsTaken: number;
-    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull?: boolean);
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    readonly animation: GpuBoneAnimation | null;
+    readonly clocks: GpuInstanceClocks | null;
+    /**
+     * An animated batch's own groups — its lit twins by the material group they were built beside, its
+     * shadow groups by what they cut with — and the renderer's group epoch they were built in, after
+     * which every one is dropped. See `WebGPURenderer.animatedGroup`.
+     */
+    readonly litGroups: Map<GPUBindGroup, GPUBindGroup>;
+    readonly depthGroups: Map<unknown, GPUBindGroup>;
+    readonly depthPeelGroups: Map<unknown, GPUBindGroup>;
+    groupEpoch: number;
+    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull?: boolean, animation?: GpuBoneAnimation | null);
     /** Last frame's packed slots, for a reconstruction; made on first use by the renderer. */
     previousBuffer: GPUBuffer | null;
     /** How many slots the upload before the last one held, and how many the last one holds. */

package/dist/render/backend/webgpu/instanced.js

@@ -1,6 +1,8 @@
 import { instancesBox } from '../../instanceCull.js';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.js';
 import { destroySlot } from './instanceCullPass.js';
+import { packInstanceClocks } from '../../boneAnimation.js';
+import { GpuInstanceClocks } from './boneAnimations.js';
 /** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
 const USAGE_VERTEX = 0x0020 | 0x0008;
 /** A culling batch's source is read by the cull as storage too. */
@@ -29,10 +31,26 @@ export class GpuInstancedBatch {
     /** The frame the slots were last taken in, and how many were taken. */
     slotFrame = -1;
     slotsTaken = 0;
-    constructor(device, mesh, capacity, label, cull = false) {
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    animation;
+    clocks;
+    /**
+     * An animated batch's own groups — its lit twins by the material group they were built beside, its
+     * shadow groups by what they cut with — and the renderer's group epoch they were built in, after
+     * which every one is dropped. See `WebGPURenderer.animatedGroup`.
+     */
+    litGroups = new Map();
+    depthGroups = new Map();
+    depthPeelGroups = new Map();
+    groupEpoch = -1;
+    constructor(device, mesh, capacity, label, cull = false, animation = null) {
         this.mesh = mesh;
         this.capacity = capacity;
+        /* An animated batch is culled whole and never by instance: see `submitInstanced`. */
         this.cull = cull;
+        this.animation = animation;
+        this.clocks =
+            animation === null ? null : new GpuInstanceClocks(device, capacity, `${label}.clocks`);
         this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
         this.buffer = device.createBuffer({
             /*
@@ -76,10 +94,15 @@ export class GpuInstancedBatch {
             return;
         packInstances(data, this.staging);
         queue.writeBuffer(this.buffer, 0, this.staging, 0, count * INSTANCE_FLOATS);
+        if (this.clocks !== null) {
+            packInstanceClocks(data, this.clocks.staging);
+            this.clocks.upload(queue, count);
+        }
     }
     dispose() {
         this.previousBuffer?.destroy();
         this.buffer.destroy();
+        this.clocks?.dispose();
         for (const slot of this.slots)
             destroySlot(slot);
     }

package/dist/render/backend/webgpu/latePass.js

@@ -111,6 +111,7 @@ export class LatePass {
         command.offsetCount = 0;
         command.vertexCount = 0;
         command.indexBuffer = null;
+        command.indexFormat = 'uint32';
         command.indexed = false;
         command.instances = 1;
         command.indirect = null;

package/dist/render/backend/webgpu/materialStore.d.ts

@@ -0,0 +1,101 @@
+import type { BudgetCounter } from '../budget.ts';
+/**
+ * The lit stage's material blocks, each kept in its slot for as long as later draws ask for the
+ * same numbers, so a material that has not changed since the last frame costs no upload at all.
+ *
+ * **Keyed by content, because nothing else names a material.** A material here is whatever the
+ * setters left in the block when a draw took it — a consumer never hands over an object that could
+ * carry an identity — so the block's own words are the key: hashed to find a bucket, compared word
+ * for word to accept a match, and bound by the slot's offset. What it gives up is a hash and a
+ * compare of a few hundred bytes per material change, against copying and uploading the whole
+ * block every frame, which a stage of four hundred materials measured at megabytes a frame.
+ *
+ * **A slot the frame has asked for is never given away within it**, for the reason `UniformRing`
+ * exists: a queue write does not interleave with recorded draws, so rewriting a slot a recorded draw
+ * reads would hand that draw the new numbers. A frame asking for more distinct blocks than there are
+ * slots is refused, counted and skipped, as the ring was. Across frames rewriting is safe, because a
+ * write issued after a submit is ordered after the commands in it.
+ *
+ * **What a new block displaces is a slot nobody asked for this frame or the last**, found by a hand
+ * that sweeps the slots in turn; only when every slot was asked for recently does it take one the
+ * last frame used. What would make that wrong is a scene whose distinct materials a frame approach
+ * the store's size: it then rewrites some of its steady materials every frame, which costs their
+ * upload and nothing else.
+ */
+export declare class MaterialStore {
+    private readonly device;
+    private readonly usage;
+    private readonly label;
+    private readonly budget;
+    /** Replaced by `growTo`, so every bind group over it is rebuilt when that says so. */
+    buffer: GPUBuffer;
+    /** Bytes per slot, rounded up to the alignment a dynamic offset requires. */
+    readonly slotSize: number;
+    private readonly words;
+    private readonly stride;
+    private capacity;
+    private staging;
+    private ints;
+    /** Per slot: its block's hash, the next slot in its bucket or -1, and whether it holds one. */
+    private hashes;
+    private next;
+    private held;
+    /** Per slot: the frame that last asked for it, and whether it was written since the last flush. */
+    private askedIn;
+    private pending;
+    /** Per slot: how many holders pinned it. A pinned slot is never displaced. */
+    private pins;
+    /**
+     * How many times the store has forgotten everything it held, which growth does: a holder of an
+     * offset compares this, because an offset from before is a slot of a buffer that is gone.
+     */
+    epoch: number;
+    /** Per bucket: its first slot, or -1. A power of two at least twice the slots. */
+    private heads;
+    private mask;
+    private lowPending;
+    private highPending;
+    private hand;
+    /** Starts past zero, so a slot never asked for reads as long unasked. */
+    private frame;
+    constructor(device: GPUDevice, bytesPerBlock: number, slots: number, usage: number, label?: string, budget?: BudgetCounter | null);
+    /** How many distinct blocks a frame may hold. */
+    get slots(): number;
+    /** Start a frame: every slot the last one asked for may be displaced from here on, last. */
+    beginFrame(): void;
+    /**
+     * The byte offset of a slot holding exactly `block`, written there if no slot did, or null when
+     * every slot is one this frame has asked for. `block` is the whole block, word for word.
+     */
+    place(block: Int32Array): number | null;
+    /** Upload every slot written since the last flush, one write per run of neighbouring slots. */
+    flush(): void;
+    /**
+     * Make room for at least `slots`, forgetting every block held, and say whether the buffer was
+     * replaced. Called where `UniformRing.growTo` is, at a frame's start, for the reasons it gives,
+     * and refused past the same ceiling.
+     */
+    growTo(slots: number): boolean;
+    /**
+     * Keep the block at `offset` where it is until `unpin`: a holder binding it by offset frame after
+     * frame — a list recorded once — whether or not anything asks for it. Counted, so two holders of
+     * one block each let go of their own pin.
+     */
+    pin(offset: number): void;
+    unpin(offset: number): void;
+    dispose(): void;
+    private holds;
+    /**
+     * The slot a new block goes in: the first from the hand nobody asked for this frame or the last,
+     * else the first this frame has not asked for, else none. One sweep at most.
+     */
+    private displace;
+    private unlink;
+}
+/**
+ * MurmurHash3's 32-bit mix over the block's words. Not FNV, whose multiply carries a difference only
+ * upward: the bucket is the hash's low bits, and a material's words are mostly floats, whose low
+ * mantissa bits are zero for every value a person types — 0.5, 1, 2 — so blocks differing only in
+ * those would all have shared one bucket. The compare that follows a match is what decides.
+ */
+export declare function hashWords(block: Int32Array, words: number): number;