@driftengine/core 3.61.0

package/src/render/shaders/bloom.ts

@@ -0,0 +1,232 @@
+/**
+ * Bloom: the three stages of spreading a bright thing past its own pixels.
+ *
+ * **What it is for, in the words of the consumer who asked for it.** Nothing in this renderer
+ * makes a bright thing look bright: an emissive surface is exactly as bright as its pixels and
+ * not one pixel wider, so anything meant to overwhelm the eye has to be faked in geometry — a
+ * core sphere, a second sphere slightly larger, and fifty-four additive particles standing in
+ * for one pass. Every neon ring, lit poster, glyph band and shaft of daylight is the same
+ * request.
+ *
+ * **It composes with the tone curve rather than replacing it.** The curve decides how a bright
+ * pixel rolls off; this decides how far it spreads. So the result is added in linear scene
+ * units, before the grade, and the grade then rolls off the sum exactly as it rolls off
+ * anything else.
+ *
+ * **The threshold is in scene units, which is only meaningful with a target that keeps them.**
+ * With an eight-bit target the scene is clipped to 0..1 before the composite ever sees it, so a
+ * star and a sheet of white paper arrive as the same colour and a threshold can only mean
+ * whiteness. That is the whole reason hdrScene exists and it is why bloom asks for it.
+ *
+ * Three stages, and the middle one repeats:
+ *
+ * 1. **Prefilter**, full resolution down to half: subtract the threshold and keep what is left.
+ * 2. **Downsample**, halving each time, six levels or as many as the frame allows. Each level
+ *    is an octave of the spread, and adding them back is what produces a wide falloff rather
+ *    than one gaussian with a hard end.
+ * 3. **Upsample**, additively back up the chain through a tent filter.
+ *
+ * Deliberately absent, because they were asked against by name: lens dirt, anamorphic streaks
+ * and ghosting. One threshold, one radius, one strength.
+ */
+
+/**
+ * The thirteen taps every downsampling stage shares, decomposed into five overlapping boxes.
+ *
+ * Shared as a string rather than copied, because the prefilter and the plain downsample differ
+ * only in how they weight these boxes and what they do to each tap on the way in. Both call a
+ * fetch the shader itself defines, which is the seam: the prefilter thresholds there and the
+ * downsample does not.
+ *
+ * **Thirteen rather than four.** A bilinear box halving is one tap and it aliases: a bright
+ * pixel that lands between two texels flickers between them as the camera moves, which is the
+ * exact failure bloom is most often blamed for. The thirteen-tap arrangement samples the ring
+ * that a plain box misses, and the boxes overlap so no source pixel is ever weighted zero.
+ *
+ * Offsets are in source texels, so uTexel is one over the *source* size rather than the target.
+ */
+const BLOOM_BOXES = `
+  vec2 t = uTexel;
+  vec3 a = fetch(vUv + vec2(-2.0,  2.0) * t);
+  vec3 b = fetch(vUv + vec2( 0.0,  2.0) * t);
+  vec3 c = fetch(vUv + vec2( 2.0,  2.0) * t);
+  vec3 d = fetch(vUv + vec2(-2.0,  0.0) * t);
+  vec3 e = fetch(vUv);
+  vec3 f = fetch(vUv + vec2( 2.0,  0.0) * t);
+  vec3 g = fetch(vUv + vec2(-2.0, -2.0) * t);
+  vec3 h = fetch(vUv + vec2( 0.0, -2.0) * t);
+  vec3 i = fetch(vUv + vec2( 2.0, -2.0) * t);
+  vec3 j = fetch(vUv + vec2(-1.0,  1.0) * t);
+  vec3 k = fetch(vUv + vec2( 1.0,  1.0) * t);
+  vec3 l = fetch(vUv + vec2(-1.0, -1.0) * t);
+  vec3 m = fetch(vUv + vec2( 1.0, -1.0) * t);
+
+  vec3 box0 = (a + b + d + e) * 0.25;
+  vec3 box1 = (b + c + e + f) * 0.25;
+  vec3 box2 = (d + e + g + h) * 0.25;
+  vec3 box3 = (e + f + h + i) * 0.25;
+  vec3 box4 = (j + k + l + m) * 0.25;
+`;
+
+/**
+ * How bright a colour is, for the purpose of deciding whether it blooms.
+ *
+ * **The largest channel rather than luminance, and that is a correction rather than a
+ * preference.** Luminance weights green at 0.7152 and blue at 0.0722, so a saturated source is
+ * dim by that measure however far past white it actually is: a pure blue at 1.4, which clips the
+ * display's blue and is unambiguously a light rather than a surface, has a luminance of 0.101
+ * and cannot reach a threshold of 1 at all. It would need to reach 13.8 to try.
+ *
+ * That was shipped, and it was found from outside by the consumer who asked for bloom in the
+ * first place: two of their worlds are built entirely out of coloured light, and both bloomed by
+ * **zero pixels of 921,600** with the effect on and the threshold meaning exactly what it says.
+ * Everything switched on, nothing wrong, and nothing happening, which is the failure this
+ * repository has now shipped three times under different names.
+ *
+ * The largest channel makes the threshold mean what a reader already thinks it means: past
+ * white. It can only ever bloom *more*, never less, because the largest channel of a colour is
+ * never below its luminance, and the two are exactly equal on any neutral grey — so a scene lit
+ * in white is unchanged by this and a scene lit in colour is fixed by it. What it costs is that
+ * a strongly red surface driven past white in red alone now blooms where a grey of the same
+ * luminance does not, which is the honest reading of "this channel is off the top of the range".
+ *
+ * The ratio is applied to all three channels rather than per channel, so the hue of the halo is
+ * the hue of the thing that cast it. Subtracting the threshold per channel is the other way to
+ * write this and it turns a warm white into an orange halo, which is a filter's look rather than
+ * a light's.
+ */
+const BLOOM_BRIGHTNESS = `
+float brightness(vec3 c) {
+  return max(c.r, max(c.g, c.b));
+}
+`;
+
+/**
+ * Stage one: threshold the scene and halve it.
+ *
+ * **Subtracted rather than stepped**, which is what keeps one number honest. A hard cut at the
+ * threshold puts a visible edge through any gradient that crosses it, and repairing that is
+ * where a second knob usually arrives. Scaling the colour by how far its own luminance sits
+ * past the threshold is continuous, starts at exactly nothing, and needs no knee: a pixel just
+ * over the line contributes almost none of itself, and one far over contributes nearly all.
+ *
+ * **The boxes are averaged by the Karis weighting here and nowhere else.** A single pixel far
+ * brighter than its neighbours — which this renderer produces, on glossy dark paint, and which
+ * STATUS 6.3 measures — would otherwise be spread into a visible blob by the very pass whose
+ * job is to spread bright things. Weighting each box by 1 / (1 + luma) before averaging makes
+ * one runaway pixel count for little against its four neighbours. It is applied only to the
+ * first stage because it is not energy-preserving, and running it down the whole chain darkens
+ * every large bright area rather than only taming isolated ones.
+ */
+export const BLOOM_PREFILTER_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+uniform sampler2D uSource;
+/** One source texel in UV. The thirteen taps are laid out in source texels. */
+uniform vec2 uTexel;
+/** In scene units. 1.0 is "brighter than white", which is the useful place to start. */
+uniform float uThreshold;
+
+out vec4 fragColor;
+
+/**
+ * A ceiling on what any one pixel may contribute, well above anything a scene means.
+ *
+ * Not a look control. A half-float target can hold an infinity, and an infinity through the
+ * threshold below is inf/inf, which is a NaN that the chain then spreads across the whole
+ * frame — the one failure mode where a post pass destroys the picture rather than degrading
+ * it. Anything above this is indistinguishable after the tone curve anyway.
+ */
+const float BLOOM_CEILING = 256.0;
+${BLOOM_BRIGHTNESS}
+vec3 fetch(vec2 uv) {
+  vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));
+  float bright = brightness(c);
+  return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));
+}
+
+/** How much a box counts for. A runaway pixel drags its box's brightness up and its weight down. */
+float firefly(vec3 c) {
+  return 1.0 / (1.0 + brightness(c));
+}
+
+void main() {
+${BLOOM_BOXES}
+  float w0 = firefly(box0) * 0.125;
+  float w1 = firefly(box1) * 0.125;
+  float w2 = firefly(box2) * 0.125;
+  float w3 = firefly(box3) * 0.125;
+  float w4 = firefly(box4) * 0.5;
+  vec3 sum = box0 * w0 + box1 * w1 + box2 * w2 + box3 * w3 + box4 * w4;
+  fragColor = vec4(sum / max(w0 + w1 + w2 + w3 + w4, 1e-4), 1.0);
+}
+`;
+
+/**
+ * Stage two: halve what is already thresholded, once per level.
+ *
+ * The weights sum to exactly one, so each level holds the average of what fed it and the chain
+ * neither gains nor loses light. Nothing is thresholded again: that decision was made once, at
+ * full resolution, where it could still be made per pixel.
+ */
+export const BLOOM_DOWNSAMPLE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+uniform sampler2D uSource;
+uniform vec2 uTexel;
+
+out vec4 fragColor;
+
+vec3 fetch(vec2 uv) {
+  return textureLod(uSource, uv, 0.0).rgb;
+}
+
+void main() {
+${BLOOM_BOXES}
+  fragColor = vec4(box4 * 0.5 + (box0 + box1 + box2 + box3) * 0.125, 1.0);
+}
+`;
+
+/**
+ * Stage three: a 3x3 tent, added into the level above.
+ *
+ * **Additive rather than a mix, and each octave counts the same.** A lone bright pixel arrives
+ * at level n divided by four to the n, spread over four to the n pixels, so summing the levels
+ * lifts its own pixel by about a third and lays a long shallow tail around it. That falloff is
+ * what a real glare looks like; a single gaussian gives a disc with an end to it.
+ *
+ * The radius is in UV rather than in texels, so it is the same fraction of the frame at every
+ * level and on every display. A tent rather than a box because the seams between the four
+ * texels a bilinear upsample reads are otherwise visible as a grid on a wide, faint halo.
+ */
+export const BLOOM_UPSAMPLE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+uniform sampler2D uSource;
+/** How far the tent reaches, in UV. One number for the whole chain. */
+uniform float uRadius;
+
+out vec4 fragColor;
+
+void main() {
+  float r = uRadius;
+  vec3 a = textureLod(uSource, vUv + vec2(-r,  r), 0.0).rgb;
+  vec3 b = textureLod(uSource, vUv + vec2(0.0, r), 0.0).rgb;
+  vec3 c = textureLod(uSource, vUv + vec2( r,  r), 0.0).rgb;
+  vec3 d = textureLod(uSource, vUv + vec2(-r, 0.0), 0.0).rgb;
+  vec3 e = textureLod(uSource, vUv, 0.0).rgb;
+  vec3 f = textureLod(uSource, vUv + vec2( r, 0.0), 0.0).rgb;
+  vec3 g = textureLod(uSource, vUv + vec2(-r, -r), 0.0).rgb;
+  vec3 h = textureLod(uSource, vUv + vec2(0.0, -r), 0.0).rgb;
+  vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;
+
+  vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);
+  fragColor = vec4(sum * 0.0625, 1.0);
+}
+`;

package/src/render/shaders/bolt.ts

@@ -0,0 +1,164 @@
+import { FOG_GLSL } from './fog.ts';
+
+/**
+ * Electrical arcs: a filament with a saturating core and a wide soft glow.
+ *
+ * **Additive, and deliberately over-bright.** A discharge is not a surface with a
+ * colour, it is light arriving — so nothing here is lit, shaded or fogged the way
+ * geometry is, and the core is allowed to exceed white so it reads as blinding
+ * rather than as a pale line. That is the whole difference between lightning and a
+ * drawn wire, and it is why this cannot be a variant of the flat material.
+ *
+ * Each segment of an arc is expanded into a quad that faces the viewer, which for
+ * a *filament* is correct where it would be wrong for a volume: a bolt has no
+ * thickness to see around, so a world-fixed cross (what `plumeRenderer` uses, for
+ * good reasons of its own) would only make half the segments vanish edge-on. What
+ * gives an arc its three-dimensionality is the path, and the path is world-space.
+ */
+
+export const BOLT_VERT = `#version 300 es
+layout(location = 0) in vec3 aFrom;
+layout(location = 1) in vec3 aTo;
+/** Along the segment (0 or 1), and which side of it (-1 or +1). */
+layout(location = 2) in vec2 aCorner;
+/** Where this segment sits along its arc, the arc's envelope, its seed, its gain. */
+layout(location = 3) in vec4 aArc;
+
+uniform mat4 uViewProj;
+uniform vec3 uCameraPos;
+/** Core half-width in metres, and how much of a pixel a far arc must still cover. */
+uniform float uWidth;
+uniform float uMinWidthPerMetre;
+
+out float vSide;
+out float vAlong;
+out float vFade;
+out float vSeed;
+out float vGain;
+out vec3 vWorldPos;
+
+void main() {
+  vec3 mid = mix(aFrom, aTo, aCorner.x);
+  vec3 dir = aTo - aFrom;
+  float len = length(dir);
+  dir = len > 1e-6 ? dir / len : vec3(0.0, 1.0, 0.0);
+
+  vec3 view = mid - uCameraPos;
+  float dist = length(view);
+  view = dist > 1e-6 ? view / dist : vec3(0.0, 0.0, 1.0);
+
+  /*
+   * Across the segment and across the line of sight. Degenerate exactly when the
+   * segment points at the viewer, where any perpendicular is as good as another —
+   * and where the segment covers almost no screen anyway.
+   */
+  vec3 across = cross(dir, view);
+  float span = length(across);
+  across = span > 1e-4 ? across / span : normalize(cross(dir, vec3(0.0, 1.0, 0.0)) + vec3(1e-3));
+
+  /*
+   * A floor on the world-space width that grows with distance, so a filament
+   * never thins below a pixel. Under a pixel a bright thin line does not get
+   * fainter, it *flickers* — the rasteriser catches it on some frames and not
+   * others — and a strobing artefact reads as a bug, not as lightning.
+   */
+  float halfWidth = max(uWidth, dist * uMinWidthPerMetre);
+  vec3 world = mid + across * aCorner.y * halfWidth;
+
+  vSide = aCorner.y;
+  vAlong = aArc.x;
+  vFade = aArc.y;
+  vSeed = aArc.z;
+  vGain = aArc.w;
+  vWorldPos = world;
+  gl_Position = uViewProj * vec4(world, 1.0);
+}
+`;
+
+export const BOLT_FRAG = `#version 300 es
+precision highp float;
+
+in float vSide;
+in float vAlong;
+in float vFade;
+in float vSeed;
+in float vGain;
+in vec3 vWorldPos;
+
+uniform float uTime;
+/** The saturating centre, and the glow it sits inside. */
+uniform vec3 uCoreColor;
+uniform vec3 uEdgeColor;
+/** How far past white the core is allowed to go. */
+uniform float uCoreGain;
+${FOG_GLSL}
+uniform vec3 uCameraPos;
+
+out vec4 outColor;
+
+float hash11(float p) {
+  return fract(sin(p * 12.9898) * 43758.5453123);
+}
+
+void main() {
+  /*
+   * Across the filament: 1 at the centre line, 0 at the quad's edge. Two powers
+   * of it are the entire look — a very tight one for the core and a loose one for
+   * the glow. A single falloff gives either a hard line with no atmosphere or a
+   * soft smudge with no filament.
+   */
+  float across = 1.0 - abs(vSide);
+  float core = pow(across, 10.0);
+  /*
+   * A *wide* halo, deliberately. This exponent is the single biggest control over
+   * whether the effect reads as lightning or as a drawn line: a tight falloff gives a
+   * crisp filament with nothing around it, which is a wire, while a broad one bleeds
+   * light into the air the way an over-exposed discharge does on film. It is the
+   * closest thing to bloom available without a second pass.
+   */
+  float glow = pow(across, 1.1);
+
+  /*
+   * Stutter. An arc is not a steady light: it is re-established many times a
+   * second, and the eye reads a *constant* bright line as neon. Two frequencies
+   * so the pattern does not read as a sine, and per-arc phase from the seed so
+   * several arcs never blink together.
+   */
+  /*
+   * Stutter, but shallow. An arc is re-established many times a second and a perfectly
+   * steady bright line reads as neon — but too *much* flicker reads as a broken effect
+   * rather than as a discharge, and at the brief lifetime these now have, deep flicker
+   * mostly hides the bolt. The path itself is already being redrawn (see 'BoltPool'),
+   * which carries most of the crackle; this only keeps the brightness alive.
+   */
+  float t = uTime * 47.0 + vSeed * 17.0;
+  float stutter = 0.78 + 0.22 * (hash11(floor(t)) * 0.6 + hash11(floor(t * 2.37)) * 0.4);
+
+  /*
+   * The tip tapers. An arc that ends in a squared-off quad reads as a drawn
+   * segment; thinning toward the far end is what makes it read as a discharge
+   * dissipating into the air.
+   */
+  float taper = 1.0 - vAlong * 0.55;
+
+  float energy = vFade * stutter * taper * vGain;
+  vec3 lit = uEdgeColor * glow + uCoreColor * core * uCoreGain;
+
+  /*
+   * Distance dims it rather than tinting it toward the fog. A discharge emits;
+   * mixing it into the medium's colour is what a *surface* does, and doing that
+   * here turned a far bolt grey instead of faint.
+   */
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+  /*
+   * Alpha is 1, and the energy is already in the colour.
+   *
+   * The additive blend is 'SRC_ALPHA, ONE', so what reaches the framebuffer is
+   * 'rgb * a'. Putting the energy in both — which the first version did — squares it,
+   * and squaring a number below one is how an effect authored as blinding arrives as
+   * faint: at a typical energy of 0.5 it delivered a quarter of what it asked for.
+   * Every emissive material here has to pick one channel and mean it.
+   */
+  outColor = vec4(lit * energy * (1.0 - fog), 1.0);
+}
+`;

package/src/render/shaders/caustics.ts

@@ -0,0 +1,169 @@
+import { GERSTNER_GLSL } from './gerstner.ts';
+import { FOG_GLSL } from './fog.ts';
+
+/**
+ * Light off water, projected onto what covers it.
+ *
+ * Everybody who has walked under a canal bridge has seen this: the soffit is
+ * dark, and the water outside throws a moving net of light across it. Almost no
+ * game bothers, because it needs the water and the enclosure to know about each
+ * other — and the pattern has to belong to the waves actually visible five
+ * metres away or it is a texture loop with extra steps.
+ *
+ * So it is computed from `gerstner.ts`, the same table, phase and clock the
+ * surface itself is displaced by. Not similar parameters: the same ones.
+ *
+ * **The model.** A ray from the dominant source strikes the water at some point
+ * and reflects up to the ceiling. To first order in the slope, the reflected ray
+ * lands at `C = W - 2·d·grad h(W)`, so the map from water to ceiling has
+ * Jacobian `J = I - 2·d·H`, with `H` the surface's Hessian and `d` the ray's
+ * path length. Radiance is conserved, so brightness goes as `1/|det J|` — and it
+ * is unbounded where `det J` crosses zero, which is the bright net. Troughs
+ * focus and crests spread, exactly as a concave and a convex mirror do.
+ *
+ * Three consequences fall out rather than being authored, and they are what sell
+ * it: the pattern crawls with the real crests; a low sun stretches the net and
+ * throws it sideways along the light, because `d` is the slant path and not the
+ * drop; and calm water gives a soft wide sheen where a built-up sea gives sharp
+ * lines.
+ *
+ * **The gates**, because a caustic on the wrong surface is worse than none: the
+ * sheet must be within a few metres of the water, on either side of it, and it
+ * must be a surface the water can actually throw light onto — which is a
+ * property of the geometry a caller submits. Enclosure is the caller's business
+ * too, though a soffit needs less care than most: a downward face receives no
+ * directional light in the first place, so the underside of anything solid is
+ * already the darkest surface in the scene, and this reads there without a fake
+ * ambient volume. A pool floor is the other half of the same effect and the more
+ * ordinary one, and it wants the sheet laid just clear of the tiles.
+ */
+export const CAUSTICS_VERT = `#version 300 es
+layout(location = 0) in vec3 aRest;
+layout(location = 1) in vec2 aLocal;
+/** x: resting height of the water below. y: spare. */
+layout(location = 2) in vec2 aParams;
+
+uniform mat4 uViewProj;
+
+out vec3 vWorldPos;
+out vec2 vLocal;
+out vec2 vParams;
+
+void main() {
+  vWorldPos = aRest;
+  vLocal = aLocal;
+  vParams = aParams;
+  gl_Position = uViewProj * vec4(aRest, 1.0);
+}
+`;
+
+export const CAUSTICS_FRAG = `#version 300 es
+precision highp float;
+
+in vec3 vWorldPos;
+in vec2 vLocal;
+in vec2 vParams;
+
+uniform vec3 uCameraPos;
+uniform vec2 uWindDir;
+uniform float uWaveGain;
+uniform float uTime;
+/** Toward the dominant source, as everywhere else in the engine. */
+uniform vec3 uLightDir;
+/** Colour of the light the water is reflecting. */
+uniform vec3 uTint;
+uniform float uStrength;
+/** How far from the water, on either side, the effect has died out entirely. */
+uniform float uMaxDrop;
+${FOG_GLSL}
+
+out vec4 outColor;
+
+${GERSTNER_GLSL}
+
+/**
+ * Shallowest the source may be and still be treated as a source.
+ *
+ * The slant path goes as 1/sin(elevation), so a light on the horizon would send
+ * the sampled water position kilometres away and the pattern would smear into
+ * noise. Clamping keeps a sunset dramatic instead of broken.
+ */
+const float MIN_ELEVATION = 0.16;
+
+void main() {
+  float waterY = vParams.x;
+  float drop = vWorldPos.y - waterY;
+
+  /*
+   * Everything is masked rather than branched on, and fwidth() below is why:
+   * screen-space derivatives are undefined in non-uniform control flow, so a
+   * discard above them would make the antialiasing of the caustic lines a
+   * driver-dependent guess. Nothing is saved by branching either — a masked
+   * fragment adds zero under additive blending.
+   *
+   * Either side of the surface is lit, and the distance from it is what matters
+   * rather than the direction. This began as a soffit-only effect — light thrown
+   * *up* onto the underside of a bridge — on the reasoning that below the water
+   * there is nothing to light. That is only true when the water is a ceiling to
+   * you. A pool floor, a flooded corridor, a tank with a lamp over it: the water
+   * focuses light onto the bottom exactly as it does onto a soffit, and it is by
+   * far the more common of the two.
+   *
+   * Only the surface's own thin band is excluded, where the sheet and the water
+   * are coplanar and the pattern would be meaningless.
+   *
+   * Too far from it and the net has spread into nothing. And the sheet dissolves
+   * at its own boundary, so a lit surface does not end in a lit rectangle.
+   */
+  float distanceFromWater = abs(drop);
+  float clear = step(0.02, distanceFromWater);
+  float height = 1.0 - smoothstep(uMaxDrop * 0.45, uMaxDrop, distanceFromWater);
+  float rim = min(min(vLocal.x, 1.0 - vLocal.x), min(vLocal.y, 1.0 - vLocal.y));
+  float edge = smoothstep(0.0, 0.12, rim);
+  float reach = clear * height * edge;
+
+  /*
+   * Which water lights *this* point. For a flat surface the reflected ray leaves
+   * along the mirrored light direction, so walking back from the ceiling gives
+   * the water position and the path length in one step. This is why the net
+   * slides along the ground as the sun moves rather than sitting under itself.
+   */
+  float elevation = max(uLightDir.y, MIN_ELEVATION);
+  float slant = 1.0 / elevation;
+  float d = drop * slant;
+  vec2 water = vWorldPos.xz + uLightDir.xz * d;
+
+  vec3 h = gerstnerCurvature(water, uTime, uWindDir, uWaveGain);
+  float a = 1.0 - 2.0 * d * h.x;
+  float b = 1.0 - 2.0 * d * h.y;
+  float c = 2.0 * d * h.z;
+  float det = a * b - c * c;
+
+  /*
+   * The bright net is where the determinant crosses zero, so its width is a
+   * gradient question, not a constant. Widening the core by the screen-space
+   * derivative antialiases it for free — without that, a line thinner than a
+   * pixel strobes as the camera moves, which is the usual reason an effect like
+   * this ends up looking like noise.
+   */
+  float soft = max(0.05, fwidth(det) * 1.6);
+  float lines = soft / max(abs(det), soft);
+  /*
+   * Between the lines, the faint brightening of merely convergent water — and it has to
+   * stay faint. At 0.45 it lit the *whole* sheet, and since the sheet hangs a few
+   * centimetres under the soffit, the result read as a pale plate floating below the
+   * bridge rather than as light on its underside — reported as being able to see through
+   * the bridge ceiling, which looked glassy and transparent. The plate was the sheet.
+   *
+   * A tighter threshold and a fifth of the weight: the net is bright, everything between
+   * it is almost nothing, and a soffit with no caustics on it is simply a soffit.
+   */
+  float sheen = clamp(1.0 / max(abs(det), 0.18) - 0.85, 0.0, 1.0);
+  float caustic = clamp(lines * 0.9 + sheen * 0.09, 0.0, 1.6);
+
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+
+  // Additive: this is light arriving at a surface that is already shaded.
+  outColor = vec4(uTint * (caustic * uStrength * reach * (1.0 - fog)), 1.0);
+}
+`;

package/src/render/shaders/conditionals.ts

@@ -0,0 +1,58 @@
+/**
+ * `#if NAME` / `#else` / `#endif` resolved here rather than left to GLSL.
+ *
+ * The driver's own preprocessor would reach the same compiled program, so this is not
+ * about the result — it is about what the driver is handed at all. A `#define` still ships
+ * every declaration in the source text and asks the compiler to discard them, which leaves
+ * the thing being avoided inside the component being blamed. Cutting the lines out in
+ * JavaScript means a shadowless profile never sends a sampler anywhere, and it turns the
+ * absence into something a test can assert on a string rather than something only a GPU
+ * could confirm.
+ *
+ * Deliberately not a preprocessor: one directive, names only, no expressions. Anything
+ * more belongs in GLSL, which already has one.
+ *
+ * It lived inside `flat.ts` until a second program needed permuting. Nothing about it was
+ * ever specific to that shader, and the reason it moved is the reason it is worth stating:
+ * the cost that justified it, a shadowless profile still compiling every sampler it could
+ * never reach, is paid by whichever program declares them, not by the one that happens to
+ * have found it first.
+ */
+export function resolveConditionals(
+  source: string,
+  defines: Readonly<Record<string, boolean>>,
+  shaderName: string,
+): string {
+  const kept: string[] = [];
+  /** One frame per open `#if`, holding whether its own branch is the live one. */
+  const stack: { keep: boolean }[] = [];
+  const keeping = (): boolean => stack.every((frame) => frame.keep);
+
+  for (const line of source.split('\n')) {
+    const directive = line.trim();
+    if (directive.startsWith('#if ')) {
+      const name = directive.slice(4).trim();
+      if (!(name in defines)) {
+        throw new Error(`${shaderName} shader: unknown condition ${name}`);
+      }
+      stack.push({ keep: defines[name] === true });
+      continue;
+    }
+    if (directive === '#else') {
+      const frame = stack[stack.length - 1];
+      if (frame === undefined) throw new Error(`${shaderName} shader: #else outside #if`);
+      frame.keep = !frame.keep;
+      continue;
+    }
+    if (directive === '#endif') {
+      if (stack.pop() === undefined) {
+        throw new Error(`${shaderName} shader: #endif outside #if`);
+      }
+      continue;
+    }
+    if (keeping()) kept.push(line);
+  }
+
+  if (stack.length > 0) throw new Error(`${shaderName} shader: unterminated #if`);
+  return kept.join('\n');
+}