@driftengine/core 4.5.0 → 4.6.1

package/dist/render/shaders/recon/resolve.wgsl.js

@@ -34,12 +34,16 @@
  * fn reconMotion(x: i32, y: i32) -> vec4<f32>         // uv, previous view depth, flag
  * fn reconHistory(x: i32, y: i32) -> vec4<f32>        // output size, colour and gathered weight
  * fn reconHistoryBilinear(p: vec2<f32>) -> vec4<f32>
+ * fn reconFlicker(x: i32, y: i32) -> vec4<f32>        // output size, last frame's flicker record
+ * fn reconSwing(x: i32, y: i32) -> f32                // output size, last frame's held depth swing
  * ```
  *
  * and the uniform `recon: ReconParams`, whose struct this module declares.
  */
 import { wgslSceneDepthToNdc } from '../../depthConvention.js';
 import { PLANAR_FROM, PLANAR_TO } from '../../recon/disocclusion.js';
+import { DEPTH_SWING_WIDTH } from '../../recon/resolve.js';
+import { FLICKER_BLEND, FLICKER_REPEAT, STILL_FROM, STILL_TO } from '../../temporalAa.js';
 /**
  * The parameters one resolve reads, as `ResolveFrame` minus its images.
  *
@@ -65,10 +69,15 @@ struct ReconParams {
   motionScale: f32,
   normalFloor: f32,
   normalCeiling: f32,
+  periodStart: u32,
+  antiFlicker: u32,
+  flickerMemory: f32,
+  flickerWidth: f32,
+  reprojection: mat4x4<f32>,
 }
 `;
 /** Floats in `ReconParams`, which is what a caller sizes its uniform buffer by. */
-export const RECON_PARAM_FLOATS = 72;
+export const RECON_PARAM_FLOATS = 92;
 /** `SAMPLE_SPREAD` and `CONFIDENT_WEIGHT`, which the reference exports and this must not restate. */
 export const RECON_SAMPLE_SPREAD = 0.47;
 export const RECON_CONFIDENT_WEIGHT = 1;
@@ -85,8 +94,8 @@ export const RECON_WORKGROUP = 8;
  */
 export const RECON_HISTORY_FORMAT = 'rgba16float';
 /**
- * The arithmetic, as text. Defines `reconResolvePixel(ox, oy) -> vec4<f32>` — the next history's
- * colour and the weight it has gathered — and `reconSharpenAt(ox, oy) -> vec3<f32>`, the picture
+ * The arithmetic, as text. Defines `reconResolvePixel(ox, oy) -> ReconResolved` — the next
+ * history's colour and the weight it has gathered, and the pixel's next flicker record — and `reconSharpenAt(ox, oy) -> vec3<f32>`, the picture
  * shown, which reads the history the first has already written.
  */
 export const RECON_RESOLVE_CORE_WGSL = /* wgsl */ `
@@ -94,6 +103,11 @@ const RECON_SAMPLE_SPREAD: f32 = ${RECON_SAMPLE_SPREAD};
 const RECON_CONFIDENT_WEIGHT: f32 = ${RECON_CONFIDENT_WEIGHT}.0;
 const RECON_PLANAR_FROM: f32 = ${PLANAR_FROM};
 const RECON_PLANAR_TO: f32 = ${PLANAR_TO};
+const RECON_FLICKER_BLEND: f32 = ${FLICKER_BLEND};
+const RECON_FLICKER_REPEAT: f32 = ${FLICKER_REPEAT};
+const RECON_STILL_FROM: f32 = ${STILL_FROM};
+const RECON_STILL_TO: f32 = ${STILL_TO};
+const RECON_DEPTH_SWING_WIDTH: f32 = ${DEPTH_SWING_WIDTH}.0;
 
 fn reconClampTexel(value: i32, size: i32) -> i32 {
   return clamp(value, 0, size - 1);
@@ -461,6 +475,10 @@ fn reconSurfaceAt(previous: bool, x: i32, y: i32, centre: f32) -> ReconSurface {
 struct ReconHistory {
   weight: f32,
   colour: vec4<f32>,
+  /* How far the surface moved, in output pixels; read only where the weight is not zero. */
+  moved: f32,
+  /* How far, relative, last frame's depth missed the one expected there; -1 where none was held. */
+  missed: f32,
 }
 
 /*
@@ -468,10 +486,12 @@ struct ReconHistory {
  * behind last frame's eye or off its picture, and otherwise what it gathered, scaled by whether it
  * is the same surface.
  */
-fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
+fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32, swing: f32) -> ReconHistory {
   var out: ReconHistory;
   out.weight = 0.0;
   out.colour = vec4<f32>(0.0);
+  out.moved = 0.0;
+  out.missed = -1.0;
   if (recon.hasHistory == 0u) { return out; }
   let rw = f32(recon.renderSize.x);
   let rh = f32(recon.renderSize.y);
@@ -484,20 +504,24 @@ fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
     mv = motion.y;
     expected = motion.z;
   } else {
-    let here = reconWorldAt(false, dx, dy);
-    if (!(here.depth > 0.0)) { return out; }
-    let clip = recon.previousViewProj * vec4<f32>(here.position, 1.0);
+    /* Through the one reprojection matrix the renderer multiplied: see resolve.ts. */
+    let du = (f32(dx) + 0.5 - recon.jitter.x) / rw;
+    let dv = (f32(dy) + 0.5 - recon.jitter.y) / rh;
+    let ndc = vec4<f32>(du * 2.0 - 1.0, dv * 2.0 - 1.0, reconDepth(dx, dy), 1.0);
+    let m = recon.inverseViewProj;
+    let hw = m[0][3] * ndc.x + m[1][3] * ndc.y + m[2][3] * ndc.z + m[3][3];
+    if (!(hw > 1e-12)) { return out; }
+    let clip = recon.reprojection * ndc;
     /*
      * A surface behind last frame's eye has a w that is not positive: the disocclusion trusts no
      * such depth, so it needs no refusal of its own here.
      */
-    expected = clip.w;
-    let du = (f32(dx) + 0.5 - recon.jitter.x) / rw;
-    let dv = (f32(dy) + 0.5 - recon.jitter.y) / rh;
-    mu = (clip.x / expected) * 0.5 + 0.5 - du;
-    mv = (clip.y / expected) * 0.5 + 0.5 - dv;
+    expected = clip.w / hw;
+    mu = (clip.x / clip.w) * 0.5 + 0.5 - du;
+    mv = (clip.y / clip.w) * 0.5 + 0.5 - dv;
   }
 
+  out.moved = length(vec2<f32>(mu * f32(recon.outputSize.x), mv * f32(recon.outputSize.y)));
   let pu = u + mu;
   let pv = v + mv;
   if (!(pu >= 0.0 && pu <= 1.0 && pv >= 0.0 && pv <= 1.0)) { return out; }
@@ -544,13 +568,41 @@ fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
       normalDot = 1.0 - planar * (1.0 - dot(hereNormal.normal, thereNormal.normal));
     }
   }
-  let trust = reconDisocclusion(expected, held, length(vec2<f32>(mu, mv)), normalDot, here.slope);
+  if (held > 0.0 && expected > 0.0) { out.missed = abs(held - expected) / expected; }
+  /* A still pixel's own held depth swing: see resolve.ts. */
+  var swung = 0.0;
+  if (swing > 0.0) {
+    swung = RECON_DEPTH_SWING_WIDTH * swing *
+      (1.0 - reconSmoothstep(RECON_STILL_FROM, RECON_STILL_TO, out.moved));
+  }
+  let trust = reconDisocclusion(
+    expected,
+    held,
+    length(vec2<f32>(mu, mv)),
+    normalDot,
+    here.slope + swung,
+  );
   out.weight = out.colour.w * trust;
   return out;
 }
 
-/* One output pixel: the history's next colour, before sharpening, and the weight it has gathered. */
-fn reconResolvePixel(ox: i32, oy: i32) -> vec4<f32> {
+/* temporalAa.ts's repeats: whether two periods' means are the same, one to zero. */
+fn reconRepeats(mean: f32, previous: f32) -> f32 {
+  let apart = abs(mean - previous) / max(max(mean, previous), 1.0 / 255.0);
+  return 1.0 - reconSmoothstep(RECON_FLICKER_REPEAT, 2.0 * RECON_FLICKER_REPEAT, apart);
+}
+
+struct ReconResolved {
+  /* The history's next colour, before sharpening, and the weight it has gathered. */
+  colour: vec4<f32>,
+  /* The pixel's next flicker record: spread, this period's sum, last period's mean, repeats. */
+  record: vec4<f32>,
+  /* And its next held depth swing. */
+  swing: f32,
+}
+
+/* One output pixel: the history's next colour and weight, and its next flicker record. */
+fn reconResolvePixel(ox: i32, oy: i32) -> ReconResolved {
   let rw = i32(recon.renderSize.x);
   let rh = i32(recon.renderSize.y);
   let ow = i32(recon.outputSize.x);
@@ -598,18 +650,68 @@ fn reconResolvePixel(ox: i32, oy: i32) -> vec4<f32> {
   accum = accum / gathered;
 
   /* The history, and the weight it still deserves; a tenth of each frame is always new. */
-  let cap = (1.0 - recon.alpha) / recon.alpha;
-  let history = reconHistoryWeight(u, v, dx, dy);
+  var swing = 0.0;
+  if (recon.antiFlicker != 0u) { swing = reconSwing(ox, oy); }
+  let history = reconHistoryWeight(u, v, dx, dy, swing);
+  var cap = (1.0 - recon.alpha) / recon.alpha;
+  var low = box.low;
+  var high = box.high;
+  var out: ReconResolved;
+  out.record = vec4<f32>(0.0);
+  out.swing = 0.0;
+  /* The anti-flicker, operation for operation resolve.ts's: see temporalAa.ts. */
+  if (recon.antiFlicker != 0u) {
+    let seen = dot(accum, vec3<f32>(0.2126, 0.7152, 0.0722));
+    let memory = recon.flickerMemory;
+    let width = recon.flickerWidth;
+    var held = vec4<f32>(0.0, seen * memory, seen, 0.0);
+    if (history.weight > 0.0) { held = reconFlicker(ox, oy); }
+    var still = 0.0;
+    if (history.weight > 0.0) {
+      still = 1.0 - reconSmoothstep(RECON_STILL_FROM, RECON_STILL_TO, history.moved);
+    }
+    let apart = abs(seen - held.z);
+    let within = apart <= width * held.x + 1.0 / 255.0;
+    let proven = held.w > 0.75 && within;
+    var widen = 0.0;
+    let base = 1.0 - recon.alpha;
+    var keep = base;
+    if (proven) {
+      widen = width * held.x * still;
+      keep = base + (RECON_FLICKER_BLEND - base) * still;
+    }
+    low = low - vec3<f32>(widen);
+    high = high + vec3<f32>(widen);
+    cap = keep / (1.0 - keep);
+    var sum = held.y;
+    var mean = held.z;
+    var repeated = 0.0;
+    if (within) { repeated = held.w; }
+    if (recon.periodStart != 0u) {
+      if (reconRepeats(sum, mean) > 0.5) { repeated = min(1.0, repeated + 0.5); } else { repeated = 0.0; }
+      mean = sum;
+      sum = 0.0;
+    }
+    out.record = vec4<f32>(
+      held.x + (apart - held.x) * memory,
+      sum + seen * memory,
+      mean,
+      repeated * still,
+    );
+    /* The peak carried on, halving over a period, whatever the test said. */
+    if (history.missed >= 0.0) { out.swing = max(history.missed, swing * pow(0.5, memory)); }
+  }
   let kept = min(cap, history.weight);
 
   let total = kept + gathered;
   var mixed = accum;
   if (kept > 0.0) {
-    let clipped = reconClipToBox(reconToYCoCg(history.colour.xyz), box.low, box.high);
+    let clipped = reconClipToBox(reconToYCoCg(history.colour.xyz), low, high);
     mixed = reconAccumulate(accum, reconFromYCoCg(clipped), 1.0, gathered / total);
   }
   let known = min(1.0, total / RECON_CONFIDENT_WEIGHT);
-  return vec4<f32>(sample * (1.0 - known) + mixed * known, total);
+  out.colour = vec4<f32>(sample * (1.0 - known) + mixed * known, total);
+  return out;
 }
 
 /*
@@ -648,8 +750,9 @@ fn reconSharpenAt(ox: i32, oy: i32) -> vec3<f32> {
  * doing its own bilinear so the comparison is arithmetic rather than a tolerance on the device's
  * sampler.
  *
- * Two entry points over one set of bindings. `resolveMain` writes four floats a pixel — the next
- * history — and `sharpenMain` reads that history back at binding 4 and writes three.
+ * Two entry points over one set of bindings. `resolveMain` writes nine floats a pixel — the next
+ * history, the next flicker record and the next depth swing — and `sharpenMain` reads that history back at binding 4
+ * and writes three.
  */
 export function reconResolveParityWgsl() {
     return /* wgsl */ `
@@ -661,6 +764,16 @@ export function reconResolveParityWgsl() {
 ${RECON_PARAMS_WGSL}
 @group(0) @binding(5) var<uniform> recon: ReconParams;
 @group(0) @binding(6) var<storage, read_write> output: array<f32>;
+@group(0) @binding(7) var flickerTexture: texture_2d<f32>;
+@group(0) @binding(8) var swingTexture: texture_2d<f32>;
+
+fn reconFlicker(x: i32, y: i32) -> vec4<f32> {
+  return textureLoad(flickerTexture, vec2<i32>(x, y), 0);
+}
+
+fn reconSwing(x: i32, y: i32) -> f32 {
+  return textureLoad(swingTexture, vec2<i32>(x, y), 0).x;
+}
 
 fn reconScene(x: i32, y: i32) -> vec3<f32> {
   return textureLoad(sceneTexture, vec2<i32>(x, y), 0).xyz;
@@ -718,11 +831,16 @@ ${RECON_RESOLVE_CORE_WGSL}
 fn resolveMain(@builtin(global_invocation_id) id: vec3<u32>) {
   if (id.x >= recon.outputSize.x || id.y >= recon.outputSize.y) { return; }
   let value = reconResolvePixel(i32(id.x), i32(id.y));
-  let at = (id.y * recon.outputSize.x + id.x) * 4u;
-  output[at] = value.x;
-  output[at + 1u] = value.y;
-  output[at + 2u] = value.z;
-  output[at + 3u] = value.w;
+  let at = (id.y * recon.outputSize.x + id.x) * 9u;
+  output[at] = value.colour.x;
+  output[at + 1u] = value.colour.y;
+  output[at + 2u] = value.colour.z;
+  output[at + 3u] = value.colour.w;
+  output[at + 4u] = value.record.x;
+  output[at + 5u] = value.record.y;
+  output[at + 6u] = value.record.z;
+  output[at + 7u] = value.record.w;
+  output[at + 8u] = value.swing;
 }
 
 @compute @workgroup_size(${RECON_WORKGROUP}, ${RECON_WORKGROUP})
@@ -772,6 +890,12 @@ ${RECON_PARAMS_WGSL}
 @group(0) @binding(6) var<uniform> recon: ReconParams;
 @group(0) @binding(7) var resolved: texture_storage_2d<rgba16float, write>;
 /* Not "target": it is a reserved keyword in WGSL, as "meta" was in the cluster cull. */
+/* Last frame's flicker records, and where this frame's go: a pair beside the histories. */
+@group(0) @binding(8) var flickerTexture: texture_2d<f32>;
+@group(0) @binding(9) var flickerOut: texture_storage_2d<rgba16float, write>;
+/* And each pixel's held depth swing, a pair of its own. */
+@group(0) @binding(10) var swingTexture: texture_2d<f32>;
+@group(0) @binding(11) var swingOut: texture_storage_2d<r32float, write>;
 
 /* Rows flip here: the reference's row 0 is the bottom one and a texture's is the top. */
 fn reconRenderRow(y: i32) -> i32 {
@@ -804,6 +928,14 @@ fn reconHistory(x: i32, y: i32) -> vec4<f32> {
   return textureLoad(historyTexture, vec2<i32>(x, reconOutputRow(y)), 0);
 }
 
+fn reconFlicker(x: i32, y: i32) -> vec4<f32> {
+  return textureLoad(flickerTexture, vec2<i32>(x, reconOutputRow(y)), 0);
+}
+
+fn reconSwing(x: i32, y: i32) -> f32 {
+  return textureLoad(swingTexture, vec2<i32>(x, reconOutputRow(y)), 0).x;
+}
+
 /* A texel coordinate becomes the uv of its centre, with the row taken from the other end. */
 fn reconSceneBilinear(p: vec2<f32>) -> vec3<f32> {
   let size = vec2<f32>(f32(recon.renderSize.x), f32(recon.renderSize.y));
@@ -823,7 +955,9 @@ fn resolveMain(@builtin(global_invocation_id) id: vec3<u32>) {
   if (id.x >= recon.outputSize.x || id.y >= recon.outputSize.y) { return; }
   let y = i32(recon.outputSize.y) - 1 - i32(id.y);
   let value = reconResolvePixel(i32(id.x), y);
-  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), value);
+  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), value.colour);
+  textureStore(flickerOut, vec2<i32>(i32(id.x), i32(id.y)), value.record);
+  textureStore(swingOut, vec2<i32>(i32(id.x), i32(id.y)), vec4<f32>(value.swing, 0.0, 0.0, 0.0));
 }
 
 @compute @workgroup_size(${RECON_WORKGROUP}, ${RECON_WORKGROUP})

package/dist/render/shaders/rush.js

@@ -102,6 +102,16 @@ uniform float uMotionMax;
  */
 uniform sampler2D uAo;
 uniform float uAoStrength;
+/**
+ * Where this frame's jitter put the picture the occlusion was measured from, in this pass's uv.
+ *
+ * The occlusion is measured from the frame's own depth, which a temporal resolve or a
+ * reconstruction jittered, and it is applied here to a picture those have already taken the jitter
+ * out of — so read at the pixel's own uv it moved by the jitter every frame, and every crevice
+ * shimmered by up to half a render texel. Read where the jitter put it, it holds still. Zero for an
+ * unjittered frame.
+ */
+uniform vec2 uAoOffset;
 
 /**
  * The bloom chain's top level, already thresholded, blurred and summed by its own pass.
@@ -339,7 +349,7 @@ void main() {
    * strength, so the parameter reads as "how much of this occlusion", and 0 is exactly the
    * frame that existed before the effect did.
    */
-  float ao = mix(1.0, textureLod(uAo, vUv, 0.0).r, uAoStrength);
+  float ao = mix(1.0, textureLod(uAo, vUv + uAoOffset, 0.0).r, uAoStrength);
 
   /*
    * Distance from the centre, corrected so the falloff is a circle on screen rather than

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

@@ -6,4 +6,4 @@
  * the alpha test is not uniform control flow.
  */
 export declare const SDF_TEXT_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec2 aUv;\n\nuniform mat4 uViewProj;\nuniform mat4 uModel;\n\nout vec2 vUv;\n\nvoid main() {\n  vUv = aUv;\n  gl_Position = uViewProj * uModel * vec4(aPosition, 1.0);\n}\n";
-export declare const SDF_TEXT_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uAtlas;\nuniform vec3 uColor;\nuniform float uOpacity;\n/* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */\nuniform float uDistanceRange;\nuniform vec2 uAtlasSize;\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  return linearToSrgb(c);\n}\n\n\n/*\n * The middle of the three channels.\n *\n * A single-channel field rounds every corner off at small sizes, because one distance\n * cannot describe two edges meeting. Three channels carry the corner and the median\n * recovers it.\n */\nfloat median(vec3 rgb) {\n  return max(min(rgb.r, rgb.g), min(max(rgb.r, rgb.g), rgb.b));\n}\n\nvoid main() {\n  vec3 sampled = textureLod(uAtlas, vUv, 0.0).rgb;\n  float distance = median(sampled) - 0.5;\n\n  /*\n   * The band is one pixel wide *in screen space*, which is what lets one atlas serve every\n   * size. A constant band is tuned for one size and is wrong at all the others.\n   */\n  vec2 texelsPerPixel = fwidth(vUv) * uAtlasSize;\n  float pixelRange = max(0.5 * (texelsPerPixel.x + texelsPerPixel.y), 0.0001);\n  float coverage = clamp(distance * uDistanceRange / pixelRange + 0.5, 0.0, 1.0);\n\n  outColor = vec4(applyOutputTransform(uColor), coverage * uOpacity);\n}\n";
+export declare const SDF_TEXT_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\n/* An array of one: every surface texture is an array, and an atlas is read at layer 0. */\nuniform mediump sampler2DArray uAtlas;\nuniform vec3 uColor;\nuniform float uOpacity;\n/* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */\nuniform float uDistanceRange;\nuniform vec2 uAtlasSize;\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  return linearToSrgb(c);\n}\n\n\n/*\n * The middle of the three channels.\n *\n * A single-channel field rounds every corner off at small sizes, because one distance\n * cannot describe two edges meeting. Three channels carry the corner and the median\n * recovers it.\n */\nfloat median(vec3 rgb) {\n  return max(min(rgb.r, rgb.g), min(max(rgb.r, rgb.g), rgb.b));\n}\n\nvoid main() {\n  vec3 sampled = textureLod(uAtlas, vec3(vUv, 0.0), 0.0).rgb;\n  float distance = median(sampled) - 0.5;\n\n  /*\n   * The band is one pixel wide *in screen space*, which is what lets one atlas serve every\n   * size. A constant band is tuned for one size and is wrong at all the others.\n   */\n  vec2 texelsPerPixel = fwidth(vUv) * uAtlasSize;\n  float pixelRange = max(0.5 * (texelsPerPixel.x + texelsPerPixel.y), 0.0001);\n  float coverage = clamp(distance * uDistanceRange / pixelRange + 0.5, 0.0, 1.0);\n\n  outColor = vec4(applyOutputTransform(uColor), coverage * uOpacity);\n}\n";

package/dist/render/shaders/sdfText.js

@@ -27,7 +27,8 @@ precision highp float;
 
 in vec2 vUv;
 
-uniform sampler2D uAtlas;
+/* An array of one: every surface texture is an array, and an atlas is read at layer 0. */
+uniform mediump sampler2DArray uAtlas;
 uniform vec3 uColor;
 uniform float uOpacity;
 /* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */
@@ -49,7 +50,7 @@ float median(vec3 rgb) {
 }
 
 void main() {
-  vec3 sampled = textureLod(uAtlas, vUv, 0.0).rgb;
+  vec3 sampled = textureLod(uAtlas, vec3(vUv, 0.0), 0.0).rgb;
   float distance = median(sampled) - 0.5;
 
   /*

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

@@ -13,5 +13,5 @@
  * gameplay camera is doing — but it still wants perspective, or a rotating
  * letter shears instead of turning.
  */
-export declare const TEXT_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aCorner;\nlayout(location = 1) in vec3 aNormal;\n/** Cell position in pixels, relative to the string's origin. */\nlayout(location = 2) in vec2 aCell;\n/** Which character this cell belongs to, for staggered animation. */\nlayout(location = 3) in float aCharIndex;\n\nuniform vec2 uViewport;\n/** Where the string's baseline-left sits, in pixels from the top left. */\nuniform vec2 uOrigin;\nuniform float uCellSize;\n/** Distance from the virtual camera; larger flattens the perspective. */\nuniform float uDepth;\n\n/** 0 before a character has arrived, 1 once it has settled. */\nuniform float uReveal;\n/** How many characters the stagger spans \u2014 the whole line, not this piece. */\nuniform float uCharCount;\n/**\n * Where this piece starts within that line.\n *\n * A line drawn in several pieces \u2014 words around a keycap \u2014 must stagger as one\n * sentence. Without this each piece restarts at zero, so the second word begins\n * arriving before the first has finished and they sit at different heights\n * through the whole animation.\n */\nuniform float uCharOffset;\n/** Radians of entry rotation, decaying to zero as a character settles. */\nuniform float uSpin;\n/** Extra scale at the moment of arrival \u2014 the overshoot. */\nuniform float uPunch;\n/** Vertical bob amplitude in pixels, and its phase. */\nuniform float uBob;\nuniform float uTime;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * This draw builds its own clip position from pixels and never multiplies by a camera, so\n * the correction every other draw carries in its view-projection cannot reach it \u2014 the same\n * gap that left the sky unprojecting through the wrong space. Two things are wrong without\n * it on WebGPU, and only one of them is visible: the generated vertex shader negates Y, so\n * the message renders upside down; and z here is a narrow slice about zero, which is inside\n * OpenGL's [-1, 1] and *outside* WebGPU's [0, 1], so half of every glyph is clipped away.\n */\nuniform mat4 uClipCorrection;\n\nout vec3 vNormal;\nout float vDepth;\nout float vChar;\n\n/**\n * Spring settle: overshoots once and comes back.\n *\n * A character that eases into place reads as an element appearing; one that\n * overshoots and settles reads as an object arriving. That difference is most\n * of what makes text feel like part of a game rather than part of a page.\n */\nfloat settle(float t) {\n  if (t <= 0.0) return 0.0;\n  if (t >= 1.0) return 1.0;\n  float d = 1.0 - t;\n  return 1.0 - d * d * cos(t * 12.0) ;\n}\n\nmat2 rot(float a) {\n  float s = sin(a);\n  float c = cos(a);\n  return mat2(c, -s, s, c);\n}\n\nvoid main() {\n  // Stagger: each character starts a fraction of the reveal later than the\n  // one before it, so the message assembles left to right.\n  float span = max(uCharCount, 1.0);\n  float start = ((aCharIndex + uCharOffset) / span) * 0.55;\n  float local = clamp((uReveal - start) / max(0.45, 1.0 - start), 0.0, 1.0);\n  float eased = settle(local);\n\n  // Arrives spinning about its own horizontal axis and dropping into place.\n  float spin = uSpin * (1.0 - eased);\n  float rise = (1.0 - eased) * uCellSize * 6.0;\n  float punch = 1.0 + uPunch * (1.0 - abs(eased * 2.0 - 1.0));\n\n  vec3 local3 = aCorner * uCellSize * 0.5 * punch;\n  local3.yz = rot(spin) * local3.yz;\n\n  vec2 cell = aCell * uCellSize;\n  float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;\n\n  // Pixels, y down from the top-left corner of the viewport.\n  vec2 screen = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);\n  vec3 view = vec3(screen + local3.xy, -uDepth + local3.z);\n\n  // A hand-built perspective divide. The near plane is the viewport itself, so\n  // a cell at depth uDepth is exactly its pixel size on screen.\n  float invDepth = uDepth / max(0.001, -view.z);\n  vec2 ndc = ((view.xy * invDepth) / uViewport) * 2.0 - 1.0;\n  // Depth from the cube's own extrusion, mapped into a narrow slice of the\n  // range so a message sorts against itself without ever reaching the scene.\n  float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;\n  gl_Position = uClipCorrection * vec4(ndc.x, -ndc.y, depth, 1.0);\n\n  vec3 n = aNormal;\n  n.yz = rot(spin) * n.yz;\n  vNormal = n;\n  vDepth = local3.z;\n  vChar = eased;\n}";
+export declare const TEXT_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aCorner;\nlayout(location = 1) in vec3 aNormal;\n/** Cell position in pixels, relative to the string's origin. */\nlayout(location = 2) in vec2 aCell;\n/** Which character this cell belongs to, for staggered animation. */\nlayout(location = 3) in float aCharIndex;\n\nuniform vec2 uViewport;\n/** Where the string's baseline-left sits, in pixels from the top left. */\nuniform vec2 uOrigin;\nuniform float uCellSize;\n/** How far each cell is seen from, head-on; larger flattens the perspective. */\nuniform float uDepth;\n\n/** 0 before a character has arrived, 1 once it has settled. */\nuniform float uReveal;\n/** How many characters the stagger spans \u2014 the whole line, not this piece. */\nuniform float uCharCount;\n/**\n * Where this piece starts within that line.\n *\n * A line drawn in several pieces \u2014 words around a keycap \u2014 must stagger as one\n * sentence. Without this each piece restarts at zero, so the second word begins\n * arriving before the first has finished and they sit at different heights\n * through the whole animation.\n */\nuniform float uCharOffset;\n/** Radians of entry rotation, decaying to zero as a character settles. */\nuniform float uSpin;\n/** Extra scale at the moment of arrival \u2014 the overshoot. */\nuniform float uPunch;\n/** Vertical bob amplitude in pixels, and its phase. */\nuniform float uBob;\nuniform float uTime;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * This draw builds its own clip position from pixels and never multiplies by a camera, so\n * the correction every other draw carries in its view-projection cannot reach it \u2014 the same\n * gap that left the sky unprojecting through the wrong space. Two things are wrong without\n * it on WebGPU, and only one of them is visible: the generated vertex shader negates Y, so\n * the message renders upside down; and z here is a narrow slice about zero, which is inside\n * OpenGL's [-1, 1] and *outside* WebGPU's [0, 1], so half of every glyph is clipped away.\n */\nuniform mat4 uClipCorrection;\n\nout vec3 vNormal;\nout float vDepth;\nout float vChar;\n\n/**\n * Spring settle: overshoots once and comes back.\n *\n * A character that eases into place reads as an element appearing; one that\n * overshoots and settles reads as an object arriving. That difference is most\n * of what makes text feel like part of a game rather than part of a page.\n */\nfloat settle(float t) {\n  if (t <= 0.0) return 0.0;\n  if (t >= 1.0) return 1.0;\n  float d = 1.0 - t;\n  return 1.0 - d * d * cos(t * 12.0) ;\n}\n\nmat2 rot(float a) {\n  float s = sin(a);\n  float c = cos(a);\n  return mat2(c, -s, s, c);\n}\n\nvoid main() {\n  // Stagger: each character starts a fraction of the reveal later than the\n  // one before it, so the message assembles left to right.\n  float span = max(uCharCount, 1.0);\n  float start = ((aCharIndex + uCharOffset) / span) * 0.55;\n  float local = clamp((uReveal - start) / max(0.45, 1.0 - start), 0.0, 1.0);\n  float eased = settle(local);\n\n  // Arrives spinning about its own horizontal axis and dropping into place.\n  float spin = uSpin * (1.0 - eased);\n  float rise = (1.0 - eased) * uCellSize * 6.0;\n  float punch = 1.0 + uPunch * (1.0 - abs(eased * 2.0 - 1.0));\n\n  vec3 local3 = aCorner * uCellSize * 0.5 * punch;\n  local3.yz = rot(spin) * local3.yz;\n\n  vec2 cell = aCell * uCellSize;\n  float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;\n\n  // The cell's centre in pixels, y down from the top-left corner of the viewport.\n  vec2 centre = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);\n\n  // A hand-built perspective divide about the cell's own centre, so every cube\n  // is seen head-on: its front face at depth zero is exactly its cell, and at\n  // rest its sides are behind it wherever on the screen it is drawn.\n  //\n  // It divided about the viewport's top-left corner until 2026-09-30, which\n  // shifted a front face by its distance from that corner times z / uDepth and\n  // showed the side it uncovered. Near the corner that was nothing; across the\n  // screen it widened every stroke by up to a pixel either side and closed the\n  // one-cell gaps a 5x7 face reads by. What this gives up is the extruded look\n  // text far from the corner had at rest; what would make it wrong is a caller\n  // wanting that look, which is then one offset for every cell, not a position.\n  float invDepth = uDepth / max(0.001, uDepth - local3.z);\n  vec2 screen = centre + local3.xy * invDepth;\n  vec2 ndc = (screen / uViewport) * 2.0 - 1.0;\n  // Depth from the cube's own extrusion, mapped into a narrow slice of the\n  // range so a message sorts against itself without ever reaching the scene.\n  float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;\n  gl_Position = uClipCorrection * vec4(ndc.x, -ndc.y, depth, 1.0);\n\n  vec3 n = aNormal;\n  n.yz = rot(spin) * n.yz;\n  vNormal = n;\n  vDepth = local3.z;\n  vChar = eased;\n}";
 export declare const TEXT_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vNormal;\nin float vDepth;\nin float vChar;\n\nuniform vec3 uColor;\n/** Self-illumination on top of the shaded colour. */\nuniform float uGlow;\nuniform float uAlpha;\n\nout vec4 fragColor;\n\nvoid main() {\n  /*\n   * A fixed key light rather than the world's. Text has to stay legible at\n   * midnight and at noon, and lighting it with the scene would make a\n   * notification unreadable on exactly the night runs where it matters most.\n   * The light only exists to give the cubes an edge.\n   */\n  vec3 key = normalize(vec3(-0.35, 0.7, 0.6));\n  float lambert = 0.55 + 0.45 * max(dot(normalize(vNormal), key), 0.0);\n\n  vec3 lit = uColor * lambert;\n  // The glow rides the arrival: brightest as a character lands, settling after.\n  vec3 emissive = uColor * uGlow * (0.45 + 0.55 * vChar);\n  fragColor = vec4(lit + emissive, uAlpha);\n}";

package/dist/render/shaders/text.js

@@ -27,7 +27,7 @@ uniform vec2 uViewport;
 /** Where the string's baseline-left sits, in pixels from the top left. */
 uniform vec2 uOrigin;
 uniform float uCellSize;
-/** Distance from the virtual camera; larger flattens the perspective. */
+/** How far each cell is seen from, head-on; larger flattens the perspective. */
 uniform float uDepth;
 
 /** 0 before a character has arrived, 1 once it has settled. */
@@ -105,14 +105,23 @@ void main() {
   vec2 cell = aCell * uCellSize;
   float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;
 
-  // Pixels, y down from the top-left corner of the viewport.
-  vec2 screen = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);
-  vec3 view = vec3(screen + local3.xy, -uDepth + local3.z);
-
-  // A hand-built perspective divide. The near plane is the viewport itself, so
-  // a cell at depth uDepth is exactly its pixel size on screen.
-  float invDepth = uDepth / max(0.001, -view.z);
-  vec2 ndc = ((view.xy * invDepth) / uViewport) * 2.0 - 1.0;
+  // The cell's centre in pixels, y down from the top-left corner of the viewport.
+  vec2 centre = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);
+
+  // A hand-built perspective divide about the cell's own centre, so every cube
+  // is seen head-on: its front face at depth zero is exactly its cell, and at
+  // rest its sides are behind it wherever on the screen it is drawn.
+  //
+  // It divided about the viewport's top-left corner until 2026-09-30, which
+  // shifted a front face by its distance from that corner times z / uDepth and
+  // showed the side it uncovered. Near the corner that was nothing; across the
+  // screen it widened every stroke by up to a pixel either side and closed the
+  // one-cell gaps a 5x7 face reads by. What this gives up is the extruded look
+  // text far from the corner had at rest; what would make it wrong is a caller
+  // wanting that look, which is then one offset for every cell, not a position.
+  float invDepth = uDepth / max(0.001, uDepth - local3.z);
+  vec2 screen = centre + local3.xy * invDepth;
+  vec2 ndc = (screen / uViewport) * 2.0 - 1.0;
   // Depth from the cube's own extrusion, mapped into a narrow slice of the
   // range so a message sorts against itself without ever reaching the scene.
   float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;

package/dist/render/surfaceEffects.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What each layer of a surface array does beyond its picture: rooms behind its windows, windows that
+ * light by night, wear, animation, and whether rain wets it.
+ *
+ * **Per layer, because a city region is one mesh.** Its facades are told apart by the layer each
+ * vertex carries (`MeshData.layers`), so an effect's parameters cannot be a per-draw uniform — two facades of one
+ * draw would share them. They are a table beside the array, six texels a layer, read at the vertex's
+ * layer with `texelFetch`, and they bind whenever the array does.
+ *
+ * **Everything off is all zeros**, so a layer a scene names no effect for — and every layer of an
+ * array given no table — costs the shader one size query and nothing else.
+ *
+ * Layout, six RGBA texels a layer, half floats on the GPU (every whole number here is under 2,048,
+ * which a half holds exactly):
+ * - 0: window cells across and up, glass mask (1: glass where the albedo's alpha is 0), seed;
+ * - 1: room layer (0: none; the layer plus one), room depth (0 to 1 of a cell), share of rooms lit,
+ *      window glow;
+ * - 2: window colour, then 1 where rain leaves the surface dry;
+ * - 3: dust, grime, streaks, the metres over which wear fades out with distance (0: never);
+ * - 4: scroll along u and v in repeats a second, pulse rate in hertz, pulse depth;
+ * - 5: flicker, flipbook frames, flipbook frames a second, the metres past which emission fades
+ *      (0: never).
+ */
+/** Texels a layer takes in the table. */
+export declare const SURFACE_EFFECT_TEXELS = 6;
+export interface SurfaceLayerEffect {
+    /**
+     * Windows across and up one repeat of the layer, for everything that works window by window:
+     * rooms, lit windows. With `glass`, a window is a hole in the albedo — glass where its alpha is 0,
+     * wall where it is 1 — which is how a facade is drawn, and the other way round would lose the
+     * wall's colour, which does not survive an upload at alpha 0.
+     */
+    readonly windows?: {
+        readonly cells: readonly [number, number];
+        readonly glass?: boolean;
+        /** Varies which windows light and which rooms show, between facades wearing one layer. */
+        readonly seed?: number;
+        /** How bright a lit window glows, 0 for none. */
+        readonly glow?: number;
+        /**
+         * The light a window shows where there is no room behind it. **A vertex that names an emissive
+         * colour overrides it** — the window's colour, or a tint on the room where there is one — which
+         * is how buildings sharing a layer each keep their own light: a window layer's vertex emissive
+         * is otherwise unused, so the colour there, strength folded in, is free to say it.
+         */
+        readonly colour?: readonly [number, number, number];
+    };
+    /** A room seen in parallax behind each window, drawn from another layer of the same array. */
+    readonly interior?: {
+        readonly roomLayer: number;
+        /** How deep a room is, as a share of a window's width. 0.5 unless stated. */
+        readonly depth?: number;
+        /** The share of rooms lit, 0 to 1. 1 unless stated. */
+        readonly lit?: number;
+    };
+    /** Procedural wear, each 0 to 1, fading out past `fade` metres (never, unless stated). */
+    readonly wear?: {
+        readonly dust?: number;
+        readonly grime?: number;
+        readonly streaks?: number;
+        readonly fade?: number;
+    };
+    /** Motion on the caller's clock (`Environment.surfaceTime`), so a held clock holds it. */
+    readonly animation?: {
+        /** Repeats a second along u and v. */
+        readonly scroll?: readonly [number, number];
+        /** Emission rising and falling: hertz, and how far it falls, 0 to 1. */
+        readonly pulse?: readonly [number, number];
+        /** Emission stuttering, 0 to 1. */
+        readonly flicker?: number;
+        /** Successive layers as frames: how many from this one, and how fast. */
+        readonly flipbook?: readonly [number, number];
+        /** Metres past which emission fades out, 0 for never. */
+        readonly fade?: number;
+    };
+    /** Rain leaves it dry: a covered walkway, an interior floor. */
+    readonly dry?: boolean;
+}
+/**
+ * The table for `effects`, one entry a layer (`undefined` for a layer with none), as floats: six
+ * RGBA texels a layer, a row a layer.
+ */
+export declare function packSurfaceEffects(effects: readonly (SurfaceLayerEffect | undefined)[]): Float32Array;

package/dist/render/surfaceEffects.js

@@ -0,0 +1,75 @@
+/**
+ * What each layer of a surface array does beyond its picture: rooms behind its windows, windows that
+ * light by night, wear, animation, and whether rain wets it.
+ *
+ * **Per layer, because a city region is one mesh.** Its facades are told apart by the layer each
+ * vertex carries (`MeshData.layers`), so an effect's parameters cannot be a per-draw uniform — two facades of one
+ * draw would share them. They are a table beside the array, six texels a layer, read at the vertex's
+ * layer with `texelFetch`, and they bind whenever the array does.
+ *
+ * **Everything off is all zeros**, so a layer a scene names no effect for — and every layer of an
+ * array given no table — costs the shader one size query and nothing else.
+ *
+ * Layout, six RGBA texels a layer, half floats on the GPU (every whole number here is under 2,048,
+ * which a half holds exactly):
+ * - 0: window cells across and up, glass mask (1: glass where the albedo's alpha is 0), seed;
+ * - 1: room layer (0: none; the layer plus one), room depth (0 to 1 of a cell), share of rooms lit,
+ *      window glow;
+ * - 2: window colour, then 1 where rain leaves the surface dry;
+ * - 3: dust, grime, streaks, the metres over which wear fades out with distance (0: never);
+ * - 4: scroll along u and v in repeats a second, pulse rate in hertz, pulse depth;
+ * - 5: flicker, flipbook frames, flipbook frames a second, the metres past which emission fades
+ *      (0: never).
+ */
+/** Texels a layer takes in the table. */
+export const SURFACE_EFFECT_TEXELS = 6;
+/**
+ * The table for `effects`, one entry a layer (`undefined` for a layer with none), as floats: six
+ * RGBA texels a layer, a row a layer.
+ */
+export function packSurfaceEffects(effects) {
+    const out = new Float32Array(effects.length * SURFACE_EFFECT_TEXELS * 4);
+    effects.forEach((effect, layer) => {
+        if (effect === undefined)
+            return;
+        const at = layer * SURFACE_EFFECT_TEXELS * 4;
+        const windows = effect.windows;
+        if (windows !== undefined) {
+            out[at] = windows.cells[0];
+            out[at + 1] = windows.cells[1];
+            out[at + 2] = windows.glass === true ? 1 : 0;
+            out[at + 3] = windows.seed ?? 0;
+            out[at + 7] = windows.glow ?? 0;
+            const colour = windows.colour ?? [1, 0.82, 0.55];
+            out[at + 8] = colour[0];
+            out[at + 9] = colour[1];
+            out[at + 10] = colour[2];
+        }
+        const interior = effect.interior;
+        if (interior !== undefined) {
+            out[at + 4] = interior.roomLayer + 1;
+            out[at + 5] = interior.depth ?? 0.5;
+            out[at + 6] = interior.lit ?? 1;
+        }
+        out[at + 11] = effect.dry === true ? 1 : 0;
+        const wear = effect.wear;
+        if (wear !== undefined) {
+            out[at + 12] = wear.dust ?? 0;
+            out[at + 13] = wear.grime ?? 0;
+            out[at + 14] = wear.streaks ?? 0;
+            out[at + 15] = wear.fade ?? 0;
+        }
+        const animation = effect.animation;
+        if (animation !== undefined) {
+            out[at + 16] = animation.scroll?.[0] ?? 0;
+            out[at + 17] = animation.scroll?.[1] ?? 0;
+            out[at + 18] = animation.pulse?.[0] ?? 0;
+            out[at + 19] = animation.pulse?.[1] ?? 0;
+            out[at + 20] = animation.flicker ?? 0;
+            out[at + 21] = animation.flipbook?.[0] ?? 0;
+            out[at + 22] = animation.flipbook?.[1] ?? 0;
+            out[at + 23] = animation.fade ?? 0;
+        }
+    });
+    return out;
+}

package/dist/render/surfaceScene.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The scene's surface clock and weather, decided once for both backends: the four numbers the lit
+ * stage reads as `uSurfaceScene`. Each backend only uploads them, so the two cannot disagree about
+ * what a wetness of 1.4 means — it means 1, as a share of lit windows past one means all of them.
+ */
+import type { Environment } from './backend/webgl2/renderer.ts';
+/** Fill `out`: seconds on the caller's clock, wetness, the lit share, the late share. */
+export declare function resolveSurfaceScene(env: Environment, out: Float32Array): void;

package/dist/render/surfaceScene.js

@@ -0,0 +1,8 @@
+const unit = (value) => Math.min(1, Math.max(0, value ?? 0));
+/** Fill `out`: seconds on the caller's clock, wetness, the lit share, the late share. */
+export function resolveSurfaceScene(env, out) {
+    out[0] = env.surfaceTime ?? 0;
+    out[1] = unit(env.wetness);
+    out[2] = unit(env.litWindows);
+    out[3] = unit(env.lateWindows);
+}