@driftengine/core 4.9.0 → 4.11.0

package/src/render/backend/webgpu/depthPass.ts

@@ -3,6 +3,8 @@ import {
   DEPTH_CUTOUT_FRAG_WGSL,
   DEPTH_CUTOUT_VERT_WGSL,
   DEPTH_FRAG_WGSL,
+  DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL,
+  DEPTH_INSTANCED_ANIMATED_VERT_WGSL,
   DEPTH_INSTANCED_CUTOUT_VERT_WGSL,
   DEPTH_INSTANCED_VERT_WGSL,
   DEPTH_SKINNED_VERT_WGSL,
@@ -13,6 +15,7 @@ import { vertexConstants } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
 import type { ClothViews } from './clothTextures.ts';
+import type { AnimationViews } from './flatPass.ts';
 
 /**
  * The shadow pass: the world drawn from the light, into a depth map.
@@ -52,6 +55,17 @@ const CLOTH_TEXTURES = [
   DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothRest,
 ] as const;
 
+/** A bone animation's three textures, at the bindings both animated depth variants declare them. */
+const ANIMATION_TEXTURES = [
+  DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBonePlaces,
+  DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBoneTurns,
+  DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uInstanceClocks,
+] as const;
+export const DEPTH_INSTANCED_ANIMATED_VERT_FIELDS =
+  DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.fields;
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_FIELDS =
+  DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT.fields;
+
 const VISIBILITY_VERTEX = 0x1;
 const VISIBILITY_FRAGMENT = 0x2;
 
@@ -82,10 +96,19 @@ export function createDepthBindGroupLayout(
    * no cutout caster pays nothing.
    */
   cutout = false,
+  /** An instanced caster playing a bone animation: its three vertex textures. */
+  animated = false,
 ): GPUBindGroupLayout {
   return device.createBindGroupLayout({
-    label: skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout',
+    label: `${skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout'}${animated ? '.animated' : ''}`,
     entries: [
+      ...(animated
+        ? ANIMATION_TEXTURES.map((binding) => ({
+            binding: binding.texture,
+            visibility: VISIBILITY_VERTEX,
+            texture: { sampleType: 'unfilterable-float' as GPUTextureSampleType },
+          }))
+        : []),
       /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
          coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
          palette. naga declares a sampler for it and nothing ever reads one. */
@@ -174,6 +197,8 @@ export function createDepthBindGroup(
   cutout: { readonly view: GPUTextureView; readonly sampler: GPUSampler } | null = null,
   /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
   cloth: ClothViews | null = null,
+  /** An animated caster's clip and clocks. See `AnimationViews`. */
+  animation: AnimationViews | null = null,
 ): GPUBindGroup {
   return device.createBindGroup({
     label:
@@ -208,6 +233,13 @@ export function createDepthBindGroup(
             { binding: CUTOUT_MAP.sampler, resource: cutout.sampler },
           ]
         : []),
+      ...(animation !== null
+        ? [
+            { binding: ANIMATION_TEXTURES[0].texture, resource: animation.places },
+            { binding: ANIMATION_TEXTURES[1].texture, resource: animation.turns },
+            { binding: ANIMATION_TEXTURES[2].texture, resource: animation.clocks },
+          ]
+        : []),
     ],
   });
 }
@@ -256,6 +288,8 @@ export function depthPipeline(
   skinEight = false,
   /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
   cloth = false,
+  /** An instanced caster playing a bone animation. The key must carry it. */
+  animated = false,
 ): GPURenderPipeline {
   return cache.get(key, () => ({
     label: key,
@@ -263,15 +297,22 @@ export function depthPipeline(
     vertex: {
       module: shaderModule(
         device,
-        cutout
-          ? instanced
-            ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
-            : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
-          : instanced
-            ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
-            : skinned
-              ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
-              : { label: 'depth.vert', code: DEPTH_VERT_WGSL },
+        animated
+          ? cutout
+            ? {
+                label: 'depth.instanced.animated.cutout.vert',
+                code: DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL,
+              }
+            : { label: 'depth.instanced.animated.vert', code: DEPTH_INSTANCED_ANIMATED_VERT_WGSL }
+          : cutout
+            ? instanced
+              ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
+              : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
+            : instanced
+              ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+              : skinned
+                ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+                : { label: 'depth.vert', code: DEPTH_VERT_WGSL },
       ),
       entryPoint: 'main',
       buffers: vertexBufferLayouts(present, instanced),

package/src/render/backend/webgpu/drawCommand.ts

@@ -2,7 +2,7 @@
  * One recorded draw, in the only shape this backend ever issues.
  *
  * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
- * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * same every time: a pipeline, a bind group with up to four dynamic offsets, some vertex
  * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
  * drawn except the values.
  *
@@ -21,14 +21,21 @@ const VERTEX_BUFFER_SLOTS = 8;
 export interface DrawCommand {
   pipeline: GPURenderPipeline | null;
   bindGroup: GPUBindGroup | null;
-  /** Dynamic offsets, held as two numbers rather than an array so a reset stays free. */
+  /**
+   * Dynamic offsets, held as numbers rather than an array so a reset stays free. Four only for a
+   * lit mesh: its draw's slot, its pass's, its material's and its view's, in binding order.
+   */
   offsetA: number;
   offsetB: number;
+  offsetC: number;
+  offsetD: number;
   offsetCount: number;
   /** Fixed length; `vertexCount` says how many slots are live. */
   readonly vertexBuffers: (GPUBuffer | null)[];
   vertexCount: number;
   indexBuffer: GPUBuffer | null;
+  /** How wide an index of `indexBuffer` is: a mesh's own, thirty-two bits for everything else. */
+  indexFormat: GPUIndexFormat;
   indexed: boolean;
   count: number;
   instances: number;
@@ -37,6 +44,12 @@ export interface DrawCommand {
    * cull's survivors, counted on the device. Null for every other draw.
    */
   indirect: GPUBuffer | null;
+  /**
+   * Render bundles to execute instead of everything above: a static list recorded once, replayed
+   * as one command. Held as the array `executeBundles` takes, kept by the list, so issuing it
+   * allocates nothing. Null for every other command, and put back to null by every take.
+   */
+  bundles: readonly GPURenderBundle[] | null;
 }
 
 export interface CommandPool {
@@ -52,14 +65,18 @@ function emptyCommand(): DrawCommand {
     bindGroup: null,
     offsetA: 0,
     offsetB: 0,
+    offsetC: 0,
+    offsetD: 0,
     offsetCount: 0,
     vertexBuffers: new Array<GPUBuffer | null>(VERTEX_BUFFER_SLOTS).fill(null),
     vertexCount: 0,
     indexBuffer: null,
+    indexFormat: 'uint32',
     indexed: false,
     count: 0,
     instances: 1,
     indirect: null,
+    bundles: null,
   };
 }
 
@@ -72,14 +89,18 @@ export function createCommandPool(capacity: number): CommandPool {
 /**
  * Hand out the next command, growing if a frame overruns.
  *
- * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
- * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ * The entry is **not cleared**, but for `bundles`. Every caller fills every field it uses, and
+ * clearing here would be a write per field per draw for no reader — the same reasoning the node
+ * arena uses. `bundles` is the exception because almost no caller knows it exists: a pooled command
+ * that once carried a static list's bundles and was then taken for an ordinary draw would replay the
+ * list instead, so the one field nobody fills is the one field put back here.
  */
 export function takeCommand(pool: CommandPool): number {
   const at = pool.taken;
   while (at >= pool.commands.length) pool.commands.push(emptyCommand());
   pool.taken = at + 1;
   if (pool.taken > pool.highWater) pool.highWater = pool.taken;
+  (pool.commands[at] as DrawCommand).bundles = null;
   return at;
 }
 

package/src/render/backend/webgpu/flatPass.ts

@@ -99,6 +99,20 @@ export interface StageBindings {
   readonly textures: Readonly<Record<string, TextureBinding>>;
   /** Each pipeline-overridable constant's id, by the GLSL name it was declared under. */
   readonly overrides?: Readonly<Record<string, number>>;
+  /**
+   * The second block, of the uniforms marked `// wgsl:material`: its binding, size and fields.
+   * Absent from a stage that marks none, which is every stage but the lit fragment's.
+   */
+  readonly materialUniforms?: number;
+  readonly materialSize?: number;
+  readonly materialFields?: StageBindings['fields'];
+  /**
+   * The vertex stage's view block, of the uniforms marked `// wgsl:view`: the camera, the light's
+   * matrix and the wind, which a pass settles. Absent from every stage but the lit vertex one.
+   */
+  readonly viewUniforms?: number;
+  readonly viewSize?: number;
+  readonly viewFields?: StageBindings['fields'];
 }
 
 /*
@@ -130,9 +144,16 @@ const VERTEX_BINDINGS = FLAT_BINDINGS.flatVert as unknown as Readonly<
 >;
 
 /** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
-export function flatVertexKey(skinned: boolean, morphed: boolean, instanced = false): string {
+export function flatVertexKey(
+  skinned: boolean,
+  morphed: boolean,
+  instanced = false,
+  /** Whether an instanced variant plays a bone animation. See `shaders/boneAnimation.ts`. */
+  animated = false,
+): string {
   const on: string[] = [];
   /* Alphabetical, because the generator's own `variantKey` sorts and the two keys must agree. */
+  if (animated) on.push('animated');
   if (instanced) on.push('instanced');
   if (morphed) on.push('morphed');
   if (skinned) on.push('skinned');
@@ -144,8 +165,9 @@ export function flatVertexBindings(
   skinned: boolean,
   morphed = false,
   instanced = false,
+  animated = false,
 ): StageBindings {
-  const key = flatVertexKey(skinned, morphed, instanced);
+  const key = flatVertexKey(skinned, morphed, instanced, animated);
   const found = VERTEX_BINDINGS[key];
   if (found === undefined) throw new Error(`flatPass: no vertex bindings for variant "${key}"`);
   return found;
@@ -221,6 +243,8 @@ for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
 }
 
 export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
+/** The animated instanced variant's block: the instanced fields, and the clip's `uBoneClip`. */
+export const FLAT_ANIMATED_VERT_FIELDS = FLAT_BINDINGS.flatVert['animated+instanced'].fields;
 /**
  * The **largest** variant's block, because one ring serves every draw.
  *
@@ -233,6 +257,35 @@ export const FLAT_VERT_SIZE = Math.max(
 );
 const FLAT_VERT_BINDING = PLAIN_VERTEX.uniforms;
 
+/*
+ * **The view block may be shorter in a variant, never different.** One slot serves every lit draw
+ * of a pass, plain and instanced alike, so every field a variant's view block declares must sit
+ * where the plain variant has it. The instanced variant declares no wind, and its block is the plain
+ * one's first two matrices.
+ */
+const PLAIN_VIEW_FIELDS = PLAIN_VERTEX.viewFields ?? {};
+for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
+  if (bindings.viewUniforms !== PLAIN_VERTEX.viewUniforms) {
+    throw new Error(`flatPass: vertex variant "${key}" binds its view block elsewhere`);
+  }
+  for (const [field, here] of Object.entries(bindings.viewFields ?? {})) {
+    if (PLAIN_VIEW_FIELDS[field]?.offset !== here.offset) {
+      throw new Error(
+        `flatPass: vertex variant "${key}" puts view field ${field} at ${here.offset} where the ` +
+          `plain variant has it at ${PLAIN_VIEW_FIELDS[field]?.offset}.`,
+      );
+    }
+  }
+}
+
+/** The view block's fields, binding and size: the largest variant's, as `FLAT_VERT_SIZE` is. */
+export const FLAT_VIEW_FIELDS = PLAIN_VIEW_FIELDS;
+export const FLAT_VIEW_SIZE = Math.max(
+  ...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.viewSize ?? 0),
+);
+const FLAT_VIEW_BINDING = PLAIN_VERTEX.viewUniforms ?? -1;
+if (FLAT_VIEW_BINDING < 0) throw new Error('flatPass: the lit vertex stage declares no view block');
+
 /**
  * The most sampled textures and distinct samplers any lit variant carrying the environment probe
  * binds in its fragment stage, counted from the generated bindings: what a device must allow per
@@ -260,6 +313,46 @@ export function flatFragmentBindings(variant: FlatVariant): StageBindings {
   return found;
 }
 
+/**
+ * The lit fragment stage's two blocks as the renderer keeps them on the CPU: the pass's, then the
+ * material's straight after it, in one scratch, with every field at its offset in that scratch.
+ *
+ * **One scratch rather than two, so no setter has to know which block its field is in.** A setter
+ * writes by name, as it always has; the draw copies the material's bytes — `passSize` onwards — into
+ * the store and the pass's bytes into a ring slot, each only when something has changed it.
+ */
+export interface FlatFragmentScratch {
+  readonly fields: StageBindings['fields'];
+  /** Bytes of the pass's block, which is where the material's starts in the scratch. */
+  readonly passSize: number;
+  readonly passBinding: number;
+  readonly materialSize: number;
+  readonly materialBinding: number;
+}
+
+export function flatFragmentScratch(variant: FlatVariant): FlatFragmentScratch {
+  const bindings = flatFragmentBindings(variant);
+  const { materialUniforms, materialSize, materialFields } = bindings;
+  if (
+    materialUniforms === undefined ||
+    materialSize === undefined ||
+    materialFields === undefined
+  ) {
+    throw new Error(`flatPass: variant "${variant}" has no material block`);
+  }
+  const fields: Record<string, StageBindings['fields'][string]> = { ...bindings.fields };
+  for (const [name, field] of Object.entries(materialFields)) {
+    fields[name] = { ...field, offset: bindings.uniformSize + field.offset };
+  }
+  return {
+    fields,
+    passSize: bindings.uniformSize,
+    passBinding: bindings.uniforms,
+    materialSize,
+    materialBinding: materialUniforms,
+  };
+}
+
 /**
  * The lit fragment stage's constants, set from the cache's switches, keyed by each one's **id**.
  *
@@ -306,6 +399,14 @@ function flatFragmentConstants(
   return constants;
 }
 
+/** The material block's binding, which every lit variant declares. */
+function materialBinding(fragment: StageBindings): number {
+  if (fragment.materialUniforms === undefined) {
+    throw new Error('flatPass: the lit fragment stage declares no material block');
+  }
+  return fragment.materialUniforms;
+}
+
 /** The depth format both backends compare with. */
 /* Re-exported so the twenty passes that already import it from here do not each learn a new
    module; `depthConvention.ts` is where the decision lives and why. */
@@ -317,15 +418,19 @@ const VISIBILITY_FRAGMENT = 0x2;
 /**
  * The layout this variant binds against.
  *
- * The vertex block is **dynamic**, because every draw supplies its own model matrix and tint
- * from its own slot of one buffer. The fragment block is not: it holds the lights, the fog
- * and the camera, settled once by `bindMeshPass` and unchanged between draws.
+ * All four blocks are **dynamic**: the vertex block because every draw supplies its own model
+ * matrix and tint from its own slot of one buffer; the fragment stage's pass block — the lights, the
+ * fog, the camera — and the vertex stage's view block because a frame binds more than one pass; and
+ * the material block because a material changes between draws. Their dynamic offsets go in binding
+ * order: the draw's, the pass's, the material's, the view's.
  */
 export function createFlatBindGroupLayout(
   device: GPUDevice,
   variant: FlatVariant,
   skinned = false,
   morphed = false,
+  /** The instanced variant that plays a bone animation: its three vertex textures. */
+  animated = false,
 ): GPUBindGroupLayout {
   const fragment = flatFragmentBindings(variant);
   const entries: GPUBindGroupLayoutEntry[] = [
@@ -334,15 +439,31 @@ export function createFlatBindGroupLayout(
       visibility: VISIBILITY_VERTEX,
       buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VERT_SIZE },
     },
+    {
+      binding: FLAT_VIEW_BINDING,
+      visibility: VISIBILITY_VERTEX,
+      /* Dynamic, a slot a pass, for the reason the fragment stage's pass block is. */
+      buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VIEW_SIZE },
+    },
     {
       binding: fragment.uniforms,
       visibility: VISIBILITY_FRAGMENT,
       /*
-       * Dynamic, because this block carries the material and a material changes between draws.
-       * See `WebGPURenderer.perFrame` for why one buffer cannot hold two answers.
+       * Dynamic, because a pass's lights and camera change between passes of one frame — a
+       * mirror's, a capture's — and one buffer cannot hold two answers. See `WebGPURenderer.passRing`.
        */
       buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: fragment.uniformSize },
     },
+    {
+      binding: materialBinding(fragment),
+      visibility: VISIBILITY_FRAGMENT,
+      /* Dynamic, because a material changes between draws. See `MaterialStore`. */
+      buffer: {
+        type: 'uniform',
+        hasDynamicOffset: true,
+        minBindingSize: fragment.materialSize ?? 0,
+      },
+    },
   ];
 
   /** What each sampler binding was declared as, so a shared one is declared once and agrees. */
@@ -489,12 +610,43 @@ export function createFlatBindGroupLayout(
     }
   }
 
+  /* A bone animation's places, turns and the batch's clocks, read by index as the palette is. */
+  if (animated) {
+    for (const binding of animationBindings()) {
+      entries.push({
+        binding,
+        visibility: VISIBILITY_VERTEX,
+        texture: { sampleType: 'unfilterable-float' },
+      });
+    }
+  }
+
   return device.createBindGroupLayout({
-    label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed)}`,
+    label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed, animated, animated)}`,
     entries,
   });
 }
 
+/** The three textures a bone animation binds, in the order `AnimationViews` holds them. */
+function animationBindings(): [number, number, number] {
+  const textures = flatVertexBindings(false, false, true, true).textures;
+  const at = (name: string): number => {
+    const found = textures[name];
+    if (found === undefined) {
+      throw new Error(`flatPass: the animated vertex shader declares no ${name}`);
+    }
+    return found.texture;
+  };
+  return [at('uBonePlaces'), at('uBoneTurns'), at('uInstanceClocks')];
+}
+
+/** What an animated draw binds besides its material: the clip's two textures and its batch's clocks. */
+export interface AnimationViews {
+  readonly places: GPUTextureView;
+  readonly turns: GPUTextureView;
+  readonly clocks: GPUTextureView;
+}
+
 /**
  * Bind the buffers and one view per declared texture.
  *
@@ -509,7 +661,9 @@ export function createFlatBindGroup(
   layout: GPUBindGroupLayout,
   variant: FlatVariant,
   perDraw: GPUBuffer,
-  perFrame: GPUBuffer,
+  passes: GPUBuffer,
+  materials: GPUBuffer,
+  views: GPUBuffer,
   resolve: (name: string) => { view: GPUTextureView; sampler: GPUSampler },
   /** The palette view for a skinned bind group, or null for an unskinned one. */
   palette: GPUTextureView | null = null,
@@ -517,6 +671,8 @@ export function createFlatBindGroup(
   deltas: GPUTextureView | null = null,
   /** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
   cloth: ClothViews | null = null,
+  /** An animated instanced group's views. See `AnimationViews`. */
+  animation: AnimationViews | null = null,
 ): GPUBindGroup {
   const fragment = flatFragmentBindings(variant);
   const entries: GPUBindGroupEntry[] = [
@@ -524,7 +680,12 @@ export function createFlatBindGroup(
       binding: FLAT_VERT_BINDING,
       resource: { buffer: perDraw, size: FLAT_VERT_SIZE },
     },
-    { binding: fragment.uniforms, resource: { buffer: perFrame, size: fragment.uniformSize } },
+    { binding: FLAT_VIEW_BINDING, resource: { buffer: views, size: FLAT_VIEW_SIZE } },
+    { binding: fragment.uniforms, resource: { buffer: passes, size: fragment.uniformSize } },
+    {
+      binding: materialBinding(fragment),
+      resource: { buffer: materials, size: fragment.materialSize ?? 0 },
+    },
   ];
 
   /* The same dedupe the layout does, and for the same reason: the shadow bindings share one
@@ -563,8 +724,15 @@ export function createFlatBindGroup(
     entries.push({ binding: restAt, resource: cloth.rest });
   }
 
+  if (animation !== null) {
+    const [places, turns, clocks] = animationBindings();
+    entries.push({ binding: places, resource: animation.places });
+    entries.push({ binding: turns, resource: animation.turns });
+    entries.push({ binding: clocks, resource: animation.clocks });
+  }
+
   return device.createBindGroup({
-    label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null)}`,
+    label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null, animation !== null, animation !== null)}`,
     layout,
     entries,
   });
@@ -641,33 +809,34 @@ export function flatPipeline(
    * targets `reflectionSurfacePass.ts` holds. The key must carry it: `|rs`.
    */
   reflectionSurface = false,
-): GPURenderPipeline {
-  return cache.get(
-    key,
-    () =>
-      flatDescriptor(
-        cache,
-        device,
-        layout,
-        variant,
-        key,
-        present,
-        translucent,
-        skinned,
-        morphed,
-        depthWrite,
-        depthLayer,
-        instanced,
-        oit,
-        doubleSided,
-        alphaToCoverage,
-        skinEight,
-        cloth,
-        model,
-        skinPass,
-        reflectionSurface,
-      ),
-    true,
+  /** An instanced pipeline that plays a bone animation. The key must carry it: `|anim`. */
+  animated = false,
+): GPURenderPipeline | null {
+  /* None where draws skip a compile and this one has not landed: see `PipelineCache.lit`. */
+  return cache.lit(key, () =>
+    flatDescriptor(
+      cache,
+      device,
+      layout,
+      variant,
+      key,
+      present,
+      translucent,
+      skinned,
+      morphed,
+      depthWrite,
+      depthLayer,
+      instanced,
+      oit,
+      doubleSided,
+      alphaToCoverage,
+      skinEight,
+      cloth,
+      model,
+      skinPass,
+      reflectionSurface,
+      animated,
+    ),
   );
 }
 
@@ -799,6 +968,8 @@ function flatDescriptor(
   model: SurfaceModelKind | null = null,
   skinPass: SkinHalf = 'whole',
   reflectionSurface = false,
+  /** An instanced pipeline that plays a bone animation. See `shaders/boneAnimation.ts`. */
+  animated = false,
 ): GPURenderPipelineDescriptor {
   const offset = depthOffsetForLayer(depthLayer);
   /* The diffuse and colour halves are the same surface again, into the blur's targets; and so is
@@ -814,13 +985,13 @@ function flatDescriptor(
        * layout validates, draws, and is wrong, exactly as this file's header says.
        */
       module: shaderModule(device, {
-        label: `flat.vert:${flatVertexKey(skinned, morphed, instanced)}`,
-        code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced)] ?? '',
+        label: `flat.vert:${flatVertexKey(skinned, morphed, instanced, animated)}`,
+        code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced, animated)] ?? '',
       }),
       entryPoint: 'main',
       buffers: vertexBufferLayouts(present, instanced),
       constants: vertexConstants(
-        flatVertexBindings(skinned, morphed, instanced),
+        flatVertexBindings(skinned, morphed, instanced, animated),
         skinEight,
         cloth,
         model === 'lightmap',