@driftengine/core 4.9.0 → 4.11.0

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

@@ -36,13 +36,56 @@ export const DIRECTIONALSHADOW_GLSL = `vec2 receiverPlaneDepthGradient(vec3 p) {
   );
 }
 
-float directionalVisibility(float receiverDepth, float compareDepth, float storedDepth) {
+/* One stored depth against a receiver, in a map spanning \`span\` metres of depth. */
+float directionalVisibilityAt(float receiverDepth, float compareDepth, float storedDepth, float span) {
   if (compareDepth <= storedDepth) return 1.0;
-  float rayDistance = max(receiverDepth - storedDepth, 0.0) * uShadowDepthSpan;
+  float rayDistance = max(receiverDepth - storedDepth, 0.0) * span;
   float groundDistance = rayDistance * length(uDirectionalDir.xz);
   return 1.0 - shadowReach(groundDistance, uShadowMaxDistance);
 }
 
+float directionalVisibility(float receiverDepth, float compareDepth, float storedDepth) {
+  return directionalVisibilityAt(receiverDepth, compareDepth, storedDepth, uShadowDepthSpan);
+}
+
+/* How far inside its square a receiver stands in a layer's map: 1 well inside, 0 at its border. */
+float sunMapFade(vec3 p) {
+  if (p.z > 1.0 || p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0) return 0.0;
+  vec2 fromCentre = abs(p.xy - 0.5) * 2.0;
+  return (1.0 - smoothstep(0.72, 0.98, max(fromCentre.x, fromCentre.y))) *
+    (1.0 - smoothstep(0.90, 1.0, p.z));
+}
+
+/*
+ * The moving layer at its own place, where it has a matrix of its own (movingSun.ts): the coarse
+ * test of shadowFactor, and its filter, each against the moving map's own depth span, and lit by
+ * how far inside the moving map's square the receiver stands rather than cut at its border.
+ */
+float movingSunCoarse(vec3 pm, float span) {
+  float inside = sunMapFade(pm);
+  if (inside <= 0.0) return 1.0;
+  float stored = textureLod(uSunShadows, vec3(pm.xy, ${SUN_DYNAMIC_LAYER}.0), 0.0).r;
+  return mix(1.0, directionalVisibilityAt(pm.z, pm.z - 1.0 / span, stored, span), inside);
+}
+
+float movingSunFiltered(vec3 pm, vec2 gradient, float span) {
+  float inside = sunMapFade(pm);
+  if (inside <= 0.0) return 1.0;
+  float texel = 1.35 / uShadowMapSize;
+  float slopeLimit = 9.1 / uShadowMapSize;
+  float lit = 0.0;
+  for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
+    if (i >= uShadowFilterTaps) break;
+    vec2 sampleUv = pm.xy + DIRECTIONAL_PCF_OFFSETS[i] * texel;
+    vec2 texelCentre = (floor(sampleUv * uShadowMapSize) + 0.5) / uShadowMapSize;
+    float slopeOffset = clamp(dot(gradient, texelCentre - pm.xy), -slopeLimit, slopeLimit);
+    float tapReceiverDepth = pm.z + slopeOffset;
+    float stored = textureLod(uSunShadows, vec3(sampleUv, ${SUN_DYNAMIC_LAYER}.0), 0.0).r;
+    lit += directionalVisibilityAt(tapReceiverDepth, tapReceiverDepth - 0.14 / span, stored, span);
+  }
+  return mix(1.0, lit / float(max(uShadowFilterTaps, 1)), inside);
+}
+
 float shadowFactor(float directionalNdl) {
   if (uShadowStrength <= 0.0) return 1.0;
 
@@ -72,6 +115,14 @@ float shadowFactor(float directionalNdl) {
   vec3 p = vLightPos.xyz / vLightPos.w;
   p = p * 0.5 + 0.5;
   vec2 depthGradient = receiverPlaneDepthGradient(p);
+  /* The moving layer's own place and plane where it has a matrix of its own (movingSun.ts), taken
+     here beside the static layer's for the same reason: above every varying-dependent return. */
+  vec3 pm = p;
+  vec2 movingGradient = depthGradient;
+  if (MOVING_SUN) {
+    pm = movingSunAt();
+    movingGradient = receiverPlaneDepthGradient(pm);
+  }
 
   // Near a surface's own light terminator its direct-light term is already
   // approaching zero, while the orthographic projection of that surface
@@ -136,7 +187,8 @@ float shadowFactor(float directionalNdl) {
   float coarseCompare = p.z - 1.0 / uShadowDepthSpan;
   float coarse =
     directionalVisibility(p.z, coarseCompare, textureLod(uSunShadows, vec3(p.xy, ${SUN_STATIC_LAYER}.0), 0.0).r) *
-    directionalVisibility(p.z, coarseCompare, textureLod(uSunShadows, vec3(p.xy, ${SUN_DYNAMIC_LAYER}.0), 0.0).r);
+    (MOVING_SUN ? movingSunCoarse(pm, movingSunSpan()) :
+      directionalVisibility(p.z, coarseCompare, textureLod(uSunShadows, vec3(p.xy, ${SUN_DYNAMIC_LAYER}.0), 0.0).r));
   if (uPeeledShadowEnabled != 0) {
     coarse *= directionalVisibility(p.z, coarseCompare, textureLod(uSunShadows, vec3(p.xy, ${SUN_PEELED_LAYER}.0), 0.0).r);
   }
@@ -200,7 +252,6 @@ float shadowFactor(float directionalNdl) {
      * there is no mip to select and level zero is the only thing \`texture\` could have read.
      */
     float staticDepth = textureLod(uSunShadows, vec3(sampleUv, ${SUN_STATIC_LAYER}.0), 0.0).r;
-    float dynamicDepth = textureLod(uSunShadows, vec3(sampleUv, ${SUN_DYNAMIC_LAYER}.0), 0.0).r;
     staticLit += directionalVisibility(tapReceiverDepth, compare, staticDepth);
     if (uPeeledShadowEnabled != 0) {
       float peeledDepth = textureLod(uSunShadows, vec3(sampleUv, ${SUN_PEELED_LAYER}.0), 0.0).r;
@@ -208,12 +259,18 @@ float shadowFactor(float directionalNdl) {
     } else {
       peeledLit += 1.0;
     }
-    dynamicLit += directionalVisibility(tapReceiverDepth, compare, dynamicDepth);
+    /* The moving layer here where it shares the static one's place; at its own below otherwise.
+       Branched on the switch itself, never its negation: see overridableConstants in transform.mjs. */
+    if (MOVING_SUN) {
+    } else {
+      float dynamicDepth = textureLod(uSunShadows, vec3(sampleUv, ${SUN_DYNAMIC_LAYER}.0), 0.0).r;
+      dynamicLit += directionalVisibility(tapReceiverDepth, compare, dynamicDepth);
+    }
   }
   float tapCount = float(max(uShadowFilterTaps, 1));
   staticLit /= tapCount;
   peeledLit /= tapCount;
-  dynamicLit /= tapCount;
+  dynamicLit = MOVING_SUN ? movingSunFiltered(pm, movingGradient, movingSunSpan()) : dynamicLit / tapCount;
 
   // Independent layers preserve every recorded fact at an overlap: each
   // caster keeps its own distance fade, and their transmissions compose
@@ -234,11 +291,11 @@ float shadowFactor(float directionalNdl) {
  * behind the receiver lending it colour within the spread, which only a receiver between two panes
  * meets. One function for both layers, because two copies were most of the lit shaders' growth.
  */
-vec3 sunGlassLayer(vec3 p, float paneLayer, float tintLayer, float bias, float texel, float uvPerMetre) {
+vec3 sunGlassLayer(vec3 p, float paneLayer, float tintLayer, float bias, float texel, float uvPerMetre, float span) {
   float tintSize = float(textureSize(uSunGlassTints, 0).x);
   float clarity = textureLod(uSunGlassTints, vec3(p.xy, tintLayer), 0.0).a;
   float behind =
-    max(p.z - textureLod(uSunShadows, vec3(p.xy, paneLayer), 0.0).r, 0.0) * uShadowDepthSpan;
+    max(p.z - textureLod(uSunShadows, vec3(p.xy, paneLayer), 0.0).r, 0.0) * span;
   float radius = clamp(
     (1.0 - clarity) * ${FROST_SPREAD.toFixed(6)} * behind * uvPerMetre,
     texel,
@@ -278,6 +335,13 @@ vec3 sunGlassLookup(float directionalNdl) {
   /* Map units per metre along the receiver, from derivatives taken first in uniform control flow,
      so a frost spread stated in metres lands the same whatever size of light matrix a consumer built. */
   float uvPerMetre = length(dFdx(p.xy)) / max(length(dFdx(vWorldPos)), 1e-6);
+  /* The moving glass at its own place where its layer has a matrix of its own: movingSun.ts. */
+  vec3 pm = p;
+  float movingPerMetre = uvPerMetre;
+  if (MOVING_SUN) {
+    pm = movingSunAt();
+    movingPerMetre = length(dFdx(pm.xy)) / max(length(dFdx(vWorldPos)), 1e-6);
+  }
   if (uShadowStrength <= 0.0 || textureSize(uSunGlassTints, 0).x <= 1) return vec3(1.0);
   if (directionalNdl <= 0.0) return vec3(1.0);
   if (p.z > 1.0 || p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0) return vec3(1.0);
@@ -295,8 +359,18 @@ vec3 sunGlassLookup(float directionalNdl) {
 
   float bias = 0.14 / uShadowDepthSpan;
   float texel = 1.35 / uShadowMapSize;
-  vec3 staticTint = sunGlassLayer(p, ${SUN_GLASS_STATIC_LAYER}.0, 0.0, bias, texel, uvPerMetre);
-  vec3 movingTint = sunGlassLayer(p, ${SUN_GLASS_MOVING_LAYER}.0, 1.0, bias, texel, uvPerMetre);
+  vec3 staticTint = sunGlassLayer(p, ${SUN_GLASS_STATIC_LAYER}.0, 0.0, bias, texel, uvPerMetre, uShadowDepthSpan);
+  vec3 movingTint = MOVING_SUN && sunMapFade(pm) <= 0.0
+    ? vec3(1.0)
+    : sunGlassLayer(
+      pm,
+      ${SUN_GLASS_MOVING_LAYER}.0,
+      1.0,
+      MOVING_SUN ? 0.14 / movingSunSpan() : bias,
+      texel,
+      movingPerMetre,
+      MOVING_SUN ? movingSunSpan() : uShadowDepthSpan
+    );
   return mix(vec3(1.0), staticTint * movingTint, strength);
 }
 

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

@@ -36,7 +36,10 @@ export type LitSwitch =
   | 'DRIFT_LIGHT'
   | 'PHYSICAL_SPECULAR'
   | 'SURFACE_OVERLAY'
-  | 'REFLECTION_MAPS';
+  | 'REFLECTION_MAPS'
+  | 'WORLD_UVS'
+  | 'MOVING_SUN'
+  | 'LAYERED';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -49,6 +52,9 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     PHYSICAL_SPECULAR: false,
     SURFACE_OVERLAY: false,
     REFLECTION_MAPS: false,
+    WORLD_UVS: false,
+    MOVING_SUN: false,
+    LAYERED: false,
   };
 }
 

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

@@ -21,7 +21,12 @@ import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
 import { overlayGlsl } from './overlay.ts';
 import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
-import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
+import { worldUvGlsl } from './worldUv.ts';
+import { movingSunGlsl } from './movingSun.ts';
+import { layeredGlsl } from './layered.ts';
+import { MAP_READS_GLSL } from './mapReads.ts';
+import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
+import { BONE_ANIMATION_GLSL } from '../boneAnimation.ts';
 import { FULL_LIGHT_BUDGET, type LightBudget } from '../../uniformVectorBudget.ts';
 
 /**
@@ -56,10 +61,16 @@ layout(location = 10) in vec4 aTangent;
 ${SKINNING_GLSL}
 #endif
 
-uniform mat4 uViewProj;
+uniform mat4 uViewProj; // wgsl:view
 /** 1 when the mesh carries a tangent frame. See vHasTangents. */
 uniform int uHasTangents;
-uniform mat4 uLightViewProj;
+uniform mat4 uLightViewProj; // wgsl:view
+/**
+ * The scene's clock, what \`setAnimationTime\` set: what a bone animation's instances read
+ * their moment from. In the view block, before the wind, so every variant's view block is the
+ * plain one's or a prefix of it — the instanced variant declares no wind and keeps this.
+ */
+uniform float uSceneTime; // wgsl:view
 /**
  * How often the surface texture repeats across this mesh's UV range, per axis.
  *
@@ -122,6 +133,9 @@ layout(location = 15) in vec4 aInstanceTint;
  * opacity of one. See lightmap.ts.
  */
 const bool LIGHTMAP_REGIONS = false; // wgsl:override
+#if ANIMATED
+${BONE_ANIMATION_GLSL}
+#endif
 #else
 uniform mat4 uModel;
 /**
@@ -147,7 +161,7 @@ uniform vec3 uTint;
  * agreeing about where the shared uniforms sit: the instanced variant drops these five along with
  * the two above it, and a dropped field moves nothing. flatPass.ts asserts exactly that.
  */
-${CHANNEL_ATTRIBUTE}
+${LIT_CHANNEL_ATTRIBUTE}
 ${CHANNEL_BEND}
 #endif
 
@@ -245,6 +259,10 @@ void main() {
   vec3 localNormal = aNormal;
   vec3 localTangent = aTangent.xyz;
 #endif
+#if ANIMATED
+  /* The clip's turn and place, in the mesh's own space, before the instance places it. */
+  local = vec4(boneAnimate(local.xyz, localNormal, localTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /*
@@ -379,6 +397,12 @@ export interface FlatVertexOptions {
    * Excludes `skinned`: the joint attributes and the instance matrix want the same locations.
    */
   readonly instanced: boolean;
+  /**
+   * Whether an instanced variant follows a bone animation: \`shaders/boneAnimation.ts\`. A
+   * variant rather than a pipeline constant, because it declares three textures the other
+   * instanced pipelines would otherwise have to bind stand-ins for. Instanced only.
+   */
+  readonly animated?: boolean;
 }
 
 /**
@@ -401,9 +425,17 @@ export function flatVert(options: FlatVertexOptions): string {
         'so every instance of the batch would wear one expression between them.',
     );
   }
+  if (options.animated === true && !options.instanced) {
+    throw new Error('flatVert: a bone animation is played by an instanced variant alone.');
+  }
   return resolveConditionals(
     FLAT_VERT_SOURCE,
-    { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced },
+    {
+      SKINNED: options.skinned,
+      MORPHED: options.morphed,
+      INSTANCED: options.instanced,
+      ANIMATED: options.animated === true,
+    },
     'flatVert',
   );
 }
@@ -480,6 +512,21 @@ export interface FlatShaderOptions {
    * the frame's materials' reflections. True when absent. See `reflectionSurfaceGlsl`.
    */
   readonly reflectionMaps?: boolean;
+  /**
+   * Whether it places a material's maps by the world, `uWorldUv` and all (`SurfaceMaterial
+   * .projection`). True when absent. See `worldUvGlsl`.
+   */
+  readonly worldUvs?: boolean;
+  /**
+   * Whether it reads the sun's moving layer through a matrix of its own, \`uMovingLightViewProj\`
+   * and all. True when absent. See \`movingSunGlsl\`.
+   */
+  readonly movingSun?: boolean;
+  /**
+   * Whether it blends a material's layers by a mask, \`uLayers\` and all (\`SurfaceMaterial.layers\`).
+   * True when absent. See \`layeredGlsl\`.
+   */
+  readonly layered?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -591,6 +638,8 @@ export function flatFrag(options: FlatShaderOptions): string {
         surfaceEffects: options.surfaceEffects ?? true,
         driftLight: options.driftLight ?? true,
       }),
+      /* Depth zero and ahead of the sun's lookup, which calls it; its switch takes the next id. */
+      movingSunGlsl(options.movingSun ?? true),
       LOBES_GLSL,
       POINTSHADOW_GLSL,
       DIRECTIONALSHADOW_GLSL,
@@ -616,8 +665,6 @@ export function flatFrag(options: FlatShaderOptions): string {
        * and `main` is unconditional by construction.
        */
       TANGENT_FRAME_GLSL,
-      /* After the frame it calls, unconditional for the same reason. See normalMap.ts. */
-      NORMAL_MAP_GLSL,
       /* Unconditional for the same reason, and called only where a cutoff was asked for. */
       CUTOUT_COVERAGE_GLSL,
       CUTOUT_DITHER_GLSL,
@@ -629,6 +676,15 @@ export function flatFrag(options: FlatShaderOptions): string {
       overlayGlsl(options.surfaceOverlay ?? true),
       /* After the overlay, so its switch takes the next id. See reflectionSurface.ts. */
       reflectionSurfaceGlsl(options.reflectionMaps ?? true),
+      /* 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),
+      /* 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
+         frame. See normalMap.ts. */
+      NORMAL_MAP_GLSL,
       /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
       AREA_LIGHT_GLSL,
       MAIN_GLSL,

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

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ *
+ * **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.
+ */
+export function layeredGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool LAYERED = false;  // wgsl:override
+bool layered() { return false; }
+void layeredBegin() {}
+vec4 layeredAlbedo() { return vec4(1.0); }
+vec3 layeredOrm() { return vec3(1.0); }
+vec3 layeredTexel() { return vec3(0.0, 0.0, 1.0); }
+bool layeredGlows() { return false; }
+vec3 layeredEmissive() { return vec3(0.0); }
+`;
+  }
+  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;
+
+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);
+}
+
+/* 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];
+  }
+  return keep;
+}
+
+float layerRepeat(int i) {
+  return i < 4 ? uLayers[0][i] : uLayers[1].x;
+}
+
+vec3 layerAt(int i) {
+  return vec3(vUv.xy * layerRepeat(i), float(i));
+}
+
+/* Colour by the shares, and the base layer's coverage, which a cutout reads. */
+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);
+    if (i == 0) sum.a = t.a;
+  }
+  return sum;
+}
+
+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);
+  }
+  return sum;
+}
+
+/* The tangent-space texels blended, each with its z rebuilt where a two-channel map stored none. */
+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);
+  }
+  float len = length(sum);
+  return len > 1e-5 ? sum / len : vec3(0.0, 0.0, 1.0);
+}
+
+/* Whether the emissive map belongs to one layer rather than to the whole surface. */
+bool layeredGlows() {
+  return uLayers[1].z > -0.5;
+}
+
+/* The emissive map at its layer's place, glowing by that layer's share. */
+vec3 layeredEmissive() {
+  int glow = int(uLayers[1].z + 0.5);
+  return texture(uEmissiveMap, layerAt(glow)).rgb * layerShare(glow);
+}
+`;
+}

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

@@ -7,6 +7,17 @@ export const MAIN_GLSL = `void main() {
    * turns a float into an array index. A plain texture is an array of one, so layer 0.
    */
   vec3 surfaceAt = vec3(vUv.xy, floor(vUv.z + 0.5));
+  /*
+   * The coordinates a map's frame and its cutout's level are measured along: the mesh's, or the
+   * world's where the material projects its maps (worldUv.ts) — in which case the mesh's tangents
+   * no longer run along them either. Triplanar reads its own three planes below; every other
+   * reader of surfaceAt takes the horizontal plane.
+   */
+  vec2 frameAt = vUv.xy;
+  int frameTangents = vHasTangents;
+  projectSurface(surfaceAt, frameAt, frameTangents);
+  /* A layered material's mask, read once for every layer's share below: layered.ts. */
+  if (LAYERED && layered()) layeredBegin();
   if (dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
   /*
    * The layer's surface effects, zeros where the albedo array carries no table — see
@@ -26,6 +37,8 @@ export const MAIN_GLSL = `void main() {
   vec2 fxDx = dFdx(surfaceAt.xy);
   vec2 fxDy = dFdy(surfaceAt.xy);
   if (uWriteMode.y != 0.0 && !ditherKeeps(uWriteMode.y)) discard;
+  /* An opacity spent on the screen door instead of the blend: preamble.ts. 0 keeps nothing. */
+  if (uWriteMode.z != 0.0 && ditherThreshold() >= vAlpha) discard;
   /* A draw's dissolve cuts the surface away before anything is shaded: overlay.ts. */
   if (SURFACE_OVERLAY) {
     if (overlayCuts(surfaceAt.xy)) discard;
@@ -63,14 +76,14 @@ export const MAIN_GLSL = `void main() {
    */
   float coverage = 1.0;
   if (uMaterialFlags.x != 0) {
-    vec4 texel = texture(uAlbedo, surfaceAt);
+    vec4 texel = albedoTexel(surfaceAt);
     // Discarded before anything else is computed: a thrown-away fragment should not pay
     // for the lighting it will never contribute to. The test credits alpha for the mip level
     // it samples, so a needle averaged thin down the chain is not lost; see cutoutCoverage.ts.
     // Behind a branch on a uniform, so a material with no cutoff pays nothing for it.
     float kept = texel.a;
     if (uCutout.x > 0.0) {
-      float tested = cutoutAlpha(texel.a, vUv.xy * vec2(textureSize(uAlbedo, 0).xy));
+      float tested = cutoutAlpha(texel.a, frameAt * vec2(textureSize(uAlbedo, 0).xy));
       if (uCutout.y == 0.0) {
         if (tested < uCutout.x) discard;
       } else {
@@ -82,7 +95,7 @@ export const MAIN_GLSL = `void main() {
          */
         float share = cutoutShare(tested, uCutout.x);
         if (uCutout.y == 1.0) {
-          if (!cutoutKeeps(share, gl_FragCoord.xy, uCutout.z)) discard;
+          if (!cutoutKeeps(share, gl_FragCoord.xy, uHighlightMin.w)) discard;
           kept = 1.0;
         } else {
           kept = share;
@@ -115,7 +128,7 @@ export const MAIN_GLSL = `void main() {
   float ormRoughness = vRoughness;
   float metal = 0.0;
   if (uMaterialFlags.y != 0) {
-    vec3 t = texture(uOrmMap, surfaceAt).rgb;
+    vec3 t = ormTexel(surfaceAt);
     ormOcclusion = mix(1.0, t.r, uOrmScale.r);
     ormRoughness = clamp(t.g * uOrmScale.g, 0.0, 1.0);
     metal = clamp(t.b * uOrmScale.b, 0.0, 1.0);
@@ -156,6 +169,14 @@ export const MAIN_GLSL = `void main() {
   vec3 glassGlow = vec3(0.0);
   float glassTransmission = uSeeThrough.z;
   float glassFrost = uSeeThrough.w;
+  /*
+   * **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.
+   * None on glass, which has its own way through.
+   */
+  float thin = glassTransmission > 0.0 ? 0.0 : uGlassTint.w;
+  bool seesBehind = glassTransmission > 0.0 || thin > 0.0;
 
   /*
    * The normal a refracting draw bends by: the shading normal, a normal map's tilt and every relief
@@ -197,7 +218,7 @@ export const MAIN_GLSL = `void main() {
      * below. The rule is about non-uniform branches, and this branch is on a uniform.
      */
     vec3 unmapped = n;
-    if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt);
+    if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt, frameAt, frameTangents);
     /* A draw's wrinkles, by region, over whatever the map made: overlay.ts. */
     if (SURFACE_OVERLAY) n = overlayWrinkle(n, unmapped, surfaceAt.xy);
 
@@ -368,6 +389,8 @@ export const MAIN_GLSL = `void main() {
      */
     shadingNormal = n;
     if (backFace) n = -n;
+    /* A blending rim, on the base colour every light below reads: overlay.ts. */
+    if (SURFACE_OVERLAY) albedo = overlayRimBase(albedo, surfaceAt.xy, n);
     /*
      * A model's surface, gathered once, on a branch on the switches alone (models.ts) — and whether
      * there is one, asked once: every site below is a branch on these two, which a pipeline with no
@@ -450,7 +473,7 @@ export const MAIN_GLSL = `void main() {
     float sunFacing = smoothstep(0.0, 0.02, surfaceNdl);
     float direct = ndl * sunShade * sunFacing;
     /* Glass: the sun on the far side of a pane lights it through the glass. See glassGlow. */
-    if (glassTransmission > 0.0) glassGlow += sunColor * max(-surfaceNdl, 0.0) * sunShade;
+    if (seesBehind) glassGlow += sunColor * max(-surfaceNdl, 0.0) * sunShade;
 
     /*
      * Hemispheric: sky above, ground below, mixed by which way the surface looks. An
@@ -1281,7 +1304,7 @@ export const MAIN_GLSL = `void main() {
        */
       float falloff;
       /*
-       * **A light may name its own falloff, and then it is Unreal's for a light without
+       * **A light may name its own falloff, and then it is the usual one for a light without
        * inverse-square falloff**: \`(1 - (d/R)^2)^n\` with no distance term, so a fill authored to
        * light a whole hall across a hundred metres does, where the inverse square would have it
        * gone a few metres out. Zero is the frame's own rule below, which every light was before.
@@ -1302,8 +1325,7 @@ export const MAIN_GLSL = `void main() {
        * the glass, shaped and shadowed like any lamp, and is added to glassGlow once its shape is
        * known below. For everything else a lamp behind the surface is skipped here, as always.
        */
-      float backNdl =
-        glassTransmission > 0.0 ? max(-dot(n, toLight / max(dist, 1e-4)), 0.0) : 0.0;
+      float backNdl = seesBehind ? max(-dot(n, toLight / max(dist, 1e-4)), 0.0) : 0.0;
       /* A model that sees light from behind keeps the lamps behind the surface. See models.ts. */
       if (ndl <= 0.0 && backNdl <= 0.0 && !modelledBehind) continue;
 
@@ -1323,7 +1345,9 @@ export const MAIN_GLSL = `void main() {
 #if POINT_SHADOWS
       float grazing = 1.0 - ndl;
       float normalOffset = (0.06 + dist * 0.05) * grazing * grazing + 0.02;
-      vec3 receiverPoint = vWorldPos + n * normalOffset;
+      /* Toward a lamp behind a thin surface, which is in the map itself: away from it, the surface
+         would stand in its own shadow. A pane is in no map, so glass keeps the usual side. */
+      vec3 receiverPoint = vWorldPos + (thin > 0.0 && ndl <= 0.0 ? -n : n) * normalOffset;
 
       /*
        * uPointShadowWeight is how present the cubemap is, and it is the difference
@@ -1699,7 +1723,7 @@ export const MAIN_GLSL = `void main() {
       float signedForm = areaSignedForm(n, seenCentre, right, up, seenHalf);
       float form = mix(max(0.0, signedForm), abs(signedForm), uAreaLightTwoSided[a]);
       /* The form factor is linear in the normal, so the one seen from behind is its negation. */
-      float backForm = glassTransmission > 0.0
+      float backForm = seesBehind
         ? mix(max(0.0, -signedForm), abs(signedForm), uAreaLightTwoSided[a])
         : 0.0;
       if (form <= 0.0 && backForm <= 0.0) continue;
@@ -1873,7 +1897,7 @@ export const MAIN_GLSL = `void main() {
      * \`driftLight.ts\`.
      */
     if (driftShare > 0.0) {
-      if (glassTransmission > 0.0) {
+      if (seesBehind) {
         glassGlow += driftLightIrradiance(vWorldPos, -n) * (driftShare * uDriftLight.w);
       }
       /* The standard expression in its own order — albedo times the field, then the share — so a
@@ -1933,6 +1957,8 @@ 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));
     diffuseAlone = lit;
     vec3 emissiveTint = vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor;
     /*
@@ -1953,7 +1979,7 @@ export const MAIN_GLSL = `void main() {
      */
     vec3 emissiveMapped = vec3(1.0);
     if (uMaterialFlags.z != 0) {
-      emissiveMapped = texture(uEmissiveMap, surfaceAt).rgb * uEmissiveScale;
+      emissiveMapped = emissiveTexel(surfaceAt) * uEmissiveScale;
     }
     /* Pulse, flicker and fade from the layer's effects; exactly 1 where it names none. */
     float fxGlow = fx4.z + fx5.x + fx5.w > 0.0 ? fxEmission(surfaceAt.z) : 1.0;
@@ -1997,7 +2023,7 @@ export const MAIN_GLSL = `void main() {
     // finishing a run reads the same at noon and at midnight. Costs one compare
     // per fragment and no extra draw call — the box is a uniform, not geometry.
     if (uHighlightMax.w > 0.0) {
-      vec3 inside = step(uHighlightMin, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
+      vec3 inside = step(uHighlightMin.xyz, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
       lit += albedo * uHighlightMax.w * inside.x * inside.y * inside.z;
     }
   }
@@ -2097,11 +2123,21 @@ export const MAIN_GLSL = `void main() {
      * map here, on a branch on uniforms alone, which keeps its derivatives legal.
      */
     vec3 refractN = shadingNormal;
-    if (uLightingEnabled == 0 && uNormalStrength > 0.0) refractN = normalMapped(refractN, surfaceAt);
+    if (uLightingEnabled == 0 && uNormalStrength > 0.0) refractN = normalMapped(refractN, surfaceAt, frameAt, frameTangents);
     vec3 refractV = normalize(uCameraPos - vWorldPos);
     ivec2 snapSize = textureSize(uRefractScene, 0);
     vec2 screenUv = gl_FragCoord.xy / vec2(snapSize);
-    vec2 bent = clamp(screenUv + refractN.xy * uSeeThrough.x, vec2(0.0), vec2(1.0));
+    /*
+     * **The normal's sideways part as the eye sees it**: the shading normal in view space, its x
+     * and y across the screen, y turned to the way this frame's rows run (w of the tint). It was the
+     * normal's world x and y until 4.10.0, which on a quad facing the camera is the quad's own lean
+     * against the world's axes: one offset over the whole quad, a lens, with a normal map's tilt a
+     * small change on top. In view space a quad facing the eye bends by nothing but its map, which
+     * is a shimmer, and a pane bends by how it leans toward the eye wherever the eye stands.
+     */
+    vec3 seenN = mat3(uView) * refractN;
+    vec2 bend = vec2(seenN.x, seenN.y * uRefractTint.w);
+    vec2 bent = clamp(screenUv + bend * uSeeThrough.x, vec2(0.0), vec2(1.0));
     /*
      * **An explicit level, and frost is what picks it** — the 2026-08-07 rule, and the reason a
      * frosted pane blurs rather than fades: the copy carries a mip chain on a frame that draws glass,
@@ -2115,7 +2151,7 @@ export const MAIN_GLSL = `void main() {
     /* Unsigned: a pane passes the same light seen from either side, and so does its Fresnel. */
     float cosView = max(abs(dot(refractN, refractV)), 0.05);
     float pathLength = uSeeThrough.y * vThickness / cosView;
-    vec3 seen = behind * pow(uRefractTint, vec3(pathLength));
+    vec3 seen = behind * pow(uRefractTint.rgb, vec3(pathLength));
     if (glassTransmission > 0.0) {
       /*
        * **Glass keeps its own surface and shows what is behind over it**, by how much it lets
@@ -2124,8 +2160,8 @@ export const MAIN_GLSL = `void main() {
        * The glow of the lights behind it is added last, by how frosted it is.
        */
       float fresnel = 0.04 + 0.96 * pow(1.0 - cosView, 5.0);
-      shaded = mix(shaded, seen * uGlassTint, glassTransmission * (1.0 - fresnel)) +
-        applyOutputTransform(glassGlow * uGlassTint * (glassFrost * glassTransmission) * (1.0 - fog));
+      shaded = mix(shaded, seen * uGlassTint.rgb, glassTransmission * (1.0 - fresnel)) +
+        applyOutputTransform(glassGlow * uGlassTint.rgb * (glassFrost * glassTransmission) * (1.0 - fog));
     } else {
       shaded = seen;
     }
@@ -2137,9 +2173,10 @@ export const MAIN_GLSL = `void main() {
    * **It did not need MeshData.colors widened to four floats**, which is how the consumer who
    * asked for it had costed the change -- widening colors moves every mesh producer, the
    * container layout and every baked asset. Alpha is a factor on the draw's opacity, not a
-   * component of its albedo, so it rides a lane instead and nothing existing moves.
+   * component of its albedo, so it rides a lane instead and nothing existing moves. Where the draw
+   * spends it on the screen door instead (\`uWriteMode.z\`), it was spent at the top and is 1 here.
    */
-  float alpha = uOpacity * coverage * vAlpha;
+  float alpha = uOpacity * coverage * (uWriteMode.z != 0.0 ? 1.0 : vAlpha);
 
   /*
    * **Order-independent transparency, when this draw is accumulating into it.**