@driftengine/core 4.11.0 → 4.12.0

package/src/render/instances.ts

@@ -46,9 +46,16 @@ export interface MeshInstances {
    * read by a draw whose material is a `lightmapModel` — instances of one mesh in one material sit
    * in different regions of one page, each applied before the material's own region. **They ride
    * the tint and the opacity**, which a lightmapped instance gives up (see `lightmap.ts`): where
-   * these are given, those are not read. **A lightmapped batch needs them**, since a bake is
+   * these are given, the tints are not read. **A lightmapped batch needs them**, since a bake is
    * different light at each instance; one drawn without them reads its tints as its regions, and
    * either mismatch is said once on the console.
+   *
+   * **The opacity survives, in sixty-fourths**, so a lightmapped instance fades by
+   * `setDitherOpacity` as any other does: its transparency travels as whole steps of 2 added to the
+   * region's U offset, which is a place in a page and so under 1, and the vertex stage takes them
+   * back off (`LIGHTMAP_OPACITY_STEPS`). Sixty-four is the screen door's own resolution, an 8x8
+   * pattern. **What it gives up**: a fading instance's offset keeps 16 bits of fraction rather than
+   * 23, a sixteenth of a texel on a 4,096 page; an opaque one is written to the bit as before.
    */
   readonly lightmapRegions?: Float32Array;
   /**
@@ -109,6 +116,12 @@ export function createMeshInstances(capacity: number): MeshInstances {
  */
 export const INSTANCE_FLOATS = 20;
 
+/**
+ * How finely a lightmapped instance's opacity travels in its region: transparency in steps of
+ * 1/64, each 2 on the U offset. See `MeshInstances.lightmapRegions`; the vertex stage reads it back.
+ */
+export const LIGHTMAP_OPACITY_STEPS = 64;
+
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
 
@@ -138,6 +151,10 @@ export function packInstances(instances: MeshInstances, out: Float32Array): void
     if (lightmapRegions !== undefined) {
       /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
       for (let c = 0; c < 4; c += 1) out[at + 16 + c] = lightmapRegions[i * 4 + c] as number;
+      /* And the opacity's transparency in whole steps of 2 on the U offset, none where opaque. */
+      const alpha = Math.min(Math.max(alphas?.[i] ?? 1, 0), 1);
+      const steps = Math.round((1 - alpha) * LIGHTMAP_OPACITY_STEPS);
+      if (steps > 0) out[at + 18] = (out[at + 18] as number) + 2 * steps;
       continue;
     }
     const t = i * 3;

package/src/render/occlusionFade.ts

@@ -0,0 +1,29 @@
+/**
+ * Where ambient occlusion fades out with distance: `setAmbientOcclusionFade`'s two numbers as the
+ * estimate reads them, `uFade` in `shaders/ambientOcclusion.ts`.
+ *
+ * **Occlusion is whole up to `distance` metres from the eye and gone `radius` metres past it.** A
+ * screen-space estimate reaches as far as the depth does, and far off the depth buffer's steps are
+ * metres apart: a sky dome or a mountain range kilometres away is shaded in rings that follow
+ * those steps, and nothing there is in contact with anything the estimate could be right about.
+ * A pixel past the fade skips the estimate's walk, as the sky does, so it costs less as well.
+ *
+ * **What it gives up**: distant contact shade that is real — a doorway a hundred metres off — fades
+ * with the rest, and the distance is the eye's and not the subject's, so a long lens fades what it
+ * frames close up. What would make it wrong is a scene whose far depth is precise enough to shade,
+ * which is a reason to fade further, not to leave the fade off.
+ */
+
+/** `uFade` for no fade: a distance below zero, which the estimate reads as "never". */
+const NO_FADE = -1;
+
+/**
+ * `distance` and `radius` into `out`, `[distance, radius]`. A distance that is not a finite number
+ * at or above zero is no fade, `[−1, 0]`, so `Infinity` reads as "never fades". A radius below zero
+ * or not a number is 0, which is a cut at `distance` rather than a ramp.
+ */
+export function resolveOcclusionFade(distance: number, radius: number, out: Float32Array): void {
+  const fades = Number.isFinite(distance) && distance >= 0;
+  out[0] = fades ? distance : NO_FADE;
+  out[1] = fades && Number.isFinite(radius) ? Math.max(radius, 0) : 0;
+}

package/src/render/sceneTarget.ts

@@ -800,6 +800,8 @@ export class SceneTarget {
       /** The projection's x and y scales, which turn a world radius into a screen one. */
       readonly projScale: Float32Array;
       readonly invProjection: Float32Array;
+      /** Where it fades out with distance, `uFade`: see `occlusionFade.ts`. */
+      readonly fade: Float32Array;
       /** Where the frame's jitter put the occlusion, in uv: see the shader's `uAoOffset`. */
       readonly offset?: Float32Array;
     },
@@ -959,6 +961,7 @@ export class SceneTarget {
         ao.radius,
         ao.projScale,
         ao.invProjection,
+        ao.fade,
       );
     }
 

package/src/render/shaders/ambientOcclusion.ts

@@ -76,6 +76,11 @@ uniform vec2 uProjScale;
 uniform mat4 uInvProjection;
 /** How far the sampling reaches, in metres of the world. */
 uniform float uRadius;
+/**
+ * Where occlusion fades out: whole up to x metres from the eye, gone y metres past it, and no fade
+ * where x is below zero. See occlusionFade.ts.
+ */
+uniform vec2 uFade;
 
 out float fragColor;
 
@@ -168,6 +173,12 @@ void main() {
     fragColor = 1.0;
     return;
   }
+  /* How far past the caller's fade this pixel is, and open with no walk where it is all the way. */
+  float faded = uFade.x < 0.0 ? 0.0 : clamp((length(p) - uFade.x) / max(uFade.y, 1e-4), 0.0, 1.0);
+  if (faded >= 1.0) {
+    fragColor = AO_STORE;
+    return;
+  }
 
   /*
    * At a silhouette, the quad derivative above is replaced by the one-sided difference that
@@ -308,7 +319,7 @@ void main() {
     visible += projectedLength * gtaoArc(h0, h1, normalAngle);
   }
 
-  fragColor = clamp(visible / float(AO_SLICES) * AO_STORE, 0.0, 1.0);
+  fragColor = clamp(mix(visible / float(AO_SLICES), 1.0, faded) * AO_STORE, 0.0, 1.0);
 }
 `;
 

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

@@ -18,6 +18,7 @@ import { modelsGlsl } from './models.ts';
 import { AREA_LIGHT_GLSL } from './areaLight.ts';
 import { NORMAL_MAP_GLSL } from './normalMap.ts';
 import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
+import { LIGHTMAP_OPACITY_STEPS } from '../../instances.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
 import { overlayGlsl } from './overlay.ts';
 import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
@@ -342,10 +343,16 @@ void main() {
   vAlpha = aInstanceTint.w;
   vThickness = 1.0;
   if (LIGHTMAP_REGIONS) {
+    /*
+     * The opacity's transparency rides the U offset as whole steps of 2, the offset itself under 1
+     * (\`MeshInstances.lightmapRegions\`): taken off, and none where the instance is opaque.
+     */
+    float steps = floor(aInstanceTint.z * 0.5);
+    float offsetU = aInstanceTint.z - 2.0 * steps;
     /* Out of the lane's \`-1 - uv\`, through the region, and back into it. See lightmap.ts. */
-    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + aInstanceTint.z);
+    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + offsetU);
     vRelief = -1.0 - ((-1.0 - aRelief) * aInstanceTint.y + aInstanceTint.w);
-    vAlpha = 1.0;
+    vAlpha = 1.0 - steps / ${LIGHTMAP_OPACITY_STEPS.toFixed(1)};
   }
 #else
   vSkyDirect = aChannel.y;
@@ -527,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.
    *
@@ -679,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,116 @@
+/**
+ * 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 layerSpecular(int i, float own) { return own; }
+float layerRepeatDown(int i, float across) { return across; }
+float layerOcclusionStrength() { return 0.0; }
+bool layerOcclusionAmbient() { return false; }
+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
+ * (6) and whether it darkens the ambient light rather than the colour (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 layer's specular, or the surface's own where it names none. */
+float layerSpecular(int i, float own) {
+  if (LAYER_LOOKS) {
+    float named = layerLook(48 + i);
+    return named < 0.0 ? own : named;
+  }
+  return own;
+}
+
+/* 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;
+}
+
+float layerOcclusionStrength() {
+  if (LAYER_LOOKS) return uLayerLooks[1].z;
+  return 0.0;
+}
+
+bool layerOcclusionAmbient() {
+  if (LAYER_LOOKS) return uLayerLooks[1].w > 0.5;
+  return false;
+}
+
+vec2 layerOcclusionRange() {
+  if (LAYER_LOOKS) return uLayerLooks[14].zw;
+  return vec2(0.0, 1.0);
+}
+`;
+}

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

@@ -1,106 +1,239 @@
+import { layerLooksGlsl } from './layerLooks.ts';
+
 /**
  * A material blended from layers by a mask: `SurfaceMaterial.layers`, packed into `uLayers` by
  * `surfaceLayers.ts`.
  *
- * **Layer `i` is layer `i` of the material's arrays**, each read at the mesh's coordinates times its
- * own repeat; the mask is layer 0 of the map a shading model would read, at the mesh's coordinates.
- * Each channel lays a layer over everything before it — red layer 1, green 2, blue 3, alpha 4 — so a
- * layer's share is its channel times one less each later channel, and the base keeps what none of
- * them took. Colour, roughness and occlusion are blended by those shares, and the normal map's
- * tangent-space texels too, before the frame turns them into the world.
+ * **Layer `i` is layer `i` of the material's arrays** — or the layer `layerLooks.ts` picks, with the
+ * tint, ranges and normal strength it gives each — each read at its own repeat of where the
+ * layers are laid: the mesh's coordinates, or the world's horizontal plane where the material has a
+ * projection (`worldUv.ts`). The mask's channels weigh layers 1 to 4 — red, green, blue, alpha — and
+ * come from a map read where a shading model's would be, from the ORM array's layer past the layers,
+ * or from the vertex colour; an added mask placed as the layers are raises one layer's weight, and
+ * one layer may be weighed by how much the surface faces up instead of by its channel.
+ *
+ * **Two ways to combine them.** Laid over, each layer covers everything before it, so a layer's
+ * share is its weight times one less each later weight, and the base keeps what none took. Summed,
+ * the base is mixed toward each layer times its weight by the weights' sum held to 1, so each
+ * layer's share is its weight times that and the base keeps the rest. The shares are worked out once
+ * a pixel, in `layeredBegin`; colour, roughness and occlusion are blended by them, and the normal
+ * map's tangent-space texels too, before the frame turns them into the world — around a normal read
+ * at the mesh's own coordinates, where the material lays one under the layers.
  *
  * **Every layer present is read, whatever its share.** A read whose level is implicit is legal only
  * in uniform control flow (AGENTS.md 2026-08-07), so the loop is bounded by the layer count, a
  * uniform, and never skips on a share, which is the pixel's own.
  *
- * **A lit switch, `LAYERED`**, off until a material first asks, declared last so every switch before
- * it keeps its id. Compiled out, its two vectors are not declared and its calls are constants.
+ * **A lit switch, `LAYERED`**, off until a material first asks, declared after every switch before
+ * it so each keeps its id. Compiled out, its four vectors are not declared and its calls are
+ * constants. `looks` compiles `LAYER_LOOKS` in beside it, and means nothing without it.
  */
-export function layeredGlsl(on: boolean): string {
+export function layeredGlsl(on: boolean, looks = false): string {
   if (!on) {
     return /* glsl */ `
 const bool LAYERED = false;  // wgsl:override
 bool layered() { return false; }
 void layeredBegin() {}
+vec3 layeredColor(vec3 color) { return color; }
 vec4 layeredAlbedo() { return vec4(1.0); }
 vec3 layeredOrm() { return vec3(1.0); }
 vec3 layeredTexel() { return vec3(0.0, 0.0, 1.0); }
+bool layeredMeshNormal() { return false; }
+vec3 layeredMeshTexel() { return vec3(0.0, 0.0, 1.0); }
 bool layeredGlows() { return false; }
 vec3 layeredEmissive() { return vec3(0.0); }
+float layeredAmbient() { return 1.0; }
+float layeredSpecular(float own) { return own; }
 `;
   }
   return /* glsl */ `
 /* Whether this program blends a material's layers. Off but where one has asked: layered.ts. */
 const bool LAYERED = true;  // wgsl:override
-/* The five repeats, base first (x y z w, then x), the count (y) and the glowing layer, or -1 (z). */
-uniform vec4 uLayers[2]; // wgsl:material
-
-/* The mask's channels that lay a layer, zero past the count: read once, in layeredBegin. */
-vec4 lMask;
+/*
+ * Four vectors, as surfaceLayers.ts packs them: the five repeats, base first (x y z w, then x); the
+ * count (y), the glowing layer or -1 (z) and where the mask is, 0 a map, 1 the ORM array, 2 the
+ * vertex colour (w); the blend, 0 over and 1 summed (x), whether a mesh normal is laid under the
+ * layers (y), the added mask's layer or -1 (z) and its repeat (w); its intensity (x), the facing
+ * layer or -1 (y), its bias (z) and its sharpness (w).
+ */
+uniform vec4 uLayers[4]; // wgsl:material
+${layerLooksGlsl(looks)}
+/* Each layer's share of this point, the base's and layers 1 to 4's: worked out once, in layeredBegin. */
+float lShareBase;
+vec4 lShare;
+/* What an occlusion read at the mesh's coordinates leaves of this point, 1 where none: layeredBegin. */
+float lMeshOcclusion;
 
 bool layered() {
   return uLayers[1].y > 0.5;
 }
 
-/* The mask, at the mesh's coordinates, where a model's map is. Under a branch on uniforms. */
-void layeredBegin() {
-  vec4 m = texture(uModelMap, vec3(vUv.xy, 0.0));
-  float n = uLayers[1].y;
-  lMask = vec4(n > 1.5 ? m.r : 0.0, n > 2.5 ? m.g : 0.0, n > 3.5 ? m.b : 0.0, n > 4.5 ? m.a : 0.0);
+float layerRepeat(int i) {
+  return i < 4 ? uLayers[0][i] : uLayers[1].x;
 }
 
-/* Layer i's share of this point: its channel, less every later layer's. */
-float layerShare(int i) {
-  float keep = 1.0;
-  for (int j = 3; j >= 0; j--) {
-    if (j + 1 == i) return lMask[j] * keep;
-    keep *= 1.0 - lMask[j];
+/* Where the layers are laid: the world's horizontal plane under a projection, the mesh's otherwise. */
+vec2 layerPlace() {
+  if (WORLD_UVS && projected()) return planarAt();
+  return vUv.xy;
+}
+
+vec3 layerAt(int i) {
+  float across = layerRepeat(i);
+  return vec3(layerPlace() * vec2(across, layerRepeatDown(i, across)), layerArray(i));
+}
+
+/* The weights as the material keeps them: the mask's channels, at the mesh's own coordinates. */
+vec4 layerWeights() {
+  float source = uLayers[1].w;
+  if (source > 1.5) return vec4(vColor, 0.0);
+  if (source > 0.5) return texture(uOrmMap, vec3(vUv.xy, layerExtras()));
+  return texture(uModelMap, vec3(vUv.xy, 0.0));
+}
+
+/* Which of layers 1 to 4 a packed layer number names, as a vector of one 1: none for -1. */
+vec4 layerPick(float layer) {
+  return vec4(equal(vec4(layer), vec4(1.0, 2.0, 3.0, 4.0)));
+}
+
+/*
+ * The weights, changed where the material asks and zero past the count, and every share from them.
+ * Under a branch on uniforms, as its reads are.
+ */
+void layeredBegin() {
+  /*
+   * The occlusion at the mesh's coordinates, once: the ORM array's layer past the layers and past
+   * any mask and added mask it carries, spread over its range and taken at its strength.
+   */
+  lMeshOcclusion = 1.0;
+  float strength = layerOcclusionStrength();
+  if (strength > 0.0) {
+    float at = layerExtras() + (abs(uLayers[1].w - 1.0) < 0.5 ? 1.0 : 0.0) + (uLayers[2].z > 0.5 ? 1.0 : 0.0);
+    vec2 range = layerOcclusionRange();
+    float occlusion = mix(range.x, range.y, texture(uOrmMap, vec3(vUv.xy, at)).r);
+    lMeshOcclusion = mix(1.0, occlusion, strength);
+  }
+  vec4 m = layerWeights();
+  if (uLayers[2].z > 0.5) {
+    /* The ORM array's layer past the layers, and past the mask where the array carries that too. */
+    float at = layerExtras() + (abs(uLayers[1].w - 1.0) < 0.5 ? 1.0 : 0.0);
+    float added = texture(uOrmMap, vec3(layerPlace() * uLayers[2].w, at)).r * uLayers[3].x;
+    m = mix(m, clamp(m + added, 0.0, 1.0), layerPick(uLayers[2].z));
+  }
+  if (uLayers[3].y > 0.5) {
+    float up = normalize(vNormal).y * 0.5 + 0.5;
+    float facing = clamp(uLayers[3].z + uLayers[3].w * up, 0.0, 1.0);
+    m = mix(m, vec4(facing), layerPick(uLayers[3].y));
   }
-  return keep;
+  float n = uLayers[1].y;
+  m *= vec4(n > 1.5 ? 1.0 : 0.0, n > 2.5 ? 1.0 : 0.0, n > 3.5 ? 1.0 : 0.0, n > 4.5 ? 1.0 : 0.0);
+  if (uLayers[2].x > 0.5) {
+    float taken = min(m.x + m.y + m.z + m.w, 1.0);
+    lShare = m * taken;
+    lShareBase = 1.0 - taken;
+    return;
+  }
+  /* Each over everything before it: a layer keeps its weight of what every later one leaves. */
+  float keep = 1.0;
+  lShare.w = m.w * keep;
+  keep *= 1.0 - m.w;
+  lShare.z = m.z * keep;
+  keep *= 1.0 - m.z;
+  lShare.y = m.y * keep;
+  keep *= 1.0 - m.y;
+  lShare.x = m.x * keep;
+  keep *= 1.0 - m.x;
+  lShareBase = keep;
 }
 
-float layerRepeat(int i) {
-  return i < 4 ? uLayers[0][i] : uLayers[1].x;
+float layerShare(int i) {
+  if (i == 0) return lShareBase;
+  return lShare[i - 1];
 }
 
-vec3 layerAt(int i) {
-  return vec3(vUv.xy * layerRepeat(i), float(i));
+/* The vertex colour's part in the albedo: none where it is the mask instead. */
+vec3 layeredColor(vec3 color) {
+  return uLayers[1].w > 1.5 ? vec3(1.0) : color;
 }
 
-/* Colour by the shares, and the base layer's coverage, which a cutout reads. */
+/*
+ * Colour by the shares, each layer's tinted, and the base layer's coverage, which a cutout reads;
+ * then darkened by the occlusion at the mesh's coordinates, where it is the colour that takes it.
+ */
 vec4 layeredAlbedo() {
   vec4 sum = vec4(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
     vec4 t = texture(uAlbedo, layerAt(i));
-    sum.rgb += t.rgb * layerShare(i);
+    sum.rgb += t.rgb * layerTint(i) * layerShare(i);
     if (i == 0) sum.a = t.a;
   }
+  if (!layerOcclusionAmbient()) sum.rgb *= lMeshOcclusion;
   return sum;
 }
 
+/* What the ambient light keeps: the occlusion at the mesh's coordinates, where it takes it. */
+float layeredAmbient() {
+  return layerOcclusionAmbient() ? lMeshOcclusion : 1.0;
+}
+
+/*
+ * The specular by the shares, each layer's own or the surface's where it names none. The surface's
+ * own, untouched, where no material has asked for looks: shares summing to one in floating point
+ * are not quite one, and a layered material that names nothing must draw exactly as before.
+ */
+float layeredSpecular(float own) {
+  if (LAYER_LOOKS) {
+    float sum = 0.0;
+    for (int i = 0; i < 5; i++) {
+      if (float(i) >= uLayers[1].y) break;
+      sum += layerSpecular(i, own) * layerShare(i);
+    }
+    return sum;
+  }
+  return own;
+}
+
+/* Occlusion, roughness and metalness by the shares, each layer's spread over its own ranges. */
 vec3 layeredOrm() {
   vec3 sum = vec3(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
-    sum += texture(uOrmMap, layerAt(i)).rgb * layerShare(i);
+    vec3 t = texture(uOrmMap, layerAt(i)).rgb;
+    t.yz = layerRanges(i, t.yz);
+    sum += t * layerShare(i);
   }
   return sum;
 }
 
-/* The tangent-space texels blended, each with its z rebuilt where a two-channel map stored none. */
+/* A tangent-space texel off the normal array, its z rebuilt where a two-channel map stored none. */
+vec3 layerNormalTexel(vec3 at) {
+  vec3 t = texture(uNormalMap, at).xyz * 2.0 - 1.0;
+  t.z = t.z > 0.0 ? t.z : sqrt(max(0.0, 1.0 - dot(t.xy, t.xy)));
+  return t;
+}
+
+/* The tangent-space texels blended by the shares. */
 vec3 layeredTexel() {
   vec3 sum = vec3(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
-    vec3 t = texture(uNormalMap, layerAt(i)).xyz * 2.0 - 1.0;
-    t.z = t.z > 0.0 ? t.z : sqrt(max(0.0, 1.0 - dot(t.xy, t.xy)));
-    sum += t * layerShare(i);
+    sum += layerStrengthen(i, layerNormalTexel(layerAt(i))) * layerShare(i);
   }
   float len = length(sum);
   return len > 1e-5 ? sum / len : vec3(0.0, 0.0, 1.0);
 }
 
+/* Whether a normal read at the mesh's own coordinates lies under the layers. */
+bool layeredMeshNormal() {
+  return uLayers[2].y > 0.5;
+}
+
+/* That normal's texel: the normal array's layer past the layers, at the mesh's coordinates. */
+vec3 layeredMeshTexel() {
+  return layerNormalTexel(vec3(vUv.xy, layerExtras()));
+}
+
 /* Whether the emissive map belongs to one layer rather than to the whole surface. */
 bool layeredGlows() {
   return uLayers[1].z > -0.5;

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

@@ -18,6 +18,9 @@ export const MAIN_GLSL = `void main() {
   projectSurface(surfaceAt, frameAt, frameTangents);
   /* A layered material's mask, read once for every layer's share below: layered.ts. */
   if (LAYERED && layered()) layeredBegin();
+  /* And the specular every highlight below reads: its layers' own, where a material gives them. */
+  surfaceSpecular = vSpecular;
+  if (LAYERED && layered()) surfaceSpecular = layeredSpecular(vSpecular);
   if (dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
   /*
    * The layer's surface effects, zeros where the albedo array carries no table — see
@@ -102,6 +105,8 @@ export const MAIN_GLSL = `void main() {
         }
       }
     }
+    /* A layered material whose mask is the vertex colour takes no tint from it: layered.ts. */
+    if (LAYERED && layered()) albedo = layeredColor(albedo);
     albedo *= texel.rgb;
     coverage = kept;
   }
@@ -172,7 +177,8 @@ export const MAIN_GLSL = `void main() {
   /*
    * **A thin surface lets light from behind through, coloured by itself**: a banner, a leaf, a
    * lampshade, an opaque material's \`diffuseTransmission\`, in the glass tint's spare lane. It
-   * gathers the light behind it in glassGlow, as a pane does, and adds it through its own colour.
+   * gathers the light behind it in glassGlow, as a pane does, and adds it through its own colour,
+   * or through the \`transmissionColor\` it names in the tint's colour lanes (transmission.ts).
    * None on glass, which has its own way through.
    */
   float thin = glassTransmission > 0.0 ? 0.0 : uGlassTint.w;
@@ -508,6 +514,8 @@ export const MAIN_GLSL = `void main() {
 #endif
     /* A draw's own ambient, where one is set, in place of the frame's: \`setAmbientSH\`. */
     if (uAmbientSH[6].w > 0.5) ambient = ambientHarmonics(n);
+    /* Less of it where a layered material's mesh occlusion darkens the ambient light: layered.ts. */
+    if (LAYERED && layered()) ambient *= layeredAmbient();
     /*
      * A metal keeps its ambient and loses its direct diffuse.
      *
@@ -561,7 +569,7 @@ export const MAIN_GLSL = `void main() {
      * mix(x, y, 0) is exactly x, so at metal 0 this is vec3(vSpecular) and the line below is the
      * one it replaces with the scalar broadened to three components.
      */
-    vec3 specColor = mix(vec3(vSpecular), albedo, metal);
+    vec3 specColor = mix(vec3(surfaceSpecular), albedo, metal);
     /*
      * **A metal's highlight goes white at a grazing angle, and that is most of what reads as
      * polished.**
@@ -1654,7 +1662,7 @@ export const MAIN_GLSL = `void main() {
        * any lamp in the scene. The condition is the old one exactly when metal is 0, so nothing
        * that binds no map takes a different branch than it took before.
        */
-      if (vSpecular > 0.0 || metal > 0.0) {
+      if (surfaceSpecular > 0.0 || metal > 0.0) {
         vec3 toEyeLamp = normalize(uCameraPos - vWorldPos);
         vec3 lampHalfway = normalize(toLight / max(dist, 1e-4) + toEyeLamp);
         /* The same grazing whitening the sun's highlight takes, and zero at metal 0 for the look. */
@@ -1957,8 +1965,12 @@ export const MAIN_GLSL = `void main() {
      * underneath: a ceiling emitting a dull warm haze over a pale panel cannot be expressed
      * by scaling the panel, and scaling it gets the brightness right and the hue wrong.
      */
-    /* What a thin surface lets through from behind, through its own colour; a metal lets none. */
-    if (thin > 0.0) lit += albedo * glassGlow * (thin * (1.0 - metal));
+    /* What a thin surface lets through from behind, in its own colour or the one it names (below
+       zero: none named, transmission.ts); a metal lets none. */
+    if (thin > 0.0) {
+      vec3 through = uGlassTint.r < 0.0 ? albedo : uGlassTint.rgb;
+      lit += through * glassGlow * (thin * (1.0 - metal));
+    }
     diffuseAlone = lit;
     vec3 emissiveTint = vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor;
     /*