@driftengine/core 4.8.7 → 4.10.0

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

@@ -25,6 +25,10 @@ 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;
+  /* A draw's dissolve cuts the surface away before anything is shaded: overlay.ts. */
+  if (SURFACE_OVERLAY) {
+    if (overlayCuts(surfaceAt.xy)) discard;
+  }
 
   /*
    * Surface colour and its coverage, resolved before anything else — including before it is
@@ -77,7 +81,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;
@@ -139,6 +143,11 @@ export const MAIN_GLSL = `void main() {
   }
 
   vec3 lit = albedo;
+  /* How much of the environment the frame shows here, and how a found reflection would land:
+     reflectionSurface.ts. None where nothing is reflected. */
+  vec3 reflectedProbe = vec3(0.0);
+  vec3 reflectedTint = vec3(0.0);
+  float reflectedRoughness = 1.0;
   /* Skin's diffuse, held before emission for the screen-space blur's own pass: models.ts. */
   vec3 diffuseAlone = vec3(0.0);
   /* The light arriving at a glass pane from behind it, gathered in each light loop below and added
@@ -186,7 +195,10 @@ export const MAIN_GLSL = `void main() {
      * right: a mipped colour image, sampled under uniform control flow, exactly as uAlbedo is
      * 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);
+    /* A draw's wrinkles, by region, over whatever the map made: overlay.ts. */
+    if (SURFACE_OVERLAY) n = overlayWrinkle(n, unmapped, surfaceAt.xy);
 
     /*
      * Microscopic relief: the surface's own texture, as a turn of the normal rather than a change
@@ -915,6 +927,15 @@ export const MAIN_GLSL = `void main() {
         environment * mix(vec3(1.0), albedo, metal),
         weight
       );
+      reflectedTint = mix(vec3(1.0), albedo, metal) * weight;
+      reflectedProbe = environment * reflectedTint;
+      reflectedRoughness = surfaceRoughness;
+    }
+    /* The reflection pass's surface half leaves here, before the lamps: reflectionSurface.ts. */
+    if (REFLECTION_SURFACE) {
+      reflectionSurfaceOut(reflectedProbe, reflectedTint, reflectedRoughness, ormOcclusion,
+        reflectionAir());
+      return;
     }
     /*
      * The sun's highlight, on top of whatever the surface reflects rather than underneath it —
@@ -1259,7 +1280,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.
@@ -1939,6 +1960,9 @@ export const MAIN_GLSL = `void main() {
       * mix(1.0, min(lightShade, sunShade), EMISSIVE_SHADOW_SHARE) * fxGlow;
     /* And a lit window's glow, which the scene's lit share already times: not gated on night. */
     lit += windowGlow * uEmission.x;
+    /* And a draw's overlay: its rim, its dissolve's band and the colour laid over. Not gated on the
+       night, as emission is: a glow the surface wears rather than light it gives off. overlay.ts. */
+    if (SURFACE_OVERLAY) lit += overlayGlow(surfaceAt.xy, n);
 
 #if NIGHT_EMISSIVE
     /*
@@ -1972,7 +1996,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;
     }
   }
@@ -2076,7 +2100,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,
@@ -2090,7 +2124,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
@@ -2137,6 +2171,10 @@ export const MAIN_GLSL = `void main() {
     return;
   }
 
+  /* WebGL2's frame writes the reflection maps itself, with the fog already reckoned above. */
+  if (REFLECTION_MAPS) {
+    reflectionSurfaceOut(reflectedProbe, reflectedTint, reflectedRoughness, ormOcclusion, fog);
+  }
   outColor = vec4(shaded, alpha);
 }
 `;

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

@@ -57,7 +57,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/dist/render/shaders/flat/overlay.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ *
+ * **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.
+ * Compiled out, the three calls are stubs and the fifteen vectors are not declared at all, which is
+ * what lets WebGL2 build a lit program without them on a device that has no room.
+ *
+ * **Images come from the atlas bound where the frame's refraction copy goes**, which an opaque draw
+ * never reads; a draw that refracts or is glass reads that copy there, so its overlay reads no image
+ * (`overlayImagesBound`). Each image is read by `textureLod` at level 0: several are reached under a
+ * branch on a per-pixel value, and the atlas carries no chain anyway.
+ */
+export declare function overlayGlsl(on: boolean): string;

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

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ *
+ * **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.
+ * Compiled out, the three calls are stubs and the fifteen vectors are not declared at all, which is
+ * what lets WebGL2 build a lit program without them on a device that has no room.
+ *
+ * **Images come from the atlas bound where the frame's refraction copy goes**, which an opaque draw
+ * never reads; a draw that refracts or is glass reads that copy there, so its overlay reads no image
+ * (`overlayImagesBound`). Each image is read by `textureLod` at level 0: several are reached under a
+ * branch on a per-pixel value, and the atlas carries no chain anyway.
+ */
+export function overlayGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool SURFACE_OVERLAY = false;  // wgsl:override
+bool overlayCuts(vec2 uv) { return false; }
+vec3 overlayWrinkle(vec3 mapped, vec3 unmapped, vec2 uv) { return mapped; }
+vec3 overlayGlow(vec2 uv, vec3 n) { return vec3(0.0); }
+`;
+    }
+    return /* glsl */ `
+/* 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]; // wgsl:material
+
+/* Whether the atlas is what the refraction slot holds: not where this draw refracts or is glass. */
+bool overlayImagesBound() {
+  return uSeeThrough.x <= 0.0 && uSeeThrough.z <= 0.0;
+}
+
+/* One image of the atlas at uv, repeated within its region; zero where the region has no size. */
+vec4 overlayImage(vec4 region, vec2 uv) {
+  if (region.x <= 0.0) return vec4(0.0);
+  return textureLod(uRefractScene, region.zw + fract(uv) * region.xy, 0.0);
+}
+
+/* The dissolve's noise at uv, and whether the draw dissolves at all: -1 where it does not. */
+float overlayDissolveNoise(vec2 uv) {
+  if (uOverlay[6].x <= 0.0 || uOverlay[7].z <= 0.0) return -1.0;
+  if (!overlayImagesBound()) return -1.0;
+  return overlayImage(uOverlay[6], uv * uOverlay[7].xy).r;
+}
+
+/* Whether the dissolve cuts this fragment away: where its noise is under the threshold, or all of
+   it at a threshold of 1. */
+bool overlayCuts(vec2 uv) {
+  float noise = overlayDissolveNoise(uv);
+  if (noise < 0.0) return false;
+  return noise < uOverlay[7].z || uOverlay[7].z >= 1.0;
+}
+
+/*
+ * The wrinkle normal blended into the mapped one by the two masks' channels times the six weights,
+ * in the frame the normal map is read in. **Under uniform control flow up to the frame**, which
+ * takes derivatives: every branch before it is on the overlay's numbers alone, and the weight a
+ * pixel takes is a mix rather than a branch.
+ */
+vec3 overlayWrinkle(vec3 mapped, vec3 unmapped, vec2 uv) {
+  if (uOverlay[10].x <= 0.0 || !overlayImagesBound()) return mapped;
+  mat3 tbn = tangentFrame(unmapped, vWorldPos, vUv.xy, vTangent, vHasTangents);
+  vec3 a = overlayImage(uOverlay[11], uv).rgb;
+  vec3 b = overlayImage(uOverlay[12], uv).rgb;
+  float weight = clamp(
+    dot(a, uOverlay[13].xyz) + dot(b, vec3(uOverlay[13].w, uOverlay[14].xy)), 0.0, 1.0);
+  vec3 wrinkle = overlayImage(uOverlay[10], uv).xyz * 2.0 - 1.0;
+  /* z rebuilt where none is stored, as normalMapped does: see normalMap.ts. */
+  wrinkle.z = wrinkle.z > 0.0 ? wrinkle.z : sqrt(max(0.0, 1.0 - dot(wrinkle.xy, wrinkle.xy)));
+  return normalize(mix(mapped, normalize(tbn * wrinkle), weight));
+}
+
+/*
+ * The rim's place on the screen, 0 to 1 up its height and its width in the same units: from view
+ * space and the projection's tangent, not from gl_FragCoord, whose y runs up on one backend and
+ * down on the other (the 2026-08-17 rule), and whose scale is a render target's, not the screen's.
+ */
+vec2 overlayScreen() {
+  vec4 eye = uView * vec4(vWorldPos, 1.0);
+  float depth = max(-eye.z, 1e-4) * uClusterFrustum.z;
+  return vec2(eye.x / depth + uClusterFrustum.w, eye.y / depth + 1.0) * 0.5;
+}
+
+/* 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. */
+vec3 overlayGlow(vec2 uv, vec3 n) {
+  vec3 glow = vec3(0.0);
+  float noise = overlayDissolveNoise(uv);
+  if (noise >= 0.0) {
+    float band = 1.0 - clamp((noise - uOverlay[7].z) / uOverlay[7].w, 0.0, 1.0);
+    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;
+  }
+  return glow;
+}
+`;
+}

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

@@ -13,7 +13,7 @@
  * picture and is its own change.
  */
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.js';
-import { OUTPUT_TRANSFORM_GLSL } from '../outputTransform.js';
+import { LIT_OUTPUT_TRANSFORM_GLSL } from '../outputTransform.js';
 import { LAMP_GLASS_GLSL } from './lampGlass.js';
 export const POINTSHADOW_GLSL = `/**
  * How much of one tap's occlusion survives its own penumbra.
@@ -341,9 +341,9 @@ float areaShadow(
 ${LAMP_GLASS_GLSL}
 #endif
 
-out vec4 outColor;
+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/dist/render/shaders/flat/preamble.js

@@ -108,9 +108,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;
 
 /**
@@ -141,7 +147,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.
  *
@@ -155,13 +161,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
@@ -169,7 +179,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) {
@@ -216,7 +226,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
@@ -237,7 +247,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.
  *
@@ -253,7 +263,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.
@@ -275,7 +285,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
 /*
@@ -362,7 +372,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.
@@ -387,7 +397,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
@@ -419,7 +429,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) {
@@ -452,7 +462,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
@@ -474,7 +484,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.
@@ -484,7 +494,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.
  *
@@ -493,7 +503,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.
  *
@@ -516,7 +526,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.
@@ -651,8 +661,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/dist/render/shaders/flat/reflectionSurface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What the lit stage leaves for a reflection traced in the frame: how much of the environment each
+ * pixel shows, and how a reflection found in the frame would land there instead. Read by the
+ * reflection pass (`screenSpaceReflection.ts`), which swaps the one for the other where its ray
+ * finds something.
+ *
+ * **The swap is exact because the lit stage's own blend is a mix**: `lit = mix(lit, environment ·
+ * tint, weight)` leaves `environment · tint · weight` of the probe in the frame, and a reflection
+ * found in the frame belongs there with the same tint and the same weight. So the frame gains
+ * `(found · tint − environment · tint) · weight` and nothing else moves: the diffuse the blend
+ * already took its share from keeps it. Both are carried the rest of the way the shaded colour
+ * goes — the occlusion, the water and the medium in front of the surface — so the swap lands in the
+ * frame's own units.
+ *
+ * **Two outputs beside the colour, written by every lit draw and kept only where a target is
+ * bound.** WebGL2 binds them during opaque lit draws alone; WebGPU's frame pass binds none, and a
+ * second pass replays the frame's opaque draws into them with `REFLECTION_SURFACE` on, which leaves
+ * before the lamps (`main`). What it gives up is a vector of arithmetic on every lit pixel whether
+ * or not anything reads it.
+ */
+export declare function reflectionSurfaceGlsl(maps: boolean): string;

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

@@ -0,0 +1,61 @@
+/**
+ * What the lit stage leaves for a reflection traced in the frame: how much of the environment each
+ * pixel shows, and how a reflection found in the frame would land there instead. Read by the
+ * reflection pass (`screenSpaceReflection.ts`), which swaps the one for the other where its ray
+ * finds something.
+ *
+ * **The swap is exact because the lit stage's own blend is a mix**: `lit = mix(lit, environment ·
+ * tint, weight)` leaves `environment · tint · weight` of the probe in the frame, and a reflection
+ * found in the frame belongs there with the same tint and the same weight. So the frame gains
+ * `(found · tint − environment · tint) · weight` and nothing else moves: the diffuse the blend
+ * already took its share from keeps it. Both are carried the rest of the way the shaded colour
+ * goes — the occlusion, the water and the medium in front of the surface — so the swap lands in the
+ * frame's own units.
+ *
+ * **Two outputs beside the colour, written by every lit draw and kept only where a target is
+ * bound.** WebGL2 binds them during opaque lit draws alone; WebGPU's frame pass binds none, and a
+ * second pass replays the frame's opaque draws into them with `REFLECTION_SURFACE` on, which leaves
+ * before the lamps (`main`). What it gives up is a vector of arithmetic on every lit pixel whether
+ * or not anything reads it.
+ */
+export function reflectionSurfaceGlsl(maps) {
+    return /* glsl */ `
+/*
+ * Whether this pipeline is the reflection pass's surface half: the frame's opaque draws again,
+ * against the depth they wrote, leaving the two outputs below and no light. Off in every other
+ * pipeline, and set from the key as skin's halves are. See reflectionSurface.ts.
+ */
+const bool REFLECTION_SURFACE = false;  // wgsl:override
+/*
+ * Whether the frame's own draws write the two outputs as well: WebGL2's arrangement, on where the
+ * frame's materials' reflections are, and off in every WebGPU pipeline, which replays the draws
+ * instead. A lit switch, so a program that does not write them carries nothing live across the
+ * lamps for them.
+ */
+const bool REFLECTION_MAPS = ${maps ? 'true' : 'false'};  // wgsl:override
+/* The environment as the frame shows it, and the surface's roughness in w. */
+layout(location = 1) out vec4 outReflectedProbe;
+/* What a reflection found in the frame is multiplied by to land where the environment did. */
+layout(location = 2) out vec4 outReflectedTint;
+
+/* How much of the surface the medium in front of it leaves: the fog block below's own measure. */
+float reflectionAir() {
+  return uFogEnabled != 0 ? mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y) : 0.0;
+}
+
+/*
+ * The two outputs, carried through what the shaded colour meets after the blend: its occlusion,
+ * the water, and the air, as \`main\` applies them. \`air\` is the fog the caller has already
+ * reckoned, so the frame's own draws pay for it once.
+ */
+void reflectionSurfaceOut(vec3 probe, vec3 tint, float roughness, float occlusion, float air) {
+  vec3 keep = vec3(occlusion * (1.0 - air));
+  if (uFogEnabled != 0) {
+    vec3 waterTransmission = vec3(0.42) + uUnderwaterColor * 2.0;
+    keep *= mix(vec3(1.0), waterTransmission, uUnderwaterFactor * 0.55);
+  }
+  outReflectedProbe = vec4(probe * keep, roughness);
+  outReflectedTint = vec4(tint * keep, 1.0);
+}
+`;
+}

package/dist/render/shaders/fog.d.ts

@@ -34,4 +34,4 @@
  * never needed the camera position in their fragment stage, and a block that declares
  * everything it uses can be pasted anywhere.
  */
-export declare const FOG_GLSL = "\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n";
+export declare const FOG_GLSL = "\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n";

package/dist/render/shaders/fog.js

@@ -84,11 +84,18 @@ float mediumFog(float dist, float pointY) {
     return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);
   }
 
+  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode
+  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density
+  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.
+  float start = min(uFogNear, dist);
+  float before = dist > 0.0 ? start / dist : 0.0;
   float t = (pointY - uFogEyeY) * uFogHeightFalloff;
+  float rest = t * (1.0 - before);
   // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than
   // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
-  float denom = abs(t) < 1e-4 ? 1e-4 : t;
-  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);
+  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;
+  float air =
+    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);
   if (uUnderwaterFactor <= 0.0) return air;
   // Water is its own medium and keeps its own curve, so crossing the surface
   // changes nothing about how the water column reads.

package/dist/render/shaders/fringe.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Chromatic aberration: a lens bending each colour by its own amount, so red and green land a
+ * little nearer the centre than blue toward the frame's edges.
+ *
+ * **Linear in wavelength, from an offset outward.** A simple lens's dispersion is close to linear
+ * in wavelength over the visible range, so red (611 nm) and green (549 nm) are pulled toward the
+ * centre by their distance from blue (464 nm), which is drawn where it is. Nothing moves inside
+ * `start` — a share of the half-frame, 0 at the centre — and the pull grows linearly past it,
+ * scaled so that the frame's edge takes the whole of `intensity`, which is a percentage.
+ *
+ * **What it gives up**: it re-reads the scene at the composite's first sample, so the camera's
+ * motion blur and the depth of field, which re-read the scene themselves, carry less of the fringe
+ * where they are strong. A pass of its own after both would carry it whole, at a full-frame read
+ * and write a frame. **What would make that wrong** is a game that blurs heavily and fringes
+ * heavily at once, where the colour edges would be seen to soften with the blur.
+ */
+/** How many floats `resolveFringe` fills: the red pull, the green pull, and where they begin. */
+export declare const FRINGE_FLOATS = 3;
+/**
+ * The fringe's three numbers, into `out`: how far red and green are pulled toward the centre at
+ * the frame's edge, as a share of the half-frame, and the start offset. `intensity` 0 or below is
+ * none; a start of 1 or more is none too, since nothing then lies past it. Not finite is none.
+ */
+export declare function resolveFringe(intensity: number, start: number, out: Float32Array): void;
+/**
+ * `withFringe(scene)`: the scene's colour with red and green read again where the lens put them.
+ * Reads `uScene` and `vUv`, which the including stage declares, and `uFringe`, which this declares.
+ */
+export declare const FRINGE_GLSL = "\n/** Red's and green's pull at the frame's edge, and where it begins: see shaders/fringe.ts. */\nuniform vec3 uFringe;\n\nvec3 withFringe(vec3 scene) {\n  if (uFringe.x <= 0.0) return scene;\n  vec2 lens = vUv * 2.0 - 1.0;\n  vec2 past = sign(lens) * clamp(abs(lens) - uFringe.z, 0.0, 1.0);\n  vec2 red = (lens - past * uFringe.x) * 0.5 + 0.5;\n  vec2 green = (lens - past * uFringe.y) * 0.5 + 0.5;\n  return vec3(textureLod(uScene, red, 0.0).r, textureLod(uScene, green, 0.0).g, scene.b);\n}\n";