@driftengine/core 4.9.0 → 4.11.0

package/src/render/boneAnimation.ts

@@ -0,0 +1,223 @@
+/**
+ * Vertex animation from bone textures: a clip that turns and places each bone frame by frame,
+ * which every vertex of an instanced batch's mesh follows — one bone a vertex, named by the mesh's
+ * second coordinates — at a moment each instance keeps its own clock for.
+ *
+ * **What a crowd is built from.** A rigged character skinned per draw costs a palette upload and a
+ * draw each; a crowd of them, played back from a clip a mesh, costs nothing on the processor once
+ * the clip is on the device, and every instance moves at the frame's rate on its own clock rather
+ * than in step with the others. What it gives up against skinning is the blend: a vertex follows
+ * exactly one bone, so a joint bends hard, which at a crowd's distance is what such clips are made
+ * for.
+ *
+ * **The vertex's bone is its second coordinates' u times `boneScale`**, rounded: a mesh's second
+ * coordinates (`MeshData.lightmapUvs`) are free on a crowd, which bakes no lightmap, and the format
+ * that writes one bone a sixty-fourth of u is the format this reads with `boneScale: 64`.
+ *
+ * **A frame's turn and place move the vertex as the bone does**: the turn about the mesh's origin,
+ * then the place added — `turn(q, p) + t` — and its normal and tangent turned with it. Between two
+ * frames both are blended: the places linearly, the turns normalised along the shorter arc. The
+ * moment is `(sceneTime × rate + phase) × framesPerSecond`, looping, where the scene's time is the
+ * clock `setAnimationTime` sets, once a frame before the shadows, and each instance's phase and
+ * rate are `MeshInstances.clocks`.
+ *
+ * Backend-neutral: both backends upload what `packBoneAnimation` packs and run
+ * `shaders/boneAnimation.ts`, which is `animateBoneVertex` below, line for line.
+ */
+import type { MeshInstances } from './instances.ts';
+
+/** A clip on the device, from `createBoneAnimation`. Opaque but for its size. */
+export interface BoneAnimationHandle {
+  readonly bones: number;
+  readonly frames: number;
+}
+
+/** A clip, as a caller hands it to `createBoneAnimation`. */
+export interface BoneAnimationClip {
+  /** Bones each frame holds. */
+  readonly bones: number;
+  /** Frames, played in order and looped. */
+  readonly frames: number;
+  readonly framesPerSecond: number;
+  /** Where each bone puts what it carries: three floats a bone, bone by bone, frame by frame. */
+  readonly places: Float32Array;
+  /** Each bone's turn: a unit quaternion, x y z w, laid out as `places` is. */
+  readonly turns: Float32Array;
+  /** How many bones one unit of the second coordinates' u counts: `bones` unless given. */
+  readonly boneScale?: number;
+}
+
+/** A clip as textures hold it: a texel a bone a frame, bones across and frames down. */
+export interface BoneAnimationTexels {
+  readonly bones: number;
+  readonly frames: number;
+  readonly framesPerSecond: number;
+  readonly boneScale: number;
+  /** RGBA floats: the place, and 1. */
+  readonly places: Float32Array;
+  /** RGBA floats: the turn, normalised. */
+  readonly turns: Float32Array;
+}
+
+/**
+ * The most bones or frames a clip may have: WebGL2's guaranteed texture size. A clip past it is
+ * refused rather than cut, since a cut clip is a crowd frozen at its last row.
+ */
+export const MAX_BONE_TEXTURE_SIZE = 2048;
+
+/** A clip checked and packed into its two textures' texels. Runs once, when the clip is made. */
+export function packBoneAnimation(clip: BoneAnimationClip): BoneAnimationTexels {
+  const { bones, frames, framesPerSecond } = clip;
+  for (const [name, value] of [
+    ['bones', bones],
+    ['frames', frames],
+  ] as const) {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_BONE_TEXTURE_SIZE) {
+      throw new Error(
+        `createBoneAnimation: ${name} is ${value}; a whole number from 1 to ${MAX_BONE_TEXTURE_SIZE}`,
+      );
+    }
+  }
+  if (!(framesPerSecond > 0)) {
+    throw new Error(`createBoneAnimation: framesPerSecond is ${framesPerSecond}; above zero`);
+  }
+  const count = bones * frames;
+  if (clip.places.length !== count * 3 || clip.turns.length !== count * 4) {
+    throw new Error(
+      `createBoneAnimation: ${bones} bones over ${frames} frames is ${count * 3} places and ` +
+        `${count * 4} turn numbers, and was given ${clip.places.length} and ${clip.turns.length}`,
+    );
+  }
+  const boneScale = clip.boneScale ?? bones;
+  if (!(boneScale > 0)) {
+    throw new Error(`createBoneAnimation: boneScale is ${boneScale}; above zero`);
+  }
+  const places = new Float32Array(count * 4);
+  const turns = new Float32Array(count * 4);
+  for (let i = 0; i < count; i++) {
+    places[i * 4] = clip.places[i * 3] as number;
+    places[i * 4 + 1] = clip.places[i * 3 + 1] as number;
+    places[i * 4 + 2] = clip.places[i * 3 + 2] as number;
+    places[i * 4 + 3] = 1;
+    const x = clip.turns[i * 4] as number;
+    const y = clip.turns[i * 4 + 1] as number;
+    const z = clip.turns[i * 4 + 2] as number;
+    const w = clip.turns[i * 4 + 3] as number;
+    const length = Math.hypot(x, y, z, w);
+    /* A zero turn is no turn, rather than a NaN through every vertex that reads it. */
+    const scale = length > 0 ? 1 / length : 0;
+    turns[i * 4] = x * scale;
+    turns[i * 4 + 1] = y * scale;
+    turns[i * 4 + 2] = z * scale;
+    turns[i * 4 + 3] = length > 0 ? w * scale : 1;
+  }
+  return { bones, frames, framesPerSecond, boneScale, places, turns };
+}
+
+/** How wide a batch's clock texture is: one row up to this many instances, then more rows. */
+export const CLOCK_TEXTURE_WIDTH = 1024;
+
+/**
+ * Each instance's clock into `out`, two floats an instance — its phase in seconds and its rate —
+ * from `data.clocks`, and `(0, 1)` where it gives none: every instance at the clip's own speed,
+ * in step. `out` is the batch's, sized once.
+ */
+export function packInstanceClocks(data: MeshInstances, out: Float32Array): void {
+  const clocks = data.clocks;
+  const count = Math.min(data.count, out.length / 2);
+  for (let i = 0; i < count; i++) {
+    out[i * 2] = clocks === undefined ? 0 : ((clocks[i * 2] as number | undefined) ?? 0);
+    out[i * 2 + 1] = clocks === undefined ? 1 : ((clocks[i * 2 + 1] as number | undefined) ?? 1);
+  }
+}
+
+/**
+ * Which two frames a moment falls between, and how far: what the shader reads. Looped, with a
+ * moment before the clip's start counted back from its end. **The first frame is clamped to the
+ * last**, with the blend left at whatever reaches the next: a moment a hair short of the loop that
+ * float error rounds up to `frames` lands on the last frame blended fully into the first, which is
+ * the first frame — the right answer — where an index of `frames` would read past the texture.
+ */
+export function boneFrame(
+  moment: number,
+  frames: number,
+  out: { first: number; second: number; blend: number },
+): void {
+  const wrapped = moment - frames * Math.floor(moment / frames);
+  const first = Math.min(Math.floor(wrapped), frames - 1);
+  out.first = first;
+  out.second = first + 1 === frames ? 0 : first + 1;
+  out.blend = Math.min(Math.max(wrapped - first, 0), 1);
+}
+
+const scratchFrame = { first: 0, second: 0, blend: 0 };
+const mixed = new Float32Array(4);
+
+/** `v` turned by the unit quaternion `q`, into `out`. */
+function turn(q: ArrayLike<number>, at: number, v: ArrayLike<number>, out: Float32Array): void {
+  const qx = q[at] as number;
+  const qy = q[at + 1] as number;
+  const qz = q[at + 2] as number;
+  const qw = q[at + 3] as number;
+  const vx = v[0] as number;
+  const vy = v[1] as number;
+  const vz = v[2] as number;
+  /* v + 2 q.xyz × (q.xyz × v + q.w v), as the shader writes it. */
+  const cx = qy * vz - qz * vy + qw * vx;
+  const cy = qz * vx - qx * vz + qw * vy;
+  const cz = qx * vy - qy * vx + qw * vz;
+  out[0] = vx + 2 * (qy * cz - qz * cy);
+  out[1] = vy + 2 * (qz * cx - qx * cz);
+  out[2] = vz + 2 * (qx * cy - qy * cx);
+}
+
+/**
+ * Where the clip puts a vertex at rest at `position`, following `bone`, at the scene's `time` on an
+ * instance clock of `phase` and `rate`, into `out`. The processor's statement of what the shader
+ * does, which the tests hold the arithmetic to and a device check holds the shader to.
+ */
+export function animateBoneVertex(
+  clip: BoneAnimationTexels,
+  bone: number,
+  position: ArrayLike<number>,
+  time: number,
+  phase: number,
+  rate: number,
+  out: Float32Array,
+): void {
+  boneFrame((time * rate + phase) * clip.framesPerSecond, clip.frames, scratchFrame);
+  const { first, second, blend } = scratchFrame;
+  const b = Math.min(Math.max(bone, 0), clip.bones - 1);
+  const a = (first * clip.bones + b) * 4;
+  const c = (second * clip.bones + b) * 4;
+  const q = clip.turns;
+  /* The shorter arc: a quaternion and its negation are one turn. */
+  const sign =
+    (q[a] as number) * (q[c] as number) +
+      (q[a + 1] as number) * (q[c + 1] as number) +
+      (q[a + 2] as number) * (q[c + 2] as number) +
+      (q[a + 3] as number) * (q[c + 3] as number) <
+    0
+      ? -1
+      : 1;
+  for (let k = 0; k < 4; k++) {
+    mixed[k] = (q[a + k] as number) * (1 - blend) + sign * (q[c + k] as number) * blend;
+  }
+  const length = Math.hypot(
+    mixed[0] as number,
+    mixed[1] as number,
+    mixed[2] as number,
+    mixed[3] as number,
+  );
+  for (let k = 0; k < 4; k++) mixed[k] = (mixed[k] as number) / length;
+  turn(mixed, 0, position, out);
+  const p = clip.places;
+  for (let k = 0; k < 3; k++) {
+    out[k] = (out[k] as number) + (p[a + k] as number) * (1 - blend) + (p[c + k] as number) * blend;
+  }
+}
+
+/** The bone a vertex follows, from its second coordinates' u: what the shader rounds. */
+export function boneOf(u: number, boneScale: number): number {
+  return Math.floor(u * boneScale + 0.5);
+}

package/src/render/compressedSource.ts

@@ -2,25 +2,106 @@
  * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
  * both backends share: whether this device takes it as blocks.
  *
- * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
- * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
- * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
- * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
- * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
- * answer is no; a caller handing a source this device cannot take is refused by name.
+ * **Uploaded as it is, or not at all.** A block format costs a byte a texel on the GPU (BC7, ETC2
+ * with alpha, ASTC 4x4) or half of one (BC1, ETC2 without) against four for RGBA, and keeps the mip
+ * chain its author built rather than one a box filter makes. **Three families, and a device has the
+ * ones it has**: desktops sample BC, phones ETC2 and ASTC, and few anything else. A device that
+ * cannot sample a format gets nothing from its blocks, and core does not convert them: the loader
+ * in `@driftengine/assets` asks `uploadsCompressed` first, and where the answer is no it decodes
+ * them — and encodes ETC2 where the device takes that — off the main thread. A caller handing a
+ * source this device cannot take is refused by name.
  *
  * Backend-neutral, because both backends must agree on what they accept before either touches a
- * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * device. `@driftengine/drft`'s `BcFormat` is the BC part of `BlockFormat`; core imports nothing
  * from that package, and a format added there without a twin here fails where the loader passes one
  * to the other, at compile time.
  */
 
-/** BC1 to BC5 and BC7. BC6H and the signed forms are not among them. */
-export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7';
+/**
+ * BC1 to BC5 and BC7; ETC2's three and EAC's two; and ASTC at every block size the LDR profile has.
+ * BC6H, ASTC HDR and the signed forms are not among them.
+ */
+export type BlockFormat =
+  | 'bc1'
+  | 'bc2'
+  | 'bc3'
+  | 'bc4'
+  | 'bc5'
+  | 'bc7'
+  | 'etc2-rgb8'
+  | 'etc2-rgb8a1'
+  | 'etc2-rgba8'
+  | 'eac-r11'
+  | 'eac-rg11'
+  | 'astc-4x4'
+  | 'astc-5x4'
+  | 'astc-5x5'
+  | 'astc-6x5'
+  | 'astc-6x6'
+  | 'astc-8x5'
+  | 'astc-8x6'
+  | 'astc-8x8'
+  | 'astc-10x5'
+  | 'astc-10x6'
+  | 'astc-10x8'
+  | 'astc-10x10'
+  | 'astc-12x10'
+  | 'astc-12x12';
+
+/** The formats with no sRGB form: one or two channels of data, never colour. */
+type LinearOnly = 'bc4' | 'bc5' | 'eac-r11' | 'eac-rg11';
 
 /** A format as a device offers it: the colour space is part of the name, as WebGPU's are. */
-export type CompressedTextureFormat =
-  'bc1' | 'bc1-srgb' | 'bc2' | 'bc2-srgb' | 'bc3' | 'bc3-srgb' | 'bc4' | 'bc5' | 'bc7' | 'bc7-srgb';
+export type CompressedTextureFormat = BlockFormat | `${Exclude<BlockFormat, LinearOnly>}-srgb`;
+
+/** A format's block: how many texels across and down, and how many bytes it takes. */
+export interface BlockShape {
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: number;
+}
+
+const shape = (width: number, height: number, bytes: number): BlockShape => ({
+  width,
+  height,
+  bytes,
+});
+
+/** Every format's block. ASTC's are sixteen bytes whatever their size, which is its whole idea. */
+export const BLOCK_SHAPES: Readonly<Record<BlockFormat, BlockShape>> = {
+  bc1: shape(4, 4, 8),
+  bc2: shape(4, 4, 16),
+  bc3: shape(4, 4, 16),
+  bc4: shape(4, 4, 8),
+  bc5: shape(4, 4, 16),
+  bc7: shape(4, 4, 16),
+  'etc2-rgb8': shape(4, 4, 8),
+  'etc2-rgb8a1': shape(4, 4, 8),
+  'etc2-rgba8': shape(4, 4, 16),
+  'eac-r11': shape(4, 4, 8),
+  'eac-rg11': shape(4, 4, 16),
+  'astc-4x4': shape(4, 4, 16),
+  'astc-5x4': shape(5, 4, 16),
+  'astc-5x5': shape(5, 5, 16),
+  'astc-6x5': shape(6, 5, 16),
+  'astc-6x6': shape(6, 6, 16),
+  'astc-8x5': shape(8, 5, 16),
+  'astc-8x6': shape(8, 6, 16),
+  'astc-8x8': shape(8, 8, 16),
+  'astc-10x5': shape(10, 5, 16),
+  'astc-10x6': shape(10, 6, 16),
+  'astc-10x8': shape(10, 8, 16),
+  'astc-10x10': shape(10, 10, 16),
+  'astc-12x10': shape(12, 10, 16),
+  'astc-12x12': shape(12, 12, 16),
+};
+
+/** Every format's family, which is what a device offers or does not. */
+export function blockFamily(format: BlockFormat): 'bc' | 'etc2' | 'astc' {
+  if (format.startsWith('bc')) return 'bc';
+  if (format.startsWith('astc')) return 'astc';
+  return 'etc2';
+}
 
 /** Block-compressed texels with their stored mip chain, level 0 first. */
 export interface CompressedTextureSource {
@@ -52,15 +133,10 @@ export function compressedLayers(
   return sources as readonly CompressedTextureSource[];
 }
 
-/** Bytes per 4x4 block. */
-export const BLOCK_BYTES: Readonly<Record<BlockFormat, number>> = {
-  bc1: 8,
-  bc2: 16,
-  bc3: 16,
-  bc4: 8,
-  bc5: 16,
-  bc7: 16,
-};
+/** Bytes per block. See `BLOCK_SHAPES` for the block's size, which is not always 4x4. */
+export const BLOCK_BYTES: Readonly<Record<BlockFormat, number>> = Object.fromEntries(
+  Object.entries(BLOCK_SHAPES).map(([format, block]) => [format, block.bytes]),
+) as Record<BlockFormat, number>;
 
 /** Whether `source` is a compressed source rather than an image. */
 export function isCompressedSource(source: unknown): source is CompressedTextureSource {
@@ -79,13 +155,15 @@ export function compressedFormatName(
   srgb: boolean,
 ): CompressedTextureFormat | null {
   if (!srgb) return format;
-  return format === 'bc4' || format === 'bc5' ? null : `${format}-srgb`;
+  return format === 'bc4' || format === 'bc5' || format === 'eac-r11' || format === 'eac-rg11'
+    ? null
+    : `${format}-srgb`;
 }
 
 /**
  * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
- * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
- * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a block
+ * texture, and WebGL2's extensions say the same, so a 6x6 image in 4x4 blocks is decoded rather than
  * refused. What would make that wrong is a device that pads; none is relied on here.
  */
 export function uploadsCompressed(
@@ -96,14 +174,26 @@ export function uploadsCompressed(
   available: readonly CompressedTextureFormat[],
 ): boolean {
   const name = compressedFormatName(format, srgb);
-  return name !== null && width % 4 === 0 && height % 4 === 0 && available.includes(name);
+  const block = BLOCK_SHAPES[format];
+  return (
+    name !== null &&
+    width % block.width === 0 &&
+    height % block.height === 0 &&
+    available.includes(name)
+  );
 }
 
 /** The bytes level `level` of a `width` by `height` image takes: whole blocks, one at least. */
-function levelBytes(format: BlockFormat, width: number, height: number, level: number): number {
+export function levelBytes(
+  format: BlockFormat,
+  width: number,
+  height: number,
+  level: number,
+): number {
   const w = Math.max(1, width >> level);
   const h = Math.max(1, height >> level);
-  return Math.ceil(w / 4) * Math.ceil(h / 4) * BLOCK_BYTES[format];
+  const block = BLOCK_SHAPES[format];
+  return Math.ceil(w / block.width) * Math.ceil(h / block.height) * block.bytes;
 }
 
 /**
@@ -162,11 +252,13 @@ export function compressedRefusal(
   available: readonly CompressedTextureFormat[],
 ): string {
   const asked = `${format.toUpperCase()}${srgb ? ' sRGB' : ''} at ${width}x${height}`;
-  const offered = available.length === 0 ? 'no BC format' : available.join(', ');
+  const offered = available.length === 0 ? 'no block format' : available.join(', ');
+  const block = BLOCK_SHAPES[format];
   return (
     `createSurfaceTexture: this device cannot take ${asked} as blocks — it offers ${offered}, and ` +
-    'a BC texture must be whole 4x4 blocks at level 0. Decode it first (decodeBc in ' +
-    '@driftengine/assets), or ask renderer.compressedFormats before choosing.'
+    `the texture must be whole ${block.width}x${block.height} blocks at level 0. Decode it first ` +
+    '(decodeBc, or encodeEtc2 for a device that takes ETC2, in @driftengine/assets), or ask ' +
+    'renderer.compressedFormats before choosing.'
   );
 }
 

package/src/render/glCompressed.ts

@@ -28,6 +28,42 @@ const INTERNAL: Readonly<Record<CompressedTextureFormat, number>> = {
   bc5: 0x8dbd, // COMPRESSED_RED_GREEN_RGTC2_EXT
   bc7: 0x8e8c, // COMPRESSED_RGBA_BPTC_UNORM_EXT
   'bc7-srgb': 0x8e8d, // COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT
+  'eac-r11': 0x9270, // COMPRESSED_R11_EAC
+  'eac-rg11': 0x9272, // COMPRESSED_RG11_EAC
+  'etc2-rgb8': 0x9274, // COMPRESSED_RGB8_ETC2
+  'etc2-rgb8-srgb': 0x9275, // COMPRESSED_SRGB8_ETC2
+  'etc2-rgb8a1': 0x9276, // COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2
+  'etc2-rgb8a1-srgb': 0x9277, // COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2
+  'etc2-rgba8': 0x9278, // COMPRESSED_RGBA8_ETC2_EAC
+  'etc2-rgba8-srgb': 0x9279, // COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
+  'astc-4x4': 0x93b0, // COMPRESSED_RGBA_ASTC_4x4_KHR
+  'astc-4x4-srgb': 0x93d0, // COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR
+  'astc-5x4': 0x93b1, // COMPRESSED_RGBA_ASTC_5x4_KHR
+  'astc-5x4-srgb': 0x93d1, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x4_KHR
+  'astc-5x5': 0x93b2, // COMPRESSED_RGBA_ASTC_5x5_KHR
+  'astc-5x5-srgb': 0x93d2, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x5_KHR
+  'astc-6x5': 0x93b3, // COMPRESSED_RGBA_ASTC_6x5_KHR
+  'astc-6x5-srgb': 0x93d3, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x5_KHR
+  'astc-6x6': 0x93b4, // COMPRESSED_RGBA_ASTC_6x6_KHR
+  'astc-6x6-srgb': 0x93d4, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x6_KHR
+  'astc-8x5': 0x93b5, // COMPRESSED_RGBA_ASTC_8x5_KHR
+  'astc-8x5-srgb': 0x93d5, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x5_KHR
+  'astc-8x6': 0x93b6, // COMPRESSED_RGBA_ASTC_8x6_KHR
+  'astc-8x6-srgb': 0x93d6, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x6_KHR
+  'astc-8x8': 0x93b7, // COMPRESSED_RGBA_ASTC_8x8_KHR
+  'astc-8x8-srgb': 0x93d7, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x8_KHR
+  'astc-10x5': 0x93b8, // COMPRESSED_RGBA_ASTC_10x5_KHR
+  'astc-10x5-srgb': 0x93d8, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x5_KHR
+  'astc-10x6': 0x93b9, // COMPRESSED_RGBA_ASTC_10x6_KHR
+  'astc-10x6-srgb': 0x93d9, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x6_KHR
+  'astc-10x8': 0x93ba, // COMPRESSED_RGBA_ASTC_10x8_KHR
+  'astc-10x8-srgb': 0x93da, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x8_KHR
+  'astc-10x10': 0x93bb, // COMPRESSED_RGBA_ASTC_10x10_KHR
+  'astc-10x10-srgb': 0x93db, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x10_KHR
+  'astc-12x10': 0x93bc, // COMPRESSED_RGBA_ASTC_12x10_KHR
+  'astc-12x10-srgb': 0x93dc, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x10_KHR
+  'astc-12x12': 0x93bd, // COMPRESSED_RGBA_ASTC_12x12_KHR
+  'astc-12x12-srgb': 0x93dd, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x12_KHR
 };
 
 const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat[]])[] = [
@@ -35,6 +71,53 @@ const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat
   ['WEBGL_compressed_texture_s3tc_srgb', ['bc1-srgb', 'bc2-srgb', 'bc3-srgb']],
   ['EXT_texture_compression_rgtc', ['bc4', 'bc5']],
   ['EXT_texture_compression_bptc', ['bc7', 'bc7-srgb']],
+  /* The two families a phone has: every GLES 3 device takes ETC2, and most take ASTC beside it. */
+  [
+    'WEBGL_compressed_texture_etc',
+    [
+      'etc2-rgb8',
+      'etc2-rgb8-srgb',
+      'etc2-rgb8a1',
+      'etc2-rgb8a1-srgb',
+      'etc2-rgba8',
+      'etc2-rgba8-srgb',
+      'eac-r11',
+      'eac-rg11',
+    ],
+  ],
+  [
+    'WEBGL_compressed_texture_astc',
+    [
+      'astc-4x4',
+      'astc-4x4-srgb',
+      'astc-5x4',
+      'astc-5x4-srgb',
+      'astc-5x5',
+      'astc-5x5-srgb',
+      'astc-6x5',
+      'astc-6x5-srgb',
+      'astc-6x6',
+      'astc-6x6-srgb',
+      'astc-8x5',
+      'astc-8x5-srgb',
+      'astc-8x6',
+      'astc-8x6-srgb',
+      'astc-8x8',
+      'astc-8x8-srgb',
+      'astc-10x5',
+      'astc-10x5-srgb',
+      'astc-10x6',
+      'astc-10x6-srgb',
+      'astc-10x8',
+      'astc-10x8-srgb',
+      'astc-10x10',
+      'astc-10x10-srgb',
+      'astc-12x10',
+      'astc-12x10-srgb',
+      'astc-12x12',
+      'astc-12x12-srgb',
+    ],
+  ],
 ];
 
 /**

package/src/render/globalMediumPass.ts

@@ -20,6 +20,8 @@ export interface MediumLight {
   readonly sunShadow: number;
   /** World → light clip, **uncorrected**: the shader does its own `* 0.5 + 0.5`. */
   readonly lightViewProj: ReadonlyMat4;
+  /** The same for the sun's moving layer, whose shadow pass may be drawn with its own. */
+  readonly movingLightViewProj: ReadonlyMat4;
   /** The sun's static, moving and peeled maps, as one array. See `shadowMap.ts`. */
   readonly sunShadows: WebGLTexture;
   readonly peeledEnabled: boolean;
@@ -240,6 +242,11 @@ export class GlobalMediumPass {
     gl.uniform1i(u['uSteps'] ?? null, steps);
     gl.uniform1f(u['uSunShadow'] ?? null, light.sunShadow);
     gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, light.lightViewProj as Float32Array);
+    gl.uniformMatrix4fv(
+      u['uMovingLightViewProj'] ?? null,
+      false,
+      light.movingLightViewProj as Float32Array,
+    );
     gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, light.peeledEnabled ? 1 : 0);
 
     gl.drawArrays(gl.TRIANGLES, 0, 3);

package/src/render/indexWidth.ts

@@ -0,0 +1,27 @@
+/**
+ * A mesh's indices in the narrowest type that holds them: sixteen bits where every vertex can be
+ * named in sixteen, thirty-two otherwise — half the index memory for every mesh of 65,536 vertices
+ * or fewer, which is most of them. Lossless because `validateMeshData` has already refused an
+ * index past the last vertex.
+ *
+ * **Padded to an even count**, so the sixteen-bit copy is a whole number of four-byte words: WebGPU
+ * writes a buffer only in whole words. The extra index is never drawn, since every draw counts the
+ * mesh's own indices. What would make this wrong is a draw that counts the buffer instead.
+ *
+ * **What it costs** is a copy of the indices while the mesh is built, let go once they are on the
+ * device; and every draw of the mesh has to say which width it holds, which is why the width
+ * travels with the mesh rather than being worked out where it is drawn.
+ */
+
+/** The most vertices sixteen-bit indices can name: every index below 65,536. */
+export const MAX_UINT16_VERTICES = 65536;
+
+export function compactIndices(
+  indices: Uint32Array,
+  vertexCount: number,
+): Uint16Array | Uint32Array {
+  if (vertexCount > MAX_UINT16_VERTICES) return indices;
+  const out = new Uint16Array(indices.length + (indices.length % 2));
+  out.set(indices);
+  return out;
+}

package/src/render/instances.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;
@@ -140,6 +148,8 @@ export function packInstances(instances: MeshInstances, out: Float32Array): void
   }
 }
 
+import type { BoneAnimationHandle } from './boneAnimation.ts';
+
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
   /**
@@ -154,4 +164,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/src/render/lightBudget.ts

@@ -276,6 +276,17 @@ 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/src/render/lightMatrix.ts

@@ -67,3 +67,18 @@ export function computeLightMatrix(
   // 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: ArrayLike<number>): number {
+  const length = Math.hypot(m[2] as number, m[6] as number, m[10] as number);
+  return length > 0 ? 2 / length : 1;
+}

package/src/render/lightmap.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.