@driftengine/core 4.10.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/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/motionPass.js

@@ -197,12 +197,17 @@ export class MotionPass {
         const eight = offsets.joints2 >= 0 && offsets.weights2 >= 0;
         /*
          * Five byte counts, each under 256 because a vertex is at most 172 bytes, as five base-256
-         * digits: exact below 2^40, so two layouts can never share a key.
+         * digits, and two bits for the weights' formats: exact below 2^42, so two layouts can never
+         * share a key.
          */
-        const key = (((stride * 256 + offsets.joints) * 256 + offsets.weights) * 256 + offsets.joints2 + 1) *
+        const key = ((((stride * 256 + offsets.joints) * 256 + offsets.weights) * 256 + offsets.joints2 + 1) *
             256 +
             offsets.weights2 +
-            1;
+            1) *
+            4 +
+            /* And whether each four weights are floats or fixed point, two bits: `vertexPacking.ts`. */
+            (offsets.weightsFormat === 'float32x4' ? 0 : 2) +
+            (offsets.weights2Format === 'float32x4' ? 0 : 1);
         const pipelines = cloth ? this.clothPipelines : this.skinnedPipelines;
         const held = pipelines.get(key);
         if (held !== undefined)
@@ -224,11 +229,15 @@ export class MotionPass {
                         attributes: [
                             { shaderLocation: 0, offset: 0, format: 'float32x3' },
                             { shaderLocation: 11, offset: offsets.joints, format: 'float32x4' },
-                            { shaderLocation: 12, offset: offsets.weights, format: 'float32x4' },
+                            { shaderLocation: 12, offset: offsets.weights, format: offsets.weightsFormat },
                             ...(eight
                                 ? [
                                     { shaderLocation: 14, offset: offsets.joints2, format: 'float32x4' },
-                                    { shaderLocation: 15, offset: offsets.weights2, format: 'float32x4' },
+                                    {
+                                        shaderLocation: 15,
+                                        offset: offsets.weights2,
+                                        format: offsets.weights2Format,
+                                    },
                                 ]
                                 : []),
                         ],
@@ -570,7 +579,7 @@ export class MotionPass {
                 }
                 pass.setBindGroup(0, this.group, [i * MOTION_DRAW_STRIDE]);
                 pass.setVertexBuffer(0, mesh.vertexBuffers[0]);
-                pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
+                pass.setIndexBuffer(mesh.indexBuffer, mesh.indexFormat);
                 pass.drawIndexed(mesh.indexCount, instances);
             }
         }

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

@@ -79,6 +79,15 @@ export declare class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     private readonly compiling;
+    /** Keys whose compile off the main thread failed, which `lit` then builds where asked for. */
+    private readonly failed;
+    /**
+     * Whether a lit pipeline first asked for inside a frame is compiled off the main thread while
+     * its draw is left out — `RenderQuality.pipelineCompile` `'skip'` — rather than built where it is
+     * asked for, which holds the GPU process for the compile. The renderer turns it off while it
+     * records static draws, which must hold every draw they were given.
+     */
+    skipsCompiling: boolean;
     constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number, glassShadows?: boolean, 
     /** The profile's `clusteredLights`, which compiles the clustered arm in or leaves it out. */
     clusteredLights?: boolean);
@@ -96,7 +105,8 @@ export declare class PipelineCache {
     /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
     lit?: boolean): Promise<GPURenderPipeline>;
     /**
-     * Resolve once every pipeline asked for so far has finished compiling.
+     * Resolve once every pipeline asked for so far has finished compiling, a switch's rebuild
+     * among them.
      *
      * A renderer awaits this before its first frame, which is what moves the compile out of the
      * queue and in front of it. A failure is not rethrown: a pipeline that cannot be built will
@@ -118,6 +128,17 @@ export declare class PipelineCache {
     get(key: string, describe: () => GPURenderPipelineDescriptor, 
     /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
     lit?: boolean): GPURenderPipeline;
+    /**
+     * A lit pipeline for a draw inside a frame: the one built, or one built here — or, where draws
+     * skip (`skipsCompiling`), none, with its compile started off the main thread for a later frame to
+     * find. A draw handed none is left out.
+     *
+     * **What skipping gives up** is the draw for the frames its compile takes, a few to a few dozen on
+     * a phone, against a frame held for the compile where it is asked for: 130 to 400 ms, reported on
+     * a phone for a material first drawn mid-scene. A compile that fails is built here the next time,
+     * so the device reports it rather than the draw vanishing for good.
+     */
+    lit(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline | null;
     /**
      * Turn one of the lit stage's switches on, for every lit pipeline built from now on and every one
      * already built. See `litSwitches`.

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

@@ -78,6 +78,15 @@ export class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     compiling = new Map();
+    /** Keys whose compile off the main thread failed, which `lit` then builds where asked for. */
+    failed = new Set();
+    /**
+     * Whether a lit pipeline first asked for inside a frame is compiled off the main thread while
+     * its draw is left out — `RenderQuality.pipelineCompile` `'skip'` — rather than built where it is
+     * asked for, which holds the GPU process for the compile. The renderer turns it off while it
+     * records static draws, which must hold every draw they were given.
+     */
+    skipsCompiling = false;
     constructor(device, format, sampleCount = 1, glassShadows = true, 
     /** The profile's `clusteredLights`, which compiles the clustered arm in or leaves it out. */
     clusteredLights = false) {
@@ -127,12 +136,19 @@ export class PipelineCache {
                 this.pipelines.set(key, built);
             this.compiling.delete(key);
             return built;
+        }, 
+        /* Out of the list, or `ready` waits on it for ever; `lit` builds it where asked next. */
+        (error) => {
+            this.compiling.delete(key);
+            this.failed.add(key);
+            throw error;
         });
         this.compiling.set(key, promise);
         return promise;
     }
     /**
-     * Resolve once every pipeline asked for so far has finished compiling.
+     * Resolve once every pipeline asked for so far has finished compiling, a switch's rebuild
+     * among them.
      *
      * A renderer awaits this before its first frame, which is what moves the compile out of the
      * queue and in front of it. A failure is not rethrown: a pipeline that cannot be built will
@@ -143,6 +159,8 @@ export class PipelineCache {
         while (this.compiling.size > 0) {
             await Promise.allSettled([...this.compiling.values()]);
         }
+        /* And a switch's rebuild, whose set replaces the pipelines in one swap: see `enable`. */
+        await this.litRebuild;
     }
     /** The pipeline for this key if it is already built, without building one. */
     peek(key) {
@@ -171,6 +189,26 @@ export class PipelineCache {
         this.pipelines.set(key, built);
         return built;
     }
+    /**
+     * A lit pipeline for a draw inside a frame: the one built, or one built here — or, where draws
+     * skip (`skipsCompiling`), none, with its compile started off the main thread for a later frame to
+     * find. A draw handed none is left out.
+     *
+     * **What skipping gives up** is the draw for the frames its compile takes, a few to a few dozen on
+     * a phone, against a frame held for the compile where it is asked for: 130 to 400 ms, reported on
+     * a phone for a material first drawn mid-scene. A compile that fails is built here the next time,
+     * so the device reports it rather than the draw vanishing for good.
+     */
+    lit(key, describe) {
+        const existing = this.pipelines.get(key);
+        if (existing !== undefined)
+            return existing;
+        if (!this.skipsCompiling || this.failed.has(key))
+            return this.get(key, describe, true);
+        if (!this.compiling.has(key))
+            void this.getAsync(key, describe, true).catch(() => { });
+        return null;
+    }
     /**
      * Turn one of the lit stage's switches on, for every lit pipeline built from now on and every one
      * already built. See `litSwitches`.

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

@@ -75,7 +75,7 @@ export declare const AO_FRAG_SIZE: 96;
 export declare const AO_BLUR_FIELDS: UniformFields;
 export declare const AO_BLUR_SIZE: 48;
 export declare const MEDIUM_FRAG_FIELDS: UniformFields;
-export declare const MEDIUM_FRAG_SIZE: 240;
+export declare const MEDIUM_FRAG_SIZE: 304;
 export declare const MEDIUM_UPSAMPLE_FIELDS: UniformFields;
 export declare const MEDIUM_UPSAMPLE_SIZE: 32;
 export declare const BLOOM_PREFILTER_FIELDS: UniformFields;