@driftengine/core 4.9.0 → 4.11.0

package/src/render/mesh.ts

@@ -3,6 +3,13 @@
 import { MorphTexture } from './backend/webgl2/morphTexture.ts';
 import { ABSENT_ATTRIBUTE } from './vertexDefaults.ts';
 import { UPLOAD_BYTES_PER_STEP } from './uploadStep.ts';
+import { compactIndices } from './indexWidth.ts';
+import {
+  fixedArray,
+  sharedValue,
+  vertexPackingOf,
+  type AttributePacking,
+} from './vertexPacking.ts';
 
 /*
  * `MeshData` and its validator live in `@driftengine/drft`, because the container's whole
@@ -92,7 +99,14 @@ export class Mesh {
   private readonly vao: WebGLVertexArrayObject;
   private readonly buffers: WebGLBuffer[] = [];
   /** Every attribute bound from a buffer, so a batch can build a vertex array of its own. */
-  private readonly layout: { location: number; buffer: WebGLBuffer; size: number }[] = [];
+  private readonly layout: {
+    location: number;
+    buffer: WebGLBuffer;
+    size: number;
+    /** `FLOAT`, or a sixteen-bit type read normalised: `vertexPacking.ts`. */
+    type: number;
+    normalized: boolean;
+  }[] = [];
   private indexBuffer: WebGLBuffer | null = null;
   /**
    * The position and normal buffers, kept so `update` can rewrite them.
@@ -110,6 +124,8 @@ export class Mesh {
    * same frame.
    */
   readonly indexCount: number;
+  /** `UNSIGNED_SHORT` or `UNSIGNED_INT`, as `compactIndices` stored them: every draw says which. */
+  private readonly indexType: number;
   /**
    * The constant values this mesh's *absent* attributes are shaded with, re-applied on
    * every draw.
@@ -149,6 +165,11 @@ export 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;
 
@@ -221,11 +242,13 @@ 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
@@ -299,7 +322,7 @@ export class Mesh {
       this.constants.push({ location: ATTR_WEIGHTS, value: ABSENT_ATTRIBUTE['weights'] });
     } 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;
@@ -308,7 +331,7 @@ export class Mesh {
       this.constants.push({ location: ATTR_WEIGHTS2, value: ABSENT_ATTRIBUTE['weights2'] });
     } 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;
@@ -316,9 +339,10 @@ export class Mesh {
       gl.disableVertexAttribArray(ATTR_TANGENT);
       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'] });
@@ -345,7 +369,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);
   }
@@ -364,7 +390,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);
   }
 
   /**
@@ -388,7 +414,14 @@ 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);
@@ -418,7 +451,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: WebGL2RenderingContext): void {
@@ -462,24 +495,49 @@ export class Mesh {
     }
   }
 
+  /**
+   * 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(
     gl: WebGL2RenderingContext,
     location: number,
     data: Float32Array,
     size: number,
     usage: number = gl.STATIC_DRAW,
+    packing: AttributePacking = 'float',
   ): WebGLBuffer {
     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. */
+  private attachShared(
+    gl: WebGL2RenderingContext,
+    location: number,
+    data: Float32Array,
+    size: number,
+    packing: AttributePacking,
+  ): void {
+    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/src/render/pointLightSelection.ts

@@ -204,10 +204,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/src/render/renderQuality.ts

@@ -50,6 +50,9 @@ 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';
 
@@ -220,6 +223,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`.
    *
@@ -973,6 +1004,7 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   lightVolumeSamples: 32,
   directionalShadowDepthLayers: 2,
   glassShadows: 'full',
+  pipelineCompile: 'wait',
   skinScattering: 'pre-integrated',
   directionalShadowMaxDistance: 6,
   directionalShadowMaxSlope: 3,
@@ -1140,6 +1172,7 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     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,
@@ -1298,6 +1331,11 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
       `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/src/render/rendererHarness.ts

@@ -58,8 +58,14 @@ export function recordingGl(
      * 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 };
   } = {},
 ) {
+  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. */
@@ -136,6 +142,13 @@ export function recordingGl(
     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. */
@@ -173,6 +186,7 @@ export function recordingGl(
       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,
@@ -200,6 +214,7 @@ export function recordingGl(
     /* 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: unknown, pname: unknown) => {
+      if (pname === 0x91b1) return compiling.done;
       if (pname === constants.ACTIVE_UNIFORMS) return uniforms.length;
       if (pname === constants.ACTIVE_ATTRIBUTES) return 0;
       if (pname !== constants.LINK_STATUS) return true;

package/src/render/screenSpaceReflection.ts

@@ -370,7 +370,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/src/render/shader.ts

@@ -26,6 +26,65 @@ export function compileProgram(
   return program;
 }
 
+/**
+ * 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 function startProgram(
+  gl: WebGL2RenderingContext,
+  vertexSource: string,
+  fragmentSource: string,
+  label: string,
+): StartedProgram {
+  const stage = (type: number, source: string, name: string): WebGLShader => {
+    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: WebGL2RenderingContext, started: StartedProgram): WebGLProgram {
+  const { program, vertex, fragment, label } = started;
+  const fail = (what: string, log: string | null): never => {
+    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/src/render/shaders/boneAnimation.ts

@@ -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/src/render/shaders/depth.ts

@@ -5,6 +5,7 @@ import { CUTOUT_DITHER_GLSL } from '../cutoutDither.ts';
 import { SKINNING_GLSL } from './skinning.ts';
 import { CLOTH_BINDING_GLSL } from './clothBinding.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.ts';
+import { BONE_ANIMATION_GLSL } from './boneAnimation.ts';
 
 /**
  * Depth-only shadow pass. Its optional peel mode rejects the first recorded
@@ -78,6 +79,17 @@ uniform vec2 uUvOffset;
 uniform vec2 uAlphaCutout;
 #endif
 
+#if ANIMATED
+/*
+ * **A bone animation's, after every other declaration** so no field of the variants before it
+ * moves: the grain lane the vertex's bone rides in, the scene's clock, and the chunk the colour
+ * pass runs — the same expression, or a crowd's shadow stands still while the crowd moves.
+ */
+layout(location = 8) in float aGrain;
+uniform float uSceneTime;
+${BONE_ANIMATION_GLSL}
+#endif
+
 out vec4 vLightPosition;
 #if CUTOUT
 /* The texture coordinate and, in z, the texture-array layer the face wears. */
@@ -99,6 +111,12 @@ void main() {
 #else
   vec4 local = vec4(aPosition, 1.0);
 #endif
+#if ANIMATED
+  /* Turned and placed as the colour pass turns and places it; its normal and tangent unused. */
+  vec3 animatedNormal = vec3(0.0, 1.0, 0.0);
+  vec3 animatedTangent = vec3(1.0, 0.0, 0.0);
+  local = vec4(boneAnimate(local.xyz, animatedNormal, animatedTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
@@ -148,14 +166,14 @@ void main() {
 /** The rigid variant: the world, a prop, a mesh with no rig behind it. */
 export const DEPTH_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false },
+  { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false },
   'depth',
 );
 
 /** The skinned variant, which reads a joint palette and moves the vertex by it. */
 export const DEPTH_SKINNED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false },
+  { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false },
   'depth-skinned',
 );
 
@@ -169,7 +187,7 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(
  */
 export const DEPTH_INSTANCED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false },
+  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: false },
   'depth-instanced',
 );
 
@@ -185,16 +203,33 @@ export const DEPTH_INSTANCED_VERT = resolveConditionals(
  */
 export const DEPTH_CUTOUT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false },
+  { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false, ANIMATED: false },
   'depth-cutout',
 );
 
 export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false },
+  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: false },
   'depth-instanced-cutout',
 );
 
+/**
+ * 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 const DEPTH_INSTANCED_ANIMATED_VERT = resolveConditionals(
+  DEPTH_VERT_SOURCE,
+  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: true },
+  'depth-instanced-animated',
+);
+
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT = resolveConditionals(
+  DEPTH_VERT_SOURCE,
+  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: true },
+  'depth-instanced-animated-cutout',
+);
+
 export const DEPTH_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
@@ -269,27 +304,27 @@ void main() {
  */
 export const GLASS_TINT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true },
+  { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false },
   'glass-tint',
 );
 export const GLASS_TINT_SKINNED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true },
+  { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false },
   'glass-tint-skinned',
 );
 export const GLASS_TINT_INSTANCED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true },
+  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true, ANIMATED: false },
   'glass-tint-instanced',
 );
 export const GLASS_TINT_CUTOUT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true },
+  { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true, ANIMATED: false },
   'glass-tint-cutout',
 );
 export const GLASS_TINT_INSTANCED_CUTOUT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true },
+  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true, ANIMATED: false },
   'glass-tint-instanced-cutout',
 );