@driftengine/core 4.11.1 → 4.12.0

package/scripts/look.mjs

@@ -0,0 +1,380 @@
+/**
+ * Look at a running game on both backends and say, in words and in exit codes, what was seen.
+ *
+ * **Written for whoever cannot see the screen, which is a coding agent first.** An agent can
+ * typecheck a game and run its tests and still have no idea whether anything drew: a renderer
+ * that throws in a frame callback, a camera inside the ground, a material with no light on it and
+ * an empty canvas all pass both. A person catches those by looking. This is the looking, done by
+ * the instrument this repository already trusts for its own captures — `browser.mjs`, which refuses
+ * a software rasteriser, and `cdp.mjs`, which reads the console from before the page loads — and
+ * reduced to the four questions an agent needs answered before it says a change works:
+ *
+ *   1. Did the page throw or print an error or a warning?
+ *   2. Did anything draw, or is the canvas one flat colour?
+ *   3. Is it moving, or did the loop stop?
+ *   4. Which backend drew it, and on which GPU?
+ *
+ * Each backend is photographed on its own, through `?backend=`, because the engine's own rule is
+ * that a picture looked at on one backend has not been looked at: a uniform one backend never
+ * uploads draws a plausible frame on that backend and a different one on the other.
+ *
+ * **What it gives up.** It sees one frame of a game after it boots, and nothing a player would
+ * have to click or press to reach; a page that waits for input photographs its waiting screen. It
+ * does not compare against a reference, because a game under construction has none — `frames.mjs`
+ * is the instrument for a before-and-after. And it refuses to look at all without a hardware GPU,
+ * which on a machine with none is a refusal rather than a picture: a frame from a software
+ * rasteriser reads exactly like evidence and is not.
+ *
+ * **What would make it wrong**: a game whose first frame is meant to be one colour, a title card
+ * on black. Then `nothing drew` is a false alarm, and the photograph says so at a glance.
+ *
+ *     import { look, formatLook } from '@driftengine/core/scripts/look.mjs';
+ *
+ *     const report = await look({ url: 'http://localhost:5173/' });
+ *     console.log(formatLook(report));
+ *     process.exitCode = report.ok ? 0 : 1;
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { launch, requireHardwareGpu } from './browser.mjs';
+import { connect } from './cdp.mjs';
+import { luminance } from './frames.mjs';
+import { decodePng, rgbaOf } from './png.mjs';
+
+/** The two backends, in the order a consumer runs them: WebGPU where it can, WebGL2 beneath. */
+export const LOOK_BACKENDS = Object.freeze(['webgpu', 'webgl2']);
+
+/**
+ * At or above this share of one colour, the canvas is called empty.
+ *
+ * Measured over the canvas alone, with the page's own interface hidden, so a readout over a blank
+ * canvas cannot carry it over the line. 99.5% leaves room for a few hundred pixels of a cursor or
+ * a dithered edge on a 1280 by 720 frame and for nothing a scene would draw on purpose.
+ */
+export const EMPTY_SHARE = 0.995;
+
+/**
+ * The flags that reach the real GPU from a headless browser, by platform.
+ *
+ * Linux is the one measured: Vulkan through ANGLE, which is what `browser.mjs` defaults to and why,
+ * since plain headless there selects a software rasteriser and says nothing. macOS takes Metal and
+ * Windows takes Direct3D 11, each ANGLE's native path on that system, and neither has been run by
+ * this module yet; `requireHardwareGpu` is what says so if one is wrong, and `headless: false` is the
+ * answer it suggests. Any other platform gets `null`, and `look` refuses it by name.
+ */
+export function gpuFlagsFor(platform = process.platform) {
+  if (platform === 'linux') return ['--use-angle=vulkan', '--enable-features=Vulkan'];
+  if (platform === 'darwin') return ['--use-angle=metal'];
+  if (platform === 'win32') return ['--use-angle=d3d11'];
+  return null;
+}
+
+/**
+ * The page's address with the backend forced and the boot badge declined.
+ *
+ * `set` rather than `append`: `URLSearchParams.get` answers with the *first* value, so a second
+ * `backend` behind one the caller already wrote would be ignored by the page, and the capture
+ * labelled WebGL2 would be whatever the caller asked for. The badge is declined because it holds
+ * the loop for three seconds after the first frame and covers the canvas while it does.
+ */
+export function lookUrl(url, backend) {
+  const next = new URL(url);
+  next.searchParams.set('backend', backend);
+  next.searchParams.set('splash', '0');
+  return next.toString();
+}
+
+/**
+ * What a frame is made of: its most common colour, how much of the frame that colour covers, and
+ * its mean luminance.
+ *
+ * Exact colours rather than buckets, because an empty canvas is exactly one colour — the clear
+ * colour — and anything a scene draws, lit and fogged, is a spread of them.
+ */
+export function frameStats(image) {
+  const { width, height, rgba } = image;
+  const counts = new Map();
+  let top = 0;
+  let topKey = 0;
+  let luma = 0;
+  for (let at = 0; at < rgba.length; at += 4) {
+    const key = (rgba[at] << 16) | (rgba[at + 1] << 8) | rgba[at + 2];
+    const count = (counts.get(key) ?? 0) + 1;
+    counts.set(key, count);
+    if (count > top) {
+      top = count;
+      topKey = key;
+    }
+    luma += luminance(rgba, at);
+  }
+  const pixels = width * height;
+  return {
+    width,
+    height,
+    dominant: `#${topKey.toString(16).padStart(6, '0')}`,
+    dominantShare: pixels === 0 ? 1 : top / pixels,
+    meanLuminance: pixels === 0 ? 0 : luma / pixels,
+  };
+}
+
+/** The share of pixels that differ between two frames of one size by more than `tolerance`. */
+export function changedShare(a, b, tolerance = 2) {
+  if (a.width !== b.width || a.height !== b.height) return 1;
+  let changed = 0;
+  for (let at = 0; at < a.rgba.length; at += 4) {
+    if (
+      Math.abs(a.rgba[at] - b.rgba[at]) > tolerance ||
+      Math.abs(a.rgba[at + 1] - b.rgba[at + 1]) > tolerance ||
+      Math.abs(a.rgba[at + 2] - b.rgba[at + 2]) > tolerance
+    ) {
+      changed += 1;
+    }
+  }
+  return changed / (a.width * a.height);
+}
+
+/**
+ * The console, sorted into what fails a look and what does not.
+ *
+ * By the level the browser reported rather than by matching words in the text, because a game is
+ * entitled to log "0 errors" and `cdp.mjs`'s own `complaints()` would count it. A warning fails as
+ * an error does: no console warnings at runtime is part of the engine's definition of done, and an
+ * agent told a warning is harmless learns to stop reading them.
+ */
+export function sortConsole(lines) {
+  const errors = [];
+  const warnings = [];
+  for (const line of lines) {
+    if (/^(error|exception|assert):/.test(line)) errors.push(line);
+    else if (/^(warning|warn):/.test(line)) warnings.push(line);
+  }
+  return { errors, warnings };
+}
+
+/**
+ * Whether the browser offers a WebGPU adapter to this page, asked only when a capture that asked
+ * for WebGPU drew with something else, so the report can say why.
+ */
+const ADAPTER = `(async () => {
+  if (!('gpu' in navigator)) return 'no navigator.gpu';
+  const adapter = await navigator.gpu.requestAdapter();
+  return adapter === null ? 'no adapter' : 'an adapter';
+})()`;
+
+/**
+ * Installed before the page's own scripts: notes every WebGPU and WebGL2 context a canvas asks for.
+ *
+ * **This is what says the game booted, and the obvious test does not.** A `<canvas>` has a drawing
+ * buffer of 300 by 150 from the moment it is parsed, so "a canvas with a size" is true before any
+ * renderer exists — the first version of this module asked exactly that, photographed a page still
+ * reading "starting…", and called it a pass. A context on a canvas in the document is the renderer
+ * itself, and its type is the backend that actually drew rather than the one the address asked
+ * for: `createRenderer` falls back to WebGL2 quietly by design, and hands the reason to the game.
+ *
+ * A context on a canvas that is not in the document at the moment of asking is left out, because
+ * that is a probe, not the game; one appended later is counted then.
+ */
+const WATCH = `(() => {
+  const seen = (window.__driftengineLook = { contexts: [] });
+  const getContext = HTMLCanvasElement.prototype.getContext;
+  HTMLCanvasElement.prototype.getContext = function (type, ...rest) {
+    const context = getContext.call(this, type, ...rest);
+    if (context !== null && (type === 'webgpu' || type === 'webgl2')) seen.contexts.push({ type, canvas: this });
+    return context;
+  };
+})();`;
+
+/** The backend of the last context asked for by a canvas that is in the document now, or null. */
+const DRAWN_WITH = `(() => {
+  const found = (window.__driftengineLook?.contexts ?? []).filter((entry) => entry.canvas.isConnected).at(-1);
+  return found === undefined ? null : found.type;
+})()`;
+
+/** Hides everything on the page except its canvases, so a frame's statistics are the canvas's. */
+const CANVAS_ONLY = `(() => {
+  const style = document.createElement('style');
+  style.id = 'driftengine-look';
+  style.textContent = '* { visibility: hidden !important; } canvas { visibility: visible !important; }';
+  document.head.append(style);
+  return true;
+})()`;
+const RESTORE = `(() => { document.getElementById('driftengine-look')?.remove(); return true; })()`;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function photograph(page, file) {
+  await page.frames(2);
+  await page.screenshot(file);
+  return rgbaOf(decodePng(await readFile(file)));
+}
+
+/**
+ * Open the game once per backend, wait for it to boot, and photograph it.
+ *
+ * `headless: false` opens a real window instead, for a machine whose headless browser cannot reach
+ * its GPU; the photographs are the same, and the window closes when it is done.
+ *
+ * Writes into `out` a PNG of what a player sees per backend (`webgpu.png`, `webgl2.png`), the canvas
+ * alone beside each (`webgpu.canvas.png`), and `look.json`, the report this returns. Throws only
+ * when it cannot look at all — no browser, no hardware GPU, an unsupported platform — and the
+ * message says which. Everything it saw, however bad, comes back in the report instead, with `ok`
+ * false.
+ *
+ * `bootMs` bounds the wait for the renderer's context; `settleMs` is a pause after it for the first
+ * frames; `drawMs` bounds the wait after that for the canvas to show more than one colour, since a
+ * game that streams its world draws empty frames until it arrives; `moveMs` is the gap between the
+ * two frames compared to tell whether it moves.
+ */
+export async function look({
+  url,
+  backends = LOOK_BACKENDS,
+  out = '.driftengine/look',
+  width = 1280,
+  height = 720,
+  bootMs = 30_000,
+  settleMs = 1000,
+  drawMs = 10_000,
+  moveMs = 500,
+  flags = gpuFlagsFor(),
+  headless = true,
+} = {}) {
+  if (typeof url !== 'string') throw new Error('look: pass the address of the running game as url');
+  if (flags === null) {
+    throw new Error(
+      `look: ${process.platform} is not supported. It runs on Windows, macOS and Linux; pass ` +
+        '`flags` to choose the browser flags for another system.',
+    );
+  }
+  await mkdir(out, { recursive: true });
+
+  const browser = await launch({ flags, headless });
+  const report = { url, gpu: '', captures: [], problems: [], ok: false };
+  try {
+    const client = await connect(browser.port);
+    try {
+      report.gpu = await requireHardwareGpu(client);
+      const timing = { bootMs, settleMs, drawMs, moveMs };
+      for (const backend of backends) {
+        report.captures.push(await lookAt(client, { url, backend, out, width, height, ...timing }));
+      }
+    } finally {
+      client.close();
+    }
+  } finally {
+    await browser.close();
+  }
+
+  for (const capture of report.captures) {
+    for (const problem of capture.problems) report.problems.push(`${capture.backend}: ${problem}`);
+  }
+  report.ok = report.problems.length === 0;
+  await writeFile(path.join(out, 'look.json'), `${JSON.stringify(report, null, 2)}\n`);
+  return report;
+}
+
+async function lookAt(client, options) {
+  const { url, backend, out, width, height, bootMs, settleMs, drawMs, moveMs } = options;
+  const address = lookUrl(url, backend);
+  const file = path.join(out, `${backend}.png`);
+  const canvasFile = path.join(out, `${backend}.canvas.png`);
+  const capture = {
+    backend,
+    url: address,
+    file,
+    drawnWith: null,
+    stats: null,
+    moved: null,
+    errors: [],
+    warnings: [],
+    logs: [],
+    problems: [],
+  };
+  const page = await client.page(address, width, height, { beforeLoad: WATCH });
+  try {
+    try {
+      await page.settled(`${DRAWN_WITH} !== null`, { timeoutMs: bootMs, settleMs });
+      capture.drawnWith = await page.eval(DRAWN_WITH);
+    } catch {
+      capture.problems.push(
+        `no canvas in the page asked for a WebGPU or WebGL2 context within ${bootMs} ms: the renderer never started, or the page threw before it did`,
+      );
+    }
+    if (capture.drawnWith !== null) {
+      if (capture.drawnWith !== backend) {
+        const adapter = backend === 'webgpu' ? await page.eval(ADAPTER) : null;
+        const why =
+          adapter === null || adapter === 'an adapter'
+            ? 'the page chose its backend without reading ?backend='
+            : `the browser offered ${adapter}`;
+        capture.problems.push(
+          `asked for ${backend} and drew with ${capture.drawnWith}, so ${backend} was not looked at: ${why}`,
+        );
+      }
+      await page.eval(CANVAS_ONLY);
+      let first = await photograph(page, canvasFile);
+      const deadline = Date.now() + drawMs;
+      while (frameStats(first).dominantShare >= EMPTY_SHARE && Date.now() < deadline) {
+        await sleep(250);
+        first = await photograph(page, canvasFile);
+      }
+      await sleep(moveMs);
+      const second = await photograph(page, canvasFile);
+      await page.eval(RESTORE);
+      await photograph(page, file);
+      capture.stats = frameStats(second);
+      capture.moved = changedShare(first, second);
+      if (capture.stats.dominantShare >= EMPTY_SHARE) {
+        capture.problems.push(
+          `nothing drew: ${percent(capture.stats.dominantShare)} of the canvas is ${capture.stats.dominant}`,
+        );
+      }
+    }
+  } finally {
+    capture.logs = [...page.logs];
+    await page.close();
+  }
+  const { errors, warnings } = sortConsole(capture.logs);
+  capture.errors = errors;
+  capture.warnings = warnings;
+  if (errors.length > 0) capture.problems.push(count(errors.length, 'console error'));
+  if (warnings.length > 0) capture.problems.push(count(warnings.length, 'console warning'));
+  return capture;
+}
+
+const percent = (share) => `${(share * 100).toFixed(1)}%`;
+const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+
+/** The report as lines a person or an agent reads top to bottom: the verdict is the last line. */
+export function formatLook(report) {
+  const lines = [`look: ${report.url}`, `gpu: ${report.gpu}`];
+  for (const capture of report.captures) {
+    lines.push(
+      '',
+      `${capture.backend}: ${capture.stats === null ? 'not photographed' : capture.file}`,
+    );
+    if (capture.drawnWith !== null) lines.push(`  drew with: ${capture.drawnWith}`);
+    if (capture.stats !== null) {
+      lines.push(
+        `  canvas: ${percent(capture.stats.dominantShare)} is its most common colour ${capture.stats.dominant}, mean luminance ${capture.stats.meanLuminance.toFixed(0)} of 255`,
+      );
+    }
+    if (capture.moved !== null) {
+      lines.push(
+        capture.moved > 0
+          ? `  moving: ${percent(capture.moved)} of the canvas changed between two frames`
+          : '  still: no pixel changed between two frames, so nothing animates or the loop stopped',
+      );
+    }
+    for (const line of capture.errors) lines.push(`  ${line}`);
+    for (const line of capture.warnings) lines.push(`  ${line}`);
+    for (const problem of capture.problems) lines.push(`  problem: ${problem}`);
+  }
+  lines.push(
+    '',
+    report.ok
+      ? 'ok: open the PNGs above and check they show what the game should'
+      : `failed: ${count(report.problems.length, 'problem')}`,
+  );
+  return lines.join('\n');
+}

package/src/index.ts

@@ -666,6 +666,8 @@ export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 export type { SurfaceProjection } from './render/surfaceProjection.ts';
+export type { SurfaceLayers } from './render/surfaceLayers.ts';
+export type { SurfaceLayerLook } from './render/surfaceLayerLooks.ts';
 /*
  * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,
  * the one question to ask before handing one over — whether this device takes its format

package/src/render/backend/webgl2/renderer.ts

@@ -117,6 +117,7 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import type { SurfaceProjection } from '../../surfaceProjection.ts';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.ts';
 import { SceneTarget } from '../../sceneTarget.ts';
@@ -1783,9 +1784,14 @@ export class WebGL2Renderer implements RendererApi {
   private readonly transmission = new Float32Array([-1, -1, -1, 0]);
   /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
   private readonly layerFloats = new Float32Array(LAYER_FLOATS);
+  /** `uLayerLooks`, the current material's layer picks and looks packed. See `surfaceLayerLooks.ts`. */
+  private readonly lookFloats = new Float32Array(LOOK_FLOATS);
   /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
   private layersRoom: boolean | null = null;
   private warnedLayersRoom = false;
+  /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
+  private looksRoom: boolean | null = null;
+  private warnedLooksRoom = false;
   private warnedLayersModelMap = false;
   private warnedLayersTriplanar = false;
   private warnedOverlayRoom = false;
@@ -4398,6 +4404,9 @@ export class WebGL2Renderer implements RendererApi {
     packSurfaceLayers(layers, this.layerFloats);
     if (layers !== null) this.askLit('LAYERED');
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+    packLayerLooks(layers, this.lookFloats);
+    if (this.looksFit(layers)) this.askLit('LAYER_LOOKS');
+    gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
     gl.uniform1i(u['uModelMap'] ?? null, MODEL_MAP_TEXTURE_UNIT);
     packModel(
       material?.model ?? null,
@@ -4691,6 +4700,28 @@ export class WebGL2Renderer implements RendererApi {
     return null;
   }
 
+  /**
+   * Whether a layered material's picks and looks are drawn: asked for, and room for their fifteen
+   * vectors beside the layers' four. Refused, the layers are drawn reading layer `i` of their arrays
+   * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
+   * the sentence names the way out.
+   */
+  private looksFit(layers: SurfaceLayers<SurfaceTexture> | null): boolean {
+    if (!asksLayerLooks(layers)) return false;
+    this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
+    if (this.looksRoom) return true;
+    if (!this.warnedLooksRoom) {
+      this.warnedLooksRoom = true;
+      console.warn(
+        "Renderer: a layered material's picks and looks are refused on this device. They take " +
+          'fifteen fragment uniform vectors the lit shader does not have, so its layers read layer ' +
+          'i of its arrays, untinted, at one repeat each. A lower `maxLights` makes the room, or ' +
+          'WebGPU has it.',
+      );
+    }
+    return false;
+  }
+
   /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
   private warnLayersTriplanar(): void {
     if (this.warnedLayersTriplanar) return;
@@ -4701,9 +4732,13 @@ export class WebGL2Renderer implements RendererApi {
     );
   }
 
-  /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
-  private switchFits(feature: LitSwitch): boolean {
+  /**
+   * Whether the lit shader with `feature` compiled in, and `beside` with it where a switch means
+   * nothing alone, fits this GPU's fragment uniform vectors.
+   */
+  private switchFits(feature: LitSwitch, beside?: LitSwitch): boolean {
     const asIf: Partial<Record<LitSwitch, boolean>> = { [feature]: true };
+    if (beside !== undefined) asIf[beside] = true;
     return (
       countUniformVectors(this.flatFragAt(this.lightBudget, asIf)) <= this.fragmentVectorLimit()
     );
@@ -6960,6 +6995,7 @@ export class WebGL2Renderer implements RendererApi {
       worldUvs: asIf.WORLD_UVS ?? this.litOn.WORLD_UVS,
       movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
       layered: asIf.LAYERED ?? this.litOn.LAYERED,
+      layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
       maxLights: budget.maxLights,
       maxAreaLights: budget.maxAreaLights,
     });
@@ -9116,6 +9152,7 @@ export class WebGL2Renderer implements RendererApi {
     resolveTransmission(null, this.transmission);
     /* Nor layers: one layer until a material asks for more. */
     this.layerFloats.fill(0);
+    this.lookFloats.fill(0);
     this.overlayMaps = null;
     this.overlayTexture = null;
     /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -9290,6 +9327,7 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
     gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+    gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
     /* Neither refracting nor glass, which is every draw that does not say otherwise. See
        `bindSeeThrough` for the four numbers in the one vector. */
     gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);

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

@@ -208,6 +208,7 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import {
   frameReflectionsRefused,
   resolveFrameReflections,
@@ -3015,6 +3016,8 @@ export class WebGPURenderer implements RendererApi {
   private readonly projection = new Float32Array(PROJECTION_FLOATS);
   /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
   private readonly layerFloats = new Float32Array(LAYER_FLOATS);
+  /** `uLayerLooks`, the material's layer picks and looks packed by `packLayerLooks`. */
+  private readonly lookFloats = new Float32Array(LOOK_FLOATS);
   /**
    * `uGlassTint` as the material leaves it, its light from behind and that light's colour, which a
    * pane overwrites for its own draw and `releaseSeeThrough` puts back. See `transmission.ts`.
@@ -3588,6 +3591,10 @@ export class WebGPURenderer implements RendererApi {
       packSurfaceLayers(layers, this.layerFloats);
       f.set(this.layerFloats, this.materialField('uLayers'));
       if (layers !== null) this.enableLit('LAYERED');
+      /* And which layer of shared arrays each reads, with its look: layerLooks.ts. */
+      packLayerLooks(layers, this.lookFloats);
+      f.set(this.lookFloats, this.materialField('uLayerLooks'));
+      if (asksLayerLooks(layers)) this.enableLit('LAYER_LOOKS');
       f.set(this.modelParams, this.materialField('uModelParams'));
     });
     /*
@@ -8976,6 +8983,7 @@ export class WebGPURenderer implements RendererApi {
     f.set(this.transmission, at('uGlassTint'));
     /* Nor layers: one layer until a material asks for more. */
     f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
+    f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
     f[at('uCutout')] = 0;
     f[at('uCutout') + 1] = 0;
     this.cutoutResolveStaged = 'hard';

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

@@ -123,7 +123,7 @@ void areaLightAdd(
   lampOpen += areaDiffuse;
   lampShadowed += areaDiffuse * occl * glass;
 
-  if (vSpecular > 0.0 || metal > 0.0) {
+  if (surfaceSpecular > 0.0 || metal > 0.0) {
     vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
     vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
     vec3 c2 = centre + right * halfSize.x - up * halfSize.y;

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

@@ -39,7 +39,8 @@ export type LitSwitch =
   | 'REFLECTION_MAPS'
   | 'WORLD_UVS'
   | 'MOVING_SUN'
-  | 'LAYERED';
+  | 'LAYERED'
+  | 'LAYER_LOOKS';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -55,6 +56,7 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     WORLD_UVS: false,
     MOVING_SUN: false,
     LAYERED: false,
+    LAYER_LOOKS: false,
   };
 }
 

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

@@ -534,6 +534,11 @@ export interface FlatShaderOptions {
    * True when absent. See \`layeredGlsl\`.
    */
   readonly layered?: boolean;
+  /**
+   * Whether a layered material's layers are picked from shared arrays and given looks of their own,
+   * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
+   */
+  readonly layerLooks?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -686,7 +691,7 @@ export function flatFrag(options: FlatShaderOptions): string {
       /* After the reflection maps, so its switch takes the next id; main calls it. worldUv.ts. */
       worldUvGlsl(options.worldUvs ?? true),
       /* After the projection, so its switch takes the next id; the normal map below calls it. */
-      layeredGlsl(options.layered ?? true),
+      layeredGlsl(options.layered ?? true, options.layerLooks ?? 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