@driftengine/core 4.11.1 → 4.13.0

package/src/render/lightMatrix.ts

@@ -68,6 +68,38 @@ export function computeLightMatrix(
   return radius * 6;
 }
 
+/**
+ * A directional light's matrix covering a box of known size whole: a model, a level, a room. The
+ * sphere around the box, at its centre, through `computeLightMatrix`, widened by the half texel the
+ * centre's snap may move it so a corner on the sphere stays inside. Returns the depth span, as that
+ * does.
+ *
+ * **For a scene whose extent is known rather than one that follows a viewer.** A radius chosen by
+ * eye around a guessed centre leaves part of the model outside the map, where it casts nothing; the
+ * bounds are the answer, and a loader has them. **What it gives up** is resolution where the box is
+ * large: the map's texels are spread over all of it, so a building's shadows are coarser than a
+ * focus on the viewer would draw them, which is what `computeLightMatrix` around the viewer is for.
+ */
+export function computeLightMatrixForBounds(
+  lightDir: Vec3,
+  min: Readonly<Vec3>,
+  max: Readonly<Vec3>,
+  shadowMapSize: number,
+  out: mat4,
+): number {
+  const half = Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) / 2;
+  const radius = Math.max(half, 1e-3) * (1 + 2 / Math.max(shadowMapSize, 1));
+  return computeLightMatrix(
+    lightDir,
+    (min[0] + max[0]) / 2,
+    (min[1] + max[1]) / 2,
+    (min[2] + max[2]) / 2,
+    radius,
+    shadowMapSize,
+    out,
+  );
+}
+
 /**
  * The depth an orthographic light matrix spans, in metres: what `computeLightMatrix` returns, read
  * back off any such matrix. Its depth row is the light's axis scaled by two over the span, so the

package/src/render/passGrade.ts

@@ -0,0 +1,58 @@
+/**
+ * Which grade a pass applies to what it draws, decided once for both backends.
+ *
+ * **Every pass grades where nothing after it will**, so a colour handed to the renderer means linear
+ * light wherever it lands. Three facts decide where that is:
+ *
+ * - **A probe's face or a capture stores radiance** for something else to light with or to show, so
+ *   it is never graded. The frame grades what it reads of one; graded at the bake as well, the curve
+ *   would be applied twice.
+ * - **A frame whose resolve grades** (`hdrScene` over a scene target) leaves every pass before the
+ *   resolve linear, because grading early throws away the range the float target exists to keep.
+ * - **Past the present, a pass lands on the canvas the resolve has already written**, so nothing
+ *   after it will grade it and it grades itself with the frame's forward code, composite or not. An
+ *   interface drawn after `endFrame` escapes the screen-space chain; it does not escape the grade.
+ *
+ * **An interface takes the screen encode and not the curve** (`interfaceGrade`). A tone curve and
+ * an exposure are how a scene's light is brought to the screen, and a caption or a panel is not
+ * light: its colour was picked for the screen, so it is encoded wherever the frame is and comes out
+ * as picked under every transform, at every exposure. What it gives up is an interface drawn inside
+ * a frame whose resolve grades (`hdrScene`): that one is part of the picture the resolve tone maps,
+ * and is drawn after `endFrame` to stay out of it. What would make any of this wrong is a composite
+ * step running after the present, which none does.
+ */
+import { forwardTransformCode } from './vertexDefaults.ts';
+
+/**
+ * The `uOutputTransform` a pass uploads: `storing` inside a probe's face or a capture, `presented`
+ * once the frame's resolve has run, `resolveGrades` where that resolve applies the transform.
+ */
+export function passGradeCode(
+  storing: boolean,
+  presented: boolean,
+  resolveGrades: boolean,
+  outputTransform: string,
+): number {
+  if (storing) return 0;
+  return presented || !resolveGrades ? forwardTransformCode(outputTransform) : 0;
+}
+
+/** The `uOutputExposure` beside it: the frame's exposure wherever the pass grades, else one. */
+export function passGradeExposure(
+  storing: boolean,
+  presented: boolean,
+  resolveGrades: boolean,
+  exposure: number,
+): number {
+  if (storing) return 1;
+  return presented || !resolveGrades ? exposure : 1;
+}
+
+/**
+ * The code an interface draws with, given the pass's: the screen encode wherever the pass grades at
+ * all, and nothing where it does not. Never a curve, so never an exposure either: a screen-space
+ * caption, a panel or a 2D layer keeps the colour it was picked as whatever the scene is graded by.
+ */
+export function interfaceGrade(passCode: number): number {
+  return passCode === 0 ? 0 : 1;
+}

package/src/render/plumeRenderer.ts

@@ -173,6 +173,8 @@ export class PlumeRenderer {
     originX = 0,
     originY = 0,
     originZ = 0,
+    outputTransform = 0,
+    outputExposure = 1,
   ): void {
     if (this.indexCount === 0) return;
     const u = this.uniforms;
@@ -200,6 +202,9 @@ export class PlumeRenderer {
     gl.uniform3f(u['uTint'] ?? null, this.tint[0], this.tint[1], this.tint[2]);
     gl.uniform1i(u['uClipEnabled'] ?? null, clipPlane === null ? 0 : 1);
     if (clipPlane !== null) gl.uniform4fv(u['uClipPlane'] ?? null, clipPlane);
+    /* The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+    gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
     bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
 
     gl.enable(gl.BLEND);

package/src/render/renderQuality.ts

@@ -61,22 +61,35 @@ export type SkinScattering = 'pre-integrated' | 'screen-space';
 
 export interface RenderQuality {
   /**
-   * The transfer curve applied at the end of every shaded pass.
-   *
-   * Construction-time, like every other quality control here, and `none` by default so
-   * no existing world changes by a single bit.
-   *
-   * **The symptom, written down because nobody searches for a transfer curve they do not know
-   * exists.** With `none`, values above 1 clip flat rather than rolling off, so a scene with
-   * bright sources against dark surroundings reads as crushed and desaturated: the highlights
-   * go to a hard white with no colour left in them and the midtones look muddy. That is
-   * reported by eye as "dark", "flat" or "not vivid", which sounds like a lighting problem, so
-   * that is where people look. A consumer built, tuned and shipped six worlds before anybody
-   * said the word. If a scene looks like that, try `outputTransform: 'aces'` with an
-   * `outputExposure` before touching a single light.
-   *
-   * The default stays `none`, and that is not the fault: a curve that changed every existing
-   * consumer's output would be far worse than one nobody found.
+   * The transfer curve applied at the end of every shaded pass. Construction-time, like every
+   * other quality control here.
+   *
+   * **`srgb` by default since 4.13.0, the encoding a display expects**: the light the renderer
+   * computes is linear, and a texture's colours are decoded to linear when they are read, so a
+   * frame written without encoding them back is a frame of linear values read as display values —
+   * every midtone far too dark. It is the encoding most renderers apply by default, so a model
+   * drawn here with no options reads as it does elsewhere. **What it gives up** is a highlight's
+   * colour: above 1 each channel clips on its own, so a bright saturated source goes to white
+   * rather than rolling off, which a curve with a shoulder (`aces`, `shoulder`) is for.
+   *
+   * **`none` was the default until 4.13.0, and it is the frame that reads as dark**: values
+   * written as they are computed, which is right only for a world whose colours were chosen by
+   * eye as display values and lit to match. It was reported by eye as "dark", "flat" or "not
+   * vivid", which sounds like a lighting problem, so that is where people looked; a consumer
+   * built, tuned and shipped six worlds under it before anybody said the word, and a model drawn
+   * from the manual came out darker than in any other engine. A world graded under it says
+   * `outputTransform: 'none'` and draws exactly as it did. **What would make `srgb` the wrong
+   * default** is a renderer whose colours are not linear, which this one's are not.
+   *
+   * **Every pass applies it where nothing after it will**, and the clear colour with them, so a
+   * colour handed to the renderer is linear wherever it lands: a frame with `hdrScene` is graded
+   * once at the resolve, and one without it is graded pass by pass to the same curve. A colour
+   * picked by eye is a display value, so it is stated through `srgbColor` (or a mesh built with
+   * `colorSpace: 'srgb'`), which gives back exactly the colour picked where a surface is lit at 1
+   * under `srgb`, and through the curve under a tone curve. **An interface** (screen text, a panel,
+   * the 2D layer) takes the screen encode and never the curve or the exposure, so its colours come
+   * out as picked under every transform; inside an `hdrScene` frame it is part of the picture the
+   * resolve grades, and is drawn after `endFrame` to stay out of the curve.
    */
   readonly outputTransform: OutputTransform;
   /**
@@ -270,9 +283,35 @@ export interface RenderQuality {
    * at a shadow's edge — that is what the blur is for.
    */
   readonly skinScattering: SkinScattering;
-  /** Horizontal world-space reach over which a directional shadow dissolves. */
+  /**
+   * How far a sun shadow may reach along the ground from its caster, in metres, before it
+   * dissolves. **Not a distance from the camera**: a shadow's own length, from where it leaves its
+   * caster to where it lands, fading from 35% of this to all of it.
+   *
+   * **1,000 since 4.13.0, so no building's shadow dissolves**: the fade starts at 350 m, past any
+   * wall, tower or canyon a shadow map covers at a useful resolution, so what bounds a shadow is
+   * its map, whose edge already fades. **What it gives up** is a way to hide a long shadow's
+   * stair-stepping at a low sun, which is what a short reach was for. It was 6 until 4.13.0: a
+   * tuning for short casters, which left a building's walls and arcades casting nothing on its
+   * floor under a high sun — the shadows vanished silently and read as random lighting. **What
+   * would make it wrong** is a scene whose shadows are too coarse to show at their full length;
+   * there a reach of the length that looks right is the setting, and the map around the viewer
+   * (`computeLightMatrix`) the better fix.
+   */
   readonly directionalShadowMaxDistance: number;
-  /** Maximum horizontal projection per vertical metre before low-angle shadows vanish. */
+  /**
+   * How low the sun may stand before its shadows fade, as the ground a metre of height may shadow:
+   * the sun's horizontal reach per vertical metre, so 1 is 45° of elevation and 60 about 1°. Every
+   * sun shadow fades from 65% of this to all of it.
+   *
+   * **60 since 4.13.0: shadows hold until the sun is about a degree above the horizon**, the
+   * stretch of a day when they are longest and most worth seeing. **What it gives up**: a sun on
+   * the horizon throws shadows kilometres long that a map can hold only as stripes, and the
+   * last degree is where they fade rather than show. It was 3 until 4.13.0, which dropped every
+   * sun shadow below about 18° — an evening without shadows. **What would make it wrong** is a
+   * scene whose low sun streaks; a smaller number here is the setting, at the cost of the
+   * shadows going earlier in the evening.
+   */
   readonly directionalShadowMaxSlope: number;
   /**
    * Metres a point light may drift from where its shadow was baked before re-baking.
@@ -958,7 +997,7 @@ export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
  * six times, while the directional map spends all of it on one focused area.
  */
 export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
-  outputTransform: 'none',
+  outputTransform: 'srgb',
   outputExposure: 1,
   pointLightFalloff: 'smooth',
   /**
@@ -1006,8 +1045,8 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   glassShadows: 'full',
   pipelineCompile: 'wait',
   skinScattering: 'pre-integrated',
-  directionalShadowMaxDistance: 6,
-  directionalShadowMaxSlope: 3,
+  directionalShadowMaxDistance: 1000,
+  directionalShadowMaxSlope: 60,
   pointShadowRebakeDistance: 0.001,
   pointShadowFacesPerFrame: 2,
   /*

package/src/render/sceneTarget.ts

@@ -785,6 +785,8 @@ export class SceneTarget {
       readonly transform: number;
       readonly exposure: number;
       readonly film?: Float32Array;
+      /** Whether the forward passes graded the scene because this resolve does not. */
+      readonly sceneGraded?: boolean;
     } = {
       transform: 0,
       exposure: 1,
@@ -1030,6 +1032,7 @@ 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);
+    gl.uniform1i(this.uniforms['uSceneGraded'] ?? null, grade.sceneGraded === true ? 1 : 0);
     if (grade.film !== undefined) {
       gl.uniform4fv(this.uniforms['uFilmA'] ?? null, grade.film, 0, 4);
       gl.uniform4fv(this.uniforms['uFilmB'] ?? null, grade.film, 4, 4);

package/src/render/sdfTextRenderer.ts

@@ -112,7 +112,7 @@ export class SdfTextRenderer {
    */
   /**
    * `outputTransform` and `outputExposure` come from the renderer rather than from here, because
-   * whether this pass grades depends on whether anything after it will. See `Renderer.gradeCode`.
+   * whether this pass grades depends on whether anything after it will. See `passGrade.ts`.
    */
   draw(
     viewProj: ReadonlyMat4,

package/src/render/shaders/arcane.ts

@@ -1,4 +1,5 @@
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * An arcane aura: the volume a floating object sits inside.
@@ -31,6 +32,8 @@ ${FOG_GLSL}
 uniform int uNoiseOctaves;
 uniform vec4 uClipPlane;
 uniform int uClipEnabled;
+/* Before \`uTint\`, where fire and smoke declare it, so one field table serves all three. */
+${OUTPUT_TRANSFORM_GLSL}
 /** The caller's colour, so an aura shifts with the world's own palette. */
 uniform vec3 uTint;
 
@@ -98,6 +101,7 @@ void main() {
   col = mix(col, mediumColor(), fog);
   alpha *= 1.0 - fog;
 
-  outColor = vec4(col, alpha);
+  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */
+  outColor = vec4(applyOutputTransform(col), alpha);
 }
 `;

package/src/render/shaders/bolt.ts

@@ -1,4 +1,5 @@
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * Electrical arcs: a filament with a saturating core and a wide soft glow.
@@ -95,6 +96,7 @@ ${FOG_GLSL}
 uniform vec3 uCameraPos;
 
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 float hash11(float p) {
   return fract(sin(p * 12.9898) * 43758.5453123);
@@ -165,6 +167,7 @@ void main() {
    * faint: at a typical energy of 0.5 it delivered a quarter of what it asked for.
    * Every emissive material here has to pick one channel and mean it.
    */
-  outColor = vec4(lit * energy * (1.0 - fog), 1.0);
+  /* Graded where nothing after this will grade it, as every pass is, light added included. */
+  outColor = vec4(applyOutputTransform(lit * energy * (1.0 - fog)), 1.0);
 }
 `;

package/src/render/shaders/caustics.ts

@@ -1,5 +1,6 @@
 import { GERSTNER_GLSL } from './gerstner.ts';
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * Light off water, projected onto what covers it.
@@ -78,6 +79,7 @@ uniform float uMaxDrop;
 ${FOG_GLSL}
 
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 ${GERSTNER_GLSL}
 
@@ -164,6 +166,7 @@ void main() {
   float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
 
   // Additive: this is light arriving at a surface that is already shaded.
-  outColor = vec4(uTint * (caustic * uStrength * reach * (1.0 - fog)), 1.0);
+  /* Graded where nothing after this will grade it, as every pass is, light added included. */
+  outColor = vec4(applyOutputTransform(uTint * (caustic * uStrength * reach * (1.0 - fog))), 1.0);
 }
 `;

package/src/render/shaders/decalProject.ts

@@ -24,6 +24,7 @@
  */
 
 import { glslIsFarDepth } from '../depthConvention.ts';
+import { LINEAR_TO_SRGB_GLSL } from './outputTransform.ts';
 
 export const DECAL_PROJECT_FRAG = `#version 300 es
 precision highp float;
@@ -63,7 +64,9 @@ uniform float uDecalOpacity;
 uniform float uDecalFacingCos;
 /** How much of the mark's radius is edge. */
 uniform float uDecalSoftness;
-
+/** How the frame under the marks was graded, 0 where the resolve grades it. See renderQuality.ts. */
+uniform int uOutputTransform;
+${LINEAR_TO_SRGB_GLSL}
 out vec4 fragColor;
 
 void main() {
@@ -122,6 +125,13 @@ void main() {
   mark *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
 
   /* White is the identity of a multiply, so a pixel the projector missed changes nothing. */
-  fragColor = vec4(mix(vec3(1.0), uDecalColor, mark * uDecalOpacity), 1.0);
+  vec3 multiply = mix(vec3(1.0), uDecalColor, mark * uDecalOpacity);
+  /*
+   * **The multiply as an encoded pixel takes it**, where the frame was graded before this: the
+   * receiver is a display value, and darkening its light by a factor is darkening the display value
+   * by that factor encoded — exact through the sRGB encode, whose power carries a product through,
+   * and close through a curve, which bends it. A frame graded at the resolve multiplies linear light.
+   */
+  fragColor = vec4(mix(multiply, linearToSrgb(multiply), float(uOutputTransform != 0)), 1.0);
 }
 `;

package/src/render/shaders/film.ts

@@ -1,4 +1,5 @@
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * A thin, wet, iridescent film lying on a surface.
@@ -122,6 +123,7 @@ uniform float uFilmRoughness;
 uniform float uFilmRoughnessCycles;
 
 out vec4 fragColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 /** A hue wheel, without a texture. Standard 6-segment ramp. */
 vec3 hue(float h) {
@@ -199,6 +201,19 @@ void main() {
   vec3 base = vTint * 0.9;
   vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);
 
+  /*
+   * **Graded before the mirror is mixed in**, as every pass grades what it draws when nothing after
+   * it will, because the mirror's own passes graded what it holds. The fog that used to follow the
+   * mirror distributes over the mix, so the film's own colour is fogged and graded here, and what
+   * the mirror shows is fogged toward the same air, graded, where it is mixed in below.
+   */
+  // The same fog every other pass applies — and now literally the same code, which
+  // it was not: this ran its own curve while claiming otherwise, so a slick receded
+  // at a different rate than the deck it was lying on.
+  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);
+  vec3 gradedAir = applyOutputTransform(mediumColor());
+  vec3 graded = applyOutputTransform(mix(color, mediumColor(), fog));
+
   /*
    * The mirrored scene, under the sheen rather than instead of it.
    *
@@ -208,7 +223,7 @@ void main() {
    *
    * Weighted by the grazing term as well as by strength, because that is what a reflection does:
    * a wet surface underfoot shows almost nothing and the same surface down the street shows the
-   * whole scene. Added before the fog so the image recedes with everything else in the frame.
+   * whole scene. Fogged as the film is, so the image recedes with everything else in the frame.
    */
   if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {
     vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;
@@ -254,15 +269,13 @@ void main() {
       valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));
     }
     vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;
-    color = mix(color, mirrored, valid * uReflectionStrength * (0.25 + grazing * 0.75));
+    graded = mix(
+      graded,
+      mix(mirrored, gradedAir, fog),
+      valid * uReflectionStrength * (0.25 + grazing * 0.75)
+    );
   }
 
-  // The same fog every other pass applies — and now literally the same code, which
-  // it was not: this ran its own curve while claiming otherwise, so a slick receded
-  // at a different rate than the deck it was lying on.
-  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);
-  color = mix(color, mediumColor(), fog);
-
   /*
    * Alpha from coverage, squared.
    *
@@ -280,6 +293,6 @@ void main() {
    */
   float coverage = clamp(vCoverage, 0.0, 1.0);
   float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;
-  fragColor = vec4(color, alpha);
+  fragColor = vec4(graded, alpha);
 }
 `;

package/src/render/shaders/fire.ts

@@ -1,4 +1,5 @@
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * Procedural flames: camera-facing quads whose shape and colour come entirely
@@ -116,6 +117,7 @@ uniform vec4 uClipPlane;
 uniform int uClipEnabled;
 
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 float hash21(vec2 p) {
   return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
@@ -175,6 +177,7 @@ void main() {
   col = mix(col, mediumColor(), fog);
   alpha *= 1.0 - fog;
 
-  outColor = vec4(col, alpha);
+  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */
+  outColor = vec4(applyOutputTransform(col), alpha);
 }
 `;

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

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

@@ -0,0 +1,108 @@
+/**
+ * Which layer of the shared arrays each of a layered material's layers reads, and how each looks:
+ * `uLayerLooks`, packed by `surfaceLayerLooks.ts`, read by `layered.ts`.
+ *
+ * **Every helper is the identity where the switch is off**, written as a branch on `LAYER_LOOKS`
+ * itself because the generated WGSL carries one string for both values of an override: layer `i`
+ * reads layer `i`, the maps beyond the layers start at the layer count, a tint is white, a range is
+ * 0 to 1, a normal is as stored, a specular is the surface's own, a repeat down is the repeat
+ * across, and nothing is occluded — exactly what `layered.ts` did before this existed, which is what
+ * a layered material that asks for none of it has to keep drawing.
+ *
+ * **A lit switch, `LAYER_LOOKS`**, off until a material first asks and declared after `LAYERED`, so
+ * every switch before it keeps its id. It is only ever compiled beside `LAYERED`, whose `uLayers`
+ * it reads.
+ */
+export function layerLooksGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool LAYER_LOOKS = false;  // wgsl:override
+float layerArray(int i) { return float(i); }
+float layerExtras() { return uLayers[1].y; }
+vec3 layerTint(int i) { return vec3(1.0); }
+vec2 layerRanges(int i, vec2 roughMetal) { return roughMetal; }
+vec3 layerStrengthen(int i, vec3 texel) { return texel; }
+float layerNamedSpecular(int i) { return -1.0; }
+float layerRepeatDown(int i, float across) { return across; }
+vec2 layerOcclusionStrengths() { return vec2(0.0); }
+vec2 layerOcclusionRange() { return vec2(0.0, 1.0); }
+`;
+  }
+  return /* glsl */ `
+/* Whether layers are picked from shared arrays and given looks of their own: layerLooks.ts. */
+const bool LAYER_LOOKS = true;  // wgsl:override
+/*
+ * Fifteen vectors, as surfaceLayerLooks.ts packs them: the array layer each of the five reads, base
+ * first (floats 0 to 4); where the maps beyond the layers start (5), the mesh occlusion's strength
+ * on the colour, from 0 up (6), and on the ambient light (7); then two vectors a
+ * layer, base first: its tint (x y z) and normal strength (w), then its roughness range (x to y)
+ * and metalness range (z to w); then each layer's specular, -1 for the surface's own (48 to 52), its
+ * repeat down (53 to 57), and the occlusion's range (58 to 59).
+ */
+uniform vec4 uLayerLooks[15]; // wgsl:material
+
+/* Float k of the fifteen vectors. */
+float layerLook(int k) {
+  return uLayerLooks[k / 4][k % 4];
+}
+
+/* The layer of the albedo, normal and ORM arrays a material's layer i reads. */
+float layerArray(int i) {
+  if (LAYER_LOOKS) return layerLook(i);
+  return float(i);
+}
+
+/* Where the maps beyond the layers start in each array. */
+float layerExtras() {
+  if (LAYER_LOOKS) return uLayerLooks[1].y;
+  return uLayers[1].y;
+}
+
+vec3 layerTint(int i) {
+  if (LAYER_LOOKS) return uLayerLooks[2 + i * 2].xyz;
+  return vec3(1.0);
+}
+
+/* The ORM's roughness and metalness, each spread over the layer's own range. */
+vec2 layerRanges(int i, vec2 roughMetal) {
+  if (LAYER_LOOKS) {
+    vec4 range = uLayerLooks[3 + i * 2];
+    return vec2(mix(range.x, range.y, roughMetal.x), mix(range.z, range.w, roughMetal.y));
+  }
+  return roughMetal;
+}
+
+/*
+ * A tangent-space texel bent further or less by the layer's strength: its x and y scaled, its z
+ * kept, so 0 lies flat and a strength above 1 steepens every slope the map holds. z is held above
+ * zero so a texel lying exactly flat on its surface cannot normalise to nothing at strength 0.
+ */
+vec3 layerStrengthen(int i, vec3 texel) {
+  if (LAYER_LOOKS) return normalize(vec3(texel.xy * uLayerLooks[2 + i * 2].w, max(texel.z, 1e-4)));
+  return texel;
+}
+
+/* The specular the layer names, or -1 where it names none and the surface's own stands. */
+float layerNamedSpecular(int i) {
+  if (LAYER_LOOKS) return layerLook(48 + i);
+  return -1.0;
+}
+
+/* The layer's repeat down, which is its repeat across unless it gave two. */
+float layerRepeatDown(int i, float across) {
+  if (LAYER_LOOKS) return layerLook(53 + i);
+  return across;
+}
+
+/* The mesh occlusion's strength on the colour (x), from 0 up, and on the ambient light (y). */
+vec2 layerOcclusionStrengths() {
+  if (LAYER_LOOKS) return uLayerLooks[1].zw;
+  return vec2(0.0);
+}
+
+vec2 layerOcclusionRange() {
+  if (LAYER_LOOKS) return uLayerLooks[14].zw;
+  return vec2(0.0, 1.0);
+}
+`;
+}