@driftengine/core 4.8.6 → 4.9.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
@@ -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
@@ -542,7 +554,7 @@ export const MAIN_GLSL = `void main() {
      * specularLobe's header argues for at length.
      */
     float sunVoH = max(dot(normalize(uCameraPos - vWorldPos), halfway), 0.0);
-    vec3 sunSpec = mix(specColor, vec3(1.0), pow(1.0 - sunVoH, 5.0) * metal);
+    vec3 sunSpec = highlightTint(specColor, sunVoH, metal);
     /*
      * **Held back until after the environment blend, because that blend is a mix and would
      * otherwise erase this.**
@@ -561,8 +573,12 @@ export const MAIN_GLSL = `void main() {
      * Zero for the whole world that carries no specular attribute and no metalness, exactly as
      * before: \`sunSpec\` is \`vec3(vSpecular)\` at metal 0 and \`vSpecular\` defaults to 0.
      */
-    vec3 sunHighlight =
-      sunColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade * sunFacing;
+    /* GGX's own where the surface asks (\`physicalSpecular\`): the sun is a point, so nothing widens it. */
+    float sunNdh = max(dot(n, halfway), 0.0);
+    float sunLobe = physicalSpecular()
+      ? physicalLobe(sunNdh, ndl, dot(n, normalize(uCameraPos - vWorldPos)), surfaceRoughness, 0.0, 1.0)
+      : specularLobe(sunNdh, surfaceRoughness);
+    vec3 sunHighlight = sunColor * sunLobe * sunSpec * sunShade * sunFacing;
     if (modelled) sunHighlight = sunModelSpecular;
     /*
      * The dielectric's share goes in here, where it has always gone, so the environment blend
@@ -911,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 —
@@ -1066,6 +1091,10 @@ export const MAIN_GLSL = `void main() {
       float cookie;
       /* The light's lighting channels, a mask: 1 unless it names others. See \`uLightIesAxis\`. */
       float lightChannels = 1.0;
+      /* The light's own falloff exponent, or 0 for the frame's falloff. See \`uLightCone\`. */
+      float lightExponent = 0.0;
+      /* A clustered rectangle's barn doors: their cosine and length, none at 0. See \`areaBarnDoors\`. */
+      vec2 areaDoors = vec2(0.0);
       /*
        * **A rectangle in the froxel table** — one past the fixed arm's \`maxAreaLights\` — which
        * its record says with a negative radius, its reach negated. Its fields come out of the
@@ -1116,8 +1145,8 @@ export const MAIN_GLSL = `void main() {
       lightWeight = sizeAndWeight.y;
       /*
        * **The fixture, read only for a light that has one.** What a plain light's record holds in
-       * the last three texels is exactly these values, so a light carrying no shadow slot, cone,
-       * profile or cookie shades the same whether they are read or assumed, and at heavy overlap
+       * the last four texels is exactly these values, so a light carrying no shadow slot, cone,
+       * profile, cookie, channels or falloff of its own shades the same whether they are read or assumed, and at heavy overlap
        * reading them was a third of the pass. A branch on a value from a texture around
        * \`texelFetch\` is not the 2026-08-07 case: an integer fetch takes no derivative.
        *
@@ -1137,6 +1166,7 @@ export const MAIN_GLSL = `void main() {
           uvec4 rec2 = clusterTexel(record + 2);
           uvec4 rec3 = clusterTexel(record + 3);
           uvec4 rec4 = clusterTexel(record + 4);
+          uvec4 rec5 = clusterTexel(record + 5);
           shadowSlot = clusteredArea ? -1 : int(uintBitsToFloat(rec2.x));
           areaTwoSided = uintBitsToFloat(rec2.x);
           lightDir = vec3(
@@ -1149,6 +1179,8 @@ export const MAIN_GLSL = `void main() {
           iesAxis = vec3(
             uintBitsToFloat(rec4.x), uintBitsToFloat(rec4.y), uintBitsToFloat(rec4.z));
           lightChannels = uintBitsToFloat(rec4.w);
+          lightExponent = uintBitsToFloat(rec5.x);
+          areaDoors = vec2(uintBitsToFloat(rec5.y), uintBitsToFloat(rec5.z));
         }
       }
       } else {
@@ -1161,7 +1193,8 @@ export const MAIN_GLSL = `void main() {
       lightWeight = uLightWeight[i];
       shadowSlot = i;
       lightDir = uLightDir[i];
-      lightCone = uLightCone[i];
+      lightCone = uLightCone[i].xy;
+      lightExponent = uLightCone[i].z;
       iesProfile = uLightIesProfile[i];
       iesAxis = uLightIesAxis[i].xyz;
       lightChannels = uLightIesAxis[i].w;
@@ -1187,12 +1220,15 @@ export const MAIN_GLSL = `void main() {
        * froxel it is binned into has no edge in the picture.
        */
       if (clusteredArea) {
-        float areaForm = areaSignedForm(n, lightPos, lightDir, iesAxis, lightCone);
+        vec3 seenCentre = lightPos;
+        vec2 seenHalf = lightCone;
+        if (!areaBarnDoors(seenCentre, lightDir, iesAxis, seenHalf, areaDoors)) continue;
+        float areaForm = areaSignedForm(n, seenCentre, lightDir, iesAxis, seenHalf);
         float areaWindow = clamp(1.0 - pow(length(lightPos - vWorldPos) / max(lightRadius, 1e-4), 4.0), 0.0, 1.0);
         areaForm = mix(max(0.0, areaForm), abs(areaForm), areaTwoSided);
         if (areaForm > 0.0) {
           areaLightAdd(
-            lightPos, lightDir, iesAxis, lightCone, lightColor * (areaWindow * areaWindow), areaForm,
+            seenCentre, lightDir, iesAxis, seenHalf, lightColor * (areaWindow * areaWindow), areaForm,
             1.0, vec3(1.0), n, albedo, metal, specColor, surfaceRoughness, modelled,
             lampOpen, lampShadowed
           );
@@ -1243,7 +1279,16 @@ export const MAIN_GLSL = `void main() {
        * same way three.js windows its own, so the light still ends where it says it does.
        */
       float falloff;
-      if (uLightFalloff == 1) {
+      /*
+       * **A light may name its own falloff, and then it is Unreal's 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.
+       */
+      if (lightExponent > 0.0) {
+        float reach = dist / max(lightRadius, 1e-4);
+        falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), lightExponent);
+      } else if (uLightFalloff == 1) {
         float window = clamp(1.0 - pow(dist / max(lightRadius, 1e-4), 4.0), 0.0, 1.0);
         falloff = window * window / max(dist * dist, 0.01);
       } else {
@@ -1506,7 +1551,11 @@ export const MAIN_GLSL = `void main() {
         photometric = mix(1.0, iesGain, step(0.0, iesProfile));
       }
 
-      float shape = (uLightFalloff == 1 ? falloff : falloff * falloff) * coneFalloff * photometric;
+      /* A light's own exponent already is its whole curve; the frame's smooth rule squares its own. */
+      float shape =
+        (lightExponent > 0.0 || uLightFalloff == 1 ? falloff : falloff * falloff) *
+        coneFalloff *
+        photometric;
       glassGlow += lightColor * backNdl * shape * lightWeight * shaded * lampGlass;
       if (ndl <= 0.0 && !modelledBehind) continue;
       /*
@@ -1583,16 +1632,15 @@ export const MAIN_GLSL = `void main() {
       if (vSpecular > 0.0 || metal > 0.0) {
         vec3 toEyeLamp = normalize(uCameraPos - vWorldPos);
         vec3 lampHalfway = normalize(toLight / max(dist, 1e-4) + toEyeLamp);
-        /* The same grazing whitening the sun's highlight takes, and zero at metal 0. */
-        vec3 lampSpec = mix(
-          specColor,
-          vec3(1.0),
-          pow(1.0 - max(dot(toEyeLamp, lampHalfway), 0.0), 5.0) * metal
-        );
+        /* The same grazing whitening the sun's highlight takes, and zero at metal 0 for the look. */
+        vec3 lampSpec = highlightTint(specColor, max(dot(toEyeLamp, lampHalfway), 0.0), metal);
+        /* The look's lobe, or GGX's own where the surface asks for it: see \`physicalLobe\`. */
+        float lampNdh = max(dot(n, lampHalfway), 0.0);
+        float lampLobe = physicalSpecular()
+          ? physicalLobe(lampNdh, ndl, dot(n, toEyeLamp), surfaceRoughness, lightSourceRadius, dist)
+          : sphereLobe(lampNdh, surfaceRoughness, lightSourceRadius, dist);
         /* Held back with the diffuse half, and shadowed by the same term it always was. */
-        vec3 lampHighlight =
-          lightColor * sphereLobe(max(dot(n, lampHalfway), 0.0), surfaceRoughness, lightSourceRadius, dist)
-          * lampSpec * shape * lightWeight;
+        vec3 lampHighlight = lightColor * lampLobe * lampSpec * shape * lightWeight;
         lampOpen += lampHighlight;
         lampShadowed += lampHighlight * shaded * lampGlass;
       }
@@ -1636,10 +1684,18 @@ export const MAIN_GLSL = `void main() {
       vec3 centre = uAreaLightPos[a];
       vec3 right = uAreaLightRight[a];
       vec3 up = uAreaLightUp[a];
-      vec2 halfSize = uAreaLightSize[a];
+      vec2 halfSize = uAreaLightSize[a].xy;
+      /*
+       * **The part of the rectangle this fragment sees past its barn doors** (\`areaBarnDoors\`),
+       * which its light and highlight come from. Its shadow keeps the whole rectangle's centre and
+       * size below, because that is what its map was baked from.
+       */
+      vec3 seenCentre = centre;
+      vec2 seenHalf = halfSize;
+      if (!areaBarnDoors(seenCentre, right, up, seenHalf, uAreaLightSize[a].zw)) continue;
 
       /* The form factor and its sign, which is the sidedness: see \`areaSignedForm\`. */
-      float signedForm = areaSignedForm(n, centre, right, up, halfSize);
+      float signedForm = areaSignedForm(n, seenCentre, right, up, seenHalf);
       float form = mix(max(0.0, signedForm), abs(signedForm), uAreaLightTwoSided[a]);
       /* The form factor is linear in the normal, so the one seen from behind is its negation. */
       float backForm = glassTransmission > 0.0
@@ -1756,7 +1812,7 @@ export const MAIN_GLSL = `void main() {
       if (form <= 0.0) continue;
       /* The diffuse, the model's answer or the lobe integrated over the rectangle: see areaLight.ts. */
       areaLightAdd(
-        centre, right, up, halfSize, uAreaLightColor[a], form, areaOccl, areaGlass,
+        seenCentre, right, up, seenHalf, uAreaLightColor[a], form, areaOccl, areaGlass,
         n, albedo, metal, specColor, surfaceRoughness, modelled, lampOpen, lampShadowed
       );
     }
@@ -1904,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
     /*
@@ -2102,6 +2161,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.d.ts

@@ -1,6 +1,9 @@
 import type { SurfaceModelKind } from '../../surfaceModel.ts';
-/** The models' whole chunk, at depth zero before `main`: see `flatFrag`. */
-export declare const MODELS_GLSL: string;
+/**
+ * The models' whole chunk, at depth zero before `main`: see `flatFrag`. `physicalSpecular` is the
+ * \`PHYSICAL_SPECULAR\` lit switch's value, written in as \`litSwitchesGlsl\` writes the others.
+ */
+export declare function modelsGlsl(physicalSpecular: boolean): string;
 /**
  * Which half of a skin a lit pipeline draws under `skinScattering: 'screen-space'`: the whole
  * surface (every other pipeline), the frame's half without its diffuse, the diffuse's light alone

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

@@ -46,6 +46,12 @@ const bool SKIN_ALBEDO = false;  // wgsl:override
  * Declared after skin's halves so that every switch before it keeps the id it shipped with.
  */
 const bool MODEL_LIGHTMAP = false;  // wgsl:override
+/*
+ * Not a model either: whether this program carries GGX's own highlight for a material that asks
+ * (\`SurfaceMaterial.physicalSpecular\`). A lit switch, off until a material first asks and then
+ * on for good, as \`litSwitchesGlsl\`'s are; declared last so every switch before it keeps its id.
+ */
+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
@@ -124,15 +130,57 @@ float smithMasking(float ndl, float ndv, float alpha) {
   );
 }
 
+/*
+ * Whether this surface's highlights are GGX's own (\`SurfaceMaterial.physicalSpecular\`), from the
+ * lane the standard, lightmap and anisotropic models leave free (\`packModel\`). Skin, hair and the
+ * eye shade their own highlights, and the eye's axis holds that lane, so they are never asked. The
+ * lit switch first, so a program built before any material asked carries none of it.
+ */
+bool physicalSpecular() {
+  if (PHYSICAL_SPECULAR) {
+    if (MODEL_HAIR) return false;
+    if (MODEL_SKIN) return false;
+    if (MODEL_EYE) return false;
+    return uModelParams[1].z > 0.5;
+  }
+  return false;
+}
+
+/**
+ * GGX as a BRDF in this engine's light units, \`π · D · Vis · N·L\` with Fresnel left to the caller:
+ * the term skin's and the eye's highlights are, for a surface that asks for it. Its peak is
+ * \`1 / (4 α²)\` of the light head-on, against the look's 1. A lamp's size widens α as \`sphereLobe\`
+ * widens it, and a normalised distribution keeps its energy as it widens.
+ */
+float physicalLobe(float ndh, float ndl, float ndv, float roughness, float sourceRadius, float dist) {
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float alpha = min(max(roughness * roughness, MIN_LOBE_ALPHA) + grow, 1.0);
+  return 3.14159265 * ggxLobe(ndh, alpha) * smithMasking(ndl, max(ndv, 1e-4), alpha) * ndl;
+}
+
+/**
+ * A highlight's colour: Schlick's Fresnel from the surface's reflectance toward white at a grazing
+ * \`voh\`. On a metal alone for the look, whose dielectric attribute is a strength rather than a
+ * reflectance; on every surface where the highlight is physical, whose attribute is its F0 — but
+ * one reflecting nothing head-on keeps nothing, as the lamps' gate on that attribute has it.
+ */
+vec3 highlightTint(vec3 specColor, float voh, float metal) {
+  float edge = pow(1.0 - voh, 5.0);
+  bool reflects = max(max(specColor.r, specColor.g), specColor.b) > 0.0;
+  return mix(specColor, vec3(1.0), physicalSpecular() && reflects ? edge : edge * metal);
+}
+
 /** The standard model's answer to one light, which a model falls back to for what it does not change. */
 void standardLight(vec3 l, float sourceRadius, float dist) {
   float ndl = max(dot(mNormal, l), 0.0);
   vec3 h = normalize(l + mToEye);
   float ndh = max(dot(mNormal, h), 0.0);
-  float lobe = sourceRadius > 0.0
-    ? sphereLobe(ndh, mRoughness, sourceRadius, dist)
-    : specularLobe(ndh, mRoughness);
-  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);
+  float lobe = physicalSpecular()
+    ? physicalLobe(ndh, ndl, dot(mNormal, mToEye), mRoughness, sourceRadius, dist)
+    : sourceRadius > 0.0
+      ? sphereLobe(ndh, mRoughness, sourceRadius, dist)
+      : specularLobe(ndh, mRoughness);
+  vec3 tint = highlightTint(mSpecColor, max(dot(mToEye, h), 0.0), mMetal);
   mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
   mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);
 }
@@ -250,20 +298,51 @@ vec3 modelEnvironment(vec3 environment) {
   return environment;
 }
 
+/**
+ * One texel of a page's irradiance layer: its four bytes put back into the rgb9e5 word they are,
+ * lowest first, and decoded — three 9-bit mantissas over the exponent in the top five bits.
+ */
+vec3 bakedIrradianceAt(ivec3 texel) {
+  uvec4 bytes = uvec4(texelFetch(uModelMap, texel, 0) * 255.0 + 0.5);
+  uint word = bytes.x | (bytes.y << 8u) | (bytes.z << 16u) | (bytes.w << 24u);
+  float scale = exp2(float(word >> 27u) - 24.0);
+  return vec3(float(word & 511u), float((word >> 9u) & 511u), float((word >> 18u) & 511u)) * scale;
+}
+
 /**
  * What a baked page adds to this surface's diffuse: nothing in any pipeline but a lightmapped one,
  * nor in one whose page is missing. The page's two layers at the surface's second coordinates, which
  * ride the grain and relief lanes as \`-1 - uv\` (lightmap.ts) and are placed by the material's
  * region: the irradiance, and the first-order harmonic its direction is, answered by the shading
  * normal.
- * **An explicit level**, because the page has one and nothing here needs a derivative.
+ *
+ * **Filtered here, because the page cannot be filtered as it is stored**: the irradiance is a
+ * shared-exponent word in four bytes, and a blend of two words is not the blend of their colours.
+ * So the four texels around the sample are fetched, decoded and blended, as a bilinear sampler
+ * clamped at the page's edge would. Fetches need no derivative, so the branch costs nothing there.
  */
 vec3 modelBaked(vec3 n, vec3 albedo, float metal) {
   if (MODEL_LIGHTMAP) {
     if (uModelParams[1].w <= 0.0) return vec3(0.0);
     vec2 at = (vec2(-1.0) - vec2(vGrain, vRelief)) * uModelParams[0].xy + uModelParams[0].zw;
-    vec3 irradiance = textureLod(uModelMap, vec3(at, 0.0), 0.0).rgb;
-    vec4 d = textureLod(uModelMap, vec3(at, 1.0), 0.0) * 2.0 - 1.0;
+    ivec2 size = textureSize(uModelMap, 0).xy;
+    vec2 texel = at * vec2(size) - 0.5;
+    vec2 corner = floor(texel);
+    vec2 f = texel - corner;
+    ivec2 last = size - 1;
+    ivec2 lo = clamp(ivec2(corner), ivec2(0), last);
+    ivec2 hi = clamp(ivec2(corner) + 1, ivec2(0), last);
+    vec3 irradiance = mix(
+      mix(bakedIrradianceAt(ivec3(lo.x, lo.y, 0)), bakedIrradianceAt(ivec3(hi.x, lo.y, 0)), f.x),
+      mix(bakedIrradianceAt(ivec3(lo.x, hi.y, 0)), bakedIrradianceAt(ivec3(hi.x, hi.y, 0)), f.x),
+      f.y
+    );
+    vec4 direction = mix(
+      mix(texelFetch(uModelMap, ivec3(lo.x, lo.y, 1), 0), texelFetch(uModelMap, ivec3(hi.x, lo.y, 1), 0), f.x),
+      mix(texelFetch(uModelMap, ivec3(lo.x, hi.y, 1), 0), texelFetch(uModelMap, ivec3(hi.x, hi.y, 1), 0), f.x),
+      f.y
+    );
+    vec4 d = direction * 2.0 - 1.0;
     return albedo * (1.0 - metal) * irradiance * max(dot(d.xyz, n) + d.w, 0.0);
   }
   return vec3(0.0);
@@ -285,15 +364,20 @@ float modelReflectance(float standard) {
   return standard;
 }
 `;
-/** The models' whole chunk, at depth zero before `main`: see `flatFrag`. */
-export const MODELS_GLSL = [
-    MODELS_HEAD,
-    ANISOTROPIC_GLSL,
-    HAIR_GLSL,
-    SKIN_GLSL,
-    EYE_GLSL,
-    MODELS_DISPATCH,
-].join('\n');
+/**
+ * The models' whole chunk, at depth zero before `main`: see `flatFrag`. `physicalSpecular` is the
+ * \`PHYSICAL_SPECULAR\` lit switch's value, written in as \`litSwitchesGlsl\` writes the others.
+ */
+export function modelsGlsl(physicalSpecular) {
+    return [
+        MODELS_HEAD.replace('PHYSICAL_SPECULAR_ON', physicalSpecular ? 'true' : 'false'),
+        ANISOTROPIC_GLSL,
+        HAIR_GLSL,
+        SKIN_GLSL,
+        EYE_GLSL,
+        MODELS_DISPATCH,
+    ].join('\n');
+}
 /** The constant each half of a skin turns on. See `SkinHalf`. */
 export const SKIN_HALF_SWITCH = {
     scene: 'SKIN_SCREEN',

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];
+
+/* 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

@@ -341,7 +341,7 @@ float areaShadow(
 ${LAMP_GLASS_GLSL}
 #endif
 
-out vec4 outColor;
+layout(location = 0) out vec4 outColor;
 
 ${OUTPUT_TRANSFORM_GLSL}
 

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

@@ -771,13 +771,15 @@ uniform float uLightWeight[MAX_LIGHTS];
  */
 uniform vec3 uLightDir[MAX_LIGHTS];
 /**
- * The cosine of each light's inner cone angle, then of its outer.
+ * The cosine of each light's inner cone angle, then of its outer, and in z the light's own falloff
+ * exponent, 0 for the frame's falloff (\`PointLightSource.falloffExponent\`): a \`vec2\` array cost
+ * a whole row a light anyway, so the exponent spends no row of its own.
  *
  * A light with no cone carries -1 and -2, which makes \`smoothstep(outer, inner, dot)\` exactly 1
  * for every direction on the sphere. See \`POINT_LIGHT_COS_OUTER\`: the pair is chosen so a point
  * light collapses to the arithmetic it had rather than to something very close to it.
  */
-uniform vec2 uLightCone[MAX_LIGHTS];
+uniform vec4 uLightCone[MAX_LIGHTS];
 /**
  * Which row of the photometric atlas each light uses, or a negative index for none.
  *
@@ -882,7 +884,12 @@ uniform vec3 uAreaLightColor[MAX_AREA_LIGHTS];
 /** The rectangle's in-plane axes, unit length, and its half extents along each. */
 uniform vec3 uAreaLightRight[MAX_AREA_LIGHTS];
 uniform vec3 uAreaLightUp[MAX_AREA_LIGHTS];
-uniform vec2 uAreaLightSize[MAX_AREA_LIGHTS];
+/*
+ * Each rectangle's half extents, and in zw its barn doors: the cosine of their angle from its normal
+ * and their length, 0 for none (\`areaBarnDoors\`). A \`vec2\` array costs a whole row a rectangle
+ * anyway, so the doors spend no row of their own.
+ */
+uniform vec4 uAreaLightSize[MAX_AREA_LIGHTS];
 /**
  * Whether the rectangle emits from both faces, 1 or 0.
  *

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;