@driftengine/core 4.8.5 → 4.8.7

package/src/render/screenSpaceReflection.ts

@@ -350,9 +350,30 @@ export function towardCameraFade(direction: ReadonlyVec3, viewDirection: Readonl
   return Math.min(1, Math.max(0, (along + 1) / 2));
 }
 
+/**
+ * What a `ReflectiveSurface` is made with: its box, which way the surfaces inside it face, and how
+ * much and how far they reflect. Every number but the box has a default; see each field.
+ */
 export interface ReflectiveSurfaceOptions extends DecalBox {
-  /** How much of what the ray finds lands on the surface, 0 to 1. */
+  /**
+   * How much of what the ray finds lands on the surface, 0 to 1: one share over the box, or with
+   * `fresnel` the surface's reflectance head-on.
+   */
   readonly strength?: number;
+  /**
+   * Whether `strength` is the surface's reflectance head-on, F0, rather than one share over the
+   * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
+   * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
+   * by — so a floor returns more toward the horizon than underfoot, and the share follows the
+   * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+   *
+   * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
+   * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion
+   * would. A floor of one material is what it is for.
+   */
+  readonly fresnel?: boolean;
+  /** The surface's roughness, 0 to 1, that `fresnel` weighs by. 0, a polished surface, if absent. */
+  readonly roughness?: number;
   /** How far a ray may travel, world metres. */
   readonly reachM?: number;
   /** How deep a depth sample is treated as being. See `ScreenSpaceMarch.thicknessM`. */
@@ -382,6 +403,9 @@ export class ReflectiveSurface {
   readonly tint = new Float32Array(3);
 
   strength: number;
+  /** See `ReflectiveSurfaceOptions.fresnel`. */
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -405,6 +429,8 @@ export class ReflectiveSurface {
     /* Half, because a mirror is the rare case: a wet floor, polished stone and a car bonnet all
        return a fraction of what lands on them, and a consumer who wants a mirror asks for one. */
     this.strength = options.strength ?? 0.5;
+    this.fresnel = options.fresnel ?? false;
+    this.roughness = options.roughness ?? 0;
     /* Eight metres covers a room and a street corner. Further costs steps rather than accuracy,
        since the step is the reach divided by them. */
     this.reachM = options.reachM ?? 8;
@@ -469,6 +495,8 @@ export interface RecordedReflection {
   readonly axis: Float32Array;
   readonly tint: Float32Array;
   strength: number;
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -482,6 +510,8 @@ function newRecord(): RecordedReflection {
     axis: new Float32Array(3),
     tint: new Float32Array(3),
     strength: 0.5,
+    fresnel: false,
+    roughness: 0,
     reachM: 8,
     thicknessM: 0.25,
     steps: 24,
@@ -537,6 +567,8 @@ export class ReflectionQueue {
     record.axis.set(surface.axis);
     record.tint.set(surface.tint);
     record.strength = Math.min(1, Math.max(0, surface.strength));
+    record.fresnel = surface.fresnel;
+    record.roughness = Math.min(1, Math.max(0, surface.roughness));
     record.reachM = Math.max(0, surface.reachM);
     record.thicknessM = Math.max(0, surface.thicknessM);
     record.steps = Math.min(32, Math.max(1, Math.round(surface.steps)));

package/src/render/shaders/bloom.ts

@@ -27,7 +27,9 @@
  * 3. **Upsample**, additively back up the chain through a tent filter.
  *
  * Deliberately absent, because they were asked against by name: lens dirt, anamorphic streaks
- * and ghosting. One threshold, one radius, one strength.
+ * and ghosting. One threshold, one radius, one strength — and, since 4.8.6, how a colour comes in
+ * past the threshold and a tint for each octave, which is how another engine's stage is matched
+ * rather than how this one looks: see `BloomResponse` in `bloomChain.ts`.
  */
 
 /**
@@ -128,6 +130,11 @@ uniform sampler2D uSource;
 uniform vec2 uTexel;
 /** In scene units. 1.0 is "brighter than white", which is the useful place to start. */
 uniform float uThreshold;
+/**
+ * Scene units over which a colour comes in past the threshold, or 0 to subtract the threshold
+ * instead. See \`BloomResponse.ramp\`.
+ */
+uniform float uRamp;
 
 out vec4 fragColor;
 
@@ -144,6 +151,8 @@ ${BLOOM_BRIGHTNESS}
 vec3 fetch(vec2 uv) {
   vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));
   float bright = brightness(c);
+  /* A ramp keeps a share of the colour, all of it a ramp's width past the line. */
+  if (uRamp > 0.0) return c * clamp((bright - uThreshold) / uRamp, 0.0, 1.0);
   return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));
 }
 
@@ -194,7 +203,9 @@ ${BLOOM_BOXES}
 /**
  * Stage three: a 3x3 tent, added into the level above.
  *
- * **Additive rather than a mix, and each octave counts the same.** A lone bright pixel arrives
+ * **Additive rather than a mix, and each octave counts the same** unless a tint says otherwise:
+ * the level being added onto is multiplied by its own tint as it is, by the blend, and the deepest
+ * by `uScale` on the first draw. White everywhere is exactly the sum. A lone bright pixel arrives
  * at level n divided by four to the n, spread over four to the n pixels, so summing the levels
  * lifts its own pixel by about a third and lays a long shallow tail around it. That falloff is
  * what a real glare looks like; a single gaussian gives a disc with an end to it.
@@ -209,6 +220,12 @@ precision highp float;
 in vec2 vUv;
 
 uniform sampler2D uSource;
+/**
+ * What the level being read is multiplied by: its tint, on the first draw up from the deepest
+ * level, and white on every other — each other level's tint is applied to the level below as it
+ * is added onto, by the blend. See \`BloomResponse.tints\`.
+ */
+uniform vec3 uScale;
 /** How far the tent reaches, in UV. One number for the whole chain. */
 uniform float uRadius;
 
@@ -227,6 +244,6 @@ void main() {
   vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;
 
   vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);
-  fragColor = vec4(sum * 0.0625, 1.0);
+  fragColor = vec4(sum * 0.0625 * uScale, 1.0);
 }
 `;

package/src/render/shaders/bolt.ts

@@ -107,7 +107,13 @@ void main() {
    * the glow. A single falloff gives either a hard line with no atmosphere or a
    * soft smudge with no filament.
    */
-  float across = 1.0 - abs(vSide);
+  /*
+   * Clamped, because a multisampled target shades a pixel on the quad's edge at its centre, which
+   * may lie outside the quad: there 'vSide' runs past one, 'across' goes negative, and 'pow' of a
+   * negative number is NaN. One NaN pixel is a dark speck; bloom then spreads it into a white disc
+   * the size of the blur. Found by a fight drawing short arcs at 4 samples.
+   */
+  float across = clamp(1.0 - abs(vSide), 0.0, 1.0);
   float core = pow(across, 10.0);
   /*
    * A *wide* halo, deliberately. This exponent is the single biggest control over

package/src/render/shaders/depth.ts

@@ -101,6 +101,12 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+  /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
+  vec4 instanceCell = vec4(model[0].w, model[1].w, model[2].w, model[3].w);
+  model[0].w = 0.0;
+  model[1].w = 0.0;
+  model[2].w = 0.0;
+  model[3].w = 1.0;
 #else
   mat4 model = uModel;
 #endif
@@ -125,7 +131,12 @@ void main() {
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
 #if CUTOUT
+#if INSTANCED
+  /* A cutout instance's shadow is cut by its own cell, as its picture is. */
+  vUv = vec3((aUv.xy * instanceCell.xy + instanceCell.zw) * uUvScale + uUvOffset, aUv.z);
+#else
   vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
+#endif
   vAlphaCutout = uAlphaCutout;
 #endif
 #if GLASS

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

@@ -30,7 +30,16 @@ void anisotropicSurface() {
     direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,
     direction.x * uModelParams[0].z + direction.y * uModelParams[0].y
   );
-  aAlong = normalize(mTangent * turned.x + mBitangent * turned.y);
+  vec3 along = mTangent * turned.x + mBitangent * turned.y;
+  /*
+   * A mesh with neither tangents nor texture coordinates has no frame to take a direction from,
+   * and normalising the zero it gives was a NaN that drew the whole surface black. Any direction in
+   * the surface stands in, the one across the world's up, so the highlight is stretched somewhere.
+   */
+  if (dot(along, along) < 1e-12) {
+    along = cross(abs(mNormal.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0), mNormal);
+  }
+  aAlong = normalize(along);
   aAcross = cross(mNormal, aAlong);
   aStrength = strength;
 }
@@ -50,12 +59,37 @@ float anisotropicLobe(vec3 h, float sourceRadius, float dist) {
   return energy / max(d * d, 1e-8);
 }
 
+/**
+ * The same stretch as GGX's own BRDF, \`π · D · Vis · N·L\`, for a surface whose highlight is
+ * physical: the distribution normalised, and Smith's height-correlated masking stretched with it
+ * (Heitz 2014, as Filament writes it). \`anisotropicPhysicalLobe\` in anisotropicLobe.ts.
+ */
+float anisotropicPhysical(vec3 l, vec3 h, float ndl, float sourceRadius, float dist) {
+  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);
+  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float along = clamp(alongWidth + grow, alongWidth, 1.0);
+  float across = clamp(alpha + grow, alpha, 1.0);
+  float x = dot(aAlong, h) / along;
+  float y = dot(aAcross, h) / across;
+  float z = dot(mNormal, h);
+  float d = x * x + y * y + z * z;
+  float distribution = 1.0 / max(3.14159265 * along * across * d * d, 1e-8);
+  float ndv = max(dot(mNormal, mToEye), 1e-4);
+  float viewed = ndl * length(vec3(along * dot(aAlong, mToEye), across * dot(aAcross, mToEye), ndv));
+  float lit = ndv * length(vec3(along * dot(aAlong, l), across * dot(aAcross, l), ndl));
+  return 3.14159265 * distribution * (0.5 / max(viewed + lit, 1e-5)) * ndl;
+}
+
 void anisotropicLight(vec3 l, float sourceRadius, float dist) {
   float ndl = max(dot(mNormal, l), 0.0);
   vec3 h = normalize(l + mToEye);
-  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);
+  vec3 tint = highlightTint(mSpecColor, max(dot(mToEye, h), 0.0), mMetal);
   mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
-  mSpecular = ndl > 0.0 ? tint * anisotropicLobe(h, sourceRadius, dist) : vec3(0.0);
+  float lobe = physicalSpecular()
+    ? anisotropicPhysical(l, h, ndl, sourceRadius, dist)
+    : anisotropicLobe(h, sourceRadius, dist);
+  mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);
 }
 
 /* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */

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

@@ -0,0 +1,142 @@
+/**
+ * One rectangle's light on a fragment: its form factor, and what it adds once its occlusion is
+ * known. **The one statement of it**, called by the fixed loop over the first `maxAreaLights`
+ * rectangles and by the froxel table's for the rest, so the two arms shade a rectangle with one
+ * body rather than two transcriptions of it — the zero-pixel gate between them means something
+ * only if that is so.
+ *
+ * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
+ */
+export const AREA_LIGHT_GLSL = /* glsl */ `
+/**
+ * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the
+ * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural
+ * order — minus, plus, plus, minus — winds the other way, and every one-sided light then clamped to
+ * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive
+ * part and a two-sided one the magnitude.
+ */
+float areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {
+  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
+  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
+  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;
+  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;
+  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);
+}
+
+/**
+ * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's
+ * positive edge: \`p\` the fragment's place along the axis, \`height\` its height above the
+ * rectangle's plane, \`halfSize\` the rectangle's half extent, and the door's tip \`tipOut\` beyond
+ * the edge and \`tipUp\` above the plane. Points of the rectangle past the answer are hidden.
+ *
+ * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a
+ * fragment beside the door and outside its line is hidden from all of it, and one inside the door's
+ * reach is hidden from none of it.
+ */
+float barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {
+  float tipAt = halfSize + tipOut;
+  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);
+  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;
+  return 1e9;
+}
+
+/**
+ * The part of a rectangle a fragment sees past its barn doors, written into \`centre\` and
+ * \`halfSize\` as the smaller rectangle that is left, or false where the doors hide all of it.
+ * \`doors\` is the cosine of their angle from the normal and their length; a length of 0 is no doors.
+ * Each axis is clipped by its own two doors, which is what makes this four projections and a min.
+ */
+bool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {
+  if (doors.y <= 0.0) return true;
+  vec3 toFragment = vWorldPos - centre;
+  float height = dot(toFragment, cross(right, up));
+  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */
+  if (height <= 0.0) return true;
+  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));
+  float tipUp = doors.y * doors.x;
+  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));
+  vec2 hi = vec2(
+    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),
+    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))
+  );
+  vec2 lo = vec2(
+    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),
+    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))
+  );
+  if (hi.x <= lo.x || hi.y <= lo.y) return false;
+  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));
+  halfSize = 0.5 * (hi - lo);
+  return true;
+}
+
+/**
+ * What one rectangle of colour \`color\` and form factor \`form\` adds to the lamps' two sums, open
+ * and shadowed by \`occl\` and \`glass\`.
+ *
+ * **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.
+ *
+ * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.
+ * What stood here once handed the closest point on the rectangle to \`sphereLobe\` and scaled it by
+ * \`form\`, the *diffuse* form factor. Measured against a brute-force integral by
+ * \`scripts/areaSpecular.mjs\`, that lost the reflection rather than blurring it: on polished metal
+ * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface
+ * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the
+ * surface reflects and 79.0% for one overhead. \`quadCoverage\` says what fraction of the specular
+ * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split
+ * the probe path uses. **\`dfg.x + dfg.y\` and not \`envSpecularEnergy\`**, deliberately: the
+ * compensation returns the multiply-scattered share, and every direct lobe in this shader is
+ * single-scattering, so adding it here returns energy the light never had. Measured at 211%
+ * against 40.1%.
+ */
+void areaLightAdd(
+  vec3 centre,
+  vec3 right,
+  vec3 up,
+  vec2 halfSize,
+  vec3 color,
+  float form,
+  float occl,
+  vec3 glass,
+  vec3 n,
+  vec3 albedo,
+  float metal,
+  vec3 specColor,
+  float roughness,
+  bool modelled,
+  inout vec3 lampOpen,
+  inout vec3 lampShadowed
+) {
+  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) * color;
+    lampOpen += areaModel;
+    lampShadowed += areaModel * occl * glass;
+    return;
+  }
+  /* Held back with the point lamps', and shadowed by the same term it always was. */
+  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);
+  lampOpen += areaDiffuse;
+  lampShadowed += areaDiffuse * occl * glass;
+
+  if (vSpecular > 0.0 || metal > 0.0) {
+    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
+    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
+    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;
+    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;
+    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);
+    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);
+    if (coverage > 0.0) {
+      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);
+      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);
+      vec3 areaHighlight = areaSpec * color * coverage;
+      lampOpen += areaHighlight;
+      lampShadowed += areaHighlight * occl * glass;
+    }
+  }
+}
+`;

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

@@ -29,7 +29,12 @@ vec4 glassUnmix(vec4 mip, float centreClarity) {
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
 export type LitSwitch =
-  'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT';
+  | 'GLASS_SHADOWS'
+  | 'CLUSTERED_LIGHTS'
+  | 'LIGHT_FIXTURES'
+  | 'SURFACE_EFFECTS'
+  | 'DRIFT_LIGHT'
+  | 'PHYSICAL_SPECULAR';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -39,6 +44,7 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     LIGHT_FIXTURES: false,
     SURFACE_EFFECTS: false,
     DRIFT_LIGHT: false,
+    PHYSICAL_SPECULAR: false,
   };
 }
 
@@ -61,7 +67,8 @@ export interface LitSwitches {
  * first uses them — a measured profile or a cookie, a material with an effects table, a DriftLight
  * volume — and then on for good; see `PipelineCache.enable` and the WebGL2 renderer's rebuild.
  * Measured on RADV against the lit shader with glass already out: 6,852 instructions and 120
- * registers, 4,641 and 96 with all four out.
+ * registers, 4,641 and 96 with all four out. `PHYSICAL_SPECULAR` is a sixth, declared with the
+ * models so that theirs keep their ids (`modelsGlsl`).
  */
 export function litSwitchesGlsl(switches: LitSwitches): string {
   return /* glsl */ `

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

@@ -14,7 +14,9 @@ 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 { modelsGlsl } from './models.ts';
+import { AREA_LIGHT_GLSL } from './areaLight.ts';
+import { NORMAL_MAP_GLSL } from './normalMap.ts';
 import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
@@ -107,7 +109,17 @@ layout(location = 11) in vec4 aInstanceModel0;
 layout(location = 12) in vec4 aInstanceModel1;
 layout(location = 13) in vec4 aInstanceModel2;
 layout(location = 14) in vec4 aInstanceModel3;
-layout(location = 15) in vec3 aInstanceTint;
+/**
+ * The instance's tint, and its opacity in w: \`MeshInstances.alphas\`, 1 where none was given — or,
+ * in a lightmapped batch's pipeline, its region of the page (\`MeshInstances.lightmapRegions\`).
+ */
+layout(location = 15) in vec4 aInstanceTint;
+/*
+ * On in the pipeline a lightmapped material draws an instanced batch with, where the lane above is
+ * a region and not a tint: the second coordinates leave scaled and offset by it, under a tint and an
+ * opacity of one. See lightmap.ts.
+ */
+const bool LIGHTMAP_REGIONS = false; // wgsl:override
 #else
 uniform mat4 uModel;
 /**
@@ -233,7 +245,17 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
-  vec3 tint = aInstanceTint;
+  /*
+   * **The bottom row is the instance's texture cell** (\`MeshInstances.uvRegions\`), which an
+   * affine placement leaves free: read, and rebuilt as the \`[0, 0, 0, 1]\` it stands for.
+   */
+  vec4 instanceCell = vec4(model[0].w, model[1].w, model[2].w, model[3].w);
+  model[0].w = 0.0;
+  model[1].w = 0.0;
+  model[2].w = 0.0;
+  model[3].w = 1.0;
+  vec3 tint = aInstanceTint.rgb;
+  if (LIGHTMAP_REGIONS) tint = vec3(1.0);
 #else
   mat4 model = uModel;
   vec3 tint = uTint;
@@ -280,17 +302,31 @@ void main() {
   vColor = aColor * tint;
   vEmissive = aEmissive;
   vSpecular = aSpecular;
+#if INSTANCED
+  /* The instance's cell first, then the material's scale and offset. */
+  vUv = vec3((aUv.xy * instanceCell.xy + instanceCell.zw) * uUvScale + uUvOffset, aUv.z);
+#else
   vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
+#endif
   vEmissiveColor = aEmissiveColor;
   vRoughness = aRoughness;
   vGrain = aGrain;
   vRelief = aRelief;
   vTangent = vec4(worldTangent, aTangent.w);
 #if INSTANCED
-  /* No channel on this path; the neutral values are what every mesh read before it existed. */
+  /*
+   * No channel on this path; the neutral values are what every mesh read before it existed — but
+   * for the opacity, which an instance carries of its own, 1 where none was given.
+   */
   vSkyDirect = 1.0;
-  vAlpha = 1.0;
+  vAlpha = aInstanceTint.w;
   vThickness = 1.0;
+  if (LIGHTMAP_REGIONS) {
+    /* Out of the lane's \`-1 - uv\`, through the region, and back into it. See lightmap.ts. */
+    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + aInstanceTint.z);
+    vRelief = -1.0 - ((-1.0 - aRelief) * aInstanceTint.y + aInstanceTint.w);
+    vAlpha = 1.0;
+  }
 #else
   vSkyDirect = aChannel.y;
   vAlpha = aChannel.z;
@@ -427,6 +463,11 @@ export interface FlatShaderOptions {
   readonly surfaceEffects?: boolean;
   /** Whether it reads a DriftLight volume. True when absent. See `litSwitchesGlsl`. */
   readonly driftLight?: boolean;
+  /**
+   * Whether it carries GGX's own highlight for a material that asks (`physicalSpecular`). True
+   * when absent. See `modelsGlsl`.
+   */
+  readonly physicalSpecular?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -563,13 +604,17 @@ export function flatFrag(options: FlatShaderOptions): string {
        * and `main` is unconditional by construction.
        */
       TANGENT_FRAME_GLSL,
+      /* After the frame it calls, unconditional for the same reason. See normalMap.ts. */
+      NORMAL_MAP_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,
+      modelsGlsl(options.physicalSpecular ?? true),
+      /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
+      AREA_LIGHT_GLSL,
       MAIN_GLSL,
     ].join('\n'),
     {

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

@@ -30,6 +30,55 @@ export const EMISSIVE_SHADOW_SHARE = 0.55;
  */
 export const MIN_LOBE_ALPHA = 0.01;
 
+/**
+ * Karis's fit to the split-sum environment BRDF, as GLSL: the lit stage's, and the screen-space
+ * reflection's when a surface asks for its Fresnel (`ReflectiveSurface.fresnel`). One text, so the
+ * two cannot drift.
+ */
+export const ENV_BRDF_GLSL = `/**
+ * The other half of the split-sum approximation: what fraction of an environment a surface returns.
+ *
+ * The convolution decides *what* a surface reflects at a given roughness; this decides *how much*.
+ * Before it the amount was fresnel times one-minus-roughness, which is a curve somebody chose
+ * standing in for an integral.
+ *
+ * Karis's analytic fit to the environment BRDF, so there is **no lookup texture and no texture
+ * unit**: a few multiply-adds against roughness and the view angle. x scales the surface's own
+ * reflectance at normal incidence and y is the additive grazing term, so a smooth dielectric at
+ * f0 0.04 returns about 0.046 head-on and approaches 1 at the edge, which is what a dielectric
+ * does. At roughness 1 it returns about 0.016 rather than the zero one-minus-roughness gave, which
+ * is the substantive difference: a fully rough dielectric does reflect its surroundings.
+ *
+ * **It replaces the Fresnel factor as well as the thinning**, because the fit already contains the
+ * angular dependence; multiplying by a separate Fresnel term would apply it twice.
+ *
+ * **How much this is worth was measured, and it is worth less than it looks on a dark room.**
+ * On demo/dev/ibl.html?ladder=1 the whole ladder moved by at most 0.2 of 255 when the old term was
+ * replaced. That is not the term failing: at high roughness the surface reads the coarsest levels
+ * of the chain, and in a room of five dark walls and one bright one those levels are dark, so a
+ * weight three times larger against a near-zero radiance is still near zero. It is worth much more
+ * against a bright environment, which is what a loaded sky is and what no captured room here is.
+ *
+ * **A warning about reading that page, paid for once.** The ladder falls about five-fold from
+ * mirror to rough, and that reads as energy being lost. It is not: a mirror concentrates the one
+ * bright wall into a sharp image and a rough surface averages it against five dark ones, so the
+ * falloff is the room's own content. The normalised falloff also happens to track one-minus-
+ * roughness closely, which made the old term look like the cause — and removing that term entirely
+ * changed nothing, which is what settled it. Perturb before believing a match.
+ *
+ * **What it costs** is a fit rather than the integral: the published error is around one per cent
+ * of the tabulated term, far below what an eight-bit frame can show. **What would make it wrong**
+ * is a material model this shader does not have — a clearcoat or a sheen lobe carries its own BRDF
+ * and its own integral, and this fit is Trowbridge-Reitz with Smith masking and nothing else.
+ */
+vec2 envBrdfApprox(float ndv, float roughness) {
+  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
+  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
+  vec4 r = roughness * c0 + c1;
+  float a004 = min(r.x * r.x, exp2(-9.28 * ndv)) * r.x + r.y;
+  return vec2(-1.04, 1.04) * a004 + r.zw;
+}`;
+
 export const LOBES_GLSL = `float shadowReach(float distance, float maxDistance) {
   return 1.0 - smoothstep(
     maxDistance * ${POINT_SHADOW_FADE_START.toFixed(2)},
@@ -156,49 +205,7 @@ float sphereLobe(float ndh, float roughness, float sourceRadius, float dist) {
   return energy * (w2 * w2) / max(d * d, 1e-8);
 }
 
-/**
- * The other half of the split-sum approximation: what fraction of an environment a surface returns.
- *
- * The convolution decides *what* a surface reflects at a given roughness; this decides *how much*.
- * Before it the amount was fresnel times one-minus-roughness, which is a curve somebody chose
- * standing in for an integral.
- *
- * Karis's analytic fit to the environment BRDF, so there is **no lookup texture and no texture
- * unit**: a few multiply-adds against roughness and the view angle. x scales the surface's own
- * reflectance at normal incidence and y is the additive grazing term, so a smooth dielectric at
- * f0 0.04 returns about 0.046 head-on and approaches 1 at the edge, which is what a dielectric
- * does. At roughness 1 it returns about 0.016 rather than the zero one-minus-roughness gave, which
- * is the substantive difference: a fully rough dielectric does reflect its surroundings.
- *
- * **It replaces the Fresnel factor as well as the thinning**, because the fit already contains the
- * angular dependence; multiplying by a separate Fresnel term would apply it twice.
- *
- * **How much this is worth was measured, and it is worth less than it looks on a dark room.**
- * On demo/dev/ibl.html?ladder=1 the whole ladder moved by at most 0.2 of 255 when the old term was
- * replaced. That is not the term failing: at high roughness the surface reads the coarsest levels
- * of the chain, and in a room of five dark walls and one bright one those levels are dark, so a
- * weight three times larger against a near-zero radiance is still near zero. It is worth much more
- * against a bright environment, which is what a loaded sky is and what no captured room here is.
- *
- * **A warning about reading that page, paid for once.** The ladder falls about five-fold from
- * mirror to rough, and that reads as energy being lost. It is not: a mirror concentrates the one
- * bright wall into a sharp image and a rough surface averages it against five dark ones, so the
- * falloff is the room's own content. The normalised falloff also happens to track one-minus-
- * roughness closely, which made the old term look like the cause — and removing that term entirely
- * changed nothing, which is what settled it. Perturb before believing a match.
- *
- * **What it costs** is a fit rather than the integral: the published error is around one per cent
- * of the tabulated term, far below what an eight-bit frame can show. **What would make it wrong**
- * is a material model this shader does not have — a clearcoat or a sheen lobe carries its own BRDF
- * and its own integral, and this fit is Trowbridge-Reitz with Smith masking and nothing else.
- */
-vec2 envBrdfApprox(float ndv, float roughness) {
-  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
-  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
-  vec4 r = roughness * c0 + c1;
-  float a004 = min(r.x * r.x, exp2(-9.28 * ndv)) * r.x + r.y;
-  return vec2(-1.04, 1.04) * a004 + r.zw;
-}
+${ENV_BRDF_GLSL}
 
 /**
  * How much of a prefiltered environment a surface returns, with the light that bounces more than