@driftengine/core 4.4.2 → 4.6.0

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

@@ -1,5 +1,6 @@
 /** Version, inputs, uniforms and the defines the rest of the fragment shader is written against. */
 import { COOKIE_TILE } from '../../lightBudget.js';
+import { IES_ATLAS_WIDTH } from '../../iesProfile.js';
 import { CLUSTER_TEXELS, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, LIGHT_REGION_TEXELS, LIGHT_TEXELS, MAX_LIGHTS_PER_CLUSTER, TABLE_WIDTH, } from '../../clusteredLights.js';
 /**
  * How much roughness a relieved or normal-mapped surface gains per unit of relief.
@@ -39,7 +40,7 @@ in vec3 vWorldPos;
 in float vEmissive;
 in float vSpecular;
 in vec4 vLightPos;
-in vec2 vUv;
+in vec3 vUv;
 in vec3 vEmissiveColor;
 in float vRoughness;
 /*
@@ -96,13 +97,20 @@ in float vThickness;
  * paid by every consumer whether or not they refract, against 19.8 KB for a branch -- which is the
  * price table Track D's three shipped rows measured.
  *
- * uRefractStrength at 0 is every draw that shipped before this existed, and it is the default, so
+ * uSeeThrough.x, the strength, at 0 is every draw that shipped before this existed, and it is the default, so
  * the sampler is bound to an empty texture and read nowhere on a frame that refracts nothing.
  */
 uniform sampler2D uRefractScene;
-uniform float uRefractStrength;
+/*
+ * **Four numbers in one vector: refraction's strength and path thickness, glass's transmission and
+ * frost** (x, y, z, w). One vector rather than four, and that is the whole reason: on a device at the
+ * WebGL2 floor of 256 fragment uniform vectors, every loose float is a vector the light budget
+ * gives up, and four separate floats cost half the shadowed lights such a device can have. The tints
+ * stay colours of their own. Zero transmission is not glass — see glass.ts.
+ */
+uniform vec4 uSeeThrough;
 uniform vec3 uRefractTint;
-uniform float uRefractThickness;
+uniform vec3 uGlassTint;
 flat in int vHasTangents;
 
 /**
@@ -117,7 +125,7 @@ flat in int vHasTangents;
  * biome recolours a whole world without a second texture, and a mesh whose texture is
  * white shades identically to one with no texture at all.
  */
-uniform sampler2D uAlbedo;
+uniform mediump sampler2DArray uAlbedo;
 /** 0 leaves every textured path unevaluated, for the majority of geometry with no image. */
 uniform int uAlbedoEnabled;
 /**
@@ -133,6 +141,12 @@ uniform int uAlbedoEnabled;
  * else changes.
  */
 uniform float uAlbedoCutout;
+/**
+ * The albedo array's per-layer effects table: six texels a layer, read with \`texelFetch\` at the
+ * layer a vertex carries. A 1×1 stand-in where the array has none, which the size test below reads
+ * as no effects at all. See \`surfaceEffects.ts\` for the layout.
+ */
+uniform mediump sampler2D uSurfaceEffects;
 
 /**
  * 1 for a surface seen from both faces: glTF's doubleSided, a curtain or a leaf card. Its draw culls
@@ -150,7 +164,7 @@ uniform int uDoubleSided;
  * display values bends every normal toward the surface and reads as a green tint over everything.
  * SurfaceTextureOptions.colorSpace already defaults to linear and says why.
  */
-uniform highp sampler2D uNormalMap;
+uniform highp sampler2DArray uNormalMap;
 /**
  * How hard the map turns the shading normal. 0 is no map at all, and gates the whole block.
  *
@@ -172,7 +186,7 @@ uniform float uNormalStrength;
  * Sampled linear and never sRGB. These three numbers *are* the data, not a picture of it, and
  * decoding them as display values would bend every one of them toward its floor.
  */
-uniform highp sampler2D uOrmMap;
+uniform highp sampler2DArray uOrmMap;
 /**
  * 1 when a map is bound. Gates the whole block, following uAlbedoEnabled.
  *
@@ -218,7 +232,7 @@ uniform float uEnvironmentPrefiltered;
  * above, and now with a number behind them: a fifth flag was built and measured at 49% of the
  * bundle. See \`ARCHITECTURE.md\` §1.
  */
-uniform highp sampler2D uEmissiveMap;
+uniform highp sampler2DArray uEmissiveMap;
 /** 1 when a map is bound. Gates the sample, following uOrmEnabled. */
 uniform int uEmissiveMapEnabled;
 /**
@@ -256,9 +270,13 @@ uniform vec3 uEmissiveScale;
  * half of the file, because a test asserts that a profile without a probe mentions them
  * nowhere — a comment is source too, and it failed that test first.
  */
-uniform highp sampler2D uStaticShadowMap;  // wgsl:share shadow
-uniform highp sampler2D uPeeledShadowMap;  // wgsl:share shadow
-uniform highp sampler2D uDynamicShadowMap;  // wgsl:share shadow
+/* The sun's static, moving and peeled maps, as layers of one array: see shadowMap.ts. Where glass
+   has cast, the last two layers are the nearest pane's depth, static then moving. */
+uniform highp sampler2DArray uSunShadows;  // wgsl:share shadow
+/* What the sun keeps through glass, static then moving: colour times colour, and clarity (see
+   glassShadow.ts). A one-texel stand-in where no glass has cast, which the lookup reads as none.
+   Mipmapped and filtered, unlike the depths: frost reads the level its spread asks for. */
+uniform highp sampler2DArray uSunGlassTints;  // wgsl:share tint
 /** 0 disables directional shadows when their source is not emitting. */
 uniform float uShadowStrength;
 uniform float uShadowMapSize;
@@ -290,9 +308,21 @@ uniform vec3 uAmbient;
 uniform vec3 uAmbientGround;
 ${FOG_GLSL}
 uniform vec3 uCameraPos;
-/** Optional world plane; reflection passes retain only the viewer's side. */
+/**
+ * Optional world plane; reflection passes retain only the viewer's side.
+ *
+ * **Zero is off, and there is no flag beside it.** A zero plane gives \`dot(p, 0) = 0\`, which is
+ * never below zero, so it discards nothing — the \`uClipEnabled\` int that stood here said nothing
+ * the plane could not, and a scalar is a whole uniform row on WebGL2. Its row paid for
+ * \`uSurfaceScene\`. Other programs keep their own flags; this is the lit stage's alone.
+ */
 uniform vec4 uClipPlane;
-uniform int uClipEnabled;
+/**
+ * The scene's surface clock and weather, from the environment: x seconds on the caller's clock, y
+ * how wet the world is, z the share of facade windows lit, w the share that stays lit however late.
+ * One row for all four, paid for by the flag the clip plane no longer needs.
+ */
+uniform vec4 uSurfaceScene;
 uniform float uEmissiveGain;
 uniform float uNightFactor;
 #if NIGHT_EMISSIVE
@@ -322,22 +352,47 @@ uniform float uNightEmissive;
 uniform float uOpacity;
 
 /**
- * Whether this draw is accumulating into the order-independent transparency buffers, and
- * therefore weights its own output. 0 is every draw that is not, which is every draw on every
+ * Two per-draw switches on how a fragment is *written* rather than what colour it is, sharing one
+ * row: on WebGL2 every scalar uniform takes a row of its own, and the eight-light rung stands at 255
+ * of the 256 an Adreno 740 offers (\`uniformVectorBudget.test.ts\`), so a second scalar would have
+ * spent the last row and the next uniform anybody added would drop that part to four lights.
+ *
+ * **\`.x\` — whether this draw is accumulating into the order-independent transparency buffers**,
+ * and therefore weights its own output. 0 is every draw that is not, which is every draw on every
  * published scene.
  *
- * **A uniform rather than a permutation, and the cost is why.** Writing the accumulation and the
+ * A uniform rather than a permutation, and the cost is why. Writing the accumulation and the
  * revealage from one pass needs a second fragment output, which is another \`flatFrag\` axis —
  * measured in \`scripts/wgsl.ts\` at about 247 KB gzipped, doubling the sixteen fragment variants,
  * and paid by every consumer whether or not they ever switch this on. A branch on a uniform costs
  * a compare, and the geometry is submitted twice instead. See \`orderIndependent.ts\`.
  *
- * **The revealage pass does not read this.** It draws with this at 0 and a blend of
+ * The revealage pass does not read it. It draws with it at 0 and a blend of
  * \`(ZERO, ONE_MINUS_SRC_ALPHA)\`, so the colour it computes is multiplied away and only its alpha
  * reaches the target — which is exactly the point: both passes run the same code to decide what
  * alpha this fragment has, so they cannot disagree about it.
+ *
+ * **\`.y\` — how much of this draw survives a screen-door dither**, for a crossfade between two
+ * levels of detail of one thing. 0 is off, and every draw that never asked for it. Positive keeps
+ * that share of an 8×8 Bayer pattern's cells; negative keeps the complement — the cells a draw at
+ * the positive amount leaves out — so two draws at \`t\` and \`-t\` cover every pixel exactly once,
+ * whatever \`t\` is. Keyed on the framebuffer's own pixel, whose y runs the other way on WebGPU, so
+ * the grain is mirrored between backends and nothing else about it differs. What it gives up: a
+ * crossfade reads as grain for as long as it lasts, which is why it should be short; and a blended
+ * draw that asks for it is dithered too, since the test is a discard.
  */
-uniform float uOitWeighted;
+uniform vec2 uWriteMode;
+
+/** Whether this fragment is one \`uWriteMode.y\` keeps. Integer arithmetic, per the device rule. */
+bool ditherKeeps(float amount) {
+  uvec2 p = uvec2(gl_FragCoord.xy) & 7u;
+  uint a = p.x ^ p.y;
+  uint b = p.y;
+  uint cell = ((a & 1u) << 5) | ((b & 1u) << 4) | ((a & 2u) << 2) | ((b & 2u) << 1) |
+    ((a & 4u) >> 1) | ((b & 4u) >> 2);
+  float threshold = (float(cell) + 0.5) / 64.0;
+  return amount > 0.0 ? threshold < amount : threshold >= -amount;
+}
 
 /**
  * Whether the fragment stage runs any lighting: ambient, the sun, point lights, specular,
@@ -361,10 +416,11 @@ uniform float uOitWeighted;
  */
 uniform int uLightingEnabled;
 /**
- * Whether this draw recedes into the medium: the atmospheric haze and the underwater tint
- * both, folded together because both are the *camera's* medium rather than a property of the
- * surface — see \`mediumFog\`/\`mediumColor\` in \`fog.ts\`. 1 keeps both, matching every draw
- * before this existed.
+ * How this draw meets the medium: the atmospheric haze and the underwater tint both, folded
+ * together because both are the *camera's* medium rather than a property of the surface — see
+ * \`mediumFog\`/\`mediumColor\` in \`fog.ts\`. 1 recedes into it, matching every draw before this
+ * existed; 2 fades in it without taking its colour, which is what an additive draw is given; 0
+ * keeps out of it. The rule is \`fogModeOf\` in \`backend/drawFog.ts\`.
  *
  * **Independent of \`uLightingEnabled\`, and that is the point of it being a second uniform
  * rather than the same one.** "Unlit but still fading into the haze" is a real thing to
@@ -714,15 +770,15 @@ uniform vec3 uLightIesAxis[MAX_LIGHTS];
  */
 uniform float uLightCookie[MAX_LIGHTS];
 /**
- * Photometric profiles: one row per fixture, a fixture's intensity by vertical angle across it.
+ * Photometric profiles: one row per fixture, a fixture's intensity by vertical angle across it, in
+ * the bottom band of the fixture atlas below.
  *
  * **Every row spans the same 0 to 180 degree arc**, whatever the file measured, which is what lets
  * a light carry only a row index — see \`iesProfile.ts\`. With no profile loaded this holds a
  * single row of ones, the multiplicative identity, because a declared sampler needs a complete
  * texture whether or not the branch reads it and a row of zeros would switch off every light.
  */
-uniform sampler2D uIesAtlas;
-/** Rows in the atlas, so a row index becomes a coordinate. At least 1. */
+/** Rows of profile in the fixture atlas, below its cookies. At least 1. */
 uniform float uIesAtlasRows;
 /**
  * Horizontal planes each profile occupies, so a row is \`profile * planes + plane\`.
@@ -742,8 +798,14 @@ uniform float uIesPlaneCount;
  * identity, because a declared sampler needs a complete texture whether or not the branch reads it
  * and a black stand-in would switch off every light that reached it.
  */
-uniform sampler2D uCookieAtlas;
 uniform float uCookieTiles;
+/**
+ * Both tables in one texture: the cookies' row of tiles in the top band, the profiles' rows below.
+ * One sampler for the two since 2026-09-30, because the lit stage bound fifteen of the sixteen
+ * WebGL2 guarantees; see \`fixtureAtlas.ts\`. The bands are found from \`textureSize\` and
+ * \`uIesAtlasRows\`, so the fold cost no uniform.
+ */
+uniform sampler2D uFixtureAtlas;
 /**
  * Half a texel of a tile, so a cookie's edge cannot reach its neighbour in the atlas.
  *
@@ -752,6 +814,10 @@ uniform float uCookieTiles;
  * cookie. Derived from \`COOKIE_TILE\` rather than written twice.
  */
 #define COOKIE_INSET (0.5 / ${COOKIE_TILE}.0)
+/** Texels across a profile's row, where a vertical angle of 0 to 180 degrees is laid. */
+#define IES_WIDTH ${IES_ATLAS_WIDTH}.0
+/** Texels a cookie's tile spans, on both axes. */
+#define COOKIE_SPAN ${COOKIE_TILE}.0
 /**
  * Rectangular area lights, and how many of them are live.
  *
@@ -854,6 +920,10 @@ uniform float uPointShadowWeight[MAX_LIGHTS];
  * it exists.
  */
 uniform highp sampler2DArray uPointShadows;  // wgsl:share shadow
+/* What each light keeps through glass: one layer a light, colour times colour and clarity, beside
+   the array above — whose light L then keeps its depth at 2L and its nearest pane at 2L + 1 (see
+   pointShadowArray.ts). A one-texel stand-in where no lamp has met glass, read as none. */
+uniform highp sampler2DArray uPointGlassTints;  // wgsl:share tint
 
 /**
  * Moving casters are separate from persistent world maps. Two live maps exist

package/dist/render/shaders/flat/surfaceEffects.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Surface effects in the lit shader: what a layer does beyond its picture, read from the albedo
+ * array's effects table at the layer a vertex carries (`surfaceEffects.ts` has the layout).
+ *
+ * **Nothing here changes a surface that asks for nothing.** With no table the fetch never runs and
+ * every value is zero; each effect is then `mix(x, y, 0)` or a multiply by exactly 1, so a scene
+ * that never names an effect draws bit for bit what it drew before. Rain is the one effect that
+ * needs no table — it is the scene's (`Environment.wetness`) — and at zero it is the same no-op.
+ *
+ * **Windows and rooms.** A layer's windows are a grid of cells over one repeat. Each window lights
+ * by a hash of its cell against the scene's lit share, quantised to tenths, so a rising share lights
+ * more windows rather than brightening the lit ones; a share of them stays lit in the small hours.
+ * A room behind a window is **interior mapping from one image**: a one-point perspective picture of
+ * a room, back wall in its centre half, is sampled where the view ray meets the room's box. A point
+ * on any wall at depth s maps into that picture at `0.5 + (xy - 0.5) / (1 + s)` — the back wall at
+ * s = 1 lands in the centre square, and a side wall runs from the picture's edge in to it — so one
+ * formula serves every wall and the picture carries its own shading.
+ *
+ * **Wear** is procedural: dust settling on what faces up, grime rising from the ground and in
+ * blotches, streaks running down walls, all fading out with distance where a table says to.
+ *
+ * Every sample inside these branches is `textureGrad` with gradients taken outside them, or
+ * `texelFetch` (the 2026-08-07 rule). Hashes are integer arithmetic (the 2026-09-20 rule).
+ *
+ * What it gives up: the room picture is one per layer, so every room of a facade is the same room
+ * lit or dark; and a room's box assumes a window as wide as it is tall, so a very tall cell
+ * stretches its room.
+ */
+export declare const SURFACE_EFFECTS_GLSL = "\n/*\n * The layer's six rows, and what every effect reads beside them, filled once at the top of main.\n * Globals rather than arguments, because naga passes every argument through a pointer and a copy,\n * and in sixteen permutations that traffic was most of what the effects cost in bytes.\n */\nvec4 fx0;\nvec4 fx1;\nvec4 fx2;\nvec4 fx3;\nvec4 fx4;\nvec4 fx5;\nvec3 fxNormal;\nfloat fxDistance;\n\n/** Fill the rows for this layer, or leave them zero where the array carries no table. */\nvoid fxLoad(int layer) {\n  fx0 = vec4(0.0);\n  fx1 = vec4(0.0);\n  fx2 = vec4(0.0);\n  fx3 = vec4(0.0);\n  fx4 = vec4(0.0);\n  fx5 = vec4(0.0);\n  ivec2 size = textureSize(uSurfaceEffects, 0);\n  if (size.x < 6 || layer < 0 || layer >= size.y) return;\n  fx0 = texelFetch(uSurfaceEffects, ivec2(0, layer), 0);\n  fx1 = texelFetch(uSurfaceEffects, ivec2(1, layer), 0);\n  fx2 = texelFetch(uSurfaceEffects, ivec2(2, layer), 0);\n  fx3 = texelFetch(uSurfaceEffects, ivec2(3, layer), 0);\n  fx4 = texelFetch(uSurfaceEffects, ivec2(4, layer), 0);\n  fx5 = texelFetch(uSurfaceEffects, ivec2(5, layer), 0);\n}\n\n/** A cell and a seed to 0..1, the same on every device. */\nfloat fxHash(vec2 cell, float seed) {\n  uvec2 q = uvec2(ivec2(cell)) + uvec2(uint(seed) * 7919u, uint(seed) * 104729u);\n  uint h = (q.x * 1597334677u) ^ (q.y * 3812015801u);\n  h = (h ^ (h >> 16)) * 2246822519u;\n  h ^= h >> 13;\n  return float(h & 16777215u) / 16777216.0;\n}\n\nfloat fxNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 u = smoothstep(0.0, 1.0, fract(p));\n  return mix(\n    mix(fxHash(i, 0.0), fxHash(i + vec2(1.0, 0.0), 0.0), u.x),\n    mix(fxHash(i + vec2(0.0, 1.0), 0.0), fxHash(i + vec2(1.0, 1.0), 0.0), u.x),\n    u.y);\n}\n\n/** Scroll and flipbook, on the caller's clock. `fract` keeps a long clock from eating precision. */\nvec3 fxAnimate(vec3 at) {\n  float time = uSurfaceScene.x;\n  at.xy += fract(fx4.xy * time);\n  if (fx5.y > 0.0) at.z += mod(floor(time * fx5.z), fx5.y);\n  return at;\n}\n\n/** Pulse, flicker and fade with distance, as a factor on the emission. */\nfloat fxEmission(float layer) {\n  float time = uSurfaceScene.x;\n  float e = 1.0 - fx4.w * (0.5 + 0.5 * sin(6.2831853 * fract(fx4.z * time)));\n  e *= 1.0 - fx5.x * step(0.7, fxHash(vec2(floor(time * 14.0), layer), 3.0));\n  if (fx5.w > 0.0) e *= 1.0 - smoothstep(fx5.w * 0.7, fx5.w, fxDistance);\n  return e;\n}\n\n/** Dust, grime and streaks, then the scene's rain: the colour in xyz, the roughness in w. */\nvec4 fxWeather(vec3 world, vec3 albedo, float roughness) {\n  float fade = fx3.w > 0.0 ? 1.0 - smoothstep(fx3.w * 0.5, fx3.w, fxDistance) : 1.0;\n  if (fx3.x + fx3.y + fx3.z > 0.0) {\n    float blotch = fxNoise(world.xz * 0.35 + world.y * 0.2);\n    float dust = fx3.x * smoothstep(0.35, 0.9, fxNormal.y) * (0.5 + 0.5 * blotch) * fade;\n    float grime = fx3.y * (0.55 - 0.55 * smoothstep(0.0, 2.5, world.y) + 0.45 * blotch) * fade;\n    float streak = fx3.z * (1.0 - abs(fxNormal.y))\n      * fxNoise(vec2((world.x + world.z) * 2.5, world.y * 0.15)) * fade;\n    albedo = mix(albedo, vec3(0.56, 0.53, 0.48), dust * 0.6) * (1.0 - 0.5 * grime - 0.35 * streak);\n    roughness = mix(roughness, 1.0, clamp(0.5 * (dust + grime), 0.0, 1.0));\n  }\n  float wet = uSurfaceScene.y * (1.0 - fx2.w) * mix(0.35, 1.0, smoothstep(0.2, 0.8, fxNormal.y));\n  return vec4(albedo * (1.0 - 0.45 * wet), mix(roughness, 0.08, wet));\n}\n\n/**\n * Windows and the rooms behind them: the glow a lit window adds to the emission in xyz, and in w\n * how much of the surface is glass, which the caller mixes toward the room's dim colour. The room\n * itself is returned through `fxRoom`. `mask` is the albedo's alpha, and a window is a hole in the\n * wall's picture: glass where it is 0. The other way round would lose the wall's colour, which does\n * not survive an upload at alpha 0.\n *\n * **A building's own light, where its vertices name one.** The table is per layer, and every\n * facade of one style shares a layer, so a light that differs from building to building \u2014 its\n * colour and its strength \u2014 cannot live there. A window layer's vertex emissive is otherwise unused\n * (its windows glow here, not through the emissive term), so the vertex's emissive colour, strength\n * folded in, is that light: the window's colour where there is no room, a tint on the room where\n * there is. An absent colour reads negative and leaves both exactly as the table says.\n */\nvec3 fxRoom;\nvec4 fxWindows(vec3 at, vec2 dx, vec2 dy, float mask) {\n  float glass = fx0.z > 0.0 ? 1.0 - mask : 1.0;\n  vec2 g = at.xy * fx0.xy;\n  vec2 local = fract(g);\n  float share = floor(max(uSurfaceScene.z, uSurfaceScene.w) * 10.0 + 0.5) / 10.0;\n  float lit = fxHash(floor(g), fx0.w) < share * (fx1.x > 0.0 ? fx1.z : 1.0) ? 1.0 : 0.0;\n  fxRoom = fx2.rgb;\n  bool own = vEmissiveColor.r >= 0.0;\n  vec3 glow = own ? vEmissiveColor : fx2.rgb;\n  float tangentLength = length(vTangent.xyz);\n  if (fx1.x > 0.0 && tangentLength > 1e-4) {\n    vec3 t = vTangent.xyz / tangentLength;\n    vec3 v = normalize(vWorldPos - uCameraPos);\n    vec3 d = vec3(dot(v, t), dot(v, cross(fxNormal, t)) * sign(vTangent.w + 0.5),\n      min(dot(v, fxNormal), -1e-3) / max(fx1.y, 0.05));\n    vec2 across = (step(0.0, d.xy) - local) / (sign(d.xy + 1e-9) * max(abs(d.xy), 1e-5));\n    float travel = min(min(across.x, across.y), -1.0 / d.z);\n    float depth = min(-d.z * travel, 1.0);\n    vec2 picture = 0.5 + (local + d.xy * travel - 0.5) / (1.0 + depth);\n    fxRoom = textureGrad(uAlbedo, vec3(picture, fx1.x - 1.0), dx * fx0.xy * 0.5, dy * fx0.xy * 0.5).rgb;\n    glow = own ? fxRoom * vEmissiveColor : fxRoom;\n  }\n  return vec4(glow * (lit * fx1.w * glass), glass);\n}\n";

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

@@ -0,0 +1,152 @@
+/**
+ * Surface effects in the lit shader: what a layer does beyond its picture, read from the albedo
+ * array's effects table at the layer a vertex carries (`surfaceEffects.ts` has the layout).
+ *
+ * **Nothing here changes a surface that asks for nothing.** With no table the fetch never runs and
+ * every value is zero; each effect is then `mix(x, y, 0)` or a multiply by exactly 1, so a scene
+ * that never names an effect draws bit for bit what it drew before. Rain is the one effect that
+ * needs no table — it is the scene's (`Environment.wetness`) — and at zero it is the same no-op.
+ *
+ * **Windows and rooms.** A layer's windows are a grid of cells over one repeat. Each window lights
+ * by a hash of its cell against the scene's lit share, quantised to tenths, so a rising share lights
+ * more windows rather than brightening the lit ones; a share of them stays lit in the small hours.
+ * A room behind a window is **interior mapping from one image**: a one-point perspective picture of
+ * a room, back wall in its centre half, is sampled where the view ray meets the room's box. A point
+ * on any wall at depth s maps into that picture at `0.5 + (xy - 0.5) / (1 + s)` — the back wall at
+ * s = 1 lands in the centre square, and a side wall runs from the picture's edge in to it — so one
+ * formula serves every wall and the picture carries its own shading.
+ *
+ * **Wear** is procedural: dust settling on what faces up, grime rising from the ground and in
+ * blotches, streaks running down walls, all fading out with distance where a table says to.
+ *
+ * Every sample inside these branches is `textureGrad` with gradients taken outside them, or
+ * `texelFetch` (the 2026-08-07 rule). Hashes are integer arithmetic (the 2026-09-20 rule).
+ *
+ * What it gives up: the room picture is one per layer, so every room of a facade is the same room
+ * lit or dark; and a room's box assumes a window as wide as it is tall, so a very tall cell
+ * stretches its room.
+ */
+export const SURFACE_EFFECTS_GLSL = /* glsl */ `
+/*
+ * The layer's six rows, and what every effect reads beside them, filled once at the top of main.
+ * Globals rather than arguments, because naga passes every argument through a pointer and a copy,
+ * and in sixteen permutations that traffic was most of what the effects cost in bytes.
+ */
+vec4 fx0;
+vec4 fx1;
+vec4 fx2;
+vec4 fx3;
+vec4 fx4;
+vec4 fx5;
+vec3 fxNormal;
+float fxDistance;
+
+/** Fill the rows for this layer, or leave them zero where the array carries no table. */
+void fxLoad(int layer) {
+  fx0 = vec4(0.0);
+  fx1 = vec4(0.0);
+  fx2 = vec4(0.0);
+  fx3 = vec4(0.0);
+  fx4 = vec4(0.0);
+  fx5 = vec4(0.0);
+  ivec2 size = textureSize(uSurfaceEffects, 0);
+  if (size.x < 6 || layer < 0 || layer >= size.y) return;
+  fx0 = texelFetch(uSurfaceEffects, ivec2(0, layer), 0);
+  fx1 = texelFetch(uSurfaceEffects, ivec2(1, layer), 0);
+  fx2 = texelFetch(uSurfaceEffects, ivec2(2, layer), 0);
+  fx3 = texelFetch(uSurfaceEffects, ivec2(3, layer), 0);
+  fx4 = texelFetch(uSurfaceEffects, ivec2(4, layer), 0);
+  fx5 = texelFetch(uSurfaceEffects, ivec2(5, layer), 0);
+}
+
+/** A cell and a seed to 0..1, the same on every device. */
+float fxHash(vec2 cell, float seed) {
+  uvec2 q = uvec2(ivec2(cell)) + uvec2(uint(seed) * 7919u, uint(seed) * 104729u);
+  uint h = (q.x * 1597334677u) ^ (q.y * 3812015801u);
+  h = (h ^ (h >> 16)) * 2246822519u;
+  h ^= h >> 13;
+  return float(h & 16777215u) / 16777216.0;
+}
+
+float fxNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 u = smoothstep(0.0, 1.0, fract(p));
+  return mix(
+    mix(fxHash(i, 0.0), fxHash(i + vec2(1.0, 0.0), 0.0), u.x),
+    mix(fxHash(i + vec2(0.0, 1.0), 0.0), fxHash(i + vec2(1.0, 1.0), 0.0), u.x),
+    u.y);
+}
+
+/** Scroll and flipbook, on the caller's clock. \`fract\` keeps a long clock from eating precision. */
+vec3 fxAnimate(vec3 at) {
+  float time = uSurfaceScene.x;
+  at.xy += fract(fx4.xy * time);
+  if (fx5.y > 0.0) at.z += mod(floor(time * fx5.z), fx5.y);
+  return at;
+}
+
+/** Pulse, flicker and fade with distance, as a factor on the emission. */
+float fxEmission(float layer) {
+  float time = uSurfaceScene.x;
+  float e = 1.0 - fx4.w * (0.5 + 0.5 * sin(6.2831853 * fract(fx4.z * time)));
+  e *= 1.0 - fx5.x * step(0.7, fxHash(vec2(floor(time * 14.0), layer), 3.0));
+  if (fx5.w > 0.0) e *= 1.0 - smoothstep(fx5.w * 0.7, fx5.w, fxDistance);
+  return e;
+}
+
+/** Dust, grime and streaks, then the scene's rain: the colour in xyz, the roughness in w. */
+vec4 fxWeather(vec3 world, vec3 albedo, float roughness) {
+  float fade = fx3.w > 0.0 ? 1.0 - smoothstep(fx3.w * 0.5, fx3.w, fxDistance) : 1.0;
+  if (fx3.x + fx3.y + fx3.z > 0.0) {
+    float blotch = fxNoise(world.xz * 0.35 + world.y * 0.2);
+    float dust = fx3.x * smoothstep(0.35, 0.9, fxNormal.y) * (0.5 + 0.5 * blotch) * fade;
+    float grime = fx3.y * (0.55 - 0.55 * smoothstep(0.0, 2.5, world.y) + 0.45 * blotch) * fade;
+    float streak = fx3.z * (1.0 - abs(fxNormal.y))
+      * fxNoise(vec2((world.x + world.z) * 2.5, world.y * 0.15)) * fade;
+    albedo = mix(albedo, vec3(0.56, 0.53, 0.48), dust * 0.6) * (1.0 - 0.5 * grime - 0.35 * streak);
+    roughness = mix(roughness, 1.0, clamp(0.5 * (dust + grime), 0.0, 1.0));
+  }
+  float wet = uSurfaceScene.y * (1.0 - fx2.w) * mix(0.35, 1.0, smoothstep(0.2, 0.8, fxNormal.y));
+  return vec4(albedo * (1.0 - 0.45 * wet), mix(roughness, 0.08, wet));
+}
+
+/**
+ * Windows and the rooms behind them: the glow a lit window adds to the emission in xyz, and in w
+ * how much of the surface is glass, which the caller mixes toward the room's dim colour. The room
+ * itself is returned through \`fxRoom\`. \`mask\` is the albedo's alpha, and a window is a hole in the
+ * wall's picture: glass where it is 0. The other way round would lose the wall's colour, which does
+ * not survive an upload at alpha 0.
+ *
+ * **A building's own light, where its vertices name one.** The table is per layer, and every
+ * facade of one style shares a layer, so a light that differs from building to building — its
+ * colour and its strength — cannot live there. A window layer's vertex emissive is otherwise unused
+ * (its windows glow here, not through the emissive term), so the vertex's emissive colour, strength
+ * folded in, is that light: the window's colour where there is no room, a tint on the room where
+ * there is. An absent colour reads negative and leaves both exactly as the table says.
+ */
+vec3 fxRoom;
+vec4 fxWindows(vec3 at, vec2 dx, vec2 dy, float mask) {
+  float glass = fx0.z > 0.0 ? 1.0 - mask : 1.0;
+  vec2 g = at.xy * fx0.xy;
+  vec2 local = fract(g);
+  float share = floor(max(uSurfaceScene.z, uSurfaceScene.w) * 10.0 + 0.5) / 10.0;
+  float lit = fxHash(floor(g), fx0.w) < share * (fx1.x > 0.0 ? fx1.z : 1.0) ? 1.0 : 0.0;
+  fxRoom = fx2.rgb;
+  bool own = vEmissiveColor.r >= 0.0;
+  vec3 glow = own ? vEmissiveColor : fx2.rgb;
+  float tangentLength = length(vTangent.xyz);
+  if (fx1.x > 0.0 && tangentLength > 1e-4) {
+    vec3 t = vTangent.xyz / tangentLength;
+    vec3 v = normalize(vWorldPos - uCameraPos);
+    vec3 d = vec3(dot(v, t), dot(v, cross(fxNormal, t)) * sign(vTangent.w + 0.5),
+      min(dot(v, fxNormal), -1e-3) / max(fx1.y, 0.05));
+    vec2 across = (step(0.0, d.xy) - local) / (sign(d.xy + 1e-9) * max(abs(d.xy), 1e-5));
+    float travel = min(min(across.x, across.y), -1.0 / d.z);
+    float depth = min(-d.z * travel, 1.0);
+    vec2 picture = 0.5 + (local + d.xy * travel - 0.5) / (1.0 + depth);
+    fxRoom = textureGrad(uAlbedo, vec3(picture, fx1.x - 1.0), dx * fx0.xy * 0.5, dy * fx0.xy * 0.5).rgb;
+    glow = own ? fxRoom * vEmissiveColor : fxRoom;
+  }
+  return vec4(glow * (lit * fx1.w * glass), glass);
+}
+`;