@driftengine/core 4.8.3 → 4.8.5

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

@@ -3,15 +3,18 @@ import { OCTAHEDRAL_GLSL } from '../octahedral.ts';
 import { PROBEGRID_GLSL } from './probeGrid.ts';
 import { TANGENT_FRAME_GLSL } from '../tangentFrame.ts';
 import { CUTOUT_COVERAGE_GLSL } from '../cutoutCoverage.ts';
+import { CUTOUT_DITHER_GLSL } from '../../cutoutDither.ts';
 import { preambleGlsl } from './preamble.ts';
 import { LOBES_GLSL } from './lobes.ts';
 import { POINTSHADOW_GLSL } from './pointShadow.ts';
 import { DIRECTIONALSHADOW_GLSL } from './directionalShadow.ts';
 import { glassTintGlsl, litSwitchesGlsl } from './glassTint.ts';
 import { MORPH_GLSL } from '../morph.ts';
+import { CLOTH_BINDING_GLSL } from '../clothBinding.ts';
 import { SKINNING_GLSL } from '../skinning.ts';
 import { SURFACE_GLSL } from './surface.ts';
 import { MAIN_GLSL } from './main.ts';
+import { MODELS_GLSL } from './models.ts';
 import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
@@ -145,6 +148,10 @@ ${CHANNEL_BEND}
 #if MORPHED
 ${MORPH_GLSL}
 #endif
+#if SKINNED
+/* Samplers and a constant alone, so no field of the vertex block moves. See clothBinding.ts. */
+${CLOTH_BINDING_GLSL}
+#endif
 
 out vec3 vNormal;
 out vec3 vColor;
@@ -218,9 +225,11 @@ void main() {
   mat4 skin = skinMatrix();
   vec4 local = skin * vec4(basePosition, 1.0);
   vec3 localNormal = mat3(skin) * aNormal;
+  vec3 localTangent = mat3(skin) * aTangent.xyz;
 #else
   vec4 local = vec4(basePosition, 1.0);
   vec3 localNormal = aNormal;
+  vec3 localTangent = aTangent.xyz;
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
@@ -241,9 +250,31 @@ void main() {
   vec3 bent = channelBend(world.xyz, aChannel.x);
 #endif
   world = vec4(bent, world.w);
-  vWorldPos = world.xyz;
   // Rotation/translation-only models (our case): mat3 is a valid normal matrix.
   vec3 worldNormal = mat3(model) * localNormal;
+  /*
+   * **The tangent turns as the normal does**, because the fragment stage crosses it with the
+   * world-space normal to build its frame. It went out in the mesh's own space until 4.8.4, which
+   * is world space only for a mesh that is moved and never turned: a turned or skinned mesh lit its
+   * normal map, and anything reading a direction along its surface, from the wrong side.
+   */
+  vec3 worldTangent = mat3(model) * localTangent;
+#if SKINNED
+  /*
+   * **Toward the cloth, after the skeleton and the bend.** The simulation already swings with the
+   * wind it was given, so the bend moves only the skinned part; the weight painted per vertex says
+   * how much of the cloth's place and turn the vertex takes. See clothBinding.ts.
+   */
+  if (CLOTH_BOUND) {
+    vec3 clothPosition;
+    mat3 turn;
+    float follow = clothPlace(clothPosition, turn);
+    world = vec4(mix(world.xyz, clothPosition, follow), world.w);
+    worldNormal = normalize(mix(worldNormal, turn * aNormal, follow));
+    worldTangent = mix(worldTangent, turn * aTangent.xyz, follow);
+  }
+#endif
+  vWorldPos = world.xyz;
   vNormal = worldNormal;
   vLightPos = uLightViewProj * world;
   vColor = aColor * tint;
@@ -254,7 +285,7 @@ void main() {
   vRoughness = aRoughness;
   vGrain = aGrain;
   vRelief = aRelief;
-  vTangent = aTangent;
+  vTangent = vec4(worldTangent, aTangent.w);
 #if INSTANCED
   /* No channel on this path; the neutral values are what every mesh read before it existed. */
   vSkyDirect = 1.0;
@@ -534,8 +565,11 @@ export function flatFrag(options: FlatShaderOptions): string {
       TANGENT_FRAME_GLSL,
       /* Unconditional for the same reason, and called only where a cutoff was asked for. */
       CUTOUT_COVERAGE_GLSL,
+      CUTOUT_DITHER_GLSL,
       DRIFT_LIGHT_GLSL,
       SURFACE_EFFECTS_GLSL,
+      /* Depth zero and after the tangent frame and the lobes it calls; see models.ts. */
+      MODELS_GLSL,
       MAIN_GLSL,
     ].join('\n'),
     {

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

@@ -21,6 +21,8 @@ export const MAIN_GLSL = `void main() {
     fxLoad(int(surfaceAt.z));
     surfaceAt = fxAnimate(surfaceAt);
   }
+  /* An eye's iris, moved by its cornea before any map reads it: models.ts. */
+  surfaceAt = modelSurfaceAt(surfaceAt);
   vec2 fxDx = dFdx(surfaceAt.xy);
   vec2 fxDy = dFdy(surfaceAt.xy);
   if (uWriteMode.y != 0.0 && !ditherKeeps(uWriteMode.y)) discard;
@@ -56,18 +58,35 @@ export const MAIN_GLSL = `void main() {
    * rectangle of haze with a picture in it, rather than a picture.
    */
   float coverage = 1.0;
-  if (uAlbedoEnabled != 0) {
+  if (uMaterialFlags.x != 0) {
     vec4 texel = texture(uAlbedo, surfaceAt);
     // Discarded before anything else is computed: a thrown-away fragment should not pay
     // for the lighting it will never contribute to. The test credits alpha for the mip level
     // it samples, so a needle averaged thin down the chain is not lost; see cutoutCoverage.ts.
     // Behind a branch on a uniform, so a material with no cutoff pays nothing for it.
-    if (uAlbedoCutout > 0.0) {
+    float kept = texel.a;
+    if (uCutout.x > 0.0) {
       float tested = cutoutAlpha(texel.a, vUv.xy * vec2(textureSize(uAlbedo, 0).xy));
-      if (tested < uAlbedoCutout) discard;
+      if (uCutout.y == 0.0) {
+        if (tested < uCutout.x) discard;
+      } else {
+        /*
+         * A dithered edge: the pixel is kept by the share of it the texture covers. Under a
+         * temporal resolve the test is against noise that moves every frame, and a kept pixel is
+         * whole; multisampled, the share is the alpha the GPU turns into coverage. See
+         * cutoutDither.ts.
+         */
+        float share = cutoutShare(tested, uCutout.x);
+        if (uCutout.y == 1.0) {
+          if (!cutoutKeeps(share, gl_FragCoord.xy, uCutout.z)) discard;
+          kept = 1.0;
+        } else {
+          kept = share;
+        }
+      }
     }
     albedo *= texel.rgb;
-    coverage = texel.a;
+    coverage = kept;
   }
 
   /*
@@ -91,7 +110,7 @@ export const MAIN_GLSL = `void main() {
   float ormOcclusion = 1.0;
   float ormRoughness = vRoughness;
   float metal = 0.0;
-  if (uOrmEnabled != 0) {
+  if (uMaterialFlags.y != 0) {
     vec3 t = texture(uOrmMap, surfaceAt).rgb;
     ormOcclusion = mix(1.0, t.r, uOrmScale.r);
     ormRoughness = clamp(t.g * uOrmScale.g, 0.0, 1.0);
@@ -121,6 +140,8 @@ export const MAIN_GLSL = `void main() {
   }
 
   vec3 lit = albedo;
+  /* 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
      over the see-through at the end. Stays zero for anything that is not glass. See glass.ts. */
   vec3 glassGlow = vec3(0.0);
@@ -143,7 +164,7 @@ export const MAIN_GLSL = `void main() {
      * Taken from the stored normal alone, a pane seen from behind glowed with the light on the
      * eye's side and not with the sun shining through it.
      */
-    bool backFace = (uDoubleSided != 0 || glassTransmission > 0.0) && dot(n, uCameraPos - vWorldPos) < 0.0;
+    bool backFace = (uMaterialFlags.w != 0 || glassTransmission > 0.0) && dot(n, uCameraPos - vWorldPos) < 0.0;
     /*
      * The authored normal, before either relief perturbs it.
      *
@@ -162,6 +183,15 @@ export const MAIN_GLSL = `void main() {
      */
     if (uNormalStrength > 0.0) {
       vec3 mapped = texture(uNormalMap, surfaceAt).xyz * 2.0 - 1.0;
+      /*
+       * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a
+       * stored z at or below zero is never a real one: it is a two-channel map, BC5, whose blue a
+       * device samples as zero and which arrives here as -1. Every map baked from BC5 to PNG before
+       * 4.8.4 carried the same zero. A select rather than a flag: no uniform to bind, no material
+       * that has to say what format it holds, and continuous at the boundary, since a unit texel
+       * 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);
       n = normalize(mix(n, normalize(tbn * mapped), uNormalStrength));
     }
@@ -268,7 +298,7 @@ export const MAIN_GLSL = `void main() {
      * and normalized: dividing the gradient by \`det\` instead would blow up on a fragment where
      * the surface is edge-on and the quad's footprint collapses.
      */
-    if (uAlbedoEnabled != 0 && uTextureRelief != 0.0) {
+    if (uMaterialFlags.x != 0 && uTextureRelief != 0.0) {
       /*
        * **A centred difference, not three.js's forward one, and that is what makes the two
        * backends agree.** WebGL2's framebuffer counts y upward and WebGPU's counts it downward,
@@ -331,6 +361,14 @@ export const MAIN_GLSL = `void main() {
      * across the fold of every curtain.
      */
     if (backFace) n = -n;
+    /*
+     * A model's surface, gathered once, on a branch on the switches alone (models.ts) — and whether
+     * there is one, asked once: every site below is a branch on these two, which a pipeline with no
+     * model folds away, and each extra call was a copy of its plumbing in all sixteen permutations.
+     */
+    bool modelled = modelOn();
+    bool modelledBehind = modelSeesBehind();
+    if (modelled) modelSurface(n, albedo, surfaceRoughness, metal, surfaceAt);
 
     /*
      * One dot product, used twice: ndl is the lit side and its negative is the night side below.
@@ -444,7 +482,19 @@ export const MAIN_GLSL = `void main() {
      * smallest change available in a shader with a documented history of shared subexpressions
      * rounding differently when their neighbours move. See the night-emissive term.
      */
-    lit = albedo * (ambient + sunColor * direct * (1.0 - metal));
+    /*
+     * A model answers the sun itself, and is shadowed as it says (models.ts). The standard line
+     * stands as it was, so a pipeline with no model compiles to exactly the arithmetic before.
+     */
+    vec3 sunModelSpecular = vec3(0.0);
+    if (modelled) {
+      modelLight(uDirectionalDir, 0.0, 0.0);
+      float sunModelFacing = modelledBehind ? 1.0 : sunFacing;
+      lit = modelAmbient(ambient) + sunColor * mDiffuse * modelShade(sunShade) * sunModelFacing;
+      sunModelSpecular = mSpecular * sunColor * sunShade * sunModelFacing;
+    } else {
+      lit = albedo * (ambient + sunColor * direct * (1.0 - metal));
+    }
 
     /*
      * A sun highlight, for the few surfaces that ask for one.
@@ -507,6 +557,7 @@ export const MAIN_GLSL = `void main() {
      */
     vec3 sunHighlight =
       sunColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade * sunFacing;
+    if (modelled) sunHighlight = sunModelSpecular;
     /*
      * The dielectric's share goes in here, where it has always gone, so the environment blend
      * below dims it by exactly the reflectance it always dimmed it by. The metal's share is added
@@ -578,18 +629,20 @@ export const MAIN_GLSL = `void main() {
      * whole block was skipped for a fully metallic surface and max(uReflectivity, metal) inside it
      * was never reached. A chromed subject came out near black with a baked probe sitting unread.
      *
-     * **Gated on uOrmEnabled rather than on metal, and that is required rather than tidy.** The
+     * **Gated on the ORM flag rather than on metal, and that is required rather than tidy.** The
      * block takes fwidth of the mirror direction, and a derivative may only be taken under uniform
-     * control flow. uOrmEnabled is a uniform; metal is a texture fetch, so branching on it would
+     * control flow. The flag is a uniform; metal is a texture fetch, so branching on it would
      * put that derivative in non-uniform control flow and WGSL refuses the module outright. See
      * AGENTS.md, 2026-08-07. The per-texel decision still happens, one line down, in the amount.
      *
-     * At uOrmEnabled 0 this is uReflectivity > 0.0 exactly, so nothing that binds no map takes a
+     * With the flag at 0 this is uReflectivity > 0.0 exactly, so nothing that binds no map takes a
      * branch it did not take before.
      */
-    if (uReflectivity > 0.0 || uOrmEnabled != 0) {
+    /* A model reflects its environment whatever the pass asked of the standard model: see
+       modelReflectance. On the switches alone, so the derivatives below stay in uniform flow. */
+    if (uReflectivity > 0.0 || uMaterialFlags.y != 0 || modelled) {
       vec3 toEye = normalize(uCameraPos - vWorldPos);
-      vec3 mirrored = reflect(-toEye, n);
+      vec3 mirrored = reflect(-toEye, modelled ? modelReflectNormal(n) : n);
       vec3 environment = mix(uAmbientGround, uAmbient, mirrored.y * 0.5 + 0.5);
 #if ENVIRONMENT_PROBE
       /*
@@ -845,6 +898,8 @@ export const MAIN_GLSL = `void main() {
 #else
       float weight = clamp(fresnel * reflectAmount, 0.0, 1.0);
 #endif
+      if (modelled) weight = modelReflectance(weight);
+      if (modelled) environment = modelEnvironment(environment);
       lit = mix(
         lit,
         environment * mix(vec3(1.0), albedo, metal),
@@ -1151,7 +1206,8 @@ export const MAIN_GLSL = `void main() {
        */
       float backNdl =
         glassTransmission > 0.0 ? max(-dot(n, toLight / max(dist, 1e-4)), 0.0) : 0.0;
-      if (ndl <= 0.0 && backNdl <= 0.0) continue;
+      /* A model that sees light from behind keeps the lamps behind the surface. See models.ts. */
+      if (ndl <= 0.0 && backNdl <= 0.0 && !modelledBehind) continue;
 
       /*
        * Normal-offset bias.
@@ -1400,13 +1456,25 @@ export const MAIN_GLSL = `void main() {
 
       float shape = (uLightFalloff == 1 ? falloff : falloff * falloff) * coneFalloff * photometric;
       glassGlow += lightColor * backNdl * shape * lightWeight * shaded * lampGlass;
-      if (ndl <= 0.0) continue;
+      if (ndl <= 0.0 && !modelledBehind) continue;
       /*
        * The cookie tints rather than scales, because a mask may be coloured — a stained window is
        * the case that makes the difference — and a greyscale one is exactly a scale. Applied to
        * the light's colour rather than to \`shape\`, which is a scalar and could not carry it.
        */
       lightColor *= cookieTint;
+      /*
+       * A model's answer to this lamp, held back and shadowed exactly as the standard terms below
+       * are — the shadowed sum through \`modelShade\`, which is where skin's penumbra reddens.
+       */
+      if (modelled) {
+        modelLight(toLight / max(dist, 1e-4), lightSourceRadius, dist);
+        vec3 lampModelLight = lightColor * shape * lightWeight;
+        lampOpen += (mDiffuse + mSpecular) * lampModelLight;
+        lampShadowed += (mDiffuse * modelShade(shaded) + mSpecular * shaded) * lampModelLight * lampGlass;
+        lightShade = min(lightShade, mix(1.0, shaded, lightWeight));
+        continue;
+      }
       /*
        * **A metal has no diffuse term, and this lamp kept giving it one.**
        *
@@ -1648,6 +1716,22 @@ export const MAIN_GLSL = `void main() {
 
       glassGlow += uAreaLightColor[a] * backForm * areaOccl * areaGlass;
       if (form <= 0.0) continue;
+      /*
+       * A model answers a rectangle as it answers a lamp at its centre, carried at the rectangle's
+       * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by
+       * the form factor. **An approximation, stated**: a model's lobe is not integrated over the
+       * rectangle as the standard lobe is, so a glossy model under a large softbox shows a lobe
+       * from its centre rather than its shape.
+       */
+      if (modelled) {
+        vec3 areaL = normalize(centre - vWorldPos);
+        modelLight(areaL, 0.0, 0.0);
+        vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form)
+          * uAreaLightColor[a];
+        lampOpen += areaModel;
+        lampShadowed += areaModel * areaOccl * areaGlass;
+        continue;
+      }
       /* Held back with the point lamps', and shadowed by the same term it always was. */
       vec3 areaDiffuse = albedo * uAreaLightColor[a] * form * (1.0 - metal);
       lampOpen += areaDiffuse;
@@ -1741,7 +1825,12 @@ export const MAIN_GLSL = `void main() {
       if (glassTransmission > 0.0) {
         glassGlow += driftLightIrradiance(vWorldPos, -n) * (driftShare * uDriftLight.w);
       }
-      lit += albedo * driftLightIrradiance(vWorldPos, n) * (driftShare * uDriftLight.w) * (1.0 - metal);
+      /* The standard expression in its own order — albedo times the field, then the share — so a
+         pipeline with no model rounds exactly as it did; a model is handed the light alone. */
+      vec3 driftField = driftLightIrradiance(vWorldPos, n);
+      lit += modelled
+        ? modelIrradiance(driftField * (driftShare * uDriftLight.w))
+        : albedo * driftField * (driftShare * uDriftLight.w) * (1.0 - metal);
     }
 
     /*
@@ -1793,6 +1882,7 @@ export const MAIN_GLSL = `void main() {
      * underneath: a ceiling emitting a dull warm haze over a pale panel cannot be expressed
      * by scaling the panel, and scaling it gets the brightness right and the hue wrong.
      */
+    diffuseAlone = lit;
     vec3 emissiveTint = vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor;
     /*
      * Where the surface glows, from an image, or everywhere if it binds none.
@@ -1811,7 +1901,7 @@ export const MAIN_GLSL = `void main() {
      * explicit level — the 2026-08-07 rule is satisfied by the gate rather than by a \`textureLod\`.
      */
     vec3 emissiveMapped = vec3(1.0);
-    if (uEmissiveMapEnabled != 0) {
+    if (uMaterialFlags.z != 0) {
       emissiveMapped = texture(uEmissiveMap, surfaceAt).rgb * uEmissiveScale;
     }
     /* Pulse, flicker and fade from the layer's effects; exactly 1 where it names none. */
@@ -1890,8 +1980,14 @@ export const MAIN_GLSL = `void main() {
     // Water is a camera medium, not a property of individual objects.
     vec3 waterTransmission = vec3(0.42) + uUnderwaterColor * 2.0;
     lit = mix(lit, lit * waterTransmission, uUnderwaterFactor * 0.55);
+    diffuseAlone = mix(diffuseAlone, diffuseAlone * waterTransmission, uUnderwaterFactor * 0.55);
     fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
   }
+  /* The diffuse pass leaves here, with skin's diffuse and the profile it is spread by. */
+  if (modelDiffuseAlone()) {
+    outColor = vec4(modelDiffuseOut(diffuseAlone * ormOcclusion, fog), skinProfileCode());
+    return;
+  }
 
   /*
    * A surface recedes into the medium; light added to the frame fades in it (\`uFogEnabled\` at 2,

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

@@ -0,0 +1,286 @@
+/**
+ * The lit stage's shading models: how a material that is not the standard one answers light.
+ *
+ * **One switch a model, each a pipeline constant, and a branch only ever on the switch itself.**
+ * `MODEL_ANISOTROPIC`, `MODEL_HAIR`, `MODEL_SKIN` and `MODEL_EYE` are off in every pipeline but the
+ * ones a material with that model asks for, so the device compiles every model out of the standard
+ * pipelines and a scene that names none carries none — the arrangement `litSwitchesGlsl` has, for
+ * its reason. Not one constant numbering the models: a comparison against an override is a
+ * specialisation-constant operation, which the WGSL generator refuses (`overridableConstants`), so
+ * every way in is a function that branches on the switches one at a time.
+ *
+ * **Where the models plug in.** `main` gathers the surface once (`modelSurface`), then asks at each
+ * place light arrives: `modelLight` for the sun, each lamp and each rectangle, `modelAmbient` for
+ * the sky and the probe's irradiance, `modelIrradiance` for DriftLight, `modelReflectNormal` and
+ * `modelReflectance` for the environment's reflection. Each returns today's term for the standard
+ * model, and each model's file is where its own answers are.
+ *
+ * **What a model returns from a light** is the two halves the standard terms are: a diffuse already
+ * weighted by the angle of arrival, and a specular lobe in the engine's peak-normalised units (see
+ * `specularLobe`), both before any shadow — the caller shadows the specular, and the diffuse through
+ * `modelShade`, which is the identity but for skin, whose penumbra reddens.
+ */
+import { SURFACE_MODEL_SWITCH } from '../../surfaceModel.ts';
+import type { SurfaceModelKind } from '../../surfaceModel.ts';
+import { ANISOTROPIC_GLSL } from './anisotropic.ts';
+import { HAIR_GLSL } from './hair.ts';
+import { SKIN_GLSL } from './skin.ts';
+import { EYE_GLSL } from './eye.ts';
+
+/** The switches, the numbers, the surface every model reads, and the standard answer it falls back on. */
+const MODELS_HEAD = /* glsl */ `
+/* Which model a pipeline shades by. Each off but where a material asks for it: see models.ts. */
+const bool MODEL_ANISOTROPIC = false;  // wgsl:override
+const bool MODEL_HAIR = false;  // wgsl:override
+const bool MODEL_SKIN = false;  // wgsl:override
+const bool MODEL_EYE = false;  // wgsl:override
+/*
+ * Skin's screen-space scattering, as two halves of one surface: the scene pass without its diffuse,
+ * and a pass that is nothing but it, which the blur spreads before it is added back. Both off but
+ * where \`skinScattering\` is \`'screen-space'\`; see \`skinBlur.ts\`.
+ */
+const bool SKIN_SCREEN = false;  // wgsl:override
+const bool SKIN_DIFFUSE = false;  // 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];
+/* The model's own channels, in the albedo's layout: what each means is each model's to say. */
+uniform highp sampler2DArray uModelMap;
+
+/** Whether this pipeline shades by any model but the standard one. */
+bool modelOn() {
+  if (MODEL_ANISOTROPIC) return true;
+  if (MODEL_HAIR) return true;
+  if (MODEL_SKIN) return true;
+  if (MODEL_EYE) return true;
+  return false;
+}
+
+/** Whether this pipeline draws skin's diffuse alone, for the screen-space blur. */
+bool modelDiffuseAlone() {
+  if (MODEL_SKIN) {
+    if (SKIN_DIFFUSE) return true;
+  }
+  return false;
+}
+
+/** Whether light from behind the surface reaches the eye through it: hair, and skin's thin parts. */
+bool modelSeesBehind() {
+  if (MODEL_HAIR) return true;
+  if (MODEL_SKIN) return true;
+  return false;
+}
+
+/* The surface a model shades, gathered once in main before any light reaches it. */
+vec3 mNormal;
+vec3 mToEye;
+vec3 mTangent;
+vec3 mBitangent;
+vec3 mAlbedo;
+vec3 mSpecColor;
+float mRoughness;
+float mMetal;
+vec4 mMap;
+/*
+ * What \`modelLight\` leaves: the diffuse weighted by its angle and the lobe, neither shadowed.
+ * Globals rather than out parameters, because every parameter a call passes is a local, a store and
+ * a pointer at each call site in \`main\` — sixteen copies of it, one a permutation.
+ */
+vec3 mDiffuse;
+vec3 mSpecular;
+
+/**
+ * Normalised GGX — the distribution itself, not the engine's peak-normalised look — for the models
+ * whose highlight is physical: skin's and the cornea's.
+ */
+float ggxLobe(float ndh, float alpha) {
+  float a2 = alpha * alpha;
+  float d = ndh * ndh * (a2 - 1.0) + 1.0;
+  return a2 / (3.14159265 * d * d);
+}
+
+/** Smith's height-correlated masking with the BRDF's 1 / 4 N·L N·V folded in, for the same. */
+float smithMasking(float ndl, float ndv, float alpha) {
+  float a2 = alpha * alpha;
+  return 0.5 / max(
+    ndl * sqrt(ndv * ndv * (1.0 - a2) + a2) + ndv * sqrt(ndl * ndl * (1.0 - a2) + a2),
+    1e-5
+  );
+}
+
+/** 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);
+  mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
+  mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);
+}
+
+`;
+
+/** Where `main` asks: each model's answer, and the standard's where a model keeps it. */
+const MODELS_DISPATCH = /* glsl */ `
+/**
+ * Where the material's maps are read: the surface's own coordinate, but for an eye, whose iris is
+ * seen through its cornea and moved by it (\`eyeRefraction.ts\`). Before any map is read, and on a
+ * branch on the switches alone, so its derivatives are in uniform control flow.
+ */
+vec3 modelSurfaceAt(vec3 at) {
+  if (MODEL_EYE) return eyeRefract(at);
+  return at;
+}
+
+/**
+ * Gather the surface. The frame and the map read derivatives, so this is called under a branch on
+ * the switches alone, which is uniform control flow by construction.
+ */
+void modelSurface(vec3 n, vec3 albedo, float roughness, float metal, vec3 at) {
+  mNormal = n;
+  mToEye = normalize(uCameraPos - vWorldPos);
+  mat3 frame = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);
+  mTangent = frame[0];
+  mBitangent = frame[1];
+  mAlbedo = albedo;
+  mSpecColor = mix(vec3(vSpecular), albedo, metal);
+  mRoughness = roughness;
+  mMetal = metal;
+  mMap = vec4(0.5, 0.5, 1.0, 1.0);
+  if (uModelParams[1].w > 0.0) mMap = texture(uModelMap, at);
+  if (MODEL_ANISOTROPIC) anisotropicSurface();
+  if (MODEL_HAIR) hairSurface();
+  if (MODEL_SKIN) skinSurface();
+  if (MODEL_EYE) eyeSurface(at);
+}
+
+/**
+ * One light, arriving along \`l\` (unit, toward the light), from a source \`sourceRadius\` across at
+ * \`dist\` — 0 for the sun. Into \`mDiffuse\`, weighted by its angle, and \`mSpecular\`, in lobe
+ * units, neither shadowed.
+ */
+void modelLight(vec3 l, float sourceRadius, float dist) {
+  if (MODEL_ANISOTROPIC) {
+    anisotropicLight(l, sourceRadius, dist);
+    return;
+  }
+  if (MODEL_HAIR) {
+    hairLight(l, sourceRadius, dist);
+    return;
+  }
+  if (MODEL_SKIN) {
+    skinLight(l, sourceRadius, dist);
+    return;
+  }
+  if (MODEL_EYE) {
+    eyeLight(l, sourceRadius, dist);
+    return;
+  }
+  standardLight(l, sourceRadius, dist);
+}
+
+/** How a shadow of \`shadow\` darkens this model's diffuse: the identity, but for hair and skin. */
+vec3 modelShade(float shadow) {
+  if (MODEL_HAIR) return hairShade(shadow);
+  if (MODEL_SKIN) return skinShade(shadow);
+  return vec3(shadow);
+}
+
+/** The sky's or the probe's light on this surface, before any reflection. */
+vec3 modelAmbient(vec3 ambient) {
+  if (MODEL_HAIR) return hairAround(ambient);
+  if (MODEL_SKIN) {
+    if (SKIN_SCREEN) return vec3(0.0);
+  }
+  return mAlbedo * ambient;
+}
+
+/** Light arriving from every side at once — DriftLight's — as this surface returns it. */
+vec3 modelIrradiance(vec3 irradiance) {
+  if (MODEL_HAIR) return hairAround(irradiance);
+  if (MODEL_SKIN) {
+    if (SKIN_SCREEN) return vec3(0.0);
+  }
+  return mAlbedo * irradiance * (1.0 - mMetal);
+}
+
+/** The normal the environment is reflected about: the surface's own, but for a stretched lobe. */
+vec3 modelReflectNormal(vec3 n) {
+  if (MODEL_ANISOTROPIC) return anisotropicReflectNormal(n);
+  if (MODEL_HAIR) return hairAcross();
+  return n;
+}
+
+/**
+ * The environment the reflection blends toward: black in skin's diffuse pass, so the blend dims
+ * the light before it by the reflection's share — as the whole surface's does, and only that light,
+ * the lamps arriving after it — and adds none of the reflection, which is the scene pass's half.
+ */
+vec3 modelEnvironment(vec3 environment) {
+  if (MODEL_SKIN) {
+    if (SKIN_DIFFUSE) return vec3(0.0);
+  }
+  return environment;
+}
+
+/** Skin's diffuse as the diffuse pass writes it, from the lit total before emission, fogged. */
+vec3 modelDiffuseOut(vec3 diffuse, float fog) {
+  return diffuse * (1.0 - fog);
+}
+
+/**
+ * How much of the environment the surface reflects — the blend's weight, Fresnel and all — from
+ * what the standard model would.
+ */
+float modelReflectance(float standard) {
+  if (MODEL_HAIR) return hairReflectance();
+  if (MODEL_SKIN) return skinReflectance();
+  if (MODEL_EYE) return eyeReflectance();
+  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');
+
+/**
+ * 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, or the diffuse alone into
+ * the blur's target — that last one depth-tested for equality against what the frame's half wrote
+ * and writing none, since it is the same surface drawn again. See `skinBlur.ts`.
+ */
+export type SkinHalf = 'whole' | 'scene' | 'diffuse';
+
+/** A skin lit stage with one half's switch on, WebGL2's way: see `SkinHalf`. */
+export function skinHalfBound(source: string, half: SkinHalf): string {
+  if (half === 'whole') return source;
+  const name = half === 'scene' ? 'SKIN_SCREEN' : 'SKIN_DIFFUSE';
+  const off = `const bool ${name} = false;`;
+  if (!source.includes(off)) {
+    throw new Error(`skinHalfBound: this lit stage declares no ${name} constant`);
+  }
+  return source.replace(off, `const bool ${name} = true;`);
+}
+
+/** A lit stage with one model's switch on: the same source, the constant flipped — WebGL2's way. */
+export function modelBound(source: string, kind: SurfaceModelKind): string {
+  const name = SURFACE_MODEL_SWITCH[kind];
+  const off = `const bool ${name} = false;`;
+  if (!source.includes(off)) {
+    throw new Error(`modelBound: this lit stage declares no ${name} constant`);
+  }
+  return source.replace(off, `const bool ${name} = true;`);
+}