@driftengine/core 4.13.6 → 4.14.0

package/src/render/globalMedium.ts

@@ -116,6 +116,16 @@ export interface GlobalMediumOptions {
   readonly sunScatter?: number;
   /** The same for the sky's fill, which lights a shadowed medium from every side. Default 1. */
   readonly skyScatter?: number;
+  /**
+   * The sky's fill the medium scatters, a colour of its own in the units of
+   * `Environment.ambient`, which `skyScatter` then scales. Absent or null, the frame's ambient, as
+   * it always was. **For a scene whose surfaces are lit by more than its flat ambient**, a sky's
+   * cubemap, probes and a bake, which keeps that ambient for what falls outside them: the ambient
+   * is then the wrong colour for the sky's light in the air, and setting it to the right one would
+   * relight those surfaces too. What it gives up is the sky's direction, as the ambient does: one
+   * colour from every side.
+   */
+  readonly skyFill?: readonly [number, number, number] | null;
   /**
    * The same for the lamps, each through its own shadow and times its own `lightMediumScatter`.
    * **Default 0**: a medium was the sun's and the sky's until there was this, and a scene that
@@ -142,6 +152,8 @@ export interface ResolvedGlobalMedium {
   readonly sunScatter: number;
   readonly skyScatter: number;
   readonly lampScatter: number;
+  /** The sky's fill of the medium's own, or null for the frame's ambient: see `mediumSkyFill`. */
+  readonly skyFill: readonly [number, number, number] | null;
 }
 
 /**
@@ -192,9 +204,28 @@ export function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): Reso
     sunScatter: Math.max(0, finite(options.sunScatter, 1)),
     skyScatter: Math.max(0, finite(options.skyScatter, 1)),
     lampScatter: Math.max(0, finite(options.lampScatter, 0)),
+    skyFill:
+      options.skyFill === undefined || options.skyFill === null
+        ? null
+        : [
+            Math.max(0, finite(options.skyFill[0], 0)),
+            Math.max(0, finite(options.skyFill[1], 0)),
+            Math.max(0, finite(options.skyFill[2], 0)),
+          ],
   };
 }
 
+/**
+ * The colour the medium scatters as the sky's fill: its own where it has one, else the frame's
+ * ambient. One decision both backends upload, so the two cannot disagree about which.
+ */
+export function mediumSkyFill(
+  medium: Pick<ResolvedGlobalMedium, 'skyFill'>,
+  ambient: ArrayLike<number>,
+): ArrayLike<number> {
+  return medium.skyFill ?? ambient;
+}
+
 /** `setGlobalMedium`'s object form: a density, and any of the rest. */
 export type GlobalMediumSettings = Partial<GlobalMediumOptions> & { readonly density: number };
 

package/src/render/globalMediumPass.ts

@@ -1,7 +1,7 @@
 import { mat4 } from 'gl-matrix';
 import type { ReadonlyMat4 } from 'gl-matrix';
 
-import { mediumTargetSize } from './globalMedium.ts';
+import { mediumSkyFill, mediumTargetSize } from './globalMedium.ts';
 import type { ResolvedGlobalMedium, ResolvedMediumLamps } from './globalMedium.ts';
 import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
@@ -236,12 +236,8 @@ export class GlobalMediumPass {
       light.sunColor[1] ?? 0,
       light.sunColor[2] ?? 0,
     );
-    gl.uniform3f(
-      u['uAmbient'] ?? null,
-      light.ambient[0] ?? 0,
-      light.ambient[1] ?? 0,
-      light.ambient[2] ?? 0,
-    );
+    const sky = mediumSkyFill(options, light.ambient);
+    gl.uniform3f(u['uAmbient'] ?? null, sky[0] ?? 0, sky[1] ?? 0, sky[2] ?? 0);
     gl.uniform1f(u['uDensity'] ?? null, options.density);
     gl.uniform2f(u['uHeight'] ?? null, options.heightFalloff, options.baseY);
     gl.uniform3f(u['uLayer2'] ?? null, options.density2, options.heightFalloff2, options.baseY2);

package/src/render/iridescentOverlay.ts

@@ -0,0 +1,177 @@
+/**
+ * A surface's iridescent overlay: a hue that shifts with the view, laid over the base colour before
+ * it is lit. `SurfaceMaterial.iridescentOverlay`, packed into `uIridescence` for the lit stage's
+ * `IRIDESCENT_OVERLAY` switch, and the same arithmetic on the CPU, which the tests hold the shader to.
+ *
+ * Per pixel, with `N` the mapped normal, `V` toward the eye and `uv` the mesh's own first
+ * coordinates, as many material systems shade a sheen on cloth or a coat:
+ *
+ *     h = saturate((N·H)^contrast), 0 where N·H ≤ 0, H = normalize(V + direction)
+ *     x = N·V + uv.x + blend · (h − N·V)
+ *     t = saturate(fract(x · tiling))
+ *     base' = base + (overlay(base, ramp(t)) − base) · x · mask · weight
+ *
+ * where `overlay` is the usual blend, `a < ½ ? 2ao : 1 − 2(1 − a)(1 − o)` per channel.
+ *
+ * **The ramp is uniforms, thirty-two colours, and not a texture**, because the lit stage has no
+ * texture binding left (`textureUnitBudget.test.ts`): a caller's ramp of any length is resampled to
+ * thirty-two on the way in and read back between neighbours. What that gives up is a ramp with
+ * detail finer than a thirty-second of its length, which a smooth spectrum does not have. **The
+ * mask is a channel of a layer of one of the material's own arrays**, for the same reason, read at
+ * the material's coordinates; alpha is linear in every array, and a colour channel of an sRGB array
+ * is decoded before it is read.
+ *
+ * Thirty-six vectors, so WebGL2 refuses it, in words, on a part whose lit stage has no room, as it
+ * refuses a material's tiled detail.
+ */
+/** Three numbers, read and never written. */
+type Three = readonly [number, number, number];
+
+/** Colours the ramp is resampled to. */
+export const IRIDESCENT_RAMP = 32;
+/** Floats in `uIridescence`: four vectors of numbers, then the ramp a vector a colour. */
+export const IRIDESCENT_FLOATS = (4 + IRIDESCENT_RAMP) * 4;
+
+/** Which of a material's arrays holds the mask. */
+export type IridescentMaskMap = 'orm' | 'model' | 'albedo' | 'emissive';
+
+/** `SurfaceMaterial.iridescentOverlay`. */
+export interface IridescentOverlay {
+  /**
+   * The overlay colour along `t`, linear, three floats a colour, at least two colours, the first at
+   * `t = 0` and the last at `t = 1`. Resampled to thirty-two.
+   */
+  readonly ramp: ArrayLike<number>;
+  /** A fixed direction in the world the sheen turns toward, `S`. Need not be unit length. */
+  readonly direction: Three;
+  /** How far the view's term is turned toward the sheen, 0 to 1. Default 0.6. */
+  readonly blend?: number;
+  /** The sheen's exponent. Default 1. */
+  readonly contrast?: number;
+  /** How many times the ramp repeats across `x`. Default 2. */
+  readonly tiling?: number;
+  /** How much of the overlay is laid on. Default 0.25. */
+  readonly weight?: number;
+  /** Where it is laid: a channel of a layer of one of the material's arrays. Absent, everywhere. */
+  readonly mask?: {
+    readonly map: IridescentMaskMap;
+    readonly layer: number;
+    /** 0 red, 1 green, 2 blue, 3 alpha. */
+    readonly channel: 0 | 1 | 2 | 3;
+  } | null;
+}
+
+const MASK_SOURCE: Readonly<Record<IridescentMaskMap, number>> = {
+  orm: 1,
+  model: 2,
+  albedo: 3,
+  emissive: 4,
+};
+
+/** Why an overlay cannot be drawn, or null where it can. */
+export function iridescentRefusal(overlay: IridescentOverlay): string | null {
+  const values = overlay.ramp.length;
+  if (values < 6 || values % 3 !== 0) {
+    return `a ramp of ${values} numbers; it is three a colour, at least two colours`;
+  }
+  const [x, y, z] = overlay.direction;
+  if (
+    !(Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)) ||
+    x * x + y * y + z * z === 0
+  ) {
+    return 'a direction that is not one';
+  }
+  const mask = overlay.mask ?? null;
+  if (mask !== null && !(Number.isInteger(mask.layer) && mask.layer >= 0)) {
+    return `a mask layer of ${mask.layer}; a layer is a whole number from 0`;
+  }
+  return null;
+}
+
+/**
+ * Pack an overlay into `out`, with the scale and offset that take the material's coordinates back
+ * to the mesh's own; all zeros, which the shader reads as none, for null. Refuse what
+ * `iridescentRefusal` refuses before calling this.
+ */
+export function packIridescentOverlay(
+  overlay: IridescentOverlay | null,
+  uv: { uScale?: number; vScale?: number; uOffset?: number; vOffset?: number },
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (overlay === null) return;
+  const [x, y, z] = overlay.direction;
+  const length = Math.hypot(x, y, z);
+  out[0] = x / length;
+  out[1] = y / length;
+  out[2] = z / length;
+  out[3] = overlay.blend ?? 0.6;
+  out[4] = overlay.contrast ?? 1;
+  out[5] = overlay.tiling ?? 2;
+  out[6] = overlay.weight ?? 0.25;
+  /* On: a zero here, which an unwritten block is, is none. */
+  out[7] = 1;
+  const mask = overlay.mask ?? null;
+  out[8] = mask === null ? 0 : MASK_SOURCE[mask.map];
+  out[9] = mask === null ? 0 : mask.layer;
+  out[10] = mask === null ? 0 : mask.channel;
+  const uScale = uv.uScale ?? 1;
+  const vScale = uv.vScale ?? 1;
+  out[12] = uScale === 0 ? 0 : 1 / uScale;
+  out[13] = vScale === 0 ? 0 : 1 / vScale;
+  out[14] = uScale === 0 ? 0 : -(uv.uOffset ?? 0) / uScale;
+  out[15] = vScale === 0 ? 0 : -(uv.vOffset ?? 0) / vScale;
+  /* The ramp, resampled to thirty-two colours between its own neighbours. */
+  const colours = overlay.ramp.length / 3;
+  for (let i = 0; i < IRIDESCENT_RAMP; i++) {
+    const at = (i / (IRIDESCENT_RAMP - 1)) * (colours - 1);
+    const below = Math.min(Math.floor(at), colours - 2);
+    const share = at - below;
+    for (let c = 0; c < 3; c++) {
+      const a = overlay.ramp[below * 3 + c] as number;
+      const b = overlay.ramp[(below + 1) * 3 + c] as number;
+      out[16 + i * 4 + c] = a + (b - a) * share;
+    }
+  }
+}
+
+/**
+ * The base colour with the overlay laid on, as the lit stage computes it from a packed block: `n`
+ * and `toEye` unit length, `uv` the mesh's own coordinates, `mask` the texel's channel. Into `out`.
+ */
+export function iridescentBase(
+  packed: ArrayLike<number>,
+  base: Three,
+  n: Three,
+  toEye: Three,
+  uv: readonly [number, number],
+  mask: number,
+  out: [number, number, number],
+): [number, number, number] {
+  const p = (i: number): number => packed[i] as number;
+  let hx = toEye[0] + p(0);
+  let hy = toEye[1] + p(1);
+  let hz = toEye[2] + p(2);
+  const hl = Math.hypot(hx, hy, hz) || 1;
+  hx /= hl;
+  hy /= hl;
+  hz /= hl;
+  const nh = n[0] * hx + n[1] * hy + n[2] * hz;
+  const h = nh > 0 ? Math.min(1, Math.max(0, nh ** p(4))) : 0;
+  const nv = n[0] * toEye[0] + n[1] * toEye[1] + n[2] * toEye[2];
+  const x = nv + uv[0] + p(3) * (h - nv);
+  const scaled = x * p(5);
+  const t = Math.min(1, Math.max(0, scaled - Math.floor(scaled)));
+  const at = t * (IRIDESCENT_RAMP - 1);
+  const below = Math.min(Math.floor(at), IRIDESCENT_RAMP - 2);
+  const share = at - below;
+  const amount = x * mask * p(6);
+  for (let c = 0; c < 3; c++) {
+    const o0 = p(16 + below * 4 + c);
+    const o = o0 + (p(16 + (below + 1) * 4 + c) - o0) * share;
+    const a = base[c] as number;
+    const blended = a < 0.5 ? 2 * a * o : 1 - 2 * (1 - a) * (1 - o);
+    out[c] = a + (blended - a) * amount;
+  }
+  return out;
+}

package/src/render/mesh.ts

@@ -40,6 +40,8 @@ import { validateMeshData } from '@driftengine/drft';
 
 /** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
 const ATTR_POSITION = 0;
+/** What the motion pass reads: positions, and a rig's two sets of joints and weights. */
+const MOTION_LOCATIONS: readonly number[] = [ATTR_POSITION, 11, 12, 14, 15];
 const ATTR_NORMAL = 1;
 const ATTR_COLOR = 2;
 const ATTR_EMISSIVE = 3;
@@ -119,6 +121,16 @@ export class Mesh {
   get streams(): { readonly positions: WebGLBuffer; readonly normals: WebGLBuffer } | null {
     return this.deformable;
   }
+  /**
+   * A dynamic mesh's positions as they stood before this frame's first rewrite, for the motion
+   * WebGL2's temporal resolve follows (`backend/webgl2/motionTarget.ts`). Made the first time one is
+   * kept, so a mesh that never moves under the resolve pays nothing.
+   */
+  private previousPositions: WebGLBuffer | null = null;
+  /** The frame that rewrite belongs to (`frameOfChange`), or -1 for none yet. */
+  changedFrame = -1;
+  /** A vertex array for the motion pass, without and with last frame's positions, made on demand. */
+  private motionArrays: (WebGLVertexArrayObject | null)[] = [null, null];
   /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
   private readonly recolourable: WebGLBuffer | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
@@ -475,6 +487,76 @@ export class Mesh {
     this.morph?.dispose(gl);
     for (const buffer of this.buffers) gl.deleteBuffer(buffer);
     gl.deleteVertexArray(this.vao);
+    for (const vao of this.motionArrays) if (vao !== null) gl.deleteVertexArray(vao);
+    if (this.previousPositions !== null) gl.deleteBuffer(this.previousPositions);
+  }
+
+  /**
+   * Keep this dynamic mesh's positions as they stand, before a rewrite: one buffer copy on the
+   * device. The caller decides whether this rewrite is the frame's first (`keepsPrevious`).
+   */
+  keepPrevious(gl: WebGL2RenderingContext): void {
+    const deformable = this.deformable;
+    if (deformable === null) return;
+    const bytes = this.positionFloats * 4;
+    if (this.previousPositions === null) {
+      const buffer = gl.createBuffer();
+      if (buffer === null) throw new Error('createBuffer failed');
+      gl.bindBuffer(gl.COPY_WRITE_BUFFER, buffer);
+      gl.bufferData(gl.COPY_WRITE_BUFFER, bytes, gl.DYNAMIC_COPY);
+      this.previousPositions = buffer;
+    }
+    gl.bindBuffer(gl.COPY_READ_BUFFER, deformable.positions);
+    gl.bindBuffer(gl.COPY_WRITE_BUFFER, this.previousPositions);
+    gl.copyBufferSubData(gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, 0, 0, bytes);
+    gl.bindBuffer(gl.COPY_READ_BUFFER, null);
+    gl.bindBuffer(gl.COPY_WRITE_BUFFER, null);
+  }
+
+  /** Whether last frame's positions have been kept: a dynamic mesh rewritten under the resolve. */
+  get keptPrevious(): boolean {
+    return this.previousPositions !== null;
+  }
+
+  /**
+   * Draw this mesh for the motion pass: its positions at 0, last frame's at 1 where `previous` asks
+   * and they were kept, and its rig's influences where `flat`'s skinning reads them, 11, 12, 14 and
+   * 15. A vertex array of its own, made once a variant, so the one the lit pass draws with is never
+   * touched.
+   */
+  drawMotion(gl: WebGL2RenderingContext, previous: boolean): void {
+    const at = previous && this.previousPositions !== null ? 1 : 0;
+    let vao = this.motionArrays[at] ?? null;
+    if (vao === null) {
+      vao = gl.createVertexArray();
+      if (vao === null) throw new Error('createVertexArray failed');
+      gl.bindVertexArray(vao);
+      for (const attribute of this.layout) {
+        if (!MOTION_LOCATIONS.includes(attribute.location)) continue;
+        gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
+        gl.enableVertexAttribArray(attribute.location);
+        gl.vertexAttribPointer(
+          attribute.location,
+          attribute.size,
+          attribute.type,
+          attribute.normalized,
+          0,
+          0,
+        );
+      }
+      if (at === 1 && this.previousPositions !== null) {
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.previousPositions);
+        gl.enableVertexAttribArray(1);
+        gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 0, 0);
+      }
+      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+      gl.bindVertexArray(null);
+      gl.bindBuffer(gl.ARRAY_BUFFER, null);
+      this.motionArrays[at] = vao;
+    }
+    gl.bindVertexArray(vao);
+    gl.drawElements(gl.TRIANGLES, this.indexCount, this.indexType, 0);
+    gl.bindVertexArray(null);
   }
 
   /**

package/src/render/pointSkin.ts

@@ -48,9 +48,27 @@ export interface PointSkinReach {
 
 /** Refuse a skin whose arrays disagree with a mesh of `vertices`, or that names a joint past the rest. */
 export function validatePointSkin(data: PointSkinData, vertices: number): void {
-  const fail = (what: string): never => {
-    throw new Error(`point skin: ${what}`);
-  };
+  checkArrays(data, vertices, 'the mesh has');
+  checkJoints(data, 0);
+}
+
+/**
+ * Refuse a rewrite of vertices `first` onward, as many as `data` holds, that does not fit a mesh of
+ * `vertices`: arrays that disagree with each other, a range that is not whole vertices inside the
+ * mesh, or a joint past the rest. Named by the mesh's own vertex numbers.
+ */
+export function validatePointSkinRange(data: PointSkinData, first: number, vertices: number): void {
+  const count = data.weights.length / 4;
+  checkArrays(data, count, 'the weights hold');
+  if (!(Number.isInteger(first) && first >= 0 && first + count <= vertices)) {
+    throw new Error(
+      `point skin: a rewrite of ${count} vertices from vertex ${first} for a mesh of ${vertices}`,
+    );
+  }
+  checkJoints(data, first);
+}
+
+function checkArrays(data: PointSkinData, vertices: number, against: string): void {
   for (const [name, values, width] of [
     ['joints', data.joints, 4],
     ['weights', data.weights, 4],
@@ -58,13 +76,22 @@ export function validatePointSkin(data: PointSkinData, vertices: number): void {
     ['normals', data.normals, 3],
   ] as const) {
     if (values.length !== vertices * width) {
-      fail(`${name} holds ${values.length / width} vertices and the mesh has ${vertices}`);
+      throw new Error(
+        `point skin: ${name} holds ${values.length / width} vertices and ${against} ${vertices}`,
+      );
     }
   }
+}
+
+/** Every joint a whole number below `MAX_JOINTS`; a vertex named as `first` plus its place. */
+function checkJoints(data: PointSkinData, first: number): void {
   for (let at = 0; at < data.joints.length; at++) {
     const joint = data.joints[at] as number;
     if (!(Number.isInteger(joint) && joint >= 0 && joint < MAX_JOINTS)) {
-      fail(`vertex ${Math.floor(at / 4)} names joint ${joint}; a joint is 0 to ${MAX_JOINTS - 1}`);
+      throw new Error(
+        `point skin: vertex ${first + Math.floor(at / 4)} names joint ${joint}; a joint is 0 to ` +
+          `${MAX_JOINTS - 1}`,
+      );
     }
   }
 }
@@ -102,6 +129,38 @@ export function reachOf(data: PointSkinData): PointSkinReach {
   };
 }
 
+/**
+ * A skin's reach after part of it is rewritten with `data`: the farther of the old reach and the
+ * new at each joint, the joints the two name between them, and the widest span of weight sums.
+ *
+ * **It widens and never narrows**, because the vertices the rewrite replaced may have been the
+ * ones that set a joint's reach, and finding out would mean keeping every vertex on the CPU and
+ * reading them all again. A skin that changes shape back and forth settles at the union of its
+ * shapes, which is still a box no posed vertex leaves, and culls a little less than it could. What
+ * would make that wrong is a skin rewritten into ever larger shapes and never back; making it
+ * again with `createPointSkin` measures it afresh.
+ */
+export function widenReach(reach: PointSkinReach, data: PointSkinData): PointSkinReach {
+  const added = reachOf(data);
+  const joints = Math.max(reach.joints, added.joints);
+  const widened = new Float32Array(joints).fill(-1);
+  for (let j = 0; j < joints; j++) {
+    widened[j] = Math.max(
+      j < reach.joints ? (reach.reach[j] as number) : -1,
+      j < added.joints ? (added.reach[j] as number) : -1,
+    );
+  }
+  const vertices = data.weights.length / 4;
+  return {
+    joints,
+    reach: widened,
+    sums:
+      vertices === 0
+        ? reach.sums
+        : [Math.min(reach.sums[0], added.sums[0]), Math.max(reach.sums[1], added.sums[1])],
+  };
+}
+
 /**
  * The bounds of a pose, into the mesh's own: `matrices` holds each joint's transform into the
  * mesh's model space, sixteen floats, column-major. Allocates nothing.

package/src/render/recon/mover.ts

@@ -8,8 +8,9 @@
  * draw, last frame's palette.
  *
  * **Plain data, advanced by the renderer.** No renderer is needed to make one, so a consumer holds
- * it beside the object it belongs to. Only a reconstructing WebGPU renderer reads or writes it; it
- * costs nothing anywhere else. The fields past `kind` are the renderer's and a caller leaves them
+ * it beside the object it belongs to. A reconstructing WebGPU renderer reads and writes it, and so
+ * does a WebGL2 one resolving temporally (`backend/webgl2/motionTarget.ts`); it costs nothing
+ * anywhere else. The fields past `kind` are the renderer's and a caller leaves them
  * alone.
  *
  * **What would make this wrong** is a consumer whose objects are rebuilt every frame with no state

package/src/render/sceneTarget.ts

@@ -850,6 +850,8 @@ export class SceneTarget {
       readonly blend: number;
       readonly periodStart: boolean;
       readonly depthToViewZ: Float32Array;
+      /** Where the frame's movers stood last frame, or absent for the camera's motion alone. */
+      readonly motion?: WebGLTexture | null;
     },
   ): void {
     const { gl } = this;
@@ -993,6 +995,7 @@ export class SceneTarget {
         temporal.blend,
         temporal.periodStart,
         temporal.depthToViewZ,
+        temporal.motion ?? null,
       );
     }
 

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

@@ -0,0 +1,71 @@
+/**
+ * Decals laid into a surface's base colour before it is lit: `setBaseDecals`, packed into
+ * `uBaseDecals` by `baseDecals.ts`, where what they are for and what they give up is said, and the
+ * material's own refusal in `uDecalReceiver` (`SurfaceMaterial.receivesDecals`).
+ *
+ * **Each decal is a test and a fetch**: the world point taken into the box by three rows, outside
+ * it or turned too far from the projection and nothing, else the image read across the box's face
+ * from its square in the fixture atlas, its colour decoded from sRGB and laid over the base colour
+ * by its alpha and the decal's opacity. The geometric normal decides the facing, so a normal map's
+ * bump does not cut a mark. The loop is over a count in a uniform and the fetch is `textureLod`, as
+ * every read of the atlas is, so neither needs uniform control flow: AGENTS.md 2026-08-07.
+ *
+ * **A lit switch, `BASE_DECALS`**, off until a frame first lays one, declared after
+ * `IRIDESCENT_OVERLAY` so each switch before it keeps its id. Compiled out, its thirty-four vectors
+ * are not declared and the call is a constant.
+ */
+export function baseDecalsGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool BASE_DECALS = false;  // wgsl:override
+vec3 baseDecals(vec3 base, vec3 world, vec3 geometric) { return base; }
+`;
+  }
+  return /* glsl */ `
+/* Whether this program lays decals into base colours. Off but where a frame has laid one. */
+const bool BASE_DECALS = true;  // wgsl:override
+/*
+ * A header, how many decals, the atlas row their band starts at and its squares' side (0); then
+ * four vectors a decal, eight decals: the three rows taking a world point into its box, x across,
+ * y up the image, z along the projection, and its image, opacity and facing cosine.
+ */
+uniform vec4 uBaseDecals[33]; // wgsl:material
+/* x 1 where the material refuses decals, so an unwritten zero receives them. */
+uniform vec4 uDecalReceiver; // wgsl:material
+
+vec3 decalLinear(vec3 c) {
+  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));
+}
+
+vec3 baseDecals(vec3 base, vec3 world, vec3 geometric) {
+  if (uDecalReceiver.x > 0.5) return base;
+  int count = int(uBaseDecals[0].x + 0.5);
+  vec2 atlas = vec2(textureSize(uFixtureAtlas, 0));
+  float span = uBaseDecals[0].z;
+  /* Half a texel of a square, so a bilinear read at its edge cannot reach the next one. */
+  float inset = 0.5 / span;
+  for (int i = 0; i < 8; i++) {
+    if (i >= count) break;
+    vec4 across = uBaseDecals[1 + i * 4];
+    vec4 up = uBaseDecals[2 + i * 4];
+    vec4 along = uBaseDecals[3 + i * 4];
+    vec4 laid = uBaseDecals[4 + i * 4];
+    vec3 local = vec3(
+      dot(across.xyz, world) + across.w,
+      dot(up.xyz, world) + up.w,
+      dot(along.xyz, world) + along.w
+    );
+    if (any(greaterThan(abs(local), vec3(1.0)))) continue;
+    if (dot(geometric, -normalize(along.xyz)) < laid.z) continue;
+    vec2 face = vec2(local.x, -local.y) * 0.5 + 0.5;
+    vec2 at = vec2(
+      (laid.x + clamp(face.x, inset, 1.0 - inset)) * span / atlas.x,
+      (uBaseDecals[0].y + clamp(face.y, inset, 1.0 - inset) * span) / atlas.y
+    );
+    vec4 texel = textureLod(uFixtureAtlas, at, 0.0);
+    base = mix(base, decalLinear(texel.rgb), clamp(texel.a * laid.y, 0.0, 1.0));
+  }
+  return base;
+}
+`;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * A material's glow moved and masked: `SurfaceMaterial.emissiveScroll` and `emissiveMaskLayer`,
+ * packed into `uEmissiveFlow` by `emissiveFlow.ts`, where what each gives up is said.
+ *
+ * **The scroll** is added to wherever the emissive map is read, the mesh's coordinates, a layer's
+ * place or a projection's planes, as its own repeats a second times the surface clock, wrapped to
+ * one repeat. **The mask** is the alpha of a layer of the emissive map's own array at the mesh's
+ * first coordinates as they are: the vertex stage has already laid the material's repeat and offset
+ * on `vUv`, so the second vector holds their inverse, which gives the mesh's own back.
+ *
+ * **A lit switch, `EMISSIVE_FLOW`**, off until a material first asks, declared after
+ * `SURFACE_DETAIL` so each switch before it keeps its id. Compiled out, its two vectors are not
+ * declared and the shift and the mask are constants.
+ */
+export function emissiveFlowGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool EMISSIVE_FLOW = false;  // wgsl:override
+vec2 emissiveShift() { return vec2(0.0); }
+float emissiveMask() { return 1.0; }
+`;
+  }
+  return /* glsl */ `
+/* Whether this program moves and masks a material's glow. Off but where one has asked. */
+const bool EMISSIVE_FLOW = true;  // wgsl:override
+/*
+ * Two vectors, as emissiveFlow.ts packs them: the scroll in repeats a second on u and v (x y) and
+ * the mask's layer of the emissive array plus one, 0 for none (z); then what takes the material's
+ * coordinates back to the mesh's own, a scale (x y) and an offset (z w).
+ */
+uniform vec4 uEmissiveFlow[2]; // wgsl:material
+
+/* The emissive map's coordinates moved by the clock, wrapped to one repeat for precision. */
+vec2 emissiveShift() {
+  return fract(uEmissiveFlow[0].xy * uSurfaceScene.x);
+}
+
+/* The mask's alpha at the mesh's own coordinates, under the branch on a bound emissive map. */
+float emissiveMask() {
+  if (uEmissiveFlow[0].z < 0.5) return 1.0;
+  vec2 own = vUv.xy * uEmissiveFlow[1].xy + uEmissiveFlow[1].zw;
+  return texture(uEmissiveMap, vec3(own, uEmissiveFlow[0].z - 1.0)).a;
+}
+`;
+}

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

@@ -41,7 +41,10 @@ export type LitSwitch =
   | 'MOVING_SUN'
   | 'LAYERED'
   | 'LAYER_LOOKS'
-  | 'SURFACE_DETAIL';
+  | 'SURFACE_DETAIL'
+  | 'EMISSIVE_FLOW'
+  | 'IRIDESCENT_OVERLAY'
+  | 'BASE_DECALS';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -59,6 +62,9 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     LAYERED: false,
     LAYER_LOOKS: false,
     SURFACE_DETAIL: false,
+    EMISSIVE_FLOW: false,
+    IRIDESCENT_OVERLAY: false,
+    BASE_DECALS: false,
   };
 }
 

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

@@ -25,6 +25,9 @@ import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
 import { worldUvGlsl } from './worldUv.ts';
 import { movingSunGlsl } from './movingSun.ts';
 import { detailGlsl } from './detail.ts';
+import { emissiveFlowGlsl } from './emissiveFlow.ts';
+import { iridescentOverlayGlsl } from './iridescentOverlay.ts';
+import { baseDecalsGlsl } from './baseDecals.ts';
 import { layeredGlsl } from './layered.ts';
 import { MAP_READS_GLSL } from './mapReads.ts';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
@@ -545,6 +548,22 @@ export interface FlatShaderOptions {
    * (\`SurfaceMaterial.detail\`). True when absent. See \`detailGlsl\`.
    */
   readonly surfaceDetail?: boolean;
+  /**
+   * Whether it moves and masks a material's glow, `uEmissiveFlow` and all
+   * (`SurfaceMaterial.emissiveScroll` and `emissiveMaskLayer`). True when absent. See
+   * `emissiveFlowGlsl`.
+   */
+  readonly emissiveFlow?: boolean;
+  /**
+   * Whether it lays a material's iridescent overlay on the base colour, `uIridescence` and all
+   * (`SurfaceMaterial.iridescentOverlay`). True when absent. See `iridescentOverlayGlsl`.
+   */
+  readonly iridescentOverlay?: boolean;
+  /**
+   * Whether it lays the frame's decals into base colours, `uBaseDecals` and all
+   * (`setBaseDecals`). True when absent. See `baseDecalsGlsl`.
+   */
+  readonly baseDecals?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -700,6 +719,12 @@ export function flatFrag(options: FlatShaderOptions): string {
       layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
       /* After the layers, so its switch takes the next id; main calls it. See detail.ts. */
       detailGlsl(options.surfaceDetail ?? true),
+      /* After the detail, so its switch takes the next id; the map reads call it. emissiveFlow.ts. */
+      emissiveFlowGlsl(options.emissiveFlow ?? true),
+      /* After the glow's flow, so its switch takes the next id; main calls it. iridescentOverlay.ts. */
+      iridescentOverlayGlsl(options.iridescentOverlay ?? true),
+      /* After the overlay, so its switch takes the next id; main calls it. baseDecals.ts. */
+      baseDecalsGlsl(options.baseDecals ?? true),
       /* Where each map is read, after both of the ways it can be read otherwise. See mapReads.ts. */
       MAP_READS_GLSL,
       /* After the frame and the projection it calls, unconditional for the same reason as the