@driftengine/core 4.9.0 → 4.10.0

package/src/render/shaders/boneAnimation.ts

@@ -0,0 +1,63 @@
+/**
+ * The vertex-stage bone animation: a crowd instance's vertex turned and placed by its bone, at its
+ * instance's moment of the clip — the GLSL of `boneAnimation.ts`'s `animateBoneVertex`, line for
+ * line. Shared by the lit stage and the depth stage, so a crowd's shadow moves with it.
+ *
+ * **Three textures, read by index and never filtered**: the places and the turns, a texel a bone a
+ * frame (bones across, frames down, sizes read with `textureSize` so no uniform says them), and the
+ * batch's clocks, two floats an instance wrapped onto rows, read at `gl_InstanceID`. The clip's speed
+ * and its bone scale are the one uniform, `uBoneClip`; the scene's time is the pass's `uSceneTime`.
+ *
+ * **The bone is read from the grain lane**, which is where a mesh's second coordinates ride, stored
+ * as `-1 - u` (`lightmap.ts`). An instanced batch reads no grain of its own from that lane: a crowd's
+ * mesh carries second coordinates, which is what makes it one.
+ *
+ * Integer arithmetic for the lattice, by the 2026-09-20 rule, except where a float is clamped onto
+ * it: the first frame is `min(floor(wrapped), frames - 1)`, so the wrap that division-by-reciprocal
+ * lands on `frames` is the last frame fully blended into the first — the first, which is right.
+ */
+export const BONE_ANIMATION_GLSL = `
+uniform highp sampler2D uBonePlaces;
+uniform highp sampler2D uBoneTurns;
+uniform highp sampler2D uInstanceClocks;
+/** x the clip's frames a second, y how many bones one unit of the second coordinates' u counts. */
+uniform vec2 uBoneClip;
+
+/** v turned by the unit quaternion q. */
+vec3 boneTurn(vec4 q, vec3 v) {
+  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);
+}
+
+/**
+ * Where the clip puts this vertex, from its place at rest; its normal and tangent turned with it.
+ */
+vec3 boneAnimate(vec3 position, inout vec3 normal, inout vec3 tangent) {
+  ivec2 size = textureSize(uBonePlaces, 0);
+  int clocksWidth = textureSize(uInstanceClocks, 0).x;
+  vec2 clock = texelFetch(
+    uInstanceClocks,
+    ivec2(gl_InstanceID % clocksWidth, gl_InstanceID / clocksWidth),
+    0
+  ).xy;
+  float moment = (uSceneTime * clock.y + clock.x) * uBoneClip.x;
+  float frames = float(size.y);
+  float wrapped = moment - frames * floor(moment / frames);
+  int first = min(int(floor(wrapped)), size.y - 1);
+  int second = first + 1 == size.y ? 0 : first + 1;
+  float blend = clamp(wrapped - float(first), 0.0, 1.0);
+  int bone = clamp(int(floor((-1.0 - aGrain) * uBoneClip.y + 0.5)), 0, size.x - 1);
+  vec4 q0 = texelFetch(uBoneTurns, ivec2(bone, first), 0);
+  vec4 q1 = texelFetch(uBoneTurns, ivec2(bone, second), 0);
+  /* The shorter arc: a quaternion and its negation are one turn. */
+  if (dot(q0, q1) < 0.0) q1 = -q1;
+  vec4 q = normalize(mix(q0, q1, blend));
+  vec3 place = mix(
+    texelFetch(uBonePlaces, ivec2(bone, first), 0).xyz,
+    texelFetch(uBonePlaces, ivec2(bone, second), 0).xyz,
+    blend
+  );
+  normal = boneTurn(q, normal);
+  tangent = boneTurn(q, tangent);
+  return boneTurn(q, position) + place;
+}
+`;

package/src/render/shaders/depth.ts

@@ -5,6 +5,7 @@ import { CUTOUT_DITHER_GLSL } from '../cutoutDither.ts';
 import { SKINNING_GLSL } from './skinning.ts';
 import { CLOTH_BINDING_GLSL } from './clothBinding.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.ts';
+import { BONE_ANIMATION_GLSL } from './boneAnimation.ts';
 
 /**
  * Depth-only shadow pass. Its optional peel mode rejects the first recorded
@@ -78,6 +79,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. */
@@ -99,6 +111,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. */
@@ -148,14 +166,14 @@ 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 },
+  { 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 },
+  { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false },
   'depth-skinned',
 );
 
@@ -169,7 +187,7 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(
  */
 export const DEPTH_INSTANCED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false },
+  { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: false },
   'depth-instanced',
 );
 
@@ -185,16 +203,33 @@ export const DEPTH_INSTANCED_VERT = resolveConditionals(
  */
 export const DEPTH_CUTOUT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false },
+  { 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 },
+  { 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;
@@ -269,27 +304,27 @@ void main() {
  */
 export const GLASS_TINT_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true },
+  { 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 },
+  { 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 },
+  { 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 },
+  { 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 },
+  { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true, ANIMATED: false },
   'glass-tint-instanced-cutout',
 );
 

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

@@ -21,7 +21,8 @@ import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
 import { overlayGlsl } from './overlay.ts';
 import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
-import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
+import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
+import { BONE_ANIMATION_GLSL } from '../boneAnimation.ts';
 import { FULL_LIGHT_BUDGET, type LightBudget } from '../../uniformVectorBudget.ts';
 
 /**
@@ -56,10 +57,16 @@ layout(location = 10) in vec4 aTangent;
 ${SKINNING_GLSL}
 #endif
 
-uniform mat4 uViewProj;
+uniform mat4 uViewProj; // wgsl:view
 /** 1 when the mesh carries a tangent frame. See vHasTangents. */
 uniform int uHasTangents;
-uniform mat4 uLightViewProj;
+uniform mat4 uLightViewProj; // wgsl:view
+/**
+ * The scene's clock, what \`setAnimationTime\` set: what a bone animation's instances read
+ * their moment from. In the view block, before the wind, so every variant's view block is the
+ * plain one's or a prefix of it — the instanced variant declares no wind and keeps this.
+ */
+uniform float uSceneTime; // wgsl:view
 /**
  * How often the surface texture repeats across this mesh's UV range, per axis.
  *
@@ -122,6 +129,9 @@ layout(location = 15) in vec4 aInstanceTint;
  * opacity of one. See lightmap.ts.
  */
 const bool LIGHTMAP_REGIONS = false; // wgsl:override
+#if ANIMATED
+${BONE_ANIMATION_GLSL}
+#endif
 #else
 uniform mat4 uModel;
 /**
@@ -147,7 +157,7 @@ uniform vec3 uTint;
  * agreeing about where the shared uniforms sit: the instanced variant drops these five along with
  * the two above it, and a dropped field moves nothing. flatPass.ts asserts exactly that.
  */
-${CHANNEL_ATTRIBUTE}
+${LIT_CHANNEL_ATTRIBUTE}
 ${CHANNEL_BEND}
 #endif
 
@@ -245,6 +255,10 @@ void main() {
   vec3 localNormal = aNormal;
   vec3 localTangent = aTangent.xyz;
 #endif
+#if ANIMATED
+  /* The clip's turn and place, in the mesh's own space, before the instance places it. */
+  local = vec4(boneAnimate(local.xyz, localNormal, localTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /*
@@ -379,6 +393,12 @@ export interface FlatVertexOptions {
    * Excludes `skinned`: the joint attributes and the instance matrix want the same locations.
    */
   readonly instanced: boolean;
+  /**
+   * Whether an instanced variant follows a bone animation: \`shaders/boneAnimation.ts\`. A
+   * variant rather than a pipeline constant, because it declares three textures the other
+   * instanced pipelines would otherwise have to bind stand-ins for. Instanced only.
+   */
+  readonly animated?: boolean;
 }
 
 /**
@@ -401,9 +421,17 @@ export function flatVert(options: FlatVertexOptions): string {
         'so every instance of the batch would wear one expression between them.',
     );
   }
+  if (options.animated === true && !options.instanced) {
+    throw new Error('flatVert: a bone animation is played by an instanced variant alone.');
+  }
   return resolveConditionals(
     FLAT_VERT_SOURCE,
-    { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced },
+    {
+      SKINNED: options.skinned,
+      MORPHED: options.morphed,
+      INSTANCED: options.instanced,
+      ANIMATED: options.animated === true,
+    },
     'flatVert',
   );
 }

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

@@ -82,7 +82,7 @@ export const MAIN_GLSL = `void main() {
          */
         float share = cutoutShare(tested, uCutout.x);
         if (uCutout.y == 1.0) {
-          if (!cutoutKeeps(share, gl_FragCoord.xy, uCutout.z)) discard;
+          if (!cutoutKeeps(share, gl_FragCoord.xy, uHighlightMin.w)) discard;
           kept = 1.0;
         } else {
           kept = share;
@@ -1281,7 +1281,7 @@ export const MAIN_GLSL = `void main() {
        */
       float falloff;
       /*
-       * **A light may name its own falloff, and then it is Unreal's for a light without
+       * **A light may name its own falloff, and then it is the usual one for a light without
        * inverse-square falloff**: \`(1 - (d/R)^2)^n\` with no distance term, so a fill authored to
        * light a whole hall across a hundred metres does, where the inverse square would have it
        * gone a few metres out. Zero is the frame's own rule below, which every light was before.
@@ -1997,7 +1997,7 @@ export const MAIN_GLSL = `void main() {
     // finishing a run reads the same at noon and at midnight. Costs one compare
     // per fragment and no extra draw call — the box is a uniform, not geometry.
     if (uHighlightMax.w > 0.0) {
-      vec3 inside = step(uHighlightMin, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
+      vec3 inside = step(uHighlightMin.xyz, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
       lit += albedo * uHighlightMax.w * inside.x * inside.y * inside.z;
     }
   }
@@ -2101,7 +2101,17 @@ export const MAIN_GLSL = `void main() {
     vec3 refractV = normalize(uCameraPos - vWorldPos);
     ivec2 snapSize = textureSize(uRefractScene, 0);
     vec2 screenUv = gl_FragCoord.xy / vec2(snapSize);
-    vec2 bent = clamp(screenUv + refractN.xy * uSeeThrough.x, vec2(0.0), vec2(1.0));
+    /*
+     * **The normal's sideways part as the eye sees it**: the shading normal in view space, its x
+     * and y across the screen, y turned to the way this frame's rows run (w of the tint). It was the
+     * normal's world x and y until 4.10.0, which on a quad facing the camera is the quad's own lean
+     * against the world's axes: one offset over the whole quad, a lens, with a normal map's tilt a
+     * small change on top. In view space a quad facing the eye bends by nothing but its map, which
+     * is a shimmer, and a pane bends by how it leans toward the eye wherever the eye stands.
+     */
+    vec3 seenN = mat3(uView) * refractN;
+    vec2 bend = vec2(seenN.x, seenN.y * uRefractTint.w);
+    vec2 bent = clamp(screenUv + bend * uSeeThrough.x, vec2(0.0), vec2(1.0));
     /*
      * **An explicit level, and frost is what picks it** — the 2026-08-07 rule, and the reason a
      * frosted pane blurs rather than fades: the copy carries a mip chain on a frame that draws glass,
@@ -2115,7 +2125,7 @@ export const MAIN_GLSL = `void main() {
     /* Unsigned: a pane passes the same light seen from either side, and so does its Fresnel. */
     float cosView = max(abs(dot(refractN, refractV)), 0.05);
     float pathLength = uSeeThrough.y * vThickness / cosView;
-    vec3 seen = behind * pow(uRefractTint, vec3(pathLength));
+    vec3 seen = behind * pow(uRefractTint.rgb, vec3(pathLength));
     if (glassTransmission > 0.0) {
       /*
        * **Glass keeps its own surface and shows what is behind over it**, by how much it lets

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

@@ -59,7 +59,7 @@ const bool PHYSICAL_SPECULAR = PHYSICAL_SPECULAR_ON;  // wgsl:override
  * A model's numbers, two vectors a material — the lit stage's uniform budget has no more room
  * (surfaceModel.ts) — and whether a model map is bound, in the last component.
  */
-uniform vec4 uModelParams[2];
+uniform vec4 uModelParams[2]; // wgsl:material
 /* The model's own channels, in the albedo's layout: what each means is each model's to say. */
 uniform highp sampler2DArray uModelMap;
 

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

@@ -26,7 +26,7 @@ vec3 overlayGlow(vec2 uv, vec3 n) { return vec3(0.0); }
 /* Whether this program carries a draw's overlay. Off but where one has been set: overlay.ts. */
 const bool SURFACE_OVERLAY = true;  // wgsl:override
 /* The overlay's fifteen vectors; packSurfaceOverlay in surfaceOverlay.ts says what each holds. */
-uniform vec4 uOverlay[15];
+uniform vec4 uOverlay[15]; // wgsl:material
 
 /* Whether the atlas is what the refraction slot holds: not where this draw refracts or is glass. */
 bool overlayImagesBound() {

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

@@ -13,7 +13,7 @@
  * picture and is its own change.
  */
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.ts';
-import { OUTPUT_TRANSFORM_GLSL } from '../outputTransform.ts';
+import { LIT_OUTPUT_TRANSFORM_GLSL } from '../outputTransform.ts';
 import { LAMP_GLASS_GLSL } from './lampGlass.ts';
 
 export const POINTSHADOW_GLSL = `/**
@@ -344,7 +344,7 @@ ${LAMP_GLASS_GLSL}
 
 layout(location = 0) out vec4 outColor;
 
-${OUTPUT_TRANSFORM_GLSL}
+${LIT_OUTPUT_TRANSFORM_GLSL}
 
 /**
  * A fixed Poisson disk avoids the grid-shaped edge left by square 3x3 PCF.

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

@@ -121,9 +121,15 @@ uniform sampler2D uRefractScene;
  * gives up, and four separate floats cost half the shadowed lights such a device can have. The tints
  * stay colours of their own. Zero transmission is not glass — see glass.ts.
  */
-uniform vec4 uSeeThrough;
-uniform vec3 uRefractTint;
-uniform vec3 uGlassTint;
+uniform vec4 uSeeThrough; // wgsl:material
+/*
+ * What a metre of the medium leaves of each channel (rgb), and in w which way this frame's rows run
+ * up the screen: +1 where the first row is the bottom (WebGL2), -1 where it is the top (WebGPU). The
+ * bend is taken in view space, whose y is up whatever the framebuffer says, so it is turned here to
+ * 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
 flat in int vHasTangents;
 
 /**
@@ -154,7 +160,7 @@ uniform mediump sampler2DArray uAlbedo;
  *   card. Its draw culls nothing, and a back face is lit as a front, with the shading normal turned
  *   toward the viewer.
  */
-uniform ivec4 uMaterialFlags;
+uniform ivec4 uMaterialFlags; // wgsl:material
 /**
  * Alpha below which a textured fragment is thrown away entirely, 0 to disable.
  *
@@ -168,13 +174,17 @@ uniform ivec4 uMaterialFlags;
  * else changes.
  *
  * **Four numbers in one row**: x is the cutoff, y how this frame resolves the edge (0 the hard test,
- * 1 a dither the temporal resolve averages, 2 alpha-to-coverage; see \`cutoutDither.ts\`), z the
- * frame the dither's pattern is offset by, w the material's lighting channels — a mask a light
- * shades it only where its own shares a bit with (\`SurfaceMaterial.lightChannels\`, 1 unless a
- * material names others). One vector rather than a float and three more, because every loose
- * scalar is a row of WebGL2's 224 that the light budget gives up.
+ * 1 a dither the temporal resolve averages, 2 alpha-to-coverage; see \`cutoutDither.ts\`), z unused,
+ * w the material's lighting channels — a mask a light shades it only where its own shares a bit
+ * with (\`SurfaceMaterial.lightChannels\`, 1 unless a material names others). One vector rather than
+ * a float and three more, because every loose scalar is a row of WebGL2's 224 that the light budget
+ * gives up.
+ *
+ * **z was the frame the dither's pattern is offset by until 4.10.0**, and that made every material
+ * new every frame: a material is kept on WebGPU by its numbers, and one of them changed with the
+ * clock. The frame is the pass's, in \`uHighlightMin.w\`.
  */
-uniform vec4 uCutout;
+uniform vec4 uCutout; // wgsl:material
 /**
  * A draw's own ambient, as nine spherical-harmonic coefficients of incoming radiance, red green blue
  * in turn, twenty-seven floats, and in the last of the twenty-eight a 1 where they are on — 0 is the
@@ -182,7 +192,7 @@ uniform vec4 uCutout;
  * and the basis, and its tests hold this to it. Seven rows of the material block, which is per draw
  * as far as anything here is: \`setAmbientSH\` moves it between two draws as \`setMaterial\` does.
  */
-uniform vec4 uAmbientSH[7];
+uniform vec4 uAmbientSH[7]; // wgsl:material
 
 /** The ambient a surface facing \`n\` receives from \`uAmbientSH\`: \`ambientFromSH\`'s arithmetic. */
 vec3 ambientHarmonics(vec3 n) {
@@ -229,7 +239,7 @@ uniform highp sampler2DArray uNormalMap;
  * shadow samplers, where a profile with shadows off should declare none of them; it is the wrong
  * tool for one image on a shader that already declares one.
  */
-uniform float uNormalStrength;
+uniform float uNormalStrength; // wgsl:material
 
 /**
  * Occlusion, roughness and metallic in one image. glTF's packing, because that is what an import
@@ -250,7 +260,7 @@ uniform highp sampler2DArray uOrmMap;
  * occlusionTexture.strength is: 1 + strength * (texel - 1). A multiply at 0 means fully occluded,
  * which is the opposite of what a caller asking for no occlusion means.
  */
-uniform vec3 uOrmScale;
+uniform vec3 uOrmScale; // wgsl:material
 /**
  * 1 when \`uEnvironment\` holds the GGX-prefiltered cube, 0 when it holds the capture's box chain.
  *
@@ -266,7 +276,7 @@ uniform vec3 uOrmScale;
  * (\`uniformVectorBudget.ts\`). y is how much of the environment the material mirrors, z how
  * bright what it mirrors is.
  */
-uniform vec3 uEnvironmentDials;
+uniform vec3 uEnvironmentDials; // wgsl:material
 
 /**
  * Where a surface glows, and in what colour.
@@ -288,7 +298,7 @@ uniform highp sampler2DArray uEmissiveMap;
  * The counterpart of \`uOrmScale\`: a factor that multiplies a texture is not a value, and this is
  * where the multiplier lives once an image supplies the shape.
  */
-uniform vec3 uEmissiveScale;
+uniform vec3 uEmissiveScale; // wgsl:material
 
 #if DIRECTIONAL_SHADOWS
 /*
@@ -375,7 +385,7 @@ uniform vec4 uSurfaceScene;
  * draw moves it), y the night factor emission is gated on. One row where two floats were two
  * (\`uniformVectorBudget.ts\`).
  */
-uniform vec2 uEmission;
+uniform vec2 uEmission; // wgsl:material
 #if NIGHT_EMISSIVE
 /**
  * Emission that only shows where the dominant light does not reach. 0 is off and is the default.
@@ -400,7 +410,7 @@ uniform float uNightEmissive;
  * of that to change one channel is how a renderer ends up with two shaders that
  * disagree about the sun. The caller owns the blend state; this owns the number.
  */
-uniform float uOpacity;
+uniform float uOpacity; // wgsl:material
 
 /**
  * Two per-draw switches on how a fragment is *written* rather than what colour it is, sharing one
@@ -432,7 +442,7 @@ uniform float uOpacity;
  * 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.
  */
-uniform vec2 uWriteMode;
+uniform vec2 uWriteMode; // wgsl:material
 
 /** Whether this fragment is one \`uWriteMode.y\` keeps. Integer arithmetic, per the device rule. */
 bool ditherKeeps(float amount) {
@@ -465,7 +475,7 @@ bool ditherKeeps(float amount) {
  * one uniform skips the untaken side rather than computing both and discarding one, which is
  * only true because nothing here reads it through a *varying*-dependent branch.
  */
-uniform int uLightingEnabled;
+uniform int uLightingEnabled; // wgsl:material
 /**
  * How this draw meets the medium: the atmospheric haze and the underwater tint both, folded
  * together because both are the *camera's* medium rather than a property of the surface — see
@@ -487,7 +497,7 @@ uniform int uLightingEnabled;
  * is what "exactly as its colour says" has to mean for it; the cost is that such a draw will
  * not tint if the camera goes under water, unlike everything else in the frame.
  */
-uniform int uFogEnabled;
+uniform int uFogEnabled; // wgsl:material
 
 /**
  * A pass-level scale over the grain the geometry declared, 0 to 1.
@@ -497,7 +507,7 @@ uniform int uFogEnabled;
  * imported model that declares nothing is drawn with the pass's own answer, and a scene
  * can dial a whole draw down without rebuilding its geometry.
  */
-uniform float uGrain;
+uniform float uGrain; // wgsl:material
 /*
  * The material's own relief: how strong, and how many bumps to a metre.
  *
@@ -506,7 +516,7 @@ uniform float uGrain;
  * between them, and the geometry carrying them is identical in all three cases. See
  * Renderer.setSurfaceRelief. x is the strength and y the bumps to a metre, in one row.
  */
-uniform vec2 uRelief;
+uniform vec2 uRelief; // wgsl:material
 /**
  * How hard the bound surface texture's own luminance turns the shading normal, 0 for not at all.
  *
@@ -529,7 +539,7 @@ uniform vec2 uRelief;
  * 0..1 like its neighbours for the same reason: this is an amplitude against a luminance
  * gradient, not a fraction of anything.
  */
-uniform float uTextureRelief;
+uniform float uTextureRelief; // wgsl:material
 
 /**
  * How much of the environment this material mirrors, 0 to 1.
@@ -664,8 +674,12 @@ uniform vec3 uProbeGridSets;
 /**
  * A world-space box that lights up regardless of time of day: its corners, and in the far corner's
  * w the gain — one row where a loose float was another (\`uniformVectorBudget.ts\`).
+ *
+ * **And in the near corner's w the frame the cutout dither's pattern is offset by**, for the same
+ * reason: a row the lit stage already pays for, holding a number the pass sets and no material does.
+ * See \`uCutout\`.
  */
-uniform vec3 uHighlightMin;
+uniform vec4 uHighlightMin;
 uniform vec4 uHighlightMax;
 
 /*