@driftengine/core 4.10.0 → 4.11.1

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

@@ -18,9 +18,14 @@ 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';
+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';
@@ -338,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;
@@ -508,6 +519,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.
    *
@@ -619,6 +645,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,
@@ -644,8 +672,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,
@@ -657,6 +683,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,198 @@
+/**
+ * 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 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 four 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() {}
+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); }
+`;
+  }
+  return /* glsl */ `
+/* Whether this program blends a material's layers. Off but where one has asked: layered.ts. */
+const bool LAYERED = true;  // wgsl:override
+/*
+ * 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
+
+/* 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;
+
+bool layered() {
+  return uLayers[1].y > 0.5;
+}
+
+float layerRepeat(int i) {
+  return i < 4 ? uLayers[0][i] : uLayers[1].x;
+}
+
+/* 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) {
+  return vec3(layerPlace() * layerRepeat(i), float(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, uLayers[1].y));
+  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() {
+  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 = uLayers[1].y + (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));
+  }
+  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 layerShare(int i) {
+  if (i == 0) return lShareBase;
+  return lShare[i - 1];
+}
+
+/* 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. */
+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;
+}
+
+/* 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;
+    sum += 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, uLayers[1].y));
+}
+
+/* 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 {
@@ -89,6 +102,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;
   }
@@ -115,7 +130,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 +171,15 @@ 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,
+   * 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;
+  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 +221,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 +392,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 +476,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
@@ -1302,8 +1328,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 +1348,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 +1726,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 +1900,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 +1960,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, 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;
     /*
@@ -1953,7 +1986,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;
@@ -2097,7 +2130,7 @@ 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);
@@ -2134,8 +2167,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;
     }
@@ -2147,9 +2180,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.**

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

@@ -0,0 +1,38 @@
+/**
+ * Where each of a material's maps is read: a layered material's blend (`layered.ts`), the three
+ * planes of a triplanar projection (`worldUv.ts`), or the map itself at the surface's coordinates.
+ *
+ * **Functions rather than branches in `main`, for the bundle's sake.** The generated WGSL stores an
+ * item once however many of the sixteen permutations share it, and `main` differs in every one, so
+ * a line there is paid sixteen times and a line here once. Called from the same uniform branches the
+ * reads stood in, so their implicit levels are as legal as they were: AGENTS.md 2026-08-07.
+ */
+export const MAP_READS_GLSL = /* glsl */ `
+/* The surface's coordinates moved onto the world's horizontal plane where a material projects them,
+   with the frame's coordinates and the mesh's tangents, which no longer run along them, set aside. */
+void projectSurface(inout vec3 at, inout vec2 frameAt, inout int frameTangents) {
+  if (WORLD_UVS && projected()) {
+    at.xy = planarAt();
+    frameAt = at.xy;
+    frameTangents = 0;
+  }
+}
+
+vec4 albedoTexel(vec3 at) {
+  if (LAYERED && layered()) return layeredAlbedo();
+  if (WORLD_UVS && triplanar()) return triplanarAlbedo(at.z);
+  return texture(uAlbedo, at);
+}
+
+vec3 ormTexel(vec3 at) {
+  if (LAYERED && layered()) return layeredOrm();
+  if (WORLD_UVS && triplanar()) return triplanarOrm(at.z);
+  return texture(uOrmMap, at).rgb;
+}
+
+vec3 emissiveTexel(vec3 at) {
+  if (LAYERED && layered() && layeredGlows()) return layeredEmissive();
+  if (WORLD_UVS && triplanar()) return triplanarEmissive(at.z);
+  return texture(uEmissiveMap, at).rgb;
+}
+`;

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

@@ -0,0 +1,46 @@
+/**
+ * The sun's moving layer read through a matrix of its own: the one the frame's dynamic shadow pass
+ * was drawn with, where that is not the static layer's.
+ *
+ * **Why a matrix of its own.** The static layer wants a square over the whole of what stands still,
+ * so distant roofs keep their shadows; what moves wants a tight one, so a character's shadow is
+ * sharp. One matrix for both is one of the two given up. A caller fits each as it likes and draws
+ * each pass with its own (`beginShadowPass(matrix, 'dynamic')`); the renderer keeps the dynamic
+ * pass's and the lit stage reads that layer through it, the receiver's position projected from the
+ * world here rather than carried in a second varying.
+ *
+ * **A lit switch, `MOVING_SUN`**, off until a frame's dynamic pass is drawn with a matrix the static
+ * layer does not share, then on for good. Declared beside the other lit switches, ahead of the
+ * shadow lookup that calls it; compiled out, the moving layer is read at the static layer's place,
+ * exactly as it always was, and its matrix and depth span are not declared at all.
+ *
+ * **What it gives up**: a receiver outside the static layer's square takes no sun shadow at all,
+ * moving casters included, since everything is faded by that square first; so the tight square
+ * belongs inside the wide one.
+ */
+export function movingSunGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool MOVING_SUN = false;  // wgsl:override
+vec3 movingSunAt() { return vec3(0.0); }
+float movingSunSpan() { return 1.0; }
+`;
+  }
+  return /* glsl */ `
+/* Whether the moving layer has a matrix of its own. Off until a frame draws it with one: movingSun.ts. */
+const bool MOVING_SUN = true;  // wgsl:override
+/* The dynamic shadow pass's world-to-light matrix, and the depth it spans in metres. */
+uniform mat4 uMovingLightViewProj;
+uniform float uMovingShadowDepthSpan;
+
+/* The receiver in the moving layer's map: x and y across it, z its depth, all 0 to 1. */
+vec3 movingSunAt() {
+  vec4 l = uMovingLightViewProj * vec4(vWorldPos, 1.0);
+  return l.xyz / l.w * 0.5 + 0.5;
+}
+
+float movingSunSpan() {
+  return uMovingShadowDepthSpan;
+}
+`;
+}

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

@@ -3,12 +3,32 @@
  * lit block for every light and by an unlit refracting draw for the direction it bends, so a lit
  * pane and an unlit distortion bend by one tilt rather than two transcriptions of it.
  *
- * Depth zero, after the tangent frame it calls; see `flatFrag`. **Only ever called under a branch
+ * The frame is built from `frameAt`, the coordinates the map was laid by — the mesh's, or the
+ * world's where a material projects them (`worldUv.ts`), with the mesh's tangents then set aside
+ * by `hasTangents`, since they run along coordinates the map no longer follows.
+ *
+ * Depth zero, after the tangent frame and the world's projection it calls; see `flatFrag`. **Only ever called under a branch
  * on a uniform** — `uNormalStrength` and whatever gates its caller — which is what makes the
  * derivatives inside `tangentFrame` and the implicit level of the read legal: AGENTS.md 2026-08-07.
  */
 export const NORMAL_MAP_GLSL = /* glsl */ `
-vec3 normalMapped(vec3 n, vec3 at) {
+vec3 normalMapped(vec3 n, vec3 at, vec2 frameAt, int hasTangents) {
+  /* On three planes where the material projects them so: worldUv.ts. */
+  if (WORLD_UVS && triplanar()) return triplanarNormal(n, at.z);
+  /*
+   * A layered material's texels, blended by its mask before the frame turns them, around a normal
+   * read at the mesh's own coordinates and tangents where the material lays one under them, which is
+   * the surface's large shape the layers' detail rides on: layered.ts.
+   */
+  if (LAYERED && layered()) {
+    vec3 under = n;
+    if (layeredMeshNormal()) {
+      mat3 meshFrame = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);
+      under = normalize(meshFrame * layeredMeshTexel());
+    }
+    mat3 layeredFrame = tangentFrame(under, vWorldPos, frameAt, vTangent, hasTangents);
+    return normalize(mix(n, normalize(layeredFrame * layeredTexel()), uNormalStrength));
+  }
   vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;
   /*
    * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a
@@ -19,7 +39,7 @@ vec3 normalMapped(vec3 n, vec3 at) {
    * lying flat has its z near zero either way. A texel with z above zero is left as it was.
    */
   mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));
-  mat3 tbn = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);
+  mat3 tbn = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);
   return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));
 }
 `;