@driftengine/core 4.9.0 → 4.11.0

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/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/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,23 @@
  * 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: layered.ts. */
+  if (LAYERED && layered()) {
+    mat3 layeredFrame = tangentFrame(n, 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 +30,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/src/render/shaders/flat/overlay.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.
@@ -19,6 +20,7 @@ export function overlayGlsl(on: boolean): string {
 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); }
 `;
   }
@@ -26,7 +28,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() {
@@ -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/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,20 @@ 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
+/*
+ * 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;
 
 /**
@@ -154,7 +165,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 +179,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 +197,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 +244,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 +265,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 +281,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 +303,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 +390,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 +415,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
@@ -431,17 +446,30 @@ uniform float uOpacity;
  * 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;
+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;
 }
 
@@ -465,7 +493,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 +515,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 +525,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 +534,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 +557,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 +692,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;
 
 /*

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

@@ -0,0 +1,113 @@
+/**
+ * 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 function worldUvGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool WORLD_UVS = false;  // wgsl:override
+bool projected() { return false; }
+bool triplanar() { return false; }
+vec2 planarAt() { return vec2(0.0); }
+vec4 triplanarAlbedo(float layer) { return vec4(0.0); }
+vec3 triplanarOrm(float layer) { return vec3(0.0); }
+vec3 triplanarEmissive(float layer) { return vec3(0.0); }
+vec3 triplanarNormal(vec3 n, float layer) { return n; }
+`;
+  }
+  return /* glsl */ `
+/* Whether this program places maps by the world. Off but where a material has asked: worldUv.ts. */
+const bool WORLD_UVS = true;  // wgsl:override
+/* x: 0 the mesh's coordinates, 1 planar, 2 triplanar; y: repeats a metre; z: the blend's sharpness. */
+uniform vec4 uWorldUv; // wgsl:material
+
+bool projected() {
+  return uWorldUv.x > 0.5;
+}
+
+bool triplanar() {
+  return uWorldUv.x > 1.5;
+}
+
+/* The horizontal axes, scaled: u along +x, v along +z. */
+vec2 planarAt() {
+  return vWorldPos.xz * uWorldUv.y;
+}
+
+/* How much each plane counts: the geometric normal's components, sharpened, summing to one. */
+vec3 triplanarWeights() {
+  vec3 w = pow(abs(normalize(vNormal)), vec3(uWorldUv.z));
+  return w / max(w.x + w.y + w.z, 1e-5);
+}
+
+/*
+ * Each map read on the three planes and blended: a function a map rather than one taking the
+ * sampler, whose precision differs between them. Under a branch on a uniform, as every map read
+ * is, so the implicit level each read takes is legal: AGENTS.md 2026-08-07.
+ */
+vec4 triplanarAlbedo(float layer) {
+  vec3 w = triplanarWeights();
+  vec3 p = vWorldPos * uWorldUv.y;
+  return texture(uAlbedo, vec3(p.zy, layer)) * w.x + texture(uAlbedo, vec3(p.xz, layer)) * w.y +
+    texture(uAlbedo, vec3(p.xy, layer)) * w.z;
+}
+
+vec3 triplanarOrm(float layer) {
+  vec3 w = triplanarWeights();
+  vec3 p = vWorldPos * uWorldUv.y;
+  return texture(uOrmMap, vec3(p.zy, layer)).rgb * w.x +
+    texture(uOrmMap, vec3(p.xz, layer)).rgb * w.y + texture(uOrmMap, vec3(p.xy, layer)).rgb * w.z;
+}
+
+vec3 triplanarEmissive(float layer) {
+  vec3 w = triplanarWeights();
+  vec3 p = vWorldPos * uWorldUv.y;
+  return texture(uEmissiveMap, vec3(p.zy, layer)).rgb * w.x +
+    texture(uEmissiveMap, vec3(p.xz, layer)).rgb * w.y +
+    texture(uEmissiveMap, vec3(p.xy, layer)).rgb * w.z;
+}
+
+/* A tangent-space normal off the map, its z rebuilt where a two-channel map stored none. */
+vec3 triplanarTexel(vec2 at, float layer) {
+  vec3 t = texture(uNormalMap, vec3(at, layer)).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 normal map on three planes, by the whiteout blend: each plane's texel added to the surface
+ * normal swizzled into that plane, its z scaled by the normal's own, and swizzled back. Each plane's
+ * coordinates run along the same world axes from both sides, so a texel's axes are the world's and
+ * nothing is flipped; what that gives up is a texture mirrored on a plane's negative side.
+ */
+vec3 triplanarNormal(vec3 n, float layer) {
+  vec3 w = triplanarWeights();
+  vec3 p = vWorldPos * uWorldUv.y;
+  vec3 tx = triplanarTexel(p.zy, layer);
+  vec3 ty = triplanarTexel(p.xz, layer);
+  vec3 tz = triplanarTexel(p.xy, layer);
+  tx = vec3(tx.xy + n.zy, abs(tx.z) * n.x);
+  ty = vec3(ty.xy + n.xz, abs(ty.z) * n.y);
+  tz = vec3(tz.xy + n.xy, abs(tz.z) * n.z);
+  vec3 blended = normalize(tx.zyx * w.x + ty.xzy * w.y + tz.xyz * w.z);
+  return normalize(mix(n, blended, uNormalStrength));
+}
+`;
+}