@driftengine/core 4.9.0 → 4.10.0

package/dist/render/backend/webgl2/renderer.js

@@ -77,7 +77,7 @@ import { MAX_AREA_LIGHTS } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { equirectToCubeFaces } from '../../equirectToCube.js';
 import { SKY_FRAG, skyVertFor } from '../../shaders/sky.js';
-import { DEPTH_CUTOUT_FRAG, DEPTH_CUTOUT_VERT, DEPTH_FRAG, DEPTH_INSTANCED_CUTOUT_VERT, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
+import { DEPTH_CUTOUT_FRAG, DEPTH_CUTOUT_VERT, DEPTH_FRAG, DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT, DEPTH_INSTANCED_ANIMATED_VERT, DEPTH_INSTANCED_CUTOUT_VERT, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
 import { OCTAHEDRAL_EDGE, PointShadowArray, strideLayers } from '../../pointShadowArray.js';
 import { SunShadowArray } from '../../shadowMap.js';
 import { POINT_SHADOW_SAMPLER, PointShadowSystem } from '../../pointShadowSystem.js';
@@ -85,6 +85,7 @@ import { castsDepth, glassOf } from '../../shadowCasters.js';
 import { GlassCasterList } from '../../glassCasters.js';
 import { SunGlassTint } from '../../sunGlassTint.js';
 import { GlassTintPrograms } from './glassTintPrograms.js';
+import { captureStaticDraws, replayStaticDraws } from '../../staticDraws.js';
 import { FACE_COUNT, PointShadowMap } from '../../pointShadowMap.js';
 import { createResolvedPointShadows, DEFAULT_SOURCE_RADIUS } from '../../pointShadowImage.js';
 import { createBakeScratch, runPointShadowBakes, selectCastingLights, } from '../../pointShadowBudget.js';
@@ -117,6 +118,9 @@ import { DEFAULT_FILMIC_CURVE, FILMIC_CLAMPED, FILMIC_CONSTANTS, FILMIC_WITHOUT_
 import { deviceSnappedCellSize } from '../../textLayout.js';
 import { WindStreakRenderer } from '../../windStreakRenderer.js';
 import { InstancedBatch } from './instanced.js';
+import { GlBoneAnimation } from './boneAnimations.js';
+import { packBoneAnimation } from '../../boneAnimation.js';
+import { BONE_PLACES_TEXTURE_UNIT, BONE_TURNS_TEXTURE_UNIT, INSTANCE_CLOCKS_TEXTURE_UNIT, } from '../../lightBudget.js';
 import { cutoutOf } from '../../cutoutCaster.js';
 import { CUTOUT_RESOLVE_CODE, resolveCutout } from '../../cutoutDither.js';
 import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
@@ -802,6 +806,11 @@ export class WebGL2Renderer {
     depthCutoutUniforms;
     depthInstancedCutoutProgram;
     depthInstancedCutoutUniforms;
+    /** A crowd's casters: the instanced depth programs that play a bone animation. */
+    depthAnimatedProgram;
+    depthAnimatedUniforms;
+    depthAnimatedCutoutProgram;
+    depthAnimatedCutoutUniforms;
     scatterDepthProgram;
     scatterDepthUniforms;
     /** The sun's static, moving and peeled maps, as layers of one array. See `shadowMap.ts`. */
@@ -1205,14 +1214,21 @@ export class WebGL2Renderer {
             const count = Math.min(data.count, gpuBatch.capacity);
             if (count === 0)
                 return;
+            const clip = gpuBatch.animation;
+            if (clip !== null && clip.disposed)
+                return;
             this.shadowDrawBudget.ask();
             const twoSided = material?.doubleSided === true;
             if (twoSided)
                 gl.disable(gl.CULL_FACE);
             const cutout = cutoutOf(material);
             if (cutout !== null) {
-                gl.useProgram(this.depthInstancedCutoutProgram);
-                this.bindCutoutDepth(this.depthInstancedCutoutUniforms, cutout);
+                /* A crowd casts where its clip has moved it, through the animated variant. */
+                const uniforms = clip === null ? this.depthInstancedCutoutUniforms : this.depthAnimatedCutoutUniforms;
+                gl.useProgram(clip === null ? this.depthInstancedCutoutProgram : this.depthAnimatedCutoutProgram);
+                this.bindCutoutDepth(uniforms, cutout);
+                if (clip !== null)
+                    this.bindAnimation(uniforms, gpuBatch);
                 gpuBatch.draw(gl, count);
                 if (twoSided && this.depthPassCullsFaces)
                     gl.enable(gl.CULL_FACE);
@@ -1220,12 +1236,14 @@ export class WebGL2Renderer {
                 this.restoreSurfaceTextureUnit();
                 return;
             }
-            const u = this.depthInstancedUniforms;
-            gl.useProgram(this.depthInstancedProgram);
+            const u = clip === null ? this.depthInstancedUniforms : this.depthAnimatedUniforms;
+            gl.useProgram(clip === null ? this.depthInstancedProgram : this.depthAnimatedProgram);
             gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, this.activeDepthViewProj);
             gl.uniform1i(u['uPeelShadowLayer'] ?? null, this.activeDepthPeel ? 1 : 0);
             if (this.activeDepthPeel)
                 gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
+            if (clip !== null)
+                this.bindAnimation(u, gpuBatch);
             gpuBatch.draw(gl, count);
             if (twoSided && this.depthPassCullsFaces)
                 gl.enable(gl.CULL_FACE);
@@ -2230,10 +2248,15 @@ export class WebGL2Renderer {
         this.depthCutoutUniforms = uniformLocations(gl, this.depthCutoutProgram, 'depth-cutout');
         this.depthInstancedCutoutProgram = compileProgram(gl, DEPTH_INSTANCED_CUTOUT_VERT, DEPTH_CUTOUT_FRAG, 'depth-instanced-cutout');
         this.depthInstancedCutoutUniforms = uniformLocations(gl, this.depthInstancedCutoutProgram, 'depth-instanced-cutout');
+        this.depthAnimatedProgram = compileProgram(gl, DEPTH_INSTANCED_ANIMATED_VERT, DEPTH_FRAG, 'depth-instanced-animated');
+        this.depthAnimatedUniforms = uniformLocations(gl, this.depthAnimatedProgram, 'depth-instanced-animated');
+        this.depthAnimatedCutoutProgram = compileProgram(gl, DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT, DEPTH_CUTOUT_FRAG, 'depth-instanced-animated-cutout');
+        this.depthAnimatedCutoutUniforms = uniformLocations(gl, this.depthAnimatedCutoutProgram, 'depth-instanced-animated-cutout');
         /* The cutout map is always read from the surface unit, which the draw borrows and gives back. */
         for (const [program, uniforms] of [
             [this.depthCutoutProgram, this.depthCutoutUniforms],
             [this.depthInstancedCutoutProgram, this.depthInstancedCutoutUniforms],
+            [this.depthAnimatedCutoutProgram, this.depthAnimatedCutoutUniforms],
         ]) {
             gl.useProgram(program);
             gl.uniform1i(uniforms['uCutoutMap'] ?? null, SURFACE_TEXTURE_UNIT);
@@ -2401,6 +2424,8 @@ export class WebGL2Renderer {
                 this.lightVolumeProgram,
                 this.depthCutoutProgram,
                 this.depthInstancedCutoutProgram,
+                this.depthAnimatedProgram,
+                this.depthAnimatedCutoutProgram,
             ]) {
                 gl.deleteProgram(program);
             }
@@ -2718,7 +2743,7 @@ export class WebGL2Renderer {
     updateSurfaceTexture(texture, source) {
         if (this.contextLost)
             return;
-        texture.update(this.gl, source);
+        texture.update(this.gl, source, this.compressedFormats);
         /* New pixels are a new copy for the overlay's slot: see `SurfaceTexture.flatLayer`. */
         if (texture === this.overlayMaps)
             this.bindOverlayMaps(texture);
@@ -2929,6 +2954,13 @@ export class WebGL2Renderer {
         this.materialDoubleSided = material?.doubleSided === true;
         this.materialHasMaps = materialHasMaps(material);
         this.currentMaterial = material;
+        const reflectivity = material?.reflectivity;
+        const environmentGain = material?.environmentGain;
+        this.materialReflectivity =
+            reflectivity === undefined ? null : Math.min(1, Math.max(0, reflectivity));
+        this.materialEnvironmentGain =
+            environmentGain === undefined ? null : Math.max(0, environmentGain);
+        this.writeEnvironmentDials();
         /* What the blur spreads this skin by: the last material to name a profile says. */
         const model = material?.model;
         warnUnpagedLightmap(model, material?.modelMap);
@@ -2966,7 +2998,8 @@ export class WebGL2Renderer {
         const v = this.cutoutVector;
         v[0] = material?.cutout ?? 0;
         v[1] = CUTOUT_RESOLVE_CODE[this.cutoutResolveNow(material, translucent)];
-        v[2] = this.cutoutFrame;
+        /* z unused: the dither's frame is the pass's, in `uHighlightMin.w`. See `uCutout`. */
+        v[2] = 0;
         /* The material's lighting channels, which the lamps' are compared with. See `uCutout`. */
         v[3] = lightChannelsOf(material?.lightChannels);
         return v;
@@ -3157,8 +3190,22 @@ export class WebGL2Renderer {
     setSurfaceReflectivity(amount) {
         if (this.contextLost)
             return;
+        this.passReflectivity = Math.min(1, Math.max(0, amount));
+        this.writeEnvironmentDials();
+    }
+    /**
+     * The reflectivity and environment gain the setters gave the pass, and the ones the material
+     * set now states, or null where it states none (`SurfaceMaterial.reflectivity`). A draw wears the
+     * material's where it has one and the pass's otherwise.
+     */
+    passReflectivity = 0;
+    passEnvironmentGain = 1;
+    materialReflectivity = null;
+    materialEnvironmentGain = null;
+    writeEnvironmentDials() {
         this.materials.dirty();
-        this.environmentDials[1] = Math.min(1, Math.max(0, amount));
+        this.environmentDials[1] = this.materialReflectivity ?? this.passReflectivity;
+        this.environmentDials[2] = this.materialEnvironmentGain ?? this.passEnvironmentGain;
         this.writeFlatVector('uEnvironmentDials', this.environmentDials);
     }
     /**
@@ -3237,9 +3284,8 @@ export class WebGL2Renderer {
     setEnvironmentGain(gain) {
         if (this.contextLost)
             return;
-        this.materials.dirty();
-        this.environmentDials[2] = Math.max(0, gain);
-        this.writeFlatVector('uEnvironmentDials', this.environmentDials);
+        this.passEnvironmentGain = Math.max(0, gain);
+        this.writeEnvironmentDials();
     }
     /**
      * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
@@ -3508,8 +3554,95 @@ export class WebGL2Renderer {
             throw new Error('WebGL2: a skinned mesh cannot be instanced — an instanced draw binds the two attribute ' +
                 'locations the joint indices and weights occupy, and this mesh supplies them.');
         }
+        const animation = (options.animation ?? null);
+        /* The bone a vertex follows is its second coordinates' u, which a mesh carries in its grain
+           lane; a mesh with none has nothing to name a bone by. See `boneAnimation.ts`. */
+        if (animation !== null && !mesh.hasGrain) {
+            throw new Error('WebGL2: a bone animation reads each vertex’s bone from the mesh’s second coordinates ' +
+                '(`MeshData.lightmapUvs`), and this mesh has none.');
+        }
         this.ensureInstancedProgram();
-        return new InstancedBatch(this.gl, mesh, capacity, options.cull ?? false);
+        if (animation !== null)
+            this.ensureAnimatedProgram();
+        return new InstancedBatch(this.gl, mesh, capacity, options.cull ?? false, animation);
+    }
+    /**
+     * A bone animation an instanced batch can play (`InstancedOptions.animation`): per frame, a turn
+     * and a place for each bone, which every vertex of the batch's mesh follows — the bone its second
+     * coordinates' u names, times `boneScale` — at each instance's own moment of the clip. What a
+     * crowd is made of: every instance moves at the frame's rate on its own clock, in the colour pass
+     * and in every shadow, with nothing on the processor after this. See `boneAnimation.ts` for the
+     * clip's layout and the arithmetic, which both backends run.
+     *
+     * What it gives up against skinning is the blend: a vertex follows one bone. Refused, with what
+     * was wrong, for a clip whose numbers are not its size, or past 2,048 bones or frames.
+     */
+    createBoneAnimation(clip) {
+        return new GlBoneAnimation(this.gl, packBoneAnimation(clip));
+    }
+    /** Release a clip. A batch still playing it draws nothing, and casts nothing, after. */
+    disposeBoneAnimation(animation) {
+        const clip = animation;
+        if (this.contextLost || clip.disposed)
+            return;
+        clip.dispose(this.gl);
+    }
+    /**
+     * The clock a bone animation plays by this frame, in seconds on the caller's clock: an instance's
+     * moment is this times its rate plus its phase (`MeshInstances.clocks`). **Set it before the
+     * shadows are drawn**, once a frame, as the wind is set: a shadow drawn under one clock and its
+     * caster under another come apart at the frame's rate. 0 until set, which holds every crowd at
+     * the moment its phases name.
+     */
+    setAnimationTime(seconds) {
+        if (Number.isFinite(seconds))
+            this.animationTime = seconds;
+    }
+    /** The clock `setAnimationTime` set. */
+    animationTime = 0;
+    /**
+     * An animated batch's clip, clocks and numbers into whichever program is bound: the three vertex
+     * textures on units of their own (`lightBudget.ts`), the clip's speed and bone scale, the clock.
+     */
+    bindAnimation(u, batch) {
+        const clip = batch.animation;
+        const clocks = batch.clocks;
+        if (clip === null || clocks === null)
+            return;
+        const { gl } = this;
+        gl.activeTexture(gl.TEXTURE0 + BONE_PLACES_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, clip.places);
+        gl.activeTexture(gl.TEXTURE0 + BONE_TURNS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, clip.turns);
+        gl.activeTexture(gl.TEXTURE0 + INSTANCE_CLOCKS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, clocks.texture);
+        gl.uniform1i(u['uBonePlaces'] ?? null, BONE_PLACES_TEXTURE_UNIT);
+        gl.uniform1i(u['uBoneTurns'] ?? null, BONE_TURNS_TEXTURE_UNIT);
+        gl.uniform1i(u['uInstanceClocks'] ?? null, INSTANCE_CLOCKS_TEXTURE_UNIT);
+        gl.uniform2f(u['uBoneClip'] ?? null, clip.framesPerSecond, clip.boneScale);
+        gl.uniform1f(u['uSceneTime'] ?? null, this.animationTime);
+    }
+    /** The animated instanced program, compiled on first use. See `ensureInstancedProgram`. */
+    flatAnimatedProgram = null;
+    flatAnimatedUniforms = null;
+    /** Compile the animated variant, once, and feed it this frame's pass state. */
+    ensureAnimatedProgram() {
+        if (this.contextLost || this.flatAnimatedProgram !== null)
+            return;
+        const { gl } = this;
+        const program = compileProgram(gl, flatVert({ skinned: false, morphed: false, instanced: true, animated: true }), this.flatFragSource, 'flat.animated');
+        const uniforms = uniformLocations(gl, program, 'flat.animated');
+        this.flatAnimatedProgram = program;
+        this.flatAnimatedUniforms = uniforms;
+        this.flatTargets.push({ program, uniforms });
+        const camera = this.lastPassCamera;
+        const env = this.lastPassEnv;
+        if (camera !== null && env !== null) {
+            gl.useProgram(program);
+            this.writeMeshPassState(uniforms, camera, env);
+            this.writeMaterialState(uniforms, this.currentMaterial);
+            this.useFlatProgram();
+        }
     }
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch, data) {
@@ -3562,18 +3695,29 @@ export class WebGL2Renderer {
         const culling = !blend && batch.cull;
         if (culling && !batchBoxVisible(batch.box, this.frustum, this.occlusion))
             return;
+        /* A batch playing a bone animation takes the animated variant; a disposed clip draws nothing. */
+        const clip = batch.animation;
+        if (clip !== null && clip.disposed)
+            return;
         this.drawBudget.ask();
         this.ensureInstancedProgram();
+        if (clip !== null)
+            this.ensureAnimatedProgram();
         /* A material with a model takes that model's instanced program; see `modelProgram`. */
         const modelKind = this.currentMaterial?.model?.kind ?? null;
-        const modelled = modelKind === null ? null : this.modelProgram('instanced', modelKind);
-        const program = modelled?.program ?? this.flatInstancedProgram;
-        const u = modelled?.uniforms ?? this.flatInstancedUniforms;
+        const modelled = modelKind === null
+            ? null
+            : this.modelProgram(clip === null ? 'instanced' : 'animated', modelKind);
+        const program = modelled?.program ?? (clip === null ? this.flatInstancedProgram : this.flatAnimatedProgram);
+        const u = modelled?.uniforms ??
+            (clip === null ? this.flatInstancedUniforms : this.flatAnimatedUniforms);
         if (program === null || u === null)
             return;
         const { gl } = this;
         gl.useProgram(program);
         gl.uniform1i(u['uHasTangents'] ?? null, mesh.hasTangents ? 1 : 0);
+        if (clip !== null)
+            this.bindAnimation(u, batch);
         const lit = options.lit ?? true;
         /* Added light fades in the medium rather than receding into it. See `drawFog.ts`. */
         const fog = fogModeOf(options.fog ?? true, blend && options.additive === true);
@@ -3643,10 +3787,14 @@ export class WebGL2Renderer {
         const keeps = !blend && this.reflectionKeeps();
         if (keeps)
             this.reflectionTargets?.on();
-        if (culling && cullsInstances(count, mesh.indexCount))
+        /* An animated batch reads its clocks by instance index, which the culled copy would reorder:
+           it is culled whole and never instance by instance. */
+        if (culling && clip === null && cullsInstances(count, mesh.indexCount)) {
             batch.drawCulled(gl, data, this.frustum);
-        else
+        }
+        else {
             batch.draw(gl, count);
+        }
         if (keeps)
             this.reflectionTargets?.off();
         if (coverage)
@@ -3710,7 +3858,9 @@ export class WebGL2Renderer {
         const glass = this.glassScratch;
         /* Strength, path thickness, transmission, frost: one vector, for the budget the shader states. */
         gl.uniform4f(u['uSeeThrough'] ?? null, Math.max(refraction, 0), options.thicknessM ?? 0, glass.transmission, glass.frost);
-        gl.uniform3fv(u['uRefractTint'] ?? null, options.refractTint ?? WHITE_TINT);
+        /* w: this framebuffer's first row is the bottom, so up the screen is up the rows. */
+        const tint = options.refractTint ?? WHITE_TINT;
+        gl.uniform4f(u['uRefractTint'] ?? null, tint[0] ?? 1, tint[1] ?? 1, tint[2] ?? 1, 1);
         gl.uniform3fv(u['uGlassTint'] ?? null, glass.tint);
         return true;
     }
@@ -4753,6 +4903,69 @@ export class WebGL2Renderer {
             return;
         casters(this.casterSink);
     }
+    /**
+     * Draws that do not change between frames, enumerated once and kept: what a stage, a set or any
+     * world that stands still draws, recorded so a frame replays it rather than issuing it.
+     *
+     * **The same enumeration `drawSceneCasters` takes**, called once, here: rigid meshes and instanced
+     * batches, each with its material. A skinned mesh or a scatter batch is refused by name, since
+     * both change every frame. What it captures is what the enumeration said at the time — the
+     * matrices and the instance counts are copied, so a caller's scratch is free to move on — while
+     * the meshes, batches, textures and materials stay the caller's: a list must be disposed, or made
+     * again, before anything it holds is, and made again when a material it holds is changed.
+     *
+     * **What it is for is the frame's processor time.** WebGPU records the list into a render bundle
+     * per view and replays it with one call, where a draw issued a frame at a time costs its encoding
+     * every frame and again for every view that draws it. This backend has no bundles and replays the
+     * entries through the scene-caster path every frame, at the cost a frame drawing them itself pays;
+     * the picture is the same.
+     *
+     * What a list gives up against drawing each frame is culling: every entry is drawn in every view,
+     * because a bundle cannot leave one out. A world split into lists by region culls by list.
+     */
+    createStaticDraws(casters) {
+        return captureStaticDraws(casters);
+    }
+    /**
+     * Draw a list into the open mesh pass, under the camera, the lights and the fog `bindMeshPass`
+     * set — the frame's, a mirror's, a capture's. Opaque draws, through each entry's material.
+     *
+     * **Its draws are rigid and wear no overlay**, so a skin palette, morph weights, cloth or a surface
+     * overlay set before it is put back to none, as `bindMeshPass` puts an overlay back; and no
+     * material is left set after it, which is what `setMaterial(null)` leaves. The state a pass set —
+     * the grain, the relief, the fog, the grade — is the list's to draw with, as it is any draw's, and
+     * a list drawn under a different one is recorded again for it on WebGPU.
+     */
+    drawStaticDraws(draws) {
+        if (this.contextLost)
+            return;
+        const list = draws;
+        if (list.disposed) {
+            this.warnStaticDisposed();
+            return;
+        }
+        this.setSkinPalette(null);
+        this.setMorphWeights(null);
+        this.setCloth(null);
+        this.setSurfaceOverlay(null);
+        this.setMaterial(null);
+        this.sceneCasterMaterial = undefined;
+        replayStaticDraws(list, this.sceneCasterSink);
+        this.setMaterial(null);
+        this.sceneCasterMaterial = undefined;
+    }
+    /** Release a list. Its meshes, batches and materials are the caller's and are not released. */
+    disposeStaticDraws(draws) {
+        draws.disposed = true;
+    }
+    /** A disposed list drawn, said once: the frame loop does not throw. */
+    warnStaticDisposed() {
+        if (this.warnedStaticDisposed)
+            return;
+        this.warnedStaticDisposed = true;
+        console.warn('drawStaticDraws: this list was disposed, and draws nothing.');
+    }
+    warnedStaticDisposed = false;
     /**
      * Draw the pass's glass twice: where the nearest pane is, and what the panes let through.
      *
@@ -4965,10 +5178,10 @@ export class WebGL2Renderer {
         const { gl } = this;
         Object.assign(this.litOn, this.litWanted);
         this.flatFragSource = this.flatFragAt(this.lightBudget);
-        const recompile = (old, skinned, morphed, instanced, label, eight = false) => {
+        const recompile = (old, skinned, morphed, instanced, label, eight = false, animated = false) => {
             if (old === null)
                 return null;
-            const vertex = flatVert({ skinned, morphed, instanced });
+            const vertex = flatVert({ skinned, morphed, instanced, animated });
             const program = compileProgram(gl, eight ? skinEight(vertex) : vertex, this.flatFragSource, label);
             gl.deleteProgram(old);
             return { program, uniforms: uniformLocations(gl, program, label) };
@@ -4996,6 +5209,9 @@ export class WebGL2Renderer {
         const instanced = recompile(this.flatInstancedProgram, false, false, true, 'flat.instanced');
         this.flatInstancedProgram = instanced?.program ?? null;
         this.flatInstancedUniforms = instanced?.uniforms ?? null;
+        const animated = recompile(this.flatAnimatedProgram, false, false, true, 'flat.animated', false, true);
+        this.flatAnimatedProgram = animated?.program ?? null;
+        this.flatAnimatedUniforms = animated?.uniforms ?? null;
         for (const [key, entry] of this.clothFlat) {
             const eight = key.startsWith('8');
             const withMorph = key.endsWith('m');
@@ -5013,7 +5229,7 @@ export class WebGL2Renderer {
             this.modelFlat.set(key, { program, uniforms: uniformLocations(gl, program, label) });
         }
         this.flatTargets.length = 0;
-        for (const target of [plain, skinned, morphed, both, skinned8, both8, instanced]) {
+        for (const target of [plain, skinned, morphed, both, skinned8, both8, instanced, animated]) {
             if (target !== null)
                 this.flatTargets.push(target);
         }
@@ -6782,6 +6998,10 @@ export class WebGL2Renderer {
         /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
         this.ambientSH.fill(0);
         /* No reflection and an environment at its own brightness; the emission the world asks for. */
+        this.passReflectivity = 0;
+        this.passEnvironmentGain = 1;
+        this.materialReflectivity = null;
+        this.materialEnvironmentGain = null;
         this.environmentDials[1] = 0;
         this.environmentDials[2] = 1;
         this.emission[0] = env.emissiveGain;
@@ -6911,7 +7131,7 @@ export class WebGL2Renderer {
         /* Neither refracting nor glass, which is every draw that does not say otherwise. See
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
-        gl.uniform3fv(u['uRefractTint'] ?? null, WHITE_TINT);
+        gl.uniform4f(u['uRefractTint'] ?? null, 1, 1, 1, 1);
         gl.uniform3fv(u['uGlassTint'] ?? null, WHITE_TINT);
         gl.uniform3fv(u['uDirectionalDir'] ?? null, env.directionalDir);
         gl.uniform3fv(u['uDirectionalColor'] ?? null, env.directionalColor);
@@ -7025,7 +7245,10 @@ export class WebGL2Renderer {
         gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, this.peelFilled ? 1 : 0);
         gl.uniform1f(u['uShadowMaxSlope'] ?? null, this.quality.directionalShadowMaxSlope);
         gl.uniform1i(u['uShadowFilterTaps'] ?? null, this.quality.shadowFilterTaps);
-        gl.uniform3fv(u['uHighlightMin'] ?? null, env.highlightMin);
+        /* The near corner, and in its w the frame the cutout dither moves with. See `uHighlightMin`.
+           An environment written by hand may leave the box out, as the far corner says below. */
+        const min = env.highlightMin;
+        gl.uniform4f(u['uHighlightMin'] ?? null, min?.[0] ?? 0, min?.[1] ?? 0, min?.[2] ?? 0, this.cutoutFrame);
         /* The far corner, and the gain in its w. See `uHighlightMax`. */
         /* An environment written by hand may leave the box out; then there is none, as before. */
         const max = env.highlightMax ?? NO_HIGHLIGHT;
@@ -8350,6 +8573,12 @@ function litVertexOf(variant) {
     }
     const skinned = variant.startsWith('skinned') || variant.startsWith('both');
     const morphed = variant === 'morphed' || variant.startsWith('both');
-    const vertex = flatVert({ skinned, morphed, instanced: variant === 'instanced' });
+    const animated = variant === 'animated';
+    const vertex = flatVert({
+        skinned,
+        morphed,
+        instanced: variant === 'instanced' || animated,
+        animated,
+    });
     return variant.endsWith('8') ? skinEight(vertex) : vertex;
 }

package/dist/render/backend/webgl2/skinPaletteTexture.d.ts

@@ -19,9 +19,11 @@ export declare class SkinPaletteTexture {
     /**
      * Upload a palette, reallocating only when the joint count changes.
      *
-     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
-     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
-     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     * **The texture grows and never shrinks**, so the steady state is one `texSubImage2D` whatever
+     * mix of rigs a frame draws. It was rebuilt whenever the joint count changed, which with one
+     * texture for every skinned draw meant a character and a prop drawn in turn reallocated it at
+     * every draw: a GPU allocation in the frame loop. The shader reads joints by index, so a texture
+     * wider than the rig is read exactly as one that fits.
      */
     update(gl: WebGL2RenderingContext, palette: Float32Array): void;
     /** Bind to a **vertex-stage** unit. See `SKIN_PALETTE_TEXTURE_UNIT` for why that is free. */

package/dist/render/backend/webgl2/skinPaletteTexture.js

@@ -20,15 +20,17 @@ export class SkinPaletteTexture {
     /**
      * Upload a palette, reallocating only when the joint count changes.
      *
-     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
-     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
-     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     * **The texture grows and never shrinks**, so the steady state is one `texSubImage2D` whatever
+     * mix of rigs a frame draws. It was rebuilt whenever the joint count changed, which with one
+     * texture for every skinned draw meant a character and a prop drawn in turn reallocated it at
+     * every draw: a GPU allocation in the frame loop. The shader reads joints by index, so a texture
+     * wider than the rig is read exactly as one that fits.
      */
     update(gl, palette) {
         validateSkinPalette(palette);
         const joints = palette.length / 16;
         const width = paletteTextureWidth(joints);
-        if (this.texture === null || this.joints !== joints) {
+        if (this.texture === null || joints > this.joints) {
             if (this.texture !== null)
                 gl.deleteTexture(this.texture);
             const created = gl.createTexture();

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

@@ -0,0 +1,34 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads by index, made once and never filtered.
+ *
+ * **`rgba32float` places and turns, and `rg32float` clocks**, all read with `textureLoad` and bound
+ * `unfilterable-float`, as the joint palette is: a turn in half floats moves a crowd's hands by a
+ * thousandth of their reach, a jitter at the frame's rate, and the bytes are a clip's, once.
+ */
+import { type BoneAnimationHandle, type BoneAnimationTexels } from '../../boneAnimation.ts';
+/** A clip on the device, from `createBoneAnimation`. */
+export declare class GpuBoneAnimation implements BoneAnimationHandle {
+    readonly bones: number;
+    readonly frames: number;
+    readonly framesPerSecond: number;
+    readonly boneScale: number;
+    readonly placesView: GPUTextureView;
+    readonly turnsView: GPUTextureView;
+    disposed: boolean;
+    private readonly places;
+    private readonly turns;
+    constructor(device: GPUDevice, texels: BoneAnimationTexels);
+    dispose(): void;
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export declare class GpuInstanceClocks {
+    readonly view: GPUTextureView;
+    readonly staging: Float32Array;
+    private readonly texture;
+    private readonly width;
+    constructor(device: GPUDevice, capacity: number, label: string);
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(queue: GPUQueue, count: number): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads by index, made once and never filtered.
+ *
+ * **`rgba32float` places and turns, and `rg32float` clocks**, all read with `textureLoad` and bound
+ * `unfilterable-float`, as the joint palette is: a turn in half floats moves a crowd's hands by a
+ * thousandth of their reach, a jitter at the frame's rate, and the bytes are a clip's, once.
+ */
+import { CLOCK_TEXTURE_WIDTH, } from '../../boneAnimation.js';
+const USAGE_TEXTURE = 0x4 | 0x2; // TEXTURE_BINDING | COPY_DST
+/** A clip on the device, from `createBoneAnimation`. */
+export class GpuBoneAnimation {
+    bones;
+    frames;
+    framesPerSecond;
+    boneScale;
+    placesView;
+    turnsView;
+    disposed = false;
+    places;
+    turns;
+    constructor(device, texels) {
+        this.bones = texels.bones;
+        this.frames = texels.frames;
+        this.framesPerSecond = texels.framesPerSecond;
+        this.boneScale = texels.boneScale;
+        const make = (label, data) => {
+            const texture = device.createTexture({
+                label,
+                size: [texels.bones, texels.frames],
+                format: 'rgba32float',
+                usage: USAGE_TEXTURE,
+            });
+            device.queue.writeTexture({ texture }, data, { bytesPerRow: texels.bones * 16, rowsPerImage: texels.frames }, [texels.bones, texels.frames]);
+            return texture;
+        };
+        this.places = make('bones.places', texels.places);
+        this.turns = make('bones.turns', texels.turns);
+        this.placesView = this.places.createView();
+        this.turnsView = this.turns.createView();
+    }
+    dispose() {
+        this.disposed = true;
+        this.places.destroy();
+        this.turns.destroy();
+    }
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export class GpuInstanceClocks {
+    view;
+    staging;
+    texture;
+    width;
+    constructor(device, capacity, label) {
+        this.width = Math.max(1, Math.min(capacity, CLOCK_TEXTURE_WIDTH));
+        const rows = Math.max(1, Math.ceil(capacity / this.width));
+        this.staging = new Float32Array(this.width * rows * 2);
+        this.texture = device.createTexture({
+            label,
+            size: [this.width, rows],
+            format: 'rg32float',
+            usage: USAGE_TEXTURE,
+        });
+        this.view = this.texture.createView();
+    }
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(queue, count) {
+        if (count <= 0)
+            return;
+        const rows = Math.ceil(count / this.width);
+        queue.writeTexture({ texture: this.texture }, this.staging, { bytesPerRow: this.width * 8, rowsPerImage: rows }, [this.width, rows]);
+    }
+    dispose() {
+        this.texture.destroy();
+    }
+}