@driftengine/core 4.9.0 → 4.11.0

package/dist/render/shaders/depth.js

@@ -5,6 +5,7 @@ import { CUTOUT_DITHER_GLSL } from '../cutoutDither.js';
 import { SKINNING_GLSL } from './skinning.js';
 import { CLOTH_BINDING_GLSL } from './clothBinding.js';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.js';
+import { BONE_ANIMATION_GLSL } from './boneAnimation.js';
 /**
  * Depth-only shadow pass. Its optional peel mode rejects the first recorded
  * surface so the next independently fading occluder can be retained.
@@ -77,6 +78,17 @@ uniform vec2 uUvOffset;
 uniform vec2 uAlphaCutout;
 #endif
 
+#if ANIMATED
+/*
+ * **A bone animation's, after every other declaration** so no field of the variants before it
+ * moves: the grain lane the vertex's bone rides in, the scene's clock, and the chunk the colour
+ * pass runs — the same expression, or a crowd's shadow stands still while the crowd moves.
+ */
+layout(location = 8) in float aGrain;
+uniform float uSceneTime;
+${BONE_ANIMATION_GLSL}
+#endif
+
 out vec4 vLightPosition;
 #if CUTOUT
 /* The texture coordinate and, in z, the texture-array layer the face wears. */
@@ -98,6 +110,12 @@ void main() {
 #else
   vec4 local = vec4(aPosition, 1.0);
 #endif
+#if ANIMATED
+  /* Turned and placed as the colour pass turns and places it; its normal and tangent unused. */
+  vec3 animatedNormal = vec3(0.0, 1.0, 0.0);
+  vec3 animatedTangent = vec3(1.0, 0.0, 0.0);
+  local = vec4(boneAnimate(local.xyz, animatedNormal, animatedTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
@@ -144,9 +162,9 @@ void main() {
 }
 `;
 /** The rigid variant: the world, a prop, a mesh with no rig behind it. */
-export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false }, 'depth');
+export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth');
 /** The skinned variant, which reads a joint palette and moves the vertex by it. */
-export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false }, 'depth-skinned');
+export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth-skinned');
 /**
  * The variant an instanced draw casts its shadow through.
  *
@@ -155,7 +173,7 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINN
  * right place and the rest stacked underneath it, which reads as a lighting fault rather than as
  * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
  */
-export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false }, 'depth-instanced');
+export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth-instanced');
 /**
  * The variants a cutout caster casts through: a leaf card, a chain link, a fence, whose shape is in
  * its texture's alpha rather than in its geometry.
@@ -166,8 +184,15 @@ export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKI
  * leaves every opaque caster byte for byte as it was. What it costs is one more program each, and
  * a skinned cutout, which nothing has asked for, is not among them.
  */
-export const DEPTH_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false }, 'depth-cutout');
-export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false }, 'depth-instanced-cutout');
+export const DEPTH_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false, ANIMATED: false }, 'depth-cutout');
+export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: false }, 'depth-instanced-cutout');
+/**
+ * The variants a crowd casts through: an instanced batch playing a bone animation, its vertices
+ * where the clip puts them at each instance's moment. See `shaders/boneAnimation.ts`. No glass
+ * variant: a crowd is not glass, and a glass batch that animates casts its tint from rest.
+ */
+export const DEPTH_INSTANCED_ANIMATED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: true }, 'depth-instanced-animated');
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: true }, 'depth-instanced-animated-cutout');
 export const DEPTH_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
@@ -238,11 +263,11 @@ void main() {
  * exactly where it casts its depth, deformed and placed the same way, or the coloured patch parts
  * from the pane's own shadow edge. The only addition is `vGlassWorld`.
  */
-export const GLASS_TINT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true }, 'glass-tint');
-export const GLASS_TINT_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true }, 'glass-tint-skinned');
-export const GLASS_TINT_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true }, 'glass-tint-instanced');
-export const GLASS_TINT_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true }, 'glass-tint-cutout');
-export const GLASS_TINT_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true }, 'glass-tint-instanced-cutout');
+export const GLASS_TINT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint');
+export const GLASS_TINT_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint-skinned');
+export const GLASS_TINT_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint-instanced');
+export const GLASS_TINT_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true, ANIMATED: false }, 'glass-tint-cutout');
+export const GLASS_TINT_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true, ANIMATED: false }, 'glass-tint-instanced-cutout');
 /**
  * What a pane lets through: its transmission and colour, less what it reflects toward the light,
  * and how clear it is — `glassShadow.ts`'s `paneTexel`, stated for the device. Drawn with a

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

@@ -29,13 +29,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;
 
@@ -65,6 +108,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
@@ -129,7 +180,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);
   }
@@ -193,7 +245,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;
@@ -201,12 +252,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
@@ -227,11 +284,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,
@@ -271,6 +328,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);
@@ -288,8 +352,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/dist/render/shaders/flat/glassTint.d.ts

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */

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

@@ -34,6 +34,9 @@ export function noLitSwitches() {
         PHYSICAL_SPECULAR: false,
         SURFACE_OVERLAY: false,
         REFLECTION_MAPS: false,
+        WORLD_UVS: false,
+        MOVING_SUN: false,
+        LAYERED: false,
     };
 }
 /**

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

@@ -38,6 +38,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;
 }
 /**
  * The flat vertex shader, built for one variant.
@@ -119,6 +125,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.
      *

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

@@ -21,7 +21,12 @@ import { DRIFT_LIGHT_GLSL } from './driftLight.js';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.js';
 import { overlayGlsl } from './overlay.js';
 import { reflectionSurfaceGlsl } from './reflectionSurface.js';
-import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.js';
+import { worldUvGlsl } from './worldUv.js';
+import { movingSunGlsl } from './movingSun.js';
+import { layeredGlsl } from './layered.js';
+import { MAP_READS_GLSL } from './mapReads.js';
+import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.js';
+import { BONE_ANIMATION_GLSL } from '../boneAnimation.js';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
 /**
  * Flat-shaded vertex colours with one dominant directional source, ambient,
@@ -55,10 +60,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.
  *
@@ -121,6 +132,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;
 /**
@@ -146,7 +160,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
 
@@ -244,6 +258,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);
   /*
@@ -353,7 +371,15 @@ export function flatVert(options) {
         throw new Error('flatVert: a variant cannot be both morphed and instanced — a morph weight is per draw, ' +
             'so every instance of the batch would wear one expression between them.');
     }
-    return resolveConditionals(FLAT_VERT_SOURCE, { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced }, 'flatVert');
+    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,
+        ANIMATED: options.animated === true,
+    }, 'flatVert');
 }
 /**
  * The flat fragment shader, built for one quality profile.
@@ -439,6 +465,8 @@ export function flatFrag(options) {
             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,
@@ -464,8 +492,6 @@ export function flatFrag(options) {
          * 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,
@@ -477,6 +503,15 @@ export function flatFrag(options) {
         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/dist/render/shaders/flat/layered.d.ts

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

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

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