@driftengine/core 4.8.5 → 4.8.7

package/src/render/shaders/gi/probeBake.wgsl.ts

@@ -684,15 +684,19 @@ fn probeLampsAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {
   var sum = vec3<f32>(0.0);
   let count = u32(bake.lightCount);
   for (var i = 0u; i < count; i = i + 1u) {
-    let at = bounceLights[i * 3u];
-    let colour = bounceLights[i * 3u + 1u];
-    let aim = bounceLights[i * 3u + 2u];
+    let at = bounceLights[i * 4u];
+    let colour = bounceLights[i * 4u + 1u];
+    let aim = bounceLights[i * 4u + 2u];
+    let lightExponent = bounceLights[i * 4u + 3u].x;
     let lightRadius = at.w;
     let toLight = at.xyz - p;
     let dist = length(toLight);
     let coneFalloff = smoothstep(aim.w, colour.w, dot(-toLight / max(dist, 1e-4), aim.xyz));
     var falloff: f32;
-    if (bake.falloff == 1.0) {
+    if (lightExponent > 0.0) {
+      let reach = dist / max(lightRadius, 1e-4);
+      falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), lightExponent);
+    } else if (bake.falloff == 1.0) {
       let 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 {
@@ -701,7 +705,7 @@ fn probeLampsAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {
     if (falloff <= 0.0) { continue; }
     let ndl = max(dot(n, toLight / max(dist, 1e-4)), 0.0);
     if (ndl <= 0.0) { continue; }
-    let shape = select(falloff * falloff, falloff, bake.falloff == 1.0) * coneFalloff;
+    let shape = select(falloff * falloff, falloff, lightExponent > 0.0 || bake.falloff == 1.0) * coneFalloff;
     if (shape <= 0.0) { continue; }
     let fixture = max(0.3, 2.0 * march.finestStep);
     let seen = probeLampVisible(p, n, toLight / max(dist, 1e-4), dist - fixture);

package/src/render/shaders/particle.ts

@@ -1,5 +1,6 @@
 import { FOG_GLSL } from './fog.ts';
 import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
+import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.ts';
 import { MAX_POINT_LIGHTS } from '../lightBudget.ts';
 
 /**
@@ -87,6 +88,11 @@ layout(location = 6) in float aAlpha;
 layout(location = 7) in float aAge;
 layout(location = 8) in float aSeed;
 layout(location = 9) in vec3 aVelocity;
+/**
+ * A sprite's flipbook frame and its half-height: \`ParticleInstances.frames\` and \`heights\`. The
+ * procedural materials read neither, and a height of 0 is a square, its height its width.
+ */
+layout(location = 10) in vec2 aSprite;
 
 uniform mat4 uViewProj;
 uniform vec3 uCameraPos;
@@ -126,6 +132,8 @@ uniform float uStretchSec;
  * from everywhere.
  */
 uniform float uCameraFacing;
+/** How far each particle is moved toward the eye, in metres: \`ParticleBatchOptions.cameraOffset\`. */
+uniform float uCameraOffset;
 
 out vec2 vUv;
 out vec3 vColor;
@@ -134,6 +142,9 @@ out float vAge;
 out float vSeed;
 out vec3 vWorldPos;
 out vec3 vNormal;
+/** The flipbook frame, for the sprite material; and the depth from the eye, for its fades. */
+out float vFrame;
+out float vViewDepth;
 
 void main() {
   float s = sin(aSpin);
@@ -150,7 +161,18 @@ void main() {
   vec3 across;
   vec3 up;
   float bladeGain;
-  if (uCameraFacing > 0.5) {
+  /*
+   * **Along its travel**, \`facing: 'velocity'\` (2): the quad's up is the velocity seen across
+   * the view, so a streak of light or a stretched spark lies along its motion and still faces the
+   * eye. A particle at rest has no such direction and faces the camera as the default does.
+   */
+  vec3 viewer = normalize(uCameraPos - aPos);
+  vec3 alongView = aVelocity - viewer * dot(aVelocity, viewer);
+  if (uCameraFacing > 1.5 && dot(alongView, alongView) > 1e-10) {
+    up = normalize(alongView);
+    across = cross(up, viewer);
+    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;
+  } else if (uCameraFacing > 0.5) {
     vec3 toCamera = normalize(uCameraPos - aPos);
     /* Any reference not parallel to the view. World up serves everywhere except looking
        straight up or down it, where the two are the same line and the cross product
@@ -173,6 +195,16 @@ void main() {
     bladeGain = 1.0;
   }
   vec3 offset = (across * rolled.x + up * rolled.y) * aSize;
+  /*
+   * **A sprite of two sizes** — a half-width and a half-height — rolls as a rectangle: the corner
+   * is scaled first and turned after. Only where a height was given, so a square particle keeps
+   * the arithmetic it always had to the bit.
+   */
+  if (aSprite.y > 0.0) {
+    vec2 extent = vec2(aCorner.x * aSize, aCorner.y * aSprite.y);
+    vec2 turned = vec2(extent.x * c - extent.y * s, extent.x * s + extent.y * c);
+    offset = across * turned.x + up * turned.y;
+  }
 
   /*
    * Stretched along travel. Applied as an extra displacement on the component of
@@ -188,7 +220,10 @@ void main() {
   /* bladeGain applied here, after the stretch rather than before it, so a dropped blade
      is degenerate whatever the stretch added: all four of its corners land on aPos. */
   vec3 world = aPos + offset * bladeGain;
+  /* Toward the eye, so a sprite set into a surface is drawn in front of it. 0 moves nothing. */
+  world += viewer * uCameraOffset * bladeGain;
   vUv = aCorner;
+  vFrame = aSprite.x;
   vColor = aColor;
   vAlpha = aAlpha;
   vAge = aAge;
@@ -207,6 +242,8 @@ void main() {
   vNormal = dot(face, toEye) < 0.0 ? -face : face;
 
   gl_Position = uViewProj * vec4(world, 1.0);
+  /* A perspective projection's w is the depth from the eye, which is what the fades measure. */
+  vViewDepth = gl_Position.w;
 }
 `;
 
@@ -436,3 +473,99 @@ void main() {
   outColor = vec4(applyOutputTransform(color), alpha);
 }
 `;
+
+/**
+ * A textured sprite: an image a consumer supplies, a cell of it at a time, at the colour and opacity
+ * each particle carries — what another engine's sprite renderer draws, and the material the three
+ * procedural ones above cannot be. Unlit: the colour is the particle's times the image's.
+ *
+ * **A flipbook** of `uCells.x` by `uCells.y` cells, numbered across then down from the top-left,
+ * a particle's frame naming one; with `uCells.z` at 1 the frame's fraction blends toward the next,
+ * so a slow flipbook does not step.
+ *
+ * **Two fades, each 0 for off.** A soft edge where the sprite meets the scene, by how far in front
+ * of the opaque depth it is over `uFade.x` metres — the hard line a flat card draws where it cuts
+ * a floor — and a fade over `uFade.y` metres in front of the eye, so a card the camera passes
+ * through does not fill the screen and vanish. The first reads a copy of the frame's depth, which
+ * is `uFade.z` at 1; where no copy can be had it is 0 and the edge stays hard.
+ */
+export const PARTICLE_SPRITE_FRAG = `#version 300 es
+precision highp float;
+
+/* Every output of the vertex stage, in its order, read or not: the generated stages number their
+   locations in declaration order, so a fragment declaring a subset reads the wrong ones. */
+in vec2 vUv;
+in vec3 vColor;
+in float vAlpha;
+in float vAge;
+in float vSeed;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in float vFrame;
+in float vViewDepth;
+
+/** The image, a surface texture: its first layer. */
+uniform mediump sampler2DArray uSprite;
+/** The frame's opaque depth, copied, for the soft edge. highp for the reason depth always is. */
+uniform highp sampler2D uDepth;
+/** Columns, rows, and 1 to blend between cells. */
+uniform vec4 uCells;
+/** The soft edge's distance, the eye fade's, and whether the depth copy is there to read. */
+uniform vec4 uFade;
+/** A depth sample to view-space metres, as the skin blur takes it. */
+uniform vec4 uDepthToViewZ;
+/** The target's size in pixels, so a fragment finds its own texel of the depth copy. */
+uniform vec2 uViewport;
+uniform vec3 uCameraPos;
+/** Whether the colour recedes into the medium: \`ParticleBatchOptions.fog\`. */
+uniform int uFogEnabled;
+${FOG_GLSL}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+/** Cell \`cell\` of the flipbook, at \`uv\` inside it. Integer arithmetic: see AGENTS.md. */
+vec2 cellUv(int cell, vec2 uv) {
+  int columns = max(int(uCells.x + 0.5), 1);
+  int rows = max(int(uCells.y + 0.5), 1);
+  int wrapped = cell % (columns * rows);
+  int column = wrapped % columns;
+  int row = wrapped / columns;
+  return (vec2(float(column), float(row)) + uv) / vec2(float(columns), float(rows));
+}
+
+float viewZ(float depth) {
+  float ndc = ${glslSceneDepthToNdc('depth')};
+  return (uDepthToViewZ.x * ndc + uDepthToViewZ.y) / (uDepthToViewZ.z * ndc + uDepthToViewZ.w);
+}
+
+void main() {
+  /* The corner's square to the image's: v runs down an image, and up a quad. */
+  vec2 uv = vec2(vUv.x * 0.5 + 0.5, 0.5 - vUv.y * 0.5);
+  float frame = max(vFrame, 0.0);
+  int first = int(floor(frame));
+  vec4 image = texture(uSprite, vec3(cellUv(first, uv), 0.0));
+  if (uCells.z > 0.5) {
+    vec4 next = texture(uSprite, vec3(cellUv(first + 1, uv), 0.0));
+    image = mix(image, next, fract(frame));
+  }
+
+  float fade = 1.0;
+  if (uFade.z > 0.5 && uFade.x > 0.0) {
+    float depth = textureLod(uDepth, gl_FragCoord.xy / uViewport, 0.0).r;
+    if (!(${glslIsFarDepth('depth')})) {
+      fade = clamp((abs(viewZ(depth)) - vViewDepth) / uFade.x, 0.0, 1.0);
+    }
+  }
+  if (uFade.y > 0.0) fade *= clamp(vViewDepth / uFade.y, 0.0, 1.0);
+
+  float alpha = vAlpha * image.a * fade;
+  if (alpha <= 0.001) discard;
+  vec3 color = vColor * image.rgb;
+  if (uFogEnabled != 0) {
+    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+    color = mix(color, mediumColor(), fog);
+  }
+  outColor = vec4(applyOutputTransform(color), alpha);
+}
+`;

package/src/render/shaders/recon/motion.wgsl.ts

@@ -248,6 +248,17 @@ fn motionDynamicVert(
   return out;
 }
 
+/* An instance's placement with its bottom row, which carries its texture cell, rebuilt as the
+   [0, 0, 0, 1] an affine placement has: \`MeshInstances.uvRegions\`. */
+fn placementOf(c0: vec4<f32>, c1: vec4<f32>, c2: vec4<f32>, c3: vec4<f32>) -> mat4x4<f32> {
+  return mat4x4<f32>(
+    vec4<f32>(c0.xyz, 0.0),
+    vec4<f32>(c1.xyz, 0.0),
+    vec4<f32>(c2.xyz, 0.0),
+    vec4<f32>(c3.xyz, 1.0),
+  );
+}
+
 /*
  * The instanced stage: each instance's matrix this frame and last frame, read from the batch's
  * placement and the copy of last frame's it kept. Slot for slot, so an instance is paired with
@@ -265,8 +276,8 @@ fn motionInstancedVert(
   @location(8) p2: vec4<f32>,
   @location(9) p3: vec4<f32>,
 ) -> Varyings {
-  let world = mat4x4<f32>(m0, m1, m2, m3) * vec4<f32>(position, 1.0);
-  let wasWorld = mat4x4<f32>(p0, p1, p2, p3) * vec4<f32>(position, 1.0);
+  let world = placementOf(m0, m1, m2, m3) * vec4<f32>(position, 1.0);
+  let wasWorld = placementOf(p0, p1, p2, p3) * vec4<f32>(position, 1.0);
   var out: Varyings;
   out.clip = frame.raster * world;
   out.now = frame.viewProj * world;

package/src/render/shaders/skinBlur.ts

@@ -6,6 +6,11 @@
  * **One pass, run twice**: along x into a target of its own, keeping the profile in the alpha, then
  * along y blended additively into the frame — its colour added, the frame's alpha kept.
  *
+ * **What it spreads is light, and the colour is applied after**, from the skin's own colour half at
+ * this pixel. Light travels beneath skin; the pigment a brow, a lip line or a freckle is made of
+ * does not, so spreading the coloured diffuse — as this did until 4.8.6 — smeared every mark on a
+ * face into the skin around it, and the blur's taps laid faint copies of each mark beside it.
+ *
  * **Refuses what is not the same skin**: a neighbour that wrote no skin, or one further in depth
  * than four of the profile's widest distances, takes no weight, and what is kept is divided by
  * what was kept, so a cheek's light does not pull toward the black beside its silhouette. A tap
@@ -34,6 +39,12 @@ uniform vec4 uDepthToViewZ;
 uniform float uFocal;
 /** Each profile's scatter distance per channel, in metres. */
 uniform vec4 uProfiles[${SKIN_PROFILES}];
+/**
+ * The skin's colour, and its coverage in the alpha: what the spread light is multiplied by on the
+ * second axis, where \`uApplyAlbedo\` is 1. Read at this pixel alone, because pigment does not move.
+ */
+uniform sampler2D uAlbedo;
+uniform float uApplyAlbedo;
 
 out vec4 fragColor;
 
@@ -50,6 +61,17 @@ vec3 burleyMass(float x, vec3 d) {
   return 0.5 - (exp(-x / d) + 3.0 * exp(-x / (3.0 * d))) * 0.125;
 }
 
+/**
+ * The spread light times the skin's colour here, on the second axis; the light as it is on the
+ * first. The colour target holds colour times coverage over coverage, so dividing gives the skin's
+ * own colour at an edge, which the light — weighted for coverage already — is then multiplied by.
+ */
+vec3 withAlbedo(vec3 light) {
+  if (uApplyAlbedo < 0.5) return light;
+  vec4 albedo = textureLod(uAlbedo, vUv, 0.0);
+  return light * albedo.rgb / max(albedo.a, 1e-4);
+}
+
 void main() {
   vec4 own = textureLod(uSkin, vUv, 0.0);
   /*
@@ -63,7 +85,7 @@ void main() {
   }
   float depth = textureLod(uDepth, vUv, 0.0).r;
   if (${glslIsFarDepth('depth')}) {
-    fragColor = own;
+    fragColor = vec4(withAlbedo(own.rgb), own.a);
     return;
   }
   /* A part-covered pixel's code is its share of the whole: read it as the nearest, which is the
@@ -75,7 +97,7 @@ void main() {
   /* The widest distance in pixels here: under half of one, there is nothing to spread across. */
   float pixels = widest * uFocal / max(z, 1e-4);
   if (pixels < 0.5) {
-    fragColor = own;
+    fragColor = vec4(withAlbedo(own.rgb), own.a);
     return;
   }
   vec3 centre = 2.0 * burleyMass(EDGES[0] * widest, d);
@@ -100,6 +122,6 @@ void main() {
       weight += w * (cover * keep);
     }
   }
-  fragColor = vec4(sum / weight, own.a);
+  fragColor = vec4(withAlbedo(sum / weight), own.a);
 }
 `;

package/src/render/shaders/ssrTrace.ts

@@ -21,6 +21,7 @@
  */
 
 import { glslIsFarDepth } from '../depthConvention.ts';
+import { ENV_BRDF_GLSL } from './flat/lobes.ts';
 
 /**
  * The most samples the march may take. `uSsrSteps` breaks out early.
@@ -64,6 +65,11 @@ uniform vec3 uSsrEye;
 uniform vec3 uSsrAxis;
 uniform vec3 uSsrTint;
 uniform float uSsrStrength;
+/**
+ * Whether \`uSsrStrength\` is the surface's reflectance head-on, carried per pixel through the
+ * split-sum BRDF (x, 1 or 0), and the roughness it is carried at (y). \`ReflectiveSurface.fresnel\`.
+ */
+uniform vec2 uSsrFresnel;
 uniform float uSsrFacingCos;
 uniform float uSsrReach;
 uniform float uSsrThickness;
@@ -73,6 +79,8 @@ uniform float uSsrEdgeFade;
 
 out vec4 fragColor;
 
+${ENV_BRDF_GLSL}
+
 /** What the frame drew at a screen position, as a world point. */
 vec3 worldAt(vec2 uv, float stored) {
   vec4 world = uSsrDepthToWorld * vec4(uv * 2.0 - 1.0, stored, 1.0);
@@ -133,7 +141,18 @@ void main() {
   mask *= smoothstep(uSsrFacingCos, min(1.0, uSsrFacingCos + 0.25), facing);
   /* Nothing was drawn here, so there is no surface to reflect in. */
   mask *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
-  mask *= uSsrStrength;
+  /*
+   * **How much the surface returns**: one number over the box, or, where the caller asks, its
+   * reflectance head-on carried through the split-sum BRDF at this pixel's own view and the
+   * surface's roughness — the lit stage's fit, so the two agree on what a surface reflects. A floor
+   * then returns more toward the horizon than underfoot, and the share follows the camera.
+   */
+  float returned = uSsrStrength;
+  if (uSsrFresnel.x > 0.5) {
+    vec2 dfg = envBrdfApprox(clamp(dot(normal, normalize(toEye)), 0.0, 1.0), uSsrFresnel.y);
+    returned = clamp(uSsrStrength * dfg.x + dfg.y, 0.0, 1.0);
+  }
+  mask *= returned;
 
   vec3 found = vec3(0.0);
   float weight = 0.0;

package/src/render/shaders/water.ts

@@ -177,8 +177,11 @@ uniform vec3 uAmbient;
  * is the single strongest cue that a surface *is* water switched off because no
  * directional source existed to make it. A lantern on a jetty threw nothing.
  *
- * Same slots, same weights and the same two falloff shapes as the surface shader, so a
- * lamp behaves the same way over water as it does over the ground beside it.
+ * Same slots, same weights and the surface shader's falloffs, a light's own exponent among
+ * them, so a lamp reaches as far over water as over the ground beside it. **What it gives up**:
+ * a spot's cone, which water does not read, so a spot lights the water around it as a lamp
+ * would; and the smooth falloff's square, which the surface applies and this has never, so under
+ * that falloff a lamp's pool on water is the wider of the two.
  */
 #define MAX_LIGHTS ${MAX_POINT_LIGHTS}
 uniform int uLightCount;
@@ -187,6 +190,8 @@ uniform vec3 uLightColor[MAX_LIGHTS];
 uniform float uLightRadius[MAX_LIGHTS];
 uniform float uLightWeight[MAX_LIGHTS];
 uniform int uLightFalloff;
+/* The surface shader's cone record, of which water reads z alone: a light's own falloff exponent. */
+uniform vec4 uLightCone[MAX_LIGHTS];
 ${FOG_GLSL}
 uniform vec3 uCameraPos;
 uniform sampler2D uReflectionMap;
@@ -243,7 +248,11 @@ void main() {
     vec3 toLight = uLightPos[i] - vWorldPos;
     float lightDist = length(toLight);
     float falloff;
-    if (uLightFalloff == 1) {
+    float exponent = uLightCone[i].z;
+    if (exponent > 0.0) {
+      float reach = lightDist / max(uLightRadius[i], 1e-4);
+      falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), exponent);
+    } else if (uLightFalloff == 1) {
       float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);
       falloff = window * window / max(lightDist * lightDist, 0.01);
     } else {

package/src/render/skinBlur.ts

@@ -3,11 +3,14 @@
  * the kernel to, and nothing at run time calls it.
  *
  * **What it spreads.** With `skinScattering: 'screen-space'`, a skin draw writes its specular to the
- * frame and its diffuse — the light that went beneath the surface — to a target of its own, with the
- * profile it scatters by in the alpha. Before anything blended is drawn, that target is blurred
- * along the screen's two axes by Burley's normalised diffusion, one width per channel, and added
- * back: light that entered a cheek leaves it a centimetre away, reddest furthest, across the
- * pixels that centimetre covers at the cheek's distance. The pre-integrated fit stays in the lit
+ * frame, the light its diffuse is made of — the light that went beneath the surface, shaded on a
+ * white surface — to a target of its own with the profile it scatters by in the alpha, and its
+ * colour to a third. Before anything blended is drawn, the light is blurred along the screen's two
+ * axes by Burley's normalised diffusion, one width per channel, multiplied by the colour at each
+ * pixel and added back: light that entered a cheek leaves it a centimetre away, reddest furthest,
+ * across the pixels that centimetre covers at the cheek's distance, and a brow stays where it is
+ * drawn. **Until 4.8.6 the coloured diffuse was spread**, which smeared every mark on a face into
+ * the skin around it and laid faint copies of each mark at the taps' offsets. The pre-integrated fit stays in the lit
  * stage for what this cannot see — a terminator's curvature — and this carries what that cannot:
  * light crossing a shadow's edge, or a nostril's rim, in the picture rather than in a fit.
  *

package/src/render/skinScatter.ts

@@ -7,7 +7,9 @@
  * neighbours' `N·L` as well as its own: the clamped cosine averaged around a ring of the surface's
  * curvature, weighted by the diffusion profile at each neighbour's distance. The profile is Burley's
  * normalised diffusion, one per channel, at a scatter distance `d` — the model's `radius` times its
- * scatter colour — projected onto the ring's plane, as a cylinder's cross-section sees it. The
+ * scatter colour, over `SKIN_MEAN_EXIT`, since `radius` is how far light travels and the profile
+ * carries it two and a half `d` — projected onto the ring's plane, as a cylinder's cross-section
+ * sees it. The
  * result depends on `N·L` and on one number per channel, `k = d × curvature`, and at `k = 0` it is
  * Lambert's.
  *

package/src/render/ssrPass.ts

@@ -173,6 +173,7 @@ export class SsrPass {
       gl.uniform3fv(u['uSsrAxis'] ?? null, surface.axis);
       gl.uniform3fv(u['uSsrTint'] ?? null, surface.tint);
       gl.uniform1f(u['uSsrStrength'] ?? null, surface.strength);
+      gl.uniform2f(u['uSsrFresnel'] ?? null, surface.fresnel ? 1 : 0, surface.roughness);
       gl.uniform1f(u['uSsrFacingCos'] ?? null, surface.facingCos);
       gl.uniform1f(u['uSsrReach'] ?? null, surface.reachM);
       gl.uniform1f(u['uSsrThickness'] ?? null, surface.thicknessM);

package/src/render/surfaceModel.ts

@@ -18,6 +18,8 @@
  * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
  */
 import type { Vec3 } from '../math/color.ts';
+import { lightmapRegionOf } from './lightmap.ts';
+import type { LightmapRegion } from './lightmap.ts';
 
 /** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
 export interface AnisotropicModel {
@@ -52,7 +54,12 @@ export interface SkinModel {
   readonly kind: 'skin';
   /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
   readonly scatterColor: Vec3;
-  /** Metres: how far light travels beneath it before it leaves. */
+  /**
+   * Metres: how far light travels beneath it, on average, before it leaves — from where it entered
+   * to where it leaves, for a channel whose share of `scatterColor` is 1. Burley's profile, which
+   * the lit stage and the screen-space blur both scatter by, does that at a distance `d` two fifths
+   * of it, and carries a tail of light out to about three and a half times it.
+   */
   readonly radius: number;
   /** 0 to 1: how much a light behind a thin part shows through it. */
   readonly transmission: number;
@@ -77,8 +84,19 @@ export interface EyeModel {
   readonly joint: number;
 }
 
+/**
+ * A surface whose static light was baked: the standard model, plus a lightmap page's light read at
+ * the mesh's second coordinates (`MeshData.lightmapUvs`). The material's `modelMap` is the page,
+ * from `createLightmap`; see `lightmap.ts` for what it adds and what it gives up.
+ */
+export interface LightmapModel {
+  readonly kind: 'lightmap';
+  /** Where this material's surfaces are on the page: `uv2 * scale + bias`. See `LightmapRegion`. */
+  readonly region: LightmapRegion;
+}
+
 /** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
-export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel | LightmapModel;
 /** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
 export type SurfaceModelKind = SurfaceModel['kind'];
 
@@ -88,6 +106,7 @@ export const SURFACE_MODEL_KINDS: readonly SurfaceModelKind[] = [
   'hair',
   'skin',
   'eye',
+  'lightmap',
 ];
 
 /** The lit stage's switch for each kind. */
@@ -96,6 +115,7 @@ export const SURFACE_MODEL_SWITCH: Readonly<Record<SurfaceModelKind, string>> =
   hair: 'MODEL_HAIR',
   skin: 'MODEL_SKIN',
   eye: 'MODEL_EYE',
+  lightmap: 'MODEL_LIGHTMAP',
 };
 
 /** Floats a material's model takes: `uModelParams[2]`. */
@@ -144,7 +164,25 @@ export function hairModel(
   });
 }
 
-/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+/**
+ * How far Burley's normalised diffusion carries light on average, in units of its own distance
+ * `d`: its radial density `(e^(−r/d) + e^(−r/3d)) / 4d` has the mean `(d² + 9d²) / 4d = 2.5 d`. So a
+ * skin whose light travels `radius` scatters by a profile at `d = radius / 2.5`.
+ *
+ * **Until 4.8.7 `radius` was `d` itself**, so light travelled two and a half times as far as the
+ * model said, and the screen-space blur — whose taps reach nine `d` — spread a face at arm's length
+ * over sixty pixels: a nose, lips and brows washed into one blur where a centimetre covers a few.
+ * The lit stage's pre-integrated fit, transmission and penumbra take the same `d`, so the two paths
+ * still agree with each other.
+ */
+export const SKIN_MEAN_EXIT = 2.5;
+
+/** Burley's distance `d` for one channel of a skin, in metres: see `SKIN_MEAN_EXIT`. */
+export function skinProfileDistance(model: SkinModel, channel: 0 | 1 | 2): number {
+  return ((model.scatterColor[channel] as number) * model.radius) / SKIN_MEAN_EXIT;
+}
+
+/** Skin. The defaults are a fair skin's: red light leaving a little over a centimetre away. */
 export function skinModel(
   options: { scatterColor?: Vec3; radius?: number; transmission?: number; profile?: number } = {},
 ): SkinModel {
@@ -188,25 +226,51 @@ export function eyeModel(
   });
 }
 
+/**
+ * A baked surface, reading its region of a lightmap page: the whole page where none is named. An
+ * instanced batch's regions compose with this one, each instance's applied first: see
+ * `MeshInstances.lightmapRegions`.
+ */
+export function lightmapModel(options: { region?: LightmapRegion } = {}): LightmapModel {
+  const region = lightmapRegionOf(options.region);
+  return Object.freeze({
+    kind: 'lightmap',
+    region: Object.freeze([region[0], region[1], region[2], region[3]]) as LightmapRegion,
+  });
+}
+
 /**
  * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
- * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
- * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ * map is bound into the last. An eye's axis goes in with the descriptor's own until the draw turns
+ * it: see `eyeAxisInWorld`. `physical` is `SurfaceMaterial.physicalSpecular`, in the lane the
+ * models that read it leave free; skin, hair and the eye shade their own highlights and never do.
  *
- * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - standard (null): − · −, −, physical, −
+ * - anisotropic: strength, cos and sin of the rotation · −, −, physical, map
  * - hair: shift, scatter, backlit, − · −, −, −, map
- * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - skin: the scatter colour, radius / `SKIN_MEAN_EXIT` · transmission, profile, −, map
  * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ * - lightmap: the region's scale and bias · −, −, physical, map
  */
-export function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void {
+export function packModel(
+  model: SurfaceModel | null,
+  mapped: boolean,
+  out: Float32Array,
+  physical = false,
+): void {
   out.fill(0);
-  if (model === null) return;
+  const highlight = physical ? 1 : 0;
+  if (model === null) {
+    out[6] = highlight;
+    return;
+  }
   out[7] = mapped ? 1 : 0;
   switch (model.kind) {
     case 'anisotropic':
       out[0] = model.strength;
       out[1] = Math.cos(model.rotation);
       out[2] = Math.sin(model.rotation);
+      out[6] = highlight;
       return;
     case 'hair':
       out[0] = model.shift;
@@ -217,7 +281,8 @@ export function packModel(model: SurfaceModel | null, mapped: boolean, out: Floa
       out[0] = model.scatterColor[0];
       out[1] = model.scatterColor[1];
       out[2] = model.scatterColor[2];
-      out[3] = model.radius;
+      /* Burley's distance for a channel of share 1, which the shader scales by each share. */
+      out[3] = model.radius / SKIN_MEAN_EXIT;
       out[4] = model.transmission;
       out[5] = model.profile;
       return;
@@ -230,6 +295,13 @@ export function packModel(model: SurfaceModel | null, mapped: boolean, out: Floa
       out[5] = model.axis[1];
       out[6] = model.axis[2];
       return;
+    case 'lightmap':
+      out[0] = model.region[0];
+      out[1] = model.region[1];
+      out[2] = model.region[2];
+      out[3] = model.region[3];
+      out[6] = highlight;
+      return;
   }
 }