@driftengine/core 4.10.0 → 4.11.1

package/dist/render/shaders/flat/main.js

@@ -6,6 +6,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
@@ -25,6 +36,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;
@@ -62,14 +75,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 {
@@ -88,6 +101,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;
   }
@@ -114,7 +129,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);
@@ -155,6 +170,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
@@ -196,7 +220,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);
 
@@ -367,6 +391,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
@@ -449,7 +475,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
@@ -1301,8 +1327,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;
 
@@ -1322,7 +1347,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
@@ -1698,7 +1725,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;
@@ -1872,7 +1899,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
@@ -1932,6 +1959,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;
     /*
@@ -1952,7 +1985,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;
@@ -2096,7 +2129,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);
@@ -2133,8 +2166,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;
     }
@@ -2146,9 +2179,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/dist/render/shaders/flat/mapReads.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const MAP_READS_GLSL = "\n/* The surface's coordinates moved onto the world's horizontal plane where a material projects them,\n   with the frame's coordinates and the mesh's tangents, which no longer run along them, set aside. */\nvoid projectSurface(inout vec3 at, inout vec2 frameAt, inout int frameTangents) {\n  if (WORLD_UVS && projected()) {\n    at.xy = planarAt();\n    frameAt = at.xy;\n    frameTangents = 0;\n  }\n}\n\nvec4 albedoTexel(vec3 at) {\n  if (LAYERED && layered()) return layeredAlbedo();\n  if (WORLD_UVS && triplanar()) return triplanarAlbedo(at.z);\n  return texture(uAlbedo, at);\n}\n\nvec3 ormTexel(vec3 at) {\n  if (LAYERED && layered()) return layeredOrm();\n  if (WORLD_UVS && triplanar()) return triplanarOrm(at.z);\n  return texture(uOrmMap, at).rgb;\n}\n\nvec3 emissiveTexel(vec3 at) {\n  if (LAYERED && layered() && layeredGlows()) return layeredEmissive();\n  if (WORLD_UVS && triplanar()) return triplanarEmissive(at.z);\n  return texture(uEmissiveMap, at).rgb;\n}\n";

package/dist/render/shaders/flat/mapReads.js

@@ -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/dist/render/shaders/flat/movingSun.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function movingSunGlsl(on: boolean): string;

package/dist/render/shaders/flat/movingSun.js

@@ -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) {
+    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/dist/render/shaders/flat/normalMap.d.ts

@@ -3,8 +3,12 @@
  * 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 declare const NORMAL_MAP_GLSL = "\nvec3 normalMapped(vec3 n, vec3 at) {\n  vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;\n  /*\n   * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a\n   * stored z at or below zero is never a real one: it is a two-channel map, BC5, whose blue a\n   * device samples as zero and which arrives here as -1. Every map baked from BC5 to PNG before\n   * 4.8.4 carried the same zero. A select rather than a flag: no uniform to bind, no material\n   * that has to say what format it holds, and continuous at the boundary, since a unit texel\n   * lying flat has its z near zero either way. A texel with z above zero is left as it was.\n   */\n  mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));\n  mat3 tbn = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);\n  return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));\n}\n";
+export declare const NORMAL_MAP_GLSL = "\nvec3 normalMapped(vec3 n, vec3 at, vec2 frameAt, int hasTangents) {\n  /* On three planes where the material projects them so: worldUv.ts. */\n  if (WORLD_UVS && triplanar()) return triplanarNormal(n, at.z);\n  /*\n   * A layered material's texels, blended by its mask before the frame turns them, around a normal\n   * read at the mesh's own coordinates and tangents where the material lays one under them, which is\n   * the surface's large shape the layers' detail rides on: layered.ts.\n   */\n  if (LAYERED && layered()) {\n    vec3 under = n;\n    if (layeredMeshNormal()) {\n      mat3 meshFrame = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);\n      under = normalize(meshFrame * layeredMeshTexel());\n    }\n    mat3 layeredFrame = tangentFrame(under, vWorldPos, frameAt, vTangent, hasTangents);\n    return normalize(mix(n, normalize(layeredFrame * layeredTexel()), uNormalStrength));\n  }\n  vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;\n  /*\n   * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a\n   * stored z at or below zero is never a real one: it is a two-channel map, BC5, whose blue a\n   * device samples as zero and which arrives here as -1. Every map baked from BC5 to PNG before\n   * 4.8.4 carried the same zero. A select rather than a flag: no uniform to bind, no material\n   * that has to say what format it holds, and continuous at the boundary, since a unit texel\n   * lying flat has its z near zero either way. A texel with z above zero is left as it was.\n   */\n  mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));\n  mat3 tbn = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);\n  return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));\n}\n";

package/dist/render/shaders/flat/normalMap.js

@@ -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));
 }
 `;

package/dist/render/shaders/flat/overlay.d.ts

@@ -1,7 +1,8 @@
 /**
  * A draw's surface overlay in the lit stage: the rim, the dissolve and the wrinkles
- * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at three places — the dissolve's cut
- * before anything is shaded, the wrinkles after the normal map, and the glow beside emission.
+ * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at four places — the dissolve's cut
+ * before anything is shaded, the wrinkles after the normal map, a blending rim on the base colour
+ * once the normal is final and before any light reads the colour, and the glow beside emission.
  *
  * **A lit switch, `SURFACE_OVERLAY`**, off until a draw first sets an overlay and then on for good,
  * as `litSwitchesGlsl`'s are; declared after the models so every switch before it keeps its id.

package/dist/render/shaders/flat/overlay.js

@@ -1,7 +1,8 @@
 /**
  * A draw's surface overlay in the lit stage: the rim, the dissolve and the wrinkles
- * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at three places — the dissolve's cut
- * before anything is shaded, the wrinkles after the normal map, and the glow beside emission.
+ * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at four places — the dissolve's cut
+ * before anything is shaded, the wrinkles after the normal map, a blending rim on the base colour
+ * once the normal is final and before any light reads the colour, and the glow beside emission.
  *
  * **A lit switch, `SURFACE_OVERLAY`**, off until a draw first sets an overlay and then on for good,
  * as `litSwitchesGlsl`'s are; declared after the models so every switch before it keeps its id.
@@ -19,6 +20,7 @@ export function overlayGlsl(on) {
 const bool SURFACE_OVERLAY = false;  // wgsl:override
 bool overlayCuts(vec2 uv) { return false; }
 vec3 overlayWrinkle(vec3 mapped, vec3 unmapped, vec2 uv) { return mapped; }
+vec3 overlayRimBase(vec3 base, vec2 uv, vec3 n) { return base; }
 vec3 overlayGlow(vec2 uv, vec3 n) { return vec3(0.0); }
 `;
     }
@@ -84,8 +86,42 @@ vec2 overlayScreen() {
   return vec2(eye.x / depth + uClusterFrustum.w, eye.y / depth + 1.0) * 0.5;
 }
 
+/*
+ * The rim's weight here, 0 to 1 before the pulse and the mask: the edge leaning toward normals that
+ * face up, raised to the contrast, times the noise laid in screen space. Its strength is the
+ * caller's: an added rim takes it times its light, a blending one times its colour.
+ */
+float overlayRimWeight(vec2 uv, vec3 n) {
+  vec3 toEye = normalize(uCameraPos - vWorldPos);
+  float edge = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), max(uOverlay[1].x, 1e-4));
+  float up = pow(clamp(n.y * 0.5 + 0.5, 0.0, 1.0), max(uOverlay[1].y, 1e-4));
+  float rim = pow(edge * up, max(uOverlay[1].z, 1e-4));
+  float time = uSurfaceScene.x;
+  if (uOverlay[2].x > 0.0 && overlayImagesBound()) {
+    vec2 at = overlayScreen() * uOverlay[3].z + uOverlay[3].xy * time;
+    rim *= overlayImage(uOverlay[2], at).r;
+  }
+  rim = min(rim, 1.0);
+  rim *= mix(uOverlay[4].x, uOverlay[4].y, 0.5 + 0.5 * sin(uOverlay[3].w * time));
+  if (uOverlay[5].x > 0.0 && overlayImagesBound()) {
+    rim *= 1.0 - uOverlay[1].w * overlayImage(uOverlay[5], uv).r;
+  }
+  return rim;
+}
+
+/*
+ * A blending rim: the base colour pulled toward the rim's by the weight times the alpha, held at
+ * one, before any light reads it, so the edge is lit as the surface is. The colour arrives already
+ * held at one a channel. Nothing where the rim adds instead, or where there is none.
+ */
+vec3 overlayRimBase(vec3 base, vec2 uv, vec3 n) {
+  if (uOverlay[0].w <= 0.0 || uOverlay[4].z < 0.5) return base;
+  float weight = clamp(uOverlay[0].w * overlayRimWeight(uv, n), 0.0, 1.0);
+  return mix(base, uOverlay[0].rgb, weight);
+}
+
 /* What the overlay adds to the light the surface gives off: the dissolve's band, the colour laid
-   over through its noise, and the rim. Zero where the draw sets none of them. */
+   over through its noise, and an adding rim. Zero where the draw sets none of them. */
 vec3 overlayGlow(vec2 uv, vec3 n) {
   vec3 glow = vec3(0.0);
   float noise = overlayDissolveNoise(uv);
@@ -94,22 +130,8 @@ vec3 overlayGlow(vec2 uv, vec3 n) {
     glow += uOverlay[8].rgb * uOverlay[8].w * band + uOverlay[9].rgb * uOverlay[9].w * noise;
   }
   float strength = uOverlay[0].w;
-  if (strength > 0.0) {
-    vec3 toEye = normalize(uCameraPos - vWorldPos);
-    float edge = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), max(uOverlay[1].x, 1e-4));
-    float up = pow(clamp(n.y * 0.5 + 0.5, 0.0, 1.0), max(uOverlay[1].y, 1e-4));
-    float rim = pow(edge * up, max(uOverlay[1].z, 1e-4));
-    float time = uSurfaceScene.x;
-    if (uOverlay[2].x > 0.0 && overlayImagesBound()) {
-      vec2 at = overlayScreen() * uOverlay[3].z + uOverlay[3].xy * time;
-      rim *= overlayImage(uOverlay[2], at).r;
-    }
-    rim = min(rim, 1.0);
-    rim *= mix(uOverlay[4].x, uOverlay[4].y, 0.5 + 0.5 * sin(uOverlay[3].w * time));
-    if (uOverlay[5].x > 0.0 && overlayImagesBound()) {
-      rim *= 1.0 - uOverlay[1].w * overlayImage(uOverlay[5], uv).r;
-    }
-    glow += uOverlay[0].rgb * strength * rim;
+  if (strength > 0.0 && uOverlay[4].z < 0.5) {
+    glow += uOverlay[0].rgb * strength * overlayRimWeight(uv, n);
   }
   return glow;
 }

package/dist/render/shaders/flat/preamble.js

@@ -116,7 +116,12 @@ uniform vec4 uSeeThrough; // wgsl:material
  * the rows a screen coordinate counts. A vec4 where a vec3 already spent the row.
  */
 uniform vec4 uRefractTint; // wgsl:material
-uniform vec3 uGlassTint; // wgsl:material
+/*
+ * A pane's colour (rgb), and in w how much light from behind an opaque thin surface lets through:
+ * \`SurfaceMaterial.diffuseTransmission\`, read where the draw is not glass. A vec4 where a vec3
+ * already spent the row.
+ */
+uniform vec4 uGlassTint; // wgsl:material
 flat in int vHasTangents;
 
 /**
@@ -428,17 +433,30 @@ uniform float uOpacity; // wgsl:material
  * the grain is mirrored between backends and nothing else about it differs. What it gives up: a
  * crossfade reads as grain for as long as it lasts, which is why it should be short; and a blended
  * draw that asks for it is dithered too, since the test is a discard.
+ *
+ * **\`.z\` — whether this draw spends its own opacity on the same screen door**: 1 keeps the cells
+ * under \`vAlpha\` (an instance's \`MeshInstances.alphas\`, a vertex's channel alpha) and blends none
+ * of it, so an opaque or cut-out draw can fade one instance at a time. 0 is off. **The same pattern
+ * as the fade, and that is the point**: a pixel is kept where its one threshold sits under both, so
+ * a crossfade at \`t\` and \`-t\` of an instance at opacity \`a\` still covers each pixel of the
+ * instance's share \`a\` once. Two independent patterns would leave holes where they disagree.
  */
-uniform vec2 uWriteMode; // wgsl:material
+uniform vec3 uWriteMode; // wgsl:material
 
-/** Whether this fragment is one \`uWriteMode.y\` keeps. Integer arithmetic, per the device rule. */
-bool ditherKeeps(float amount) {
+/** Where this fragment's cell of the 8×8 Bayer pattern falls, in (0, 1). Integer arithmetic,
+    per the device rule. */
+float ditherThreshold() {
   uvec2 p = uvec2(gl_FragCoord.xy) & 7u;
   uint a = p.x ^ p.y;
   uint b = p.y;
   uint cell = ((a & 1u) << 5) | ((b & 1u) << 4) | ((a & 2u) << 2) | ((b & 2u) << 1) |
     ((a & 4u) >> 1) | ((b & 4u) >> 2);
-  float threshold = (float(cell) + 0.5) / 64.0;
+  return (float(cell) + 0.5) / 64.0;
+}
+
+/** Whether this fragment is one \`uWriteMode.y\` keeps. */
+bool ditherKeeps(float amount) {
+  float threshold = ditherThreshold();
   return amount > 0.0 ? threshold < amount : threshold >= -amount;
 }
 

package/dist/render/shaders/flat/worldUv.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A material's maps placed by where a point is in the world rather than by the mesh's texture
+ * coordinates: `SurfaceMaterial.projection`, packed into `uWorldUv` by `surfaceProjection.ts`.
+ *
+ * **Planar** takes the two horizontal axes, `x` and `z`, at so many repeats a metre: a floor whose
+ * mesh carries no useful coordinates, or one coordinate for the whole of it, shows its texture at
+ * the size the material asks. **Triplanar** reads every map three times, on the planes across `x`,
+ * `y` and `z`, and blends them by how squarely the surface faces each — the geometric normal raised
+ * to a sharpness — so a wall, a cliff and a rock wear it as a floor does. A normal map on three
+ * planes is turned into the world by the whiteout blend, each plane's tangent-space normal added to
+ * the surface's own swizzled into that plane, which keeps the detail of each without a tangent
+ * frame per plane.
+ *
+ * **A lit switch, `WORLD_UVS`**, off until a material first asks and then on for good, declared
+ * last so every switch before it keeps its id. Compiled out, its vector is not declared and its
+ * calls are constants, so a scene that never asks pays nothing.
+ *
+ * **What it gives up**: a projection is the world's, so a mesh that moves slides under its own
+ * texture, which is right for ground and wrong for a crate; triplanar reads each map three times;
+ * and a map that is an array reads one layer for the whole surface, the one the face names.
+ */
+export declare function worldUvGlsl(on: boolean): string;