@driftengine/core 4.9.0 → 4.11.0

package/dist/render/instances.d.ts

@@ -66,6 +66,14 @@ export interface MeshInstances {
      */
     readonly uvRegions?: Float32Array;
     /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
+    /**
+     * Two floats each, the instance's clock for a batch that plays a bone animation
+     * (`InstancedOptions.animation`): its phase in seconds, added to the scene's time once the rate has
+     * scaled it, and its rate, 1 for the clip's own speed. **Absent, or an instance past its end, is
+     * `(0, 1)`** — every instance at the clip's speed and in step. Read by `uploadInstanced`, as the
+     * matrices are; a batch with no animation ignores it.
+     */
+    readonly clocks?: Float32Array;
     readonly capacity: number;
     /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
     count: number;
@@ -103,6 +111,7 @@ export declare const INSTANCE_STRIDE: number;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export declare function packInstances(instances: MeshInstances, out: Float32Array): void;
+import type { BoneAnimationHandle } from './boneAnimation.ts';
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
     /**
@@ -117,4 +126,21 @@ export interface InstancedOptions {
      * place gains only the whole-batch test, which it could as well do itself.
      */
     readonly cull?: boolean;
+    /**
+     * A bone animation every instance plays (`createBoneAnimation`): each vertex follows the bone its
+     * mesh's second coordinates name, at the instance's own moment of the clip (`MeshInstances.clocks`
+     * and the clock `setAnimationTime` sets), in the colour pass and in every shadow. The mesh must
+     * carry second coordinates. See `boneAnimation.ts`.
+     *
+     * **An animated batch is culled whole, never instance by instance**: its instances read their
+     * clocks by index, which a cull that compacts the survivors would reorder. And its bounds are the
+     * rest pose's, so a clip that carries vertices far from it wants a mesh whose bounds hold them.
+     *
+     * **What it gives up**: under reconstruction or the temporal resolve, a crowd's own movement is not
+     * in the frame's motion — the motion pass places a batch by its matrices, not by its clip — so its
+     * moving parts are reprojected as though still, which softens a fast clip a little; and a glass
+     * batch's coloured shadow is cast from rest. What would make the first wrong is a clip fast enough
+     * at the size it is seen to smear, which is then the motion pass's to learn.
+     */
+    readonly animation?: BoneAnimationHandle;
 }

package/dist/render/lightBudget.d.ts

@@ -243,6 +243,16 @@ export declare const SKIN_BLUR_ALBEDO_UNIT: number;
  */
 export declare const PARTICLE_SPRITE_UNIT: number;
 export declare const PARTICLE_DEPTH_UNIT: number;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export declare const BONE_PLACES_TEXTURE_UNIT: number;
+export declare const BONE_TURNS_TEXTURE_UNIT: number;
+export declare const INSTANCE_CLOCKS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -244,6 +244,16 @@ export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
  */
 export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
 export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export const BONE_PLACES_TEXTURE_UNIT = PARTICLE_DEPTH_UNIT + 1;
+export const BONE_TURNS_TEXTURE_UNIT = BONE_PLACES_TEXTURE_UNIT + 1;
+export const INSTANCE_CLOCKS_TEXTURE_UNIT = BONE_TURNS_TEXTURE_UNIT + 1;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightMatrix.d.ts

@@ -1,3 +1,14 @@
 import { mat4 } from 'gl-matrix';
 import type { Vec3 } from '../math/color.ts';
 export declare function computeLightMatrix(lightDir: Vec3, focusX: number, focusY: number, focusZ: number, radius: number, shadowMapSize: number, out: mat4): number;
+/**
+ * The depth an orthographic light matrix spans, in metres: what `computeLightMatrix` returns, read
+ * back off any such matrix. Its depth row is the light's axis scaled by two over the span, so the
+ * span is two over that row's length — whatever focus, radius or bearing built it.
+ *
+ * **For a matrix the renderer is handed rather than one it built**: the sun's moving layer is read
+ * through the matrix its shadow pass was drawn with, and its depth tolerance and distance fade are
+ * in metres of that matrix. What would make this wrong is a perspective light, whose depth is not
+ * linear; the sun's never is.
+ */
+export declare function orthographicDepthSpan(m: ArrayLike<number>): number;

package/dist/render/lightMatrix.js

@@ -43,3 +43,17 @@ export function computeLightMatrix(lightDir, focusX, focusY, focusZ, radius, sha
     // to express its residual depth tolerance in stable world-space metres.
     return radius * 6;
 }
+/**
+ * The depth an orthographic light matrix spans, in metres: what `computeLightMatrix` returns, read
+ * back off any such matrix. Its depth row is the light's axis scaled by two over the span, so the
+ * span is two over that row's length — whatever focus, radius or bearing built it.
+ *
+ * **For a matrix the renderer is handed rather than one it built**: the sun's moving layer is read
+ * through the matrix its shadow pass was drawn with, and its depth tolerance and distance fade are
+ * in metres of that matrix. What would make this wrong is a perspective light, whose depth is not
+ * linear; the sun's never is.
+ */
+export function orthographicDepthSpan(m) {
+    const length = Math.hypot(m[2], m[6], m[10]);
+    return length > 0 ? 2 / length : 1;
+}

package/dist/render/lightmap.d.ts

@@ -15,7 +15,7 @@
  *     light = irradiance(uv) * max(0, dot(d.xyz, n) + d.w)
  *     diffuse += albedo * (1 - metal) * light
  *
- * Unreal's high-quality lightmap read, `GetLightMapColorHQ`, once its own vectors have decoded the
+ * A directional lightmap read, once its own vectors have decoded the
  * page — the first-order spherical harmonic its direction carries, in this engine's axes. **Added
  * to what the dynamic lights give**, and to the ambient: a consumer whose bake already holds the
  * sky's light zeroes the ambient for those draws itself, with `setAmbientSH` and nine zeros.

package/dist/render/mesh.d.ts

@@ -26,6 +26,8 @@ export declare class Mesh {
      * same frame.
      */
     readonly indexCount: number;
+    /** `UNSIGNED_SHORT` or `UNSIGNED_INT`, as `compactIndices` stored them: every draw says which. */
+    private readonly indexType;
     /**
      * The constant values this mesh's *absent* attributes are shaded with, re-applied on
      * every draw.
@@ -63,6 +65,11 @@ export declare class Mesh {
     readonly isSkinnedEight: boolean;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     readonly hasUvs: boolean;
+    /**
+     * Whether it carries a grain lane, which is where second coordinates ride (`lightmap.ts`): what
+     * a bone animation reads each vertex's bone from.
+     */
+    readonly hasGrain: boolean;
     /** How many vertices it has, which a cloth binding is checked against. */
     readonly vertexCount: number;
     /**
@@ -137,7 +144,14 @@ export declare class Mesh {
      * still visible, which is the kind of bug that only shows up at the edge of the frame.
      */
     update(gl: WebGL2RenderingContext, positions: Float32Array, normals?: Float32Array): void;
+    /**
+     * One attribute's buffer, as floats or in its sixteen-bit fixed point (`vertexPacking.ts`), which
+     * WebGL2 reads back through a normalised `SHORT` or `UNSIGNED_SHORT`: three lanes wide where
+     * WebGPU needs four, so a normal costs six bytes here.
+     */
     private attachAttribute;
+    /** A buffer, or the one value every vertex shares as a constant, as the packing says. */
+    private attachShared;
     /**
      * Give a bound buffer its storage, and its contents now or later.
      *

package/dist/render/mesh.js

@@ -2,6 +2,8 @@
 import { MorphTexture } from './backend/webgl2/morphTexture.js';
 import { ABSENT_ATTRIBUTE } from './vertexDefaults.js';
 import { UPLOAD_BYTES_PER_STEP } from './uploadStep.js';
+import { compactIndices } from './indexWidth.js';
+import { fixedArray, sharedValue, vertexPackingOf, } from './vertexPacking.js';
 /*
  * `MeshData` and its validator live in `@driftengine/drft`, because the container's whole
  * job is to carry one and the format package must be readable by something that never
@@ -99,6 +101,8 @@ export class Mesh {
      * same frame.
      */
     indexCount;
+    /** `UNSIGNED_SHORT` or `UNSIGNED_INT`, as `compactIndices` stored them: every draw says which. */
+    indexType;
     /**
      * The constant values this mesh's *absent* attributes are shaded with, re-applied on
      * every draw.
@@ -136,6 +140,11 @@ export class Mesh {
     isSkinnedEight;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     hasUvs;
+    /**
+     * Whether it carries a grain lane, which is where second coordinates ride (`lightmap.ts`): what
+     * a bone animation reads each vertex's bone from.
+     */
+    hasGrain;
     /** How many vertices it has, which a cloth binding is checked against. */
     vertexCount;
     /**
@@ -202,12 +211,14 @@ export class Mesh {
          * that has been told a lie every frame is the shape of a stall nobody can find.
          */
         const usage = dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW;
+        /* How each attribute travels: sixteen-bit fixed point, or one value as a constant. */
+        const packing = vertexPackingOf(data, dynamic);
         const positions = this.attachAttribute(gl, ATTR_POSITION, data.positions, 3, usage);
-        const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage);
+        const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage, packing.normals);
         if (dynamic)
             this.deformable = { positions, normals };
-        this.attachAttribute(gl, ATTR_COLOR, data.colors, 3);
-        this.attachAttribute(gl, ATTR_EMISSIVE, data.emissive, 1);
+        this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+        this.attachShared(gl, ATTR_EMISSIVE, data.emissive, 1, packing.emissive);
         /*
          * Absent means "not shiny", supplied as a constant rather than as a buffer of
          * zeroes. `vertexAttrib1f` sets the value a *disabled* attribute reads, so this
@@ -284,7 +295,7 @@ export class Mesh {
         }
         else {
             this.attachAttribute(gl, ATTR_JOINTS, data.joints, 4);
-            this.attachAttribute(gl, ATTR_WEIGHTS, data.weights, 4);
+            this.attachAttribute(gl, ATTR_WEIGHTS, data.weights, 4, gl.STATIC_DRAW, packing.weights);
         }
         /* The fifth to eighth influences, or zeros, which add nothing. See `isSkinnedEight`. */
         this.isSkinnedEight = this.isSkinned && data.joints2 !== undefined;
@@ -294,7 +305,7 @@ export class Mesh {
         }
         else {
             this.attachAttribute(gl, ATTR_JOINTS2, data.joints2, 4);
-            this.attachAttribute(gl, ATTR_WEIGHTS2, data.weights2, 4);
+            this.attachAttribute(gl, ATTR_WEIGHTS2, data.weights2, 4, gl.STATIC_DRAW, packing.weights2);
         }
         this.hasTangents = data.tangents !== undefined;
         if (data.tangents === undefined) {
@@ -302,8 +313,9 @@ export class Mesh {
             this.constants.push({ location: ATTR_TANGENT, value: ABSENT_ATTRIBUTE['tangents'] });
         }
         else {
-            this.attachAttribute(gl, ATTR_TANGENT, data.tangents, 4);
+            this.attachAttribute(gl, ATTR_TANGENT, data.tangents, 4, gl.STATIC_DRAW, packing.tangents);
         }
+        this.hasGrain = data.grain !== undefined;
         if (data.grain === undefined) {
             gl.disableVertexAttribArray(ATTR_GRAIN);
             this.constants.push({ location: ATTR_GRAIN, value: ABSENT_ATTRIBUTE['grain'] });
@@ -331,7 +343,9 @@ export class Mesh {
         this.buffers.push(indexBuffer);
         gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
         this.indexBuffer = indexBuffer;
-        this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, data.indices, gl.STATIC_DRAW);
+        const indices = compactIndices(data.indices, this.vertexCount);
+        this.indexType = indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT;
+        this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, indices, gl.STATIC_DRAW);
         gl.bindVertexArray(null);
     }
     /** Caller is responsible for having the flat program + uniforms bound. */
@@ -348,7 +362,7 @@ export class Mesh {
             const value = constant.value;
             applyConstant(gl, constant.location, value);
         }
-        gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0);
+        gl.drawElements(gl.TRIANGLES, this.indexCount, this.indexType, 0);
     }
     /**
      * A vertex array for one instanced batch: every attribute this mesh binds from a buffer, its index
@@ -368,7 +382,7 @@ export class Mesh {
         for (const attribute of this.layout) {
             gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
             gl.enableVertexAttribArray(attribute.location);
-            gl.vertexAttribPointer(attribute.location, attribute.size, gl.FLOAT, false, 0, 0);
+            gl.vertexAttribPointer(attribute.location, attribute.size, attribute.type, attribute.normalized, 0, 0);
         }
         gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
         gl.bindBuffer(gl.ARRAY_BUFFER, instances);
@@ -393,7 +407,7 @@ export class Mesh {
             const value = constant.value;
             applyConstant(gl, constant.location, value);
         }
-        gl.drawElementsInstanced(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0, count);
+        gl.drawElementsInstanced(gl.TRIANGLES, this.indexCount, this.indexType, 0, count);
     }
     dispose(gl) {
         this.morph?.dispose(gl);
@@ -431,18 +445,34 @@ export class Mesh {
             gl.bufferSubData(gl.ARRAY_BUFFER, 0, normals);
         }
     }
-    attachAttribute(gl, location, data, size, usage = gl.STATIC_DRAW) {
+    /**
+     * One attribute's buffer, as floats or in its sixteen-bit fixed point (`vertexPacking.ts`), which
+     * WebGL2 reads back through a normalised `SHORT` or `UNSIGNED_SHORT`: three lanes wide where
+     * WebGPU needs four, so a normal costs six bytes here.
+     */
+    attachAttribute(gl, location, data, size, usage = gl.STATIC_DRAW, packing = 'float') {
         const buffer = gl.createBuffer();
         if (buffer === null)
             throw new Error('createBuffer failed');
         this.buffers.push(buffer);
         gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-        this.allocate(gl, gl.ARRAY_BUFFER, buffer, data, usage);
+        const fixed = packing === 'snorm16' || packing === 'unorm16';
+        this.allocate(gl, gl.ARRAY_BUFFER, buffer, fixed ? fixedArray(data, packing) : data, usage);
+        const type = packing === 'snorm16' ? gl.SHORT : packing === 'unorm16' ? gl.UNSIGNED_SHORT : gl.FLOAT;
         gl.enableVertexAttribArray(location);
-        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
-        this.layout.push({ location, buffer, size });
+        gl.vertexAttribPointer(location, size, type, fixed, 0, 0);
+        this.layout.push({ location, buffer, size, type, normalized: fixed });
         return buffer;
     }
+    /** A buffer, or the one value every vertex shares as a constant, as the packing says. */
+    attachShared(gl, location, data, size, packing) {
+        if (packing !== 'constant') {
+            this.attachAttribute(gl, location, data, size, gl.STATIC_DRAW, packing);
+            return;
+        }
+        gl.disableVertexAttribArray(location);
+        this.constants.push({ location, value: sharedValue(data, size) });
+    }
     /**
      * Give a bound buffer its storage, and its contents now or later.
      *

package/dist/render/pointLightSelection.d.ts

@@ -71,10 +71,10 @@ export interface PointLightSource {
     inLightField?: boolean;
     /**
      * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
-     * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
-     * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
-     * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
-     * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+     * term, `R` its radius and `n` this. The usual falloff for a light without inverse-square
+     * falloff, so a rig authored that way — a fill of brightness 160 across 164 m, a key at exponent
+     * 8 — lights the space it was authored for rather than one that ends a few metres out. Absent or
+     * 0, the frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
      */
     falloffExponent?: number;
 }

package/dist/render/renderQuality.d.ts

@@ -42,6 +42,8 @@ export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder' | 'filmic';
 export type ShadowFilterTaps = 4 | 8 | 12;
 export type DirectionalShadowDepthLayers = 1 | 2;
 export type WaterReflectionFilterTaps = 1 | 5 | 9;
+/** What a draw does when its pipeline has not compiled yet: see `RenderQuality.pipelineCompile`. */
+export type PipelineCompile = 'wait' | 'skip';
 /** How light through glass is coloured: see `RenderQuality.glassShadows`. */
 export type GlassShadows = 'full' | 'half' | 'off';
 /** How light scattered beneath skin is drawn: see `RenderQuality.skinScattering`. */
@@ -210,6 +212,34 @@ export interface RenderQuality {
      * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
      */
     readonly glassShadows: GlassShadows;
+    /**
+     * What a lit draw does when the pipeline it needs has not compiled: one first needed inside a
+     * frame, by a material's own state — two-sided, cut out, a surface model — or a draw state a
+     * mesh's creation did not warm.
+     *
+     * **`'wait'`, the default**: the pipeline is built where the draw asks for it, and on WebGPU the
+     * browser compiles it on its GPU process's main thread, holding the frame — 130 to 400 ms a
+     * pipeline was reported on a phone, for a material first drawn mid-scene. **`'skip'`** starts the
+     * compile off that thread and leaves the draw out until it lands, a few frames to a few dozen,
+     * and the draw then appears; nothing waits. Static draws always wait, since a recorded list keeps
+     * what it recorded, and a compile that fails is built where it is next asked for, so the device
+     * says why rather than the draw vanishing for good.
+     *
+     * **The way to have neither** is to draw what a scene will use once, behind a loading screen, and
+     * await `ready()`, which waits for every compile started — whichever this says. What would make
+     * `'skip'` wrong is a frame that must hold everything it was given, such as a capture of the first
+     * frame of a scene not awaited.
+     *
+     * **Measured on a desktop GPU** (`demo/dev/pipelineCompile.html`, eight new variants at once): on
+     * WebGPU the frame that met them took 700 to 3,700 ms waiting and 17 ms skipping, the draws
+     * landing 21 to 26 frames later. WebGL2 compiles its lit programs when it is made, all but a
+     * surface model's, which it compiles at the first draw that wants one: there `'skip'` asks the
+     * driver through `KHR_parallel_shader_compile` and waits where a context does not offer it — which
+     * ANGLE on Vulkan does not. Where it is offered, ANGLE on OpenGL, the longest frame went from 820 to
+     * 1,120 ms to 630 to 700 ms: the driver still finishes its own compile at the program's first
+     * draw, which nothing above it can move.
+     */
+    readonly pipelineCompile: PipelineCompile;
     /**
      * How light that scatters beneath skin is drawn, for a material whose model is `skinModel`.
      *

package/dist/render/renderQuality.js

@@ -63,6 +63,7 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     lightVolumeSamples: 32,
     directionalShadowDepthLayers: 2,
     glassShadows: 'full',
+    pipelineCompile: 'wait',
     skinScattering: 'pre-integrated',
     directionalShadowMaxDistance: 6,
     directionalShadowMaxSlope: 3,
@@ -218,6 +219,7 @@ export function resolveRenderQuality(options = {}) {
         lightVolumeSamples: options.lightVolumeSamples ?? DEFAULT_RENDER_QUALITY.lightVolumeSamples,
         directionalShadowDepthLayers: options.directionalShadowDepthLayers ?? DEFAULT_RENDER_QUALITY.directionalShadowDepthLayers,
         glassShadows: options.glassShadows ?? DEFAULT_RENDER_QUALITY.glassShadows,
+        pipelineCompile: options.pipelineCompile ?? DEFAULT_RENDER_QUALITY.pipelineCompile,
         skinScattering: options.skinScattering ?? DEFAULT_RENDER_QUALITY.skinScattering,
         directionalShadowMaxDistance: options.directionalShadowMaxDistance ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxDistance,
         directionalShadowMaxSlope: options.directionalShadowMaxSlope ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxSlope,
@@ -318,6 +320,9 @@ export function resolveRenderQuality(options = {}) {
         quality.glassShadows !== 'off') {
         throw new Error(`RenderQuality.glassShadows must be 'full', 'half' or 'off', got ${String(quality.glassShadows)}`);
     }
+    if (quality.pipelineCompile !== 'wait' && quality.pipelineCompile !== 'skip') {
+        throw new Error(`RenderQuality.pipelineCompile must be 'wait' or 'skip', got ${String(quality.pipelineCompile)}`);
+    }
     if (quality.skinScattering !== 'pre-integrated' && quality.skinScattering !== 'screen-space') {
         throw new Error(`RenderQuality.skinScattering must be 'pre-integrated' or 'screen-space', got ${String(quality.skinScattering)}`);
     }

package/dist/render/rendererHarness.d.ts

@@ -38,6 +38,13 @@ export declare function recordingGl(options?: {
      * recording.
      */
     readonly uniforms?: readonly string[];
+    /**
+     * Whether a program started under `KHR_parallel_shader_compile` has finished, which the test
+     * flips: `COMPLETION_STATUS_KHR` answers `done`. Finished by default, as every program here is.
+     */
+    readonly compiling?: {
+        done: boolean;
+    };
 }): {
     gl: WebGL2RenderingContext;
     canvas: HTMLCanvasElement;

package/dist/render/rendererHarness.js

@@ -17,6 +17,7 @@
  */
 import { countUniformVectors } from './uniformVectorBudget.js';
 export function recordingGl(options = {}) {
+    const compiling = options.compiling ?? { done: true };
     const extensions = new Set(options.extensions ?? []);
     const uniforms = options.uniforms ?? [];
     /* What `clearDepth` last set, so a module that borrows the value can be seen to put it back. */
@@ -93,6 +94,13 @@ export function recordingGl(options = {}) {
         HALF_FLOAT: 0x140b,
         DEPTH_COMPONENT: 0x1902,
         UNSIGNED_INT: 0x1405,
+        /* Named so a mesh's index width and each attribute's type can be read back: the buffer its
+           indices fill, the type every draw of it names, and how each attribute is read. See
+           `mesh.test.ts`. */
+        UNSIGNED_SHORT: 0x1403,
+        SHORT: 0x1402,
+        FLOAT: 0x1406,
+        ELEMENT_ARRAY_BUFFER: 0x8893,
         LINEAR: 0x2601,
         COLOR_BUFFER_BIT: 0x00004000,
         /* Named so a test can tell a mesh that declared itself deforming from one that did not. */
@@ -137,6 +145,8 @@ export function recordingGl(options = {}) {
             if (name === 'EXT_clip_control') {
                 return { LOWER_LEFT_EXT: 0x8ca1, ZERO_TO_ONE_EXT: 0x935f, clipControlEXT: () => undefined };
             }
+            if (name === 'KHR_parallel_shader_compile')
+                return { COMPLETION_STATUS_KHR: 0x91b1 };
             return {};
         },
         getShaderParameter: () => true,
@@ -166,6 +176,8 @@ export function recordingGl(options = {}) {
         /* Linked yes; zero active uniforms and attributes, which ends every reflection loop at once
            and is why this harness does not have to know a single uniform name. */
         getProgramParameter: (program, pname) => {
+            if (pname === 0x91b1)
+                return compiling.done;
             if (pname === constants.ACTIVE_UNIFORMS)
                 return uniforms.length;
             if (pname === constants.ACTIVE_ATTRIBUTES)

package/dist/render/screenSpaceReflection.d.ts

@@ -179,7 +179,8 @@ export interface ReflectiveSurfaceOptions extends DecalBox {
      * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
      * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
      * by — so a floor returns more toward the horizon than underfoot, and the share follows the
-     * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+     * camera as a physically based renderer weighs its reflections. **False by default**, the one
+     * share as before.
      *
      * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
      * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion

package/dist/render/shader.d.ts

@@ -1,5 +1,20 @@
 /** Shader compilation with fail-fast diagnostics (init-time only, never per-frame). */
 export declare function compileProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string): WebGLProgram;
+/**
+ * A program compiled and linked without asking whether that worked, since asking waits for the
+ * driver to finish: for a context offering `KHR_parallel_shader_compile`, whose
+ * `COMPLETION_STATUS_KHR` says when asking no longer waits. `finishProgram` asks then, and fails
+ * as loudly as `compileProgram` does; the stages are kept until it does, for their logs.
+ */
+export interface StartedProgram {
+    readonly program: WebGLProgram;
+    readonly vertex: WebGLShader;
+    readonly fragment: WebGLShader;
+    readonly label: string;
+}
+export declare function startProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string): StartedProgram;
+/** A started program, checked as `compileProgram` checks one: its stages, then its link. */
+export declare function finishProgram(gl: WebGL2RenderingContext, started: StartedProgram): WebGLProgram;
 export declare function setUniformStrictMode(on: boolean): void;
 /** Locations of every active uniform, keyed by name. */
 export declare function uniformLocations(gl: WebGL2RenderingContext, program: WebGLProgram, label?: string): Record<string, WebGLUniformLocation>;

package/dist/render/shader.js

@@ -17,6 +17,47 @@ export function compileProgram(gl, vertexSource, fragmentSource, label) {
     }
     return program;
 }
+export function startProgram(gl, vertexSource, fragmentSource, label) {
+    const stage = (type, source, name) => {
+        const shader = gl.createShader(type);
+        if (shader === null)
+            throw new Error(`[${label}.${name}] createShader failed`);
+        gl.shaderSource(shader, source);
+        gl.compileShader(shader);
+        return shader;
+    };
+    const vertex = stage(gl.VERTEX_SHADER, vertexSource, 'vert');
+    const fragment = stage(gl.FRAGMENT_SHADER, fragmentSource, 'frag');
+    const program = gl.createProgram();
+    if (program === null)
+        throw new Error(`[${label}] createProgram failed`);
+    gl.attachShader(program, vertex);
+    gl.attachShader(program, fragment);
+    gl.linkProgram(program);
+    return { program, vertex, fragment, label };
+}
+/** A started program, checked as `compileProgram` checks one: its stages, then its link. */
+export function finishProgram(gl, started) {
+    const { program, vertex, fragment, label } = started;
+    const fail = (what, log) => {
+        gl.deleteShader(vertex);
+        gl.deleteShader(fragment);
+        gl.deleteProgram(program);
+        throw new Error(`[${label}${what}] ${log ?? 'no log'}`);
+    };
+    if (!gl.getShaderParameter(vertex, gl.COMPILE_STATUS)) {
+        fail('.vert compile failed:', gl.getShaderInfoLog(vertex));
+    }
+    if (!gl.getShaderParameter(fragment, gl.COMPILE_STATUS)) {
+        fail('.frag compile failed:', gl.getShaderInfoLog(fragment));
+    }
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        fail(' link failed:', gl.getProgramInfoLog(program));
+    }
+    gl.deleteShader(vertex);
+    gl.deleteShader(fragment);
+    return program;
+}
 /**
  * Whether a uniform lookup that cannot reach the GPU is reported.
  *

package/dist/render/shaders/boneAnimation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The vertex-stage bone animation: a crowd instance's vertex turned and placed by its bone, at its
+ * instance's moment of the clip — the GLSL of `boneAnimation.ts`'s `animateBoneVertex`, line for
+ * line. Shared by the lit stage and the depth stage, so a crowd's shadow moves with it.
+ *
+ * **Three textures, read by index and never filtered**: the places and the turns, a texel a bone a
+ * frame (bones across, frames down, sizes read with `textureSize` so no uniform says them), and the
+ * batch's clocks, two floats an instance wrapped onto rows, read at `gl_InstanceID`. The clip's speed
+ * and its bone scale are the one uniform, `uBoneClip`; the scene's time is the pass's `uSceneTime`.
+ *
+ * **The bone is read from the grain lane**, which is where a mesh's second coordinates ride, stored
+ * as `-1 - u` (`lightmap.ts`). An instanced batch reads no grain of its own from that lane: a crowd's
+ * mesh carries second coordinates, which is what makes it one.
+ *
+ * Integer arithmetic for the lattice, by the 2026-09-20 rule, except where a float is clamped onto
+ * it: the first frame is `min(floor(wrapped), frames - 1)`, so the wrap that division-by-reciprocal
+ * lands on `frames` is the last frame fully blended into the first — the first, which is right.
+ */
+export declare const BONE_ANIMATION_GLSL = "\nuniform highp sampler2D uBonePlaces;\nuniform highp sampler2D uBoneTurns;\nuniform highp sampler2D uInstanceClocks;\n/** x the clip's frames a second, y how many bones one unit of the second coordinates' u counts. */\nuniform vec2 uBoneClip;\n\n/** v turned by the unit quaternion q. */\nvec3 boneTurn(vec4 q, vec3 v) {\n  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);\n}\n\n/**\n * Where the clip puts this vertex, from its place at rest; its normal and tangent turned with it.\n */\nvec3 boneAnimate(vec3 position, inout vec3 normal, inout vec3 tangent) {\n  ivec2 size = textureSize(uBonePlaces, 0);\n  int clocksWidth = textureSize(uInstanceClocks, 0).x;\n  vec2 clock = texelFetch(\n    uInstanceClocks,\n    ivec2(gl_InstanceID % clocksWidth, gl_InstanceID / clocksWidth),\n    0\n  ).xy;\n  float moment = (uSceneTime * clock.y + clock.x) * uBoneClip.x;\n  float frames = float(size.y);\n  float wrapped = moment - frames * floor(moment / frames);\n  int first = min(int(floor(wrapped)), size.y - 1);\n  int second = first + 1 == size.y ? 0 : first + 1;\n  float blend = clamp(wrapped - float(first), 0.0, 1.0);\n  int bone = clamp(int(floor((-1.0 - aGrain) * uBoneClip.y + 0.5)), 0, size.x - 1);\n  vec4 q0 = texelFetch(uBoneTurns, ivec2(bone, first), 0);\n  vec4 q1 = texelFetch(uBoneTurns, ivec2(bone, second), 0);\n  /* The shorter arc: a quaternion and its negation are one turn. */\n  if (dot(q0, q1) < 0.0) q1 = -q1;\n  vec4 q = normalize(mix(q0, q1, blend));\n  vec3 place = mix(\n    texelFetch(uBonePlaces, ivec2(bone, first), 0).xyz,\n    texelFetch(uBonePlaces, ivec2(bone, second), 0).xyz,\n    blend\n  );\n  normal = boneTurn(q, normal);\n  tangent = boneTurn(q, tangent);\n  return boneTurn(q, position) + place;\n}\n";

package/dist/render/shaders/boneAnimation.js

@@ -0,0 +1,63 @@
+/**
+ * The vertex-stage bone animation: a crowd instance's vertex turned and placed by its bone, at its
+ * instance's moment of the clip — the GLSL of `boneAnimation.ts`'s `animateBoneVertex`, line for
+ * line. Shared by the lit stage and the depth stage, so a crowd's shadow moves with it.
+ *
+ * **Three textures, read by index and never filtered**: the places and the turns, a texel a bone a
+ * frame (bones across, frames down, sizes read with `textureSize` so no uniform says them), and the
+ * batch's clocks, two floats an instance wrapped onto rows, read at `gl_InstanceID`. The clip's speed
+ * and its bone scale are the one uniform, `uBoneClip`; the scene's time is the pass's `uSceneTime`.
+ *
+ * **The bone is read from the grain lane**, which is where a mesh's second coordinates ride, stored
+ * as `-1 - u` (`lightmap.ts`). An instanced batch reads no grain of its own from that lane: a crowd's
+ * mesh carries second coordinates, which is what makes it one.
+ *
+ * Integer arithmetic for the lattice, by the 2026-09-20 rule, except where a float is clamped onto
+ * it: the first frame is `min(floor(wrapped), frames - 1)`, so the wrap that division-by-reciprocal
+ * lands on `frames` is the last frame fully blended into the first — the first, which is right.
+ */
+export const BONE_ANIMATION_GLSL = `
+uniform highp sampler2D uBonePlaces;
+uniform highp sampler2D uBoneTurns;
+uniform highp sampler2D uInstanceClocks;
+/** x the clip's frames a second, y how many bones one unit of the second coordinates' u counts. */
+uniform vec2 uBoneClip;
+
+/** v turned by the unit quaternion q. */
+vec3 boneTurn(vec4 q, vec3 v) {
+  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);
+}
+
+/**
+ * Where the clip puts this vertex, from its place at rest; its normal and tangent turned with it.
+ */
+vec3 boneAnimate(vec3 position, inout vec3 normal, inout vec3 tangent) {
+  ivec2 size = textureSize(uBonePlaces, 0);
+  int clocksWidth = textureSize(uInstanceClocks, 0).x;
+  vec2 clock = texelFetch(
+    uInstanceClocks,
+    ivec2(gl_InstanceID % clocksWidth, gl_InstanceID / clocksWidth),
+    0
+  ).xy;
+  float moment = (uSceneTime * clock.y + clock.x) * uBoneClip.x;
+  float frames = float(size.y);
+  float wrapped = moment - frames * floor(moment / frames);
+  int first = min(int(floor(wrapped)), size.y - 1);
+  int second = first + 1 == size.y ? 0 : first + 1;
+  float blend = clamp(wrapped - float(first), 0.0, 1.0);
+  int bone = clamp(int(floor((-1.0 - aGrain) * uBoneClip.y + 0.5)), 0, size.x - 1);
+  vec4 q0 = texelFetch(uBoneTurns, ivec2(bone, first), 0);
+  vec4 q1 = texelFetch(uBoneTurns, ivec2(bone, second), 0);
+  /* The shorter arc: a quaternion and its negation are one turn. */
+  if (dot(q0, q1) < 0.0) q1 = -q1;
+  vec4 q = normalize(mix(q0, q1, blend));
+  vec3 place = mix(
+    texelFetch(uBonePlaces, ivec2(bone, first), 0).xyz,
+    texelFetch(uBonePlaces, ivec2(bone, second), 0).xyz,
+    blend
+  );
+  normal = boneTurn(q, normal);
+  tangent = boneTurn(q, tangent);
+  return boneTurn(q, position) + place;
+}
+`;

package/dist/render/shaders/depth.d.ts

@@ -23,6 +23,13 @@ export declare const DEPTH_INSTANCED_VERT: string;
  */
 export declare const DEPTH_CUTOUT_VERT: string;
 export declare const DEPTH_INSTANCED_CUTOUT_VERT: string;
+/**
+ * The variants a crowd casts through: an instanced batch playing a bone animation, its vertices
+ * where the clip puts them at each instance's moment. See `shaders/boneAnimation.ts`. No glass
+ * variant: a crowd is not glass, and a glass batch that animates casts its tint from rest.
+ */
+export declare const DEPTH_INSTANCED_ANIMATED_VERT: string;
+export declare const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT: string;
 export declare const DEPTH_FRAG = "#version 300 es\nprecision highp float;\nin vec4 vLightPosition;\n\nuniform highp sampler2DArray uPreviousShadowMap;\nuniform int uPeelShadowLayer;\n\nvoid main() {\n  if (uPeelShadowLayer != 0) {\n    vec3 p = vLightPosition.xyz / vLightPosition.w;\n    vec2 uv = p.xy * 0.5 + 0.5;\n    float previousDepth = texture(uPreviousShadowMap, vec3(uv, 0.0)).r;\n    // Discard the already-recorded surface and everything in front of it. The\n    // ordinary depth test then stores the next independently fading occluder.\n    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;\n  }\n}\n";
 /**
  * The cutout caster's depth: the plain pass, and a texel of alpha under the cutoff writes nothing.