@driftengine/core 4.8.7 → 4.10.0

package/src/render/reflectionSurfaceTargets.ts

@@ -0,0 +1,105 @@
+/**
+ * The frame's materials' reflection maps on WebGL2: two half-float textures on the scene's own
+ * framebuffer, beside its colour, written by the opaque lit draws as they are drawn. What the two
+ * hold is `shaders/flat/reflectionSurface.ts`'s to say; this is where they live on this backend.
+ *
+ * **Written in the frame's own pass, where WebGPU replays the draws in a second one.** A WebGL2
+ * program writing an output its framebuffer has no buffer enabled for loses that output and nothing
+ * else, so the maps are enabled around an opaque lit draw (`on`, `off`) and stay disabled for every
+ * other: the sky, glass, text and particles write no material, and a draw into a mirror, a probe or
+ * a capture is into another framebuffer, whose draw buffers this never touches.
+ *
+ * **Detached once the trace has read them** (`detach`), because the resolve then draws into the
+ * scene's framebuffer while sampling both, and a texture sampled while attached to the framebuffer
+ * being drawn is a feedback loop whether or not its buffer is enabled. `begin` attaches them again.
+ */
+const ZERO = new Float32Array(4);
+
+export class ReflectionSurfaceTargets {
+  private probe: WebGLTexture | null = null;
+  private tint: WebGLTexture | null = null;
+  private width = 0;
+  private height = 0;
+  private readonly all: number[];
+  private readonly colourAlone: number[];
+
+  constructor(private readonly gl: WebGL2RenderingContext) {
+    this.all = [gl.COLOR_ATTACHMENT0, gl.COLOR_ATTACHMENT1, gl.COLOR_ATTACHMENT2];
+    this.colourAlone = [gl.COLOR_ATTACHMENT0];
+  }
+
+  /** The environment as the frame shows it, and the roughness in alpha. */
+  get probeTexture(): WebGLTexture | null {
+    return this.probe;
+  }
+
+  /** What a found reflection is multiplied by. */
+  get tintTexture(): WebGLTexture | null {
+    return this.tint;
+  }
+
+  /**
+   * At the frame's start, with the scene's framebuffer bound: both at its size, attached, cleared to
+   * nothing reflected, and left disabled.
+   */
+  begin(width: number, height: number): void {
+    const { gl } = this;
+    if (this.probe === null || this.width !== width || this.height !== height) {
+      this.release();
+      this.probe = this.make(width, height);
+      this.tint = this.make(width, height);
+      this.width = width;
+      this.height = height;
+    }
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, this.probe, 0);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, this.tint, 0);
+    gl.drawBuffers(this.all);
+    gl.clearBufferfv(gl.COLOR, 1, ZERO);
+    gl.clearBufferfv(gl.COLOR, 2, ZERO);
+    gl.drawBuffers(this.colourAlone);
+  }
+
+  /** Around an opaque lit draw into the frame: its two extra outputs land. */
+  on(): void {
+    this.gl.drawBuffers(this.all);
+  }
+
+  /** And after it: only the colour does. */
+  off(): void {
+    this.gl.drawBuffers(this.colourAlone);
+  }
+
+  /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+  detach(): void {
+    const { gl } = this;
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, null, 0);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, null, 0);
+  }
+
+  dispose(): void {
+    this.release();
+  }
+
+  private make(width: number, height: number): WebGLTexture {
+    const { gl } = this;
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('ReflectionSurfaceTargets: createTexture failed');
+    /* Unit 0, chosen rather than inherited, for the reason `SsrPass` gives. */
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA16F, width, height);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return texture;
+  }
+
+  private release(): void {
+    if (this.probe !== null) this.gl.deleteTexture(this.probe);
+    if (this.tint !== null) this.gl.deleteTexture(this.tint);
+    this.probe = null;
+    this.tint = null;
+  }
+}

package/src/render/renderQuality.ts

@@ -1,5 +1,6 @@
 /** Construction-time GPU quality controls shared by every renderer resource. */
 
+import type { FrameReflections } from './frameReflections.ts';
 import { MAX_AREA_LIGHTS } from './areaLights.ts';
 import { MAX_GLOBAL_MEDIUM_STEPS } from './globalMedium.ts';
 import { MAX_POINT_LIGHTS } from './lightBudget.ts';
@@ -26,8 +27,14 @@ import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.ts';
  * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
  * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
  * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
+ *
+ * `filmic` is a film curve shaped by five numbers — a slope, a toe, a shoulder and how far black
+ * and white clip — that holds a mid grey of 0.18 at 0.18 where `aces` gives about 0.11, so a look
+ * graded against such a curve is matched by its numbers (`setFilmicCurve`) rather than by a lookup
+ * table. Applied by the composite alone, so it needs `screenEffects` and `hdrScene`; without them
+ * every pass grades with `aces` and the renderer says so once. See `filmicCurve.ts`.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder' | 'filmic';
 
 /**
  * The three settings whose accepted values are a closed set, written as one.
@@ -355,6 +362,18 @@ export interface RenderQuality {
    * eight-bit and this buys only the consistent grading.
    */
   readonly hdrScene: boolean;
+  /**
+   * Ask for a high dynamic range display: a canvas whose highlights run past paper white to as
+   * far as the display allows, where it reports one. Off by default.
+   *
+   * **Asked for, not assumed.** It needs WebGPU, a display reporting a high dynamic range, and a
+   * composite that holds the light to give it (`screenEffects` and `hdrScene`); where any of those
+   * is missing the frame goes out as it always did and the renderer says which in
+   * `displayRangeReason`. `displayRange` is the answer a game reads to choose a look graded for the
+   * output it got. `setDisplayLuminance` sets how far above paper white the highlights may reach.
+   * WebGL2 has no extended-range canvas to draw into, so there it is always the standard range.
+   */
+  readonly highDynamicRange: boolean;
   /** Camera-depth water tint and scattering across every visible pass. */
   readonly underwaterAtmosphere: boolean;
   /** Procedural noise octaves evaluated by plume shaders. */
@@ -522,14 +541,14 @@ export interface RenderQuality {
    */
   readonly sceneSamples: number;
   /**
-   * Camera motion blur, 0 to 1. Off by default.
+   * Motion blur, 0 to 1. Off by default.
    *
-   * Camera rather than per-object, and that is a decision rather than a stage. Per-object
-   * blur needs a velocity buffer: every mesh writing its own screen-space motion into a
-   * second render target, so a second set of matrices per draw and a wider G-buffer, which
-   * is a structural change to a forward renderer that writes one colour target. Camera blur
-   * needs only the previous view-projection, which is one matrix, and it covers the case
-   * that actually matters — a camera whipping round a turntable or through a world.
+   * By the camera's motion everywhere, and **by each drawn object's own motion where a
+   * reconstruction draws one** (DriftTR, WebGPU): a mover's pixels smear along its path while a
+   * still stage stays sharp. Elsewhere a velocity buffer would be every mesh writing its motion into
+   * a second target — a structural change to a forward renderer — so those frames blur by the
+   * camera alone, which needs only the previous view-projection, and say so once when a draw names
+   * where it was. `setCameraMotionBlur` is the per-frame dial and the longest smear.
    *
    * Runs inside the composite pass, so it costs a depth sample and eight taps on the pixels
    * that are moving and nothing on a still frame. Needs `screenEffects`, since without the
@@ -580,6 +599,18 @@ export interface RenderQuality {
    * Needs `screenEffects`, since the resolve composites over the finished scene.
    */
   readonly orderIndependent: boolean;
+  /**
+   * Every opaque lit surface reflects the frame by its own material: a ray marched against the
+   * frame's depth swaps the probes' share of each pixel for what it finds, at the pixel's own
+   * roughness and reflectance, and a surface past `maxRoughness` keeps the probes alone. Off by
+   * default; `true` for the defaults, or the numbers. See `frameReflections.ts`.
+   *
+   * Needs `screenEffects` and `hdrScene`, since the swap is made in scene light, and a frame of one
+   * sample; it says once where it cannot be drawn. What it costs on WebGPU is every opaque lit draw
+   * a second time without its lamps, into two half-float targets, and a march per reflective pixel;
+   * on WebGL2 the same two targets, written beside the colour by the opaque lit draws themselves.
+   */
+  readonly screenSpaceReflections: boolean | FrameReflections;
   /**
    * Depth of field: how wide the blur may reach, as a fraction of the frame's height. Off by
    * default.
@@ -964,9 +995,11 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   sceneSamples: 1,
   planarReflections: false,
   hdrScene: false,
+  highDynamicRange: false,
   cameraMotionBlur: 0,
   temporalAa: false,
   orderIndependent: false,
+  screenSpaceReflections: false,
   depthOfField: 0,
   reconstruction: 0,
   indirectLight: false,
@@ -1126,12 +1159,15 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     ),
     planarReflections: options.planarReflections ?? DEFAULT_RENDER_QUALITY.planarReflections,
     hdrScene: options.hdrScene ?? DEFAULT_RENDER_QUALITY.hdrScene,
+    highDynamicRange: options.highDynamicRange ?? DEFAULT_RENDER_QUALITY.highDynamicRange,
     cameraMotionBlur: Math.min(
       1,
       Math.max(0, options.cameraMotionBlur ?? DEFAULT_RENDER_QUALITY.cameraMotionBlur),
     ),
     temporalAa: options.temporalAa ?? DEFAULT_RENDER_QUALITY.temporalAa,
     orderIndependent: options.orderIndependent ?? DEFAULT_RENDER_QUALITY.orderIndependent,
+    screenSpaceReflections:
+      options.screenSpaceReflections ?? DEFAULT_RENDER_QUALITY.screenSpaceReflections,
     /* Off, or a ratio at least 1.3 and at most 2 — never a number between zero and the range. */
     reconstruction: resolveReconstruction(options.reconstruction),
     indirectLight: options.indirectLight ?? DEFAULT_RENDER_QUALITY.indirectLight,

package/src/render/sceneTarget.ts

@@ -1,5 +1,6 @@
 import { glSceneDepthFormat } from './depthConvention.ts';
 import { clampGrain, clampVignette, grainSeed } from './shaders/filmLook.ts';
+import { FRINGE_FLOATS, resolveFringe } from './shaders/fringe.ts';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.ts';
 import { ExposurePass } from './exposurePass.ts';
 import { clampAutoExposure } from './shaders/exposure.ts';
@@ -99,6 +100,8 @@ export class SceneTarget {
   private gradeStrength = 0;
   /** The lens and the print, held like the grade. See `filmLook.ts`. */
   private vignette = 0;
+  /** The lens's colour fringe: red's and green's pull and where it begins. See `fringe.ts`. */
+  private readonly fringe = new Float32Array(FRINGE_FLOATS);
   private grain = 0;
   private grainSeed = 0;
   /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
@@ -702,6 +705,11 @@ export class SceneTarget {
     this.vignette = clampVignette(strength);
   }
 
+  /** The lens's colour fringe, held until changed. See `Renderer.setChromaticAberration`. */
+  setChromaticAberration(intensity: number, start: number): void {
+    resolveFringe(intensity, start, this.fringe);
+  }
+
   /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
   setFilmGrain(strength: number, seed: number): void {
     this.grain = clampGrain(strength);
@@ -769,8 +777,15 @@ export class SceneTarget {
   resolve(
     strength: number,
     reachUv: number,
-    /* The grade, applied here because this is the last pass. See RUSH_FRAG's own note. */
-    grade: { readonly transform: number; readonly exposure: number } = {
+    /*
+     * The grade, applied here because this is the last pass. See RUSH_FRAG's own note. `film` is
+     * the `filmic` curve's eight constants (`resolveFilmicCurve`), read only under transform 4.
+     */
+    grade: {
+      readonly transform: number;
+      readonly exposure: number;
+      readonly film?: Float32Array;
+    } = {
       transform: 0,
       exposure: 1,
     },
@@ -1012,6 +1027,12 @@ export class SceneTarget {
     gl.uniform1f(this.uniforms['uReach'] ?? null, reachUv);
     gl.uniform1i(this.uniforms['uOutputTransform'] ?? null, grade.transform);
     gl.uniform1f(this.uniforms['uOutputExposure'] ?? null, grade.exposure);
+    if (grade.film !== undefined) {
+      gl.uniform4fv(this.uniforms['uFilmA'] ?? null, grade.film, 0, 4);
+      gl.uniform4fv(this.uniforms['uFilmB'] ?? null, grade.film, 4, 4);
+    }
+    /* A standard range always here: see `Renderer.displayRange`. */
+    gl.uniform1f(this.uniforms['uDisplayHeadroom'] ?? null, 1);
 
     /*
      * Depth on its own unit, and the reprojection with it. Bound every frame rather than
@@ -1113,6 +1134,12 @@ export class SceneTarget {
       this.uniforms['uLocalExposure'] ?? null,
       localGrid === null ? 0 : this.localExposure,
     );
+    /* Each object's own motion is WebGPU's under a reconstruction; here the scene stands in on
+       unit 7 and the flag says not to read it, so the camera's motion alone blurs. */
+    gl.activeTexture(gl.TEXTURE7);
+    gl.bindTexture(gl.TEXTURE_2D, scene);
+    gl.uniform1i(this.uniforms['uMotion'] ?? null, 7);
+    gl.uniform1f(this.uniforms['uObjectMotion'] ?? null, 0);
     gl.activeTexture(gl.TEXTURE0);
 
     /* No unit and no texture: a flat colour, not a sample. Uploaded unconditionally — two
@@ -1122,6 +1149,7 @@ export class SceneTarget {
     gl.uniform3fv(this.uniforms['uVeilColor'] ?? null, veilColor);
     gl.uniform1f(this.uniforms['uVeilAlpha'] ?? null, veilAlpha);
     gl.uniform1f(this.uniforms['uVignette'] ?? null, this.vignette);
+    gl.uniform3fv(this.uniforms['uFringe'] ?? null, this.fringe);
     gl.uniform2f(this.uniforms['uGrain'] ?? null, this.grain, this.grainSeed);
 
     gl.bindVertexArray(this.vao);

package/src/render/screenSpaceReflection.ts

@@ -27,6 +27,11 @@ import type { DecalBox } from './decalProjector.ts';
  * which is the same price the temporal row declined for a velocity buffer. A caller declares a
  * `ReflectiveSurface` instead: a box, and a facing rule for which surfaces inside it reflect. It is
  * the shape `DecalProjector` already has, for the same reason.
+ *
+ * **Or every surface by its own material**, where the renderer was built with
+ * `screenSpaceReflections`: the lit stage leaves two maps of what it reflected — not a G-buffer, the
+ * environment's share and its tint, which is all a swap needs — and the same trace runs in a
+ * material mode over every pixel. See `frameReflections.ts`.
  */
 
 /**
@@ -365,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/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',
 );
 

package/src/render/shaders/filmLook.ts

@@ -88,7 +88,8 @@ export function grainWeight(luma: number): number {
 
 /** Both backends' words when there is no composite to apply the look in. */
 export const FILM_LOOK_WITHOUT_COMPOSITE =
-  '[driftengine] setVignette and setFilmGrain need `screenEffects`: without a composite every ' +
+  '[driftengine] setVignette, setFilmGrain and setChromaticAberration need `screenEffects`: ' +
+  'without a composite every ' +
   'pass is the last thing to touch the frame, so there is no one place to apply a lens or a ' +
   'print. The look was not applied.';
 

package/src/render/shaders/flat/glassTint.ts

@@ -34,7 +34,9 @@ export type LitSwitch =
   | 'LIGHT_FIXTURES'
   | 'SURFACE_EFFECTS'
   | 'DRIFT_LIGHT'
-  | 'PHYSICAL_SPECULAR';
+  | 'PHYSICAL_SPECULAR'
+  | 'SURFACE_OVERLAY'
+  | 'REFLECTION_MAPS';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -45,6 +47,8 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     SURFACE_EFFECTS: false,
     DRIFT_LIGHT: false,
     PHYSICAL_SPECULAR: false,
+    SURFACE_OVERLAY: false,
+    REFLECTION_MAPS: false,
   };
 }
 

package/src/render/shaders/flat/index.ts

@@ -19,7 +19,10 @@ import { AREA_LIGHT_GLSL } from './areaLight.ts';
 import { NORMAL_MAP_GLSL } from './normalMap.ts';
 import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
-import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
+import { overlayGlsl } from './overlay.ts';
+import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
+import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
+import { BONE_ANIMATION_GLSL } from '../boneAnimation.ts';
 import { FULL_LIGHT_BUDGET, type LightBudget } from '../../uniformVectorBudget.ts';
 
 /**
@@ -54,10 +57,16 @@ layout(location = 10) in vec4 aTangent;
 ${SKINNING_GLSL}
 #endif
 
-uniform mat4 uViewProj;
+uniform mat4 uViewProj; // wgsl:view
 /** 1 when the mesh carries a tangent frame. See vHasTangents. */
 uniform int uHasTangents;
-uniform mat4 uLightViewProj;
+uniform mat4 uLightViewProj; // wgsl:view
+/**
+ * The scene's clock, what \`setAnimationTime\` set: what a bone animation's instances read
+ * their moment from. In the view block, before the wind, so every variant's view block is the
+ * plain one's or a prefix of it — the instanced variant declares no wind and keeps this.
+ */
+uniform float uSceneTime; // wgsl:view
 /**
  * How often the surface texture repeats across this mesh's UV range, per axis.
  *
@@ -120,6 +129,9 @@ layout(location = 15) in vec4 aInstanceTint;
  * opacity of one. See lightmap.ts.
  */
 const bool LIGHTMAP_REGIONS = false; // wgsl:override
+#if ANIMATED
+${BONE_ANIMATION_GLSL}
+#endif
 #else
 uniform mat4 uModel;
 /**
@@ -145,7 +157,7 @@ uniform vec3 uTint;
  * agreeing about where the shared uniforms sit: the instanced variant drops these five along with
  * the two above it, and a dropped field moves nothing. flatPass.ts asserts exactly that.
  */
-${CHANNEL_ATTRIBUTE}
+${LIT_CHANNEL_ATTRIBUTE}
 ${CHANNEL_BEND}
 #endif
 
@@ -243,6 +255,10 @@ void main() {
   vec3 localNormal = aNormal;
   vec3 localTangent = aTangent.xyz;
 #endif
+#if ANIMATED
+  /* The clip's turn and place, in the mesh's own space, before the instance places it. */
+  local = vec4(boneAnimate(local.xyz, localNormal, localTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /*
@@ -377,6 +393,12 @@ export interface FlatVertexOptions {
    * Excludes `skinned`: the joint attributes and the instance matrix want the same locations.
    */
   readonly instanced: boolean;
+  /**
+   * Whether an instanced variant follows a bone animation: \`shaders/boneAnimation.ts\`. A
+   * variant rather than a pipeline constant, because it declares three textures the other
+   * instanced pipelines would otherwise have to bind stand-ins for. Instanced only.
+   */
+  readonly animated?: boolean;
 }
 
 /**
@@ -399,9 +421,17 @@ export function flatVert(options: FlatVertexOptions): string {
         'so every instance of the batch would wear one expression between them.',
     );
   }
+  if (options.animated === true && !options.instanced) {
+    throw new Error('flatVert: a bone animation is played by an instanced variant alone.');
+  }
   return resolveConditionals(
     FLAT_VERT_SOURCE,
-    { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced },
+    {
+      SKINNED: options.skinned,
+      MORPHED: options.morphed,
+      INSTANCED: options.instanced,
+      ANIMATED: options.animated === true,
+    },
     'flatVert',
   );
 }
@@ -468,6 +498,16 @@ export interface FlatShaderOptions {
    * when absent. See `modelsGlsl`.
    */
   readonly physicalSpecular?: boolean;
+  /**
+   * Whether it carries a draw's surface overlay, `uOverlay` and all (`setSurfaceOverlay`). True
+   * when absent. See `overlayGlsl`.
+   */
+  readonly surfaceOverlay?: boolean;
+  /**
+   * Whether the frame's own draws write the reflection maps beside their colour: WebGL2's way to
+   * the frame's materials' reflections. True when absent. See `reflectionSurfaceGlsl`.
+   */
+  readonly reflectionMaps?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -613,6 +653,10 @@ export function flatFrag(options: FlatShaderOptions): string {
       SURFACE_EFFECTS_GLSL,
       /* Depth zero and after the tangent frame and the lobes it calls; see models.ts. */
       modelsGlsl(options.physicalSpecular ?? true),
+      /* After the models, so its switch takes the next id; depth zero, as main calls it. */
+      overlayGlsl(options.surfaceOverlay ?? true),
+      /* After the overlay, so its switch takes the next id. See reflectionSurface.ts. */
+      reflectionSurfaceGlsl(options.reflectionMaps ?? true),
       /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
       AREA_LIGHT_GLSL,
       MAIN_GLSL,