@driftengine/core 4.13.3 → 4.13.5

package/dist/render/hairLobes.js

@@ -17,6 +17,16 @@ export const HAIR_MIN_BETA = 0.05;
  * and its integral 4π times that. Over π: **1.33**.
  */
 export const HAIR_SCATTER_SPHERE = 1.33;
+/**
+ * How far every lobe is widened for light from every side, in radians: the angle a source would
+ * subtend to widen them as much, `sourceRadius / 2·dist` in `hairLight`'s terms.
+ *
+ * **0.2, the real-time form's own value**, which stands one direction in for the sphere: a lobe as
+ * narrow as a lamp's would put the whole sky's light into one highlight wherever the eye's
+ * direction happens to meet it. What it gives up is the sky's shape: a sun low in a clear sky and
+ * an even overcast light hair through the same widened lobes.
+ */
+export const HAIR_AREA = 0.2;
 /** How much the scatter term leans toward the strand's own direction rather than the pseudo-normal. */
 const KAJIYA_SHARE = 0.33;
 /** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
@@ -39,13 +49,55 @@ export const HAIR_OUT = { r: 0, tt: 1, trt: 4, scatter: 7, length: 10 };
 /**
  * One light on a strand, in lamp units and unshadowed, into `out` (`HAIR_OUT`'s layout: R is grey,
  * the rest colours). `tangent`, `toLight` and `toEye` are unit vectors but for a tangent that could
- * not be made one, which comes in as zeros; `fibre` is the base colour.
+ * not be made one, which comes in as zeros; `fibre` is the base colour; `specular` is the strand's,
+ * the model map's red, which scales the reflected lobe by twice it, so 0.5 draws the lobe as the
+ * fit gives it and 0 is a strand that reflects nothing off its surface.
  *
  * **A lamp with a size widens every lobe by the angle it subtends**, `sourceRadius / 2·dist` as
  * `sphereLobe` takes it, and the lobes are normalised Gaussians, so a wider one carries the same
  * light rather than more. The sun passes zeros.
  */
-export function hairLight(tangent, toLight, toEye, fibre, roughness, shift, scatter, backlit, sourceRadius, dist, out) {
+export function hairLight(tangent, toLight, toEye, fibre, roughness, shift, specular, scatter, backlit, sourceRadius, dist, out) {
+    const grow = sourceRadius / Math.max(2 * dist, 1e-3);
+    hairLobes(tangent, toLight, toEye, fibre, roughness, shift, specular, scatter, backlit, grow, out);
+}
+/** The flattened eye `hairIndirect` lights a strand along, as the shader finds it. */
+const flattened = new Float64Array(3);
+/**
+ * The share of light from every side a strand returns, a colour into `out`, with the one
+ * direction's lobes it is made of into `lobes` (`HAIR_OUT`'s layout). `normal` is the surface's,
+ * which stands in for the flattened eye where the eye runs along the strand and there is none.
+ *
+ * **One direction for the sphere**: the eye flattened across the strand, `V − T(V·T)`, unshadowed,
+ * with no light from behind and so no transmitted lobe, every lobe widened by `HAIR_AREA`. Twice
+ * the sum, and at most all of what arrives. **Why twice**: the scatter's half is then
+ * `HAIR_SCATTER_SPHERE`, its own answer to an even sky — along the flattened eye its shape is
+ * `mix(1/2, 1, 0.33)`, 0.665, which doubled is that constant's 1.33 — so the lobes ride on a
+ * scatter the sphere's quadrature already holds to, and R and TRT are what the direction adds.
+ */
+export function hairIndirect(tangent, toEye, normal, fibre, roughness, shift, specular, scatter, lobes, out) {
+    const along = dot(tangent, toEye);
+    let length2 = 0;
+    for (let c = 0; c < 3; c++) {
+        const across = toEye[c] - tangent[c] * along;
+        flattened[c] = across;
+        length2 += across * across;
+    }
+    for (let c = 0; c < 3; c++) {
+        flattened[c] =
+            length2 > 1e-8 ? flattened[c] / Math.sqrt(length2) : normal[c];
+    }
+    hairLobes(tangent, flattened, toEye, fibre, roughness, shift, specular, scatter, 0, HAIR_AREA, lobes);
+    for (let c = 0; c < 3; c++) {
+        const sum = lobes[HAIR_OUT.r] +
+            lobes[HAIR_OUT.tt + c] +
+            lobes[HAIR_OUT.trt + c] +
+            lobes[HAIR_OUT.scatter + c];
+        out[c] = Math.min(1, 2 * sum);
+    }
+}
+/** `hairLight`'s arithmetic, every lobe widened by `grow` radians. */
+function hairLobes(tangent, toLight, toEye, fibre, roughness, shift, specular, scatter, backlit, grow, out) {
     const sinI = clamp(dot(tangent, toLight), -1, 1);
     const sinO = clamp(dot(tangent, toEye), -1, 1);
     /*
@@ -68,12 +120,13 @@ export function hairLight(tangent, toLight, toEye, fibre, roughness, shift, scat
     const cosPhi = lpvp / Math.sqrt(lp2 * vp2 + 1e-4);
     const cosHalfPhi = Math.sqrt(clamp(0.5 + 0.5 * cosPhi, 0, 1));
     const beta = Math.max(roughness * roughness, HAIR_MIN_BETA);
-    const grow = sourceRadius / Math.max(2 * dist, 1e-3);
     const x = sinI + sinO;
     const r = hairLongitudinal(beta + grow, x + 2 * shift) *
         0.25 *
         cosHalfPhi *
-        hairFresnel(Math.sqrt(clamp(0.5 + 0.5 * dot(toLight, toEye), 0, 1)));
+        hairFresnel(Math.sqrt(clamp(0.5 + 0.5 * dot(toLight, toEye), 0, 1))) *
+        2 *
+        specular;
     const a = 1 / (1.19 / cosD + 0.36 * cosD);
     const h = cosHalfPhi * (1 + a * (0.6 - 0.8 * cosPhi));
     const fTT = hairFresnel(cosD * Math.sqrt(clamp(1 - h * h, 0, 1)));

package/dist/render/lightBudget.d.ts

@@ -389,6 +389,13 @@ export interface PointLightSet {
      * falls off as it did. See `PointLightSource.falloffExponent`.
      */
     readonly lightFalloffExponents?: Float32Array;
+    /**
+     * One per light: how strongly it scatters in the global medium, as a share of how strongly it
+     * lights a surface, beside `setGlobalMedium`'s `lampScatter` for every lamp at once. **Absent, or
+     * a short array, is 1 for every light.** A lamp turned up here lights a fog bank brighter than it
+     * lights the floor in it, which is how a lamp authored for its shaft rather than its pool reads.
+     */
+    readonly lightMediumScatter?: Float32Array;
 }
 /**
  * A cone that admits every direction, for every light.
@@ -477,6 +484,11 @@ export interface ResolvedPointLights {
     readonly heldSourceRadii: Float32Array;
     readonly heldWeights: Float32Array;
 }
+/**
+ * A target for `resolvePointLights`, made once outside the frame loop. Its arrays are references
+ * the resolve points at the caller's own or at the defaults, but for the four it owns.
+ */
+export declare function createResolvedPointLights(): ResolvedPointLights;
 /**
  * Choose which array each slot actually gets, with every fallback applied.
  *

package/dist/render/lightBudget.js

@@ -471,6 +471,30 @@ export function bindAreaShadows(gl, uniforms, shadows) {
     gl.uniform1fv(uniforms['uLiveAreaShadowNear[0]'] ?? null, shadows.liveNear);
     gl.uniform1fv(uniforms['uLiveAreaShadowWeight[0]'] ?? null, shadows.liveWeight);
 }
+/**
+ * A target for `resolvePointLights`, made once outside the frame loop. Its arrays are references
+ * the resolve points at the caller's own or at the defaults, but for the four it owns.
+ */
+export function createResolvedPointLights() {
+    return {
+        count: 0,
+        falloff: 0,
+        positions: NO_POSITIONS,
+        colors: NO_COLORS,
+        radii: POINT_SOURCES,
+        sourceRadii: POINT_SOURCES,
+        weights: FULLY_PRESENT,
+        directions: NO_DIRECTIONS,
+        coneCos: OPEN_CONES,
+        iesProfiles: NO_PROFILES,
+        iesAxes: NO_IES_AXES,
+        cookies: NO_COOKIES,
+        axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+        conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
+        heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
+        heldWeights: new Float32Array(MAX_POINT_LIGHTS),
+    };
+}
 /** One per GL binder, refilled per call: holds references, allocates nothing. */
 const glLights = {
     count: 0,

package/dist/render/sceneTarget.d.ts

@@ -1,3 +1,4 @@
+import type { LocalExposureOptions } from './shaders/localExposure.ts';
 import { type ColourGradeLut } from './colourGrade.ts';
 import type { Vec3 } from '../math/color.ts';
 /**
@@ -96,8 +97,9 @@ export declare class SceneTarget {
     /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
     private autoExposure;
     private autoExposureDt;
-    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+    /** Whether regions move, and how, as `resolveLocalExposure` packs it. See `setLocalExposure`. */
     private localExposure;
+    private readonly localExposureShape;
     private exposure;
     private width;
     private height;
@@ -285,8 +287,8 @@ export declare class SceneTarget {
     setFilmGrain(strength: number, seed: number): void;
     /** How far the eye adapts, and the time since the last frame. See `Renderer.setAutoExposure`. */
     setAutoExposure(strength: number, dtSec: number): void;
-    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
-    setLocalExposure(strength: number): void;
+    /** How regions are brought toward the frame. See `Renderer.setLocalExposure`. */
+    setLocalExposure(setting: number | LocalExposureOptions): void;
     /** A new shot: the eye meters it afresh rather than easing in from the last one. */
     cutExposure(): void;
     setColourGrade(lut: ColourGradeLut | null, strength: number): void;

package/dist/render/sceneTarget.js

@@ -4,7 +4,7 @@ import { FRINGE_FLOATS, resolveFringe } from './shaders/fringe.js';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.js';
 import { ExposurePass } from './exposurePass.js';
 import { clampAutoExposure } from './shaders/exposure.js';
-import { clampLocalExposure } from './shaders/localExposure.js';
+import { LOCAL_EXPOSURE_FLOATS, resolveLocalExposure } from './shaders/localExposure.js';
 import { BloomPass } from './bloomPass.js';
 import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from './colourGrade.js';
 import { compileProgram, uniformLocations } from './shader.js';
@@ -101,8 +101,9 @@ export class SceneTarget {
     /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
     autoExposure = 0;
     autoExposureDt = 0;
-    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
-    localExposure = 0;
+    /** Whether regions move, and how, as `resolveLocalExposure` packs it. See `setLocalExposure`. */
+    localExposure = false;
+    localExposureShape = new Float32Array(LOCAL_EXPOSURE_FLOATS);
     exposure = null;
     width = 0;
     height = 0;
@@ -622,9 +623,9 @@ export class SceneTarget {
         this.autoExposure = clampAutoExposure(strength);
         this.autoExposureDt = dtSec;
     }
-    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
-    setLocalExposure(strength) {
-        this.localExposure = clampLocalExposure(strength);
+    /** How regions are brought toward the frame. See `Renderer.setLocalExposure`. */
+    setLocalExposure(setting) {
+        this.localExposure = resolveLocalExposure(setting, this.localExposureShape);
     }
     /** A new shot: the eye meters it afresh rather than easing in from the last one. */
     cutExposure() {
@@ -800,7 +801,7 @@ export class SceneTarget {
          * reason: the composite consumes it. Off at zero strength, where nothing is allocated or drawn.
          */
         let heldExposure = null;
-        const local = this.localExposure > 0;
+        const local = this.localExposure;
         if ((this.autoExposure > 0 || local) && scene !== null) {
             this.exposure ??= new ExposurePass(gl);
             heldExposure = this.exposure.run(scene, this.autoExposureDt, local);
@@ -910,7 +911,12 @@ export class SceneTarget {
         gl.activeTexture(gl.TEXTURE6);
         gl.bindTexture(gl.TEXTURE_2D, localGrid ?? scene);
         gl.uniform1i(this.uniforms['uExposureLocal'] ?? null, 6);
-        gl.uniform1f(this.uniforms['uLocalExposure'] ?? null, localGrid === null ? 0 : this.localExposure);
+        gl.uniform1f(this.uniforms['uLocalExposure'] ?? null, localGrid === null ? 0 : 1);
+        /* Its shape only where it is on: off, the shader returns before reading it. */
+        if (localGrid !== null) {
+            gl.uniform4fv(this.uniforms['uLocalShape'] ?? null, this.localExposureShape, 0, 4);
+            gl.uniform4fv(this.uniforms['uLocalPivot'] ?? null, this.localExposureShape, 4, 4);
+        }
         /* Each object's own motion is WebGPU's under a reconstruction; here the scene stands in on
            unit 7 and the flag says not to read it, so the camera's motion alone blurs. */
         gl.activeTexture(gl.TEXTURE7);

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

@@ -16,4 +16,4 @@
  * gets motion without direction. That is what separates a spell from a lamp on a
  * dimmer.
  */
-export declare const ARCANE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin float vSeed;\nin float vDistance;\nin vec3 vWorldPos;\n\nuniform float uTime;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform int uNoiseOctaves;\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n/* Before `uTint`, where fire and smoke declare it, so one field table serves all three. */\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n/** The caller's colour, so an aura shifts with the world's own palette. */\nuniform vec3 uTint;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),\n    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),\n    u.y\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  // Polar about the quad centre. This is the line that makes it an orb rather\n  // than a column; everything downstream reads radius and angle, never height.\n  float radius = length(vUv - 0.5) * 2.0;\n  if (radius >= 1.0) discard;\n\n  vec2 d = vUv - 0.5;\n  float angle = atan(d.y, d.x);\n  float t = uTime + vSeed * 37.0;\n\n  /*\n   * Two bands, turning opposite ways at different rates. Sampled in (angle, radius)\n   * space so the noise wraps around the disc instead of sliding across it \u2014 noise in\n   * UV space would drift off one edge and read as a texture being scrolled.\n   */\n  float inner = valueNoise(vec2(angle * 1.9 + t * 0.55, radius * 4.2));\n  float outer = valueNoise(vec2(angle * 3.1 - t * 0.34, radius * 2.6));\n  float swirl = inner * 0.62 + outer * 0.38;\n  if (uNoiseOctaves > 1) {\n    swirl = mix(swirl, swirl * valueNoise(vec2(angle * 6.3 + t * 0.9, radius * 8.0)) * 2.0, 0.35);\n  }\n\n  /*\n   * Core and corona as two separate falloffs rather than one curve. A single falloff\n   * gives a blob; what makes this read as *contained energy* is a small bright centre\n   * with a much wider, much fainter halo, so the object inside stays legible.\n   */\n  float core = 1.0 - smoothstep(0.0, 0.28, radius);\n  float corona = (1.0 - smoothstep(0.18, 1.0, radius)) * (0.35 + swirl * 0.65);\n  float body = core * 0.9 + corona;\n  if (body <= 0.02) discard;\n\n  // Hot centre through the tint to a dark rim, so the core reads as white-hot\n  // energy and the edge as the colour it is made of.\n  vec3 col = mix(uTint * 0.35, uTint, smoothstep(0.0, 0.55, body));\n  col = mix(col, vec3(1.0), smoothstep(0.82, 1.4, body));\n  col *= uTint;\n\n  float alpha = clamp(body * 1.6, 0.0, 1.0);\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant aura glow through fog and through water.\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, mediumColor(), fog);\n  alpha *= 1.0 - fog;\n\n  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */\n  outColor = vec4(applyOutputTransform(col), alpha);\n}\n";
+export declare const ARCANE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin float vSeed;\nin float vDistance;\nin vec3 vWorldPos;\n\nuniform float uTime;\n\nuniform vec3 uFogColor;\n/**\n * The haze: its extinction per metre **at the camera's own height**, not at the base; its\n * reciprocal scale height per metre, 0 for a uniform medium; the camera's height, so a fragment's\n * own height is one subtraction away; and the water column's own density.\n *\n * **Four numbers in one vector rather than four uniforms**, and the reason is a phone: a scalar\n * costs a whole row of the uniform grid, and the lit stage at its eight-light rung must fit the 256\n * rows an Adreno 740 offers (uniformVectorBudget.ts). Packed, the haze's eight scalars cost two\n * rows where they cost eight, which is what paid for the second layer and the sun's glow below.\n */\nuniform vec4 uFogMedium;\n/** Where haze begins, where a linear ramp is total, and the mode: 0 a medium, 1 a ramp. */\nuniform vec4 uFogRange;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n/**\n * The second layer's extinction per metre at the camera's height and its falloff; then the least of\n * a surface the haze must leave, Atmosphere.fogMaxOpacity's complement, and the distance past which\n * it hides nothing (0 is none). **Every lane is none at zero**, and so are uFogGlow's: a program a\n * binder never wrote these into draws the haze it drew before they existed, rather than none.\n */\nuniform vec4 uFogLayer2;\n/** The sun's glow in the haze: its colour, black for none, and the exponent of its lobe. */\nuniform vec4 uFogGlow;\n/** Surface \u2192 the glow's light, and how far past the haze's start the glow begins. */\nuniform vec4 uFogGlowDir;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * The haze's optical depth from where it begins along the ray to a point at height pointY, dist\n * metres away: each layer's density at the eye carried over what is left of the ray, with the\n * second layer only where there is one. The fog and the sun's glow both integrate it.\n */\nfloat hazeDepth(float dist, float pointY) {\n  // Where the medium begins along the ray: uFogRange.x, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogRange.x, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogMedium.z) * uFogMedium.y;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float depth = uFogMedium.x * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom;\n  if (uFogLayer2.x > 0.0) {\n    float t2 = (pointY - uFogMedium.z) * uFogLayer2.y;\n    float rest2 = t2 * (1.0 - before);\n    float denom2 = abs(rest2) < 1e-4 ? 1e-4 : rest2;\n    depth += uFogLayer2.x * exp(-t2 * before) * (dist - start) * (1.0 - exp(-denom2)) / denom2;\n  }\n  return depth;\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /* Past the cutoff the air hides nothing, in either mode; the water column keeps its own law. */\n  bool cut = uFogLayer2.w > 0.0 && dist > uFogLayer2.w;\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogRange.z == 1.0) {\n    float span = max(uFogRange.y - uFogRange.x, 1e-4);\n    float ramp = cut ? 0.0 : min(clamp((dist - uFogRange.x) / span, 0.0, 1.0), 1.0 - uFogLayer2.z);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uFogMedium.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Beer-Lambert through both layers, leaving at least uFogLayer2.z of the surface: a floor on\n  // what survives rather than a ceiling on the depth, so the curve keeps its shape above it.\n  float air = cut ? 0.0 : 1.0 - max(exp(-hazeDepth(dist, pointY)), uFogLayer2.z);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uFogMedium.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/**\n * The sun's light the haze scatters toward the eye along a ray to a point at height pointY, dist\n * metres away in the direction toPoint: added to a surface after its fog, never mixed. A lobe of\n * cos^exponent about the light, by as much of the ray past the glow's own start as the haze hides \u2014\n * the haze's depth per metre carried over that stretch. None in a linear ramp, past the cutoff, or\n * under water, which keeps its own medium.\n */\nvec3 mediumGlow(float dist, float pointY, vec3 toPoint) {\n  if (uFogRange.z == 1.0 || max(max(uFogGlow.r, uFogGlow.g), uFogGlow.b) <= 0.0) return vec3(0.0);\n  if (uFogLayer2.w > 0.0 && dist > uFogLayer2.w) return vec3(0.0);\n  float span = dist - min(uFogRange.x, dist);\n  if (span <= 0.0) return vec3(0.0);\n  float perMetre = hazeDepth(dist, pointY) / span;\n  float hidden = 1.0 - exp(-perMetre * max(span - uFogGlowDir.w, 0.0));\n  float lobe = pow(clamp(dot(toPoint, uFogGlowDir.xyz), 0.0, 1.0), uFogGlow.a);\n  return uFogGlow.rgb * (lobe * hidden * (1.0 - uUnderwaterFactor));\n}\n\nuniform int uNoiseOctaves;\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n/* Before `uTint`, where fire and smoke declare it, so one field table serves all three. */\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n/** The caller's colour, so an aura shifts with the world's own palette. */\nuniform vec3 uTint;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),\n    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),\n    u.y\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  // Polar about the quad centre. This is the line that makes it an orb rather\n  // than a column; everything downstream reads radius and angle, never height.\n  float radius = length(vUv - 0.5) * 2.0;\n  if (radius >= 1.0) discard;\n\n  vec2 d = vUv - 0.5;\n  float angle = atan(d.y, d.x);\n  float t = uTime + vSeed * 37.0;\n\n  /*\n   * Two bands, turning opposite ways at different rates. Sampled in (angle, radius)\n   * space so the noise wraps around the disc instead of sliding across it \u2014 noise in\n   * UV space would drift off one edge and read as a texture being scrolled.\n   */\n  float inner = valueNoise(vec2(angle * 1.9 + t * 0.55, radius * 4.2));\n  float outer = valueNoise(vec2(angle * 3.1 - t * 0.34, radius * 2.6));\n  float swirl = inner * 0.62 + outer * 0.38;\n  if (uNoiseOctaves > 1) {\n    swirl = mix(swirl, swirl * valueNoise(vec2(angle * 6.3 + t * 0.9, radius * 8.0)) * 2.0, 0.35);\n  }\n\n  /*\n   * Core and corona as two separate falloffs rather than one curve. A single falloff\n   * gives a blob; what makes this read as *contained energy* is a small bright centre\n   * with a much wider, much fainter halo, so the object inside stays legible.\n   */\n  float core = 1.0 - smoothstep(0.0, 0.28, radius);\n  float corona = (1.0 - smoothstep(0.18, 1.0, radius)) * (0.35 + swirl * 0.65);\n  float body = core * 0.9 + corona;\n  if (body <= 0.02) discard;\n\n  // Hot centre through the tint to a dark rim, so the core reads as white-hot\n  // energy and the edge as the colour it is made of.\n  vec3 col = mix(uTint * 0.35, uTint, smoothstep(0.0, 0.55, body));\n  col = mix(col, vec3(1.0), smoothstep(0.82, 1.4, body));\n  col *= uTint;\n\n  float alpha = clamp(body * 1.6, 0.0, 1.0);\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant aura glow through fog and through water.\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, mediumColor(), fog);\n  alpha *= 1.0 - fog;\n\n  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */\n  outColor = vec4(applyOutputTransform(col), alpha);\n}\n";

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

@@ -14,4 +14,4 @@
  * gives an arc its three-dimensionality is the path, and the path is world-space.
  */
 export declare const BOLT_VERT = "#version 300 es\nlayout(location = 0) in vec3 aFrom;\nlayout(location = 1) in vec3 aTo;\n/** Along the segment (0 or 1), and which side of it (-1 or +1). */\nlayout(location = 2) in vec2 aCorner;\n/** Where this segment sits along its arc, the arc's envelope, its seed, its gain. */\nlayout(location = 3) in vec4 aArc;\n\nuniform mat4 uViewProj;\nuniform vec3 uCameraPos;\n/** Core half-width in metres, and how much of a pixel a far arc must still cover. */\nuniform float uWidth;\nuniform float uMinWidthPerMetre;\n\nout float vSide;\nout float vAlong;\nout float vFade;\nout float vSeed;\nout float vGain;\nout vec3 vWorldPos;\n\nvoid main() {\n  vec3 mid = mix(aFrom, aTo, aCorner.x);\n  vec3 dir = aTo - aFrom;\n  float len = length(dir);\n  dir = len > 1e-6 ? dir / len : vec3(0.0, 1.0, 0.0);\n\n  vec3 view = mid - uCameraPos;\n  float dist = length(view);\n  view = dist > 1e-6 ? view / dist : vec3(0.0, 0.0, 1.0);\n\n  /*\n   * Across the segment and across the line of sight. Degenerate exactly when the\n   * segment points at the viewer, where any perpendicular is as good as another \u2014\n   * and where the segment covers almost no screen anyway.\n   */\n  vec3 across = cross(dir, view);\n  float span = length(across);\n  across = span > 1e-4 ? across / span : normalize(cross(dir, vec3(0.0, 1.0, 0.0)) + vec3(1e-3));\n\n  /*\n   * A floor on the world-space width that grows with distance, so a filament\n   * never thins below a pixel. Under a pixel a bright thin line does not get\n   * fainter, it *flickers* \u2014 the rasteriser catches it on some frames and not\n   * others \u2014 and a strobing artefact reads as a bug, not as lightning.\n   */\n  float halfWidth = max(uWidth, dist * uMinWidthPerMetre);\n  vec3 world = mid + across * aCorner.y * halfWidth;\n\n  vSide = aCorner.y;\n  vAlong = aArc.x;\n  vFade = aArc.y;\n  vSeed = aArc.z;\n  vGain = aArc.w;\n  vWorldPos = world;\n  gl_Position = uViewProj * vec4(world, 1.0);\n}\n";
-export declare const BOLT_FRAG = "#version 300 es\nprecision highp float;\n\nin float vSide;\nin float vAlong;\nin float vFade;\nin float vSeed;\nin float vGain;\nin vec3 vWorldPos;\n\nuniform float uTime;\n/** The saturating centre, and the glow it sits inside. */\nuniform vec3 uCoreColor;\nuniform vec3 uEdgeColor;\n/** How far past white the core is allowed to go. */\nuniform float uCoreGain;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform vec3 uCameraPos;\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\nfloat hash11(float p) {\n  return fract(sin(p * 12.9898) * 43758.5453123);\n}\n\nvoid main() {\n  /*\n   * Across the filament: 1 at the centre line, 0 at the quad's edge. Two powers\n   * of it are the entire look \u2014 a very tight one for the core and a loose one for\n   * the glow. A single falloff gives either a hard line with no atmosphere or a\n   * soft smudge with no filament.\n   */\n  /*\n   * Clamped, because a multisampled target shades a pixel on the quad's edge at its centre, which\n   * may lie outside the quad: there 'vSide' runs past one, 'across' goes negative, and 'pow' of a\n   * negative number is NaN. One NaN pixel is a dark speck; bloom then spreads it into a white disc\n   * the size of the blur. Found by a fight drawing short arcs at 4 samples.\n   */\n  float across = clamp(1.0 - abs(vSide), 0.0, 1.0);\n  float core = pow(across, 10.0);\n  /*\n   * A *wide* halo, deliberately. This exponent is the single biggest control over\n   * whether the effect reads as lightning or as a drawn line: a tight falloff gives a\n   * crisp filament with nothing around it, which is a wire, while a broad one bleeds\n   * light into the air the way an over-exposed discharge does on film. It is the\n   * closest thing to bloom available without a second pass.\n   */\n  float glow = pow(across, 1.1);\n\n  /*\n   * Stutter. An arc is not a steady light: it is re-established many times a\n   * second, and the eye reads a *constant* bright line as neon. Two frequencies\n   * so the pattern does not read as a sine, and per-arc phase from the seed so\n   * several arcs never blink together.\n   */\n  /*\n   * Stutter, but shallow. An arc is re-established many times a second and a perfectly\n   * steady bright line reads as neon \u2014 but too *much* flicker reads as a broken effect\n   * rather than as a discharge, and at the brief lifetime these now have, deep flicker\n   * mostly hides the bolt. The path itself is already being redrawn (see 'BoltPool'),\n   * which carries most of the crackle; this only keeps the brightness alive.\n   */\n  float t = uTime * 47.0 + vSeed * 17.0;\n  float stutter = 0.78 + 0.22 * (hash11(floor(t)) * 0.6 + hash11(floor(t * 2.37)) * 0.4);\n\n  /*\n   * The tip tapers. An arc that ends in a squared-off quad reads as a drawn\n   * segment; thinning toward the far end is what makes it read as a discharge\n   * dissipating into the air.\n   */\n  float taper = 1.0 - vAlong * 0.55;\n\n  float energy = vFade * stutter * taper * vGain;\n  vec3 lit = uEdgeColor * glow + uCoreColor * core * uCoreGain;\n\n  /*\n   * Distance dims it rather than tinting it toward the fog. A discharge emits;\n   * mixing it into the medium's colour is what a *surface* does, and doing that\n   * here turned a far bolt grey instead of faint.\n   */\n  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n  /*\n   * Alpha is 1, and the energy is already in the colour.\n   *\n   * The additive blend is 'SRC_ALPHA, ONE', so what reaches the framebuffer is\n   * 'rgb * a'. Putting the energy in both \u2014 which the first version did \u2014 squares it,\n   * and squaring a number below one is how an effect authored as blinding arrives as\n   * faint: at a typical energy of 0.5 it delivered a quarter of what it asked for.\n   * Every emissive material here has to pick one channel and mean it.\n   */\n  /* Graded where nothing after this will grade it, as every pass is, light added included. */\n  outColor = vec4(applyOutputTransform(lit * energy * (1.0 - fog)), 1.0);\n}\n";
+export declare const BOLT_FRAG = "#version 300 es\nprecision highp float;\n\nin float vSide;\nin float vAlong;\nin float vFade;\nin float vSeed;\nin float vGain;\nin vec3 vWorldPos;\n\nuniform float uTime;\n/** The saturating centre, and the glow it sits inside. */\nuniform vec3 uCoreColor;\nuniform vec3 uEdgeColor;\n/** How far past white the core is allowed to go. */\nuniform float uCoreGain;\n\nuniform vec3 uFogColor;\n/**\n * The haze: its extinction per metre **at the camera's own height**, not at the base; its\n * reciprocal scale height per metre, 0 for a uniform medium; the camera's height, so a fragment's\n * own height is one subtraction away; and the water column's own density.\n *\n * **Four numbers in one vector rather than four uniforms**, and the reason is a phone: a scalar\n * costs a whole row of the uniform grid, and the lit stage at its eight-light rung must fit the 256\n * rows an Adreno 740 offers (uniformVectorBudget.ts). Packed, the haze's eight scalars cost two\n * rows where they cost eight, which is what paid for the second layer and the sun's glow below.\n */\nuniform vec4 uFogMedium;\n/** Where haze begins, where a linear ramp is total, and the mode: 0 a medium, 1 a ramp. */\nuniform vec4 uFogRange;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n/**\n * The second layer's extinction per metre at the camera's height and its falloff; then the least of\n * a surface the haze must leave, Atmosphere.fogMaxOpacity's complement, and the distance past which\n * it hides nothing (0 is none). **Every lane is none at zero**, and so are uFogGlow's: a program a\n * binder never wrote these into draws the haze it drew before they existed, rather than none.\n */\nuniform vec4 uFogLayer2;\n/** The sun's glow in the haze: its colour, black for none, and the exponent of its lobe. */\nuniform vec4 uFogGlow;\n/** Surface \u2192 the glow's light, and how far past the haze's start the glow begins. */\nuniform vec4 uFogGlowDir;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * The haze's optical depth from where it begins along the ray to a point at height pointY, dist\n * metres away: each layer's density at the eye carried over what is left of the ray, with the\n * second layer only where there is one. The fog and the sun's glow both integrate it.\n */\nfloat hazeDepth(float dist, float pointY) {\n  // Where the medium begins along the ray: uFogRange.x, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogRange.x, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogMedium.z) * uFogMedium.y;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float depth = uFogMedium.x * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom;\n  if (uFogLayer2.x > 0.0) {\n    float t2 = (pointY - uFogMedium.z) * uFogLayer2.y;\n    float rest2 = t2 * (1.0 - before);\n    float denom2 = abs(rest2) < 1e-4 ? 1e-4 : rest2;\n    depth += uFogLayer2.x * exp(-t2 * before) * (dist - start) * (1.0 - exp(-denom2)) / denom2;\n  }\n  return depth;\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /* Past the cutoff the air hides nothing, in either mode; the water column keeps its own law. */\n  bool cut = uFogLayer2.w > 0.0 && dist > uFogLayer2.w;\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogRange.z == 1.0) {\n    float span = max(uFogRange.y - uFogRange.x, 1e-4);\n    float ramp = cut ? 0.0 : min(clamp((dist - uFogRange.x) / span, 0.0, 1.0), 1.0 - uFogLayer2.z);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uFogMedium.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Beer-Lambert through both layers, leaving at least uFogLayer2.z of the surface: a floor on\n  // what survives rather than a ceiling on the depth, so the curve keeps its shape above it.\n  float air = cut ? 0.0 : 1.0 - max(exp(-hazeDepth(dist, pointY)), uFogLayer2.z);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uFogMedium.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/**\n * The sun's light the haze scatters toward the eye along a ray to a point at height pointY, dist\n * metres away in the direction toPoint: added to a surface after its fog, never mixed. A lobe of\n * cos^exponent about the light, by as much of the ray past the glow's own start as the haze hides \u2014\n * the haze's depth per metre carried over that stretch. None in a linear ramp, past the cutoff, or\n * under water, which keeps its own medium.\n */\nvec3 mediumGlow(float dist, float pointY, vec3 toPoint) {\n  if (uFogRange.z == 1.0 || max(max(uFogGlow.r, uFogGlow.g), uFogGlow.b) <= 0.0) return vec3(0.0);\n  if (uFogLayer2.w > 0.0 && dist > uFogLayer2.w) return vec3(0.0);\n  float span = dist - min(uFogRange.x, dist);\n  if (span <= 0.0) return vec3(0.0);\n  float perMetre = hazeDepth(dist, pointY) / span;\n  float hidden = 1.0 - exp(-perMetre * max(span - uFogGlowDir.w, 0.0));\n  float lobe = pow(clamp(dot(toPoint, uFogGlowDir.xyz), 0.0, 1.0), uFogGlow.a);\n  return uFogGlow.rgb * (lobe * hidden * (1.0 - uUnderwaterFactor));\n}\n\nuniform vec3 uCameraPos;\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\nfloat hash11(float p) {\n  return fract(sin(p * 12.9898) * 43758.5453123);\n}\n\nvoid main() {\n  /*\n   * Across the filament: 1 at the centre line, 0 at the quad's edge. Two powers\n   * of it are the entire look \u2014 a very tight one for the core and a loose one for\n   * the glow. A single falloff gives either a hard line with no atmosphere or a\n   * soft smudge with no filament.\n   */\n  /*\n   * Clamped, because a multisampled target shades a pixel on the quad's edge at its centre, which\n   * may lie outside the quad: there 'vSide' runs past one, 'across' goes negative, and 'pow' of a\n   * negative number is NaN. One NaN pixel is a dark speck; bloom then spreads it into a white disc\n   * the size of the blur. Found by a fight drawing short arcs at 4 samples.\n   */\n  float across = clamp(1.0 - abs(vSide), 0.0, 1.0);\n  float core = pow(across, 10.0);\n  /*\n   * A *wide* halo, deliberately. This exponent is the single biggest control over\n   * whether the effect reads as lightning or as a drawn line: a tight falloff gives a\n   * crisp filament with nothing around it, which is a wire, while a broad one bleeds\n   * light into the air the way an over-exposed discharge does on film. It is the\n   * closest thing to bloom available without a second pass.\n   */\n  float glow = pow(across, 1.1);\n\n  /*\n   * Stutter. An arc is not a steady light: it is re-established many times a\n   * second, and the eye reads a *constant* bright line as neon. Two frequencies\n   * so the pattern does not read as a sine, and per-arc phase from the seed so\n   * several arcs never blink together.\n   */\n  /*\n   * Stutter, but shallow. An arc is re-established many times a second and a perfectly\n   * steady bright line reads as neon \u2014 but too *much* flicker reads as a broken effect\n   * rather than as a discharge, and at the brief lifetime these now have, deep flicker\n   * mostly hides the bolt. The path itself is already being redrawn (see 'BoltPool'),\n   * which carries most of the crackle; this only keeps the brightness alive.\n   */\n  float t = uTime * 47.0 + vSeed * 17.0;\n  float stutter = 0.78 + 0.22 * (hash11(floor(t)) * 0.6 + hash11(floor(t * 2.37)) * 0.4);\n\n  /*\n   * The tip tapers. An arc that ends in a squared-off quad reads as a drawn\n   * segment; thinning toward the far end is what makes it read as a discharge\n   * dissipating into the air.\n   */\n  float taper = 1.0 - vAlong * 0.55;\n\n  float energy = vFade * stutter * taper * vGain;\n  vec3 lit = uEdgeColor * glow + uCoreColor * core * uCoreGain;\n\n  /*\n   * Distance dims it rather than tinting it toward the fog. A discharge emits;\n   * mixing it into the medium's colour is what a *surface* does, and doing that\n   * here turned a far bolt grey instead of faint.\n   */\n  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n  /*\n   * Alpha is 1, and the energy is already in the colour.\n   *\n   * The additive blend is 'SRC_ALPHA, ONE', so what reaches the framebuffer is\n   * 'rgb * a'. Putting the energy in both \u2014 which the first version did \u2014 squares it,\n   * and squaring a number below one is how an effect authored as blinding arrives as\n   * faint: at a typical energy of 0.5 it delivered a quarter of what it asked for.\n   * Every emissive material here has to pick one channel and mean it.\n   */\n  /* Graded where nothing after this will grade it, as every pass is, light added included. */\n  outColor = vec4(applyOutputTransform(lit * energy * (1.0 - fog)), 1.0);\n}\n";

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

@@ -35,4 +35,4 @@
  * ordinary one, and it wants the sheet laid just clear of the tiles.
  */
 export declare const CAUSTICS_VERT = "#version 300 es\nlayout(location = 0) in vec3 aRest;\nlayout(location = 1) in vec2 aLocal;\n/** x: resting height of the water below. y: spare. */\nlayout(location = 2) in vec2 aParams;\n\nuniform mat4 uViewProj;\n\nout vec3 vWorldPos;\nout vec2 vLocal;\nout vec2 vParams;\n\nvoid main() {\n  vWorldPos = aRest;\n  vLocal = aLocal;\n  vParams = aParams;\n  gl_Position = uViewProj * vec4(aRest, 1.0);\n}\n";
-export declare const CAUSTICS_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorldPos;\nin vec2 vLocal;\nin vec2 vParams;\n\nuniform vec3 uCameraPos;\nuniform vec2 uWindDir;\nuniform float uWaveGain;\nuniform float uTime;\n/** Toward the dominant source, as everywhere else in the engine. */\nuniform vec3 uLightDir;\n/** Colour of the light the water is reflecting. */\nuniform vec3 uTint;\nuniform float uStrength;\n/** How far from the water, on either side, the effect has died out entirely. */\nuniform float uMaxDrop;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\n\nconst int GERSTNER_COUNT = 4;\n/*\n * direction.xy, steepness, wavelength. Amplitude is steepness/k, so these sum to\n * roughly a 1m swell \u2014 enough to read as a living surface, low enough that crests\n * never wash over an island whose deck sits ~1.8m above sea level.\n */\nconst vec4 GERSTNER_WAVES[4] = vec4[4](\n  vec4( 1.0,  0.0,  0.115, 34.0),\n  vec4( 0.6,  0.8,  0.100, 18.0),\n  vec4(-0.7,  0.7,  0.080,  9.0),\n  vec4( 0.2, -0.98, 0.060,  5.0)\n);\n\n/*\n * Steer each wave toward the wind, but only partway. A real sea is a dominant\n * swell plus cross-chop; rotating all four onto one bearing gives corduroy,\n * which reads as a material rather than as water.\n */\nvec2 gerstnerDirection(int i, vec2 windDir) {\n  return normalize(mix(normalize(GERSTNER_WAVES[i].xy), windDir, 0.62));\n}\n\nfloat gerstnerWavenumber(int i) {\n  return 6.28318530718 / GERSTNER_WAVES[i].w;\n}\n\n/** Deep-water phase in radians at a point on the resting plane. */\nfloat gerstnerPhase(float k, vec2 dir, vec2 p, float time) {\n  float c = sqrt(9.81 / k);              // deep-water phase speed\n  return k * (dot(dir, p) - c * time);\n}\n\nstruct GerstnerSurface {\n  /** Displacement from the resting plane \u2014 horizontal as well as vertical. */\n  vec3 offset;\n  vec3 normal;\n  /** Height in units of steepness; positive near a crest. */\n  float crest;\n};\n\nGerstnerSurface gerstnerSurface(vec2 p, float time, vec2 windDir, float gain) {\n  GerstnerSurface s;\n  s.offset = vec3(0.0);\n  s.normal = vec3(0.0, 1.0, 0.0);\n  s.crest = 0.0;\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    float a = steepness / k;             // amplitude from steepness\n\n    s.offset.x += dir.x * a * cos(f);\n    s.offset.y += a * sin(f);\n    s.offset.z += dir.y * a * cos(f);\n\n    // Analytic normal: the partial derivatives of the displacement above.\n    s.normal.x -= dir.x * steepness * cos(f);\n    s.normal.z -= dir.y * steepness * cos(f);\n    s.normal.y -= steepness * sin(f);\n\n    s.crest += sin(f) * steepness;\n  }\n  return s;\n}\n\n/**\n * Second derivatives of the height field: (d2h/dx2, d2h/dz2, d2h/dxdz).\n *\n * How the surface *bends*, which is what decides where reflected light\n * converges. Analytic from the same sum, so it cannot disagree with the shape\n * the vertex stage displaced.\n */\nvec3 gerstnerCurvature(vec2 p, float time, vec2 windDir, float gain) {\n  vec3 h = vec3(0.0);\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    // Second derivative of (steepness/k)*sin(f) along the wave's own bearing.\n    float second = -steepness * k * sin(f);\n    h.x += second * dir.x * dir.x;\n    h.y += second * dir.y * dir.y;\n    h.z += second * dir.x * dir.y;\n  }\n  return h;\n}\n\n\n/**\n * Shallowest the source may be and still be treated as a source.\n *\n * The slant path goes as 1/sin(elevation), so a light on the horizon would send\n * the sampled water position kilometres away and the pattern would smear into\n * noise. Clamping keeps a sunset dramatic instead of broken.\n */\nconst float MIN_ELEVATION = 0.16;\n\nvoid main() {\n  float waterY = vParams.x;\n  float drop = vWorldPos.y - waterY;\n\n  /*\n   * Everything is masked rather than branched on, and fwidth() below is why:\n   * screen-space derivatives are undefined in non-uniform control flow, so a\n   * discard above them would make the antialiasing of the caustic lines a\n   * driver-dependent guess. Nothing is saved by branching either \u2014 a masked\n   * fragment adds zero under additive blending.\n   *\n   * Either side of the surface is lit, and the distance from it is what matters\n   * rather than the direction. This began as a soffit-only effect \u2014 light thrown\n   * *up* onto the underside of a bridge \u2014 on the reasoning that below the water\n   * there is nothing to light. That is only true when the water is a ceiling to\n   * you. A pool floor, a flooded corridor, a tank with a lamp over it: the water\n   * focuses light onto the bottom exactly as it does onto a soffit, and it is by\n   * far the more common of the two.\n   *\n   * Only the surface's own thin band is excluded, where the sheet and the water\n   * are coplanar and the pattern would be meaningless.\n   *\n   * Too far from it and the net has spread into nothing. And the sheet dissolves\n   * at its own boundary, so a lit surface does not end in a lit rectangle.\n   */\n  float distanceFromWater = abs(drop);\n  float clear = step(0.02, distanceFromWater);\n  float height = 1.0 - smoothstep(uMaxDrop * 0.45, uMaxDrop, distanceFromWater);\n  float rim = min(min(vLocal.x, 1.0 - vLocal.x), min(vLocal.y, 1.0 - vLocal.y));\n  float edge = smoothstep(0.0, 0.12, rim);\n  float reach = clear * height * edge;\n\n  /*\n   * Which water lights *this* point. For a flat surface the reflected ray leaves\n   * along the mirrored light direction, so walking back from the ceiling gives\n   * the water position and the path length in one step. This is why the net\n   * slides along the ground as the sun moves rather than sitting under itself.\n   */\n  float elevation = max(uLightDir.y, MIN_ELEVATION);\n  float slant = 1.0 / elevation;\n  float d = drop * slant;\n  vec2 water = vWorldPos.xz + uLightDir.xz * d;\n\n  vec3 h = gerstnerCurvature(water, uTime, uWindDir, uWaveGain);\n  float a = 1.0 - 2.0 * d * h.x;\n  float b = 1.0 - 2.0 * d * h.y;\n  float c = 2.0 * d * h.z;\n  float det = a * b - c * c;\n\n  /*\n   * The bright net is where the determinant crosses zero, so its width is a\n   * gradient question, not a constant. Widening the core by the screen-space\n   * derivative antialiases it for free \u2014 without that, a line thinner than a\n   * pixel strobes as the camera moves, which is the usual reason an effect like\n   * this ends up looking like noise.\n   */\n  float soft = max(0.05, fwidth(det) * 1.6);\n  float lines = soft / max(abs(det), soft);\n  /*\n   * Between the lines, the faint brightening of merely convergent water \u2014 and it has to\n   * stay faint. At 0.45 it lit the *whole* sheet, and since the sheet hangs a few\n   * centimetres under the soffit, the result read as a pale plate floating below the\n   * bridge rather than as light on its underside \u2014 reported as being able to see through\n   * the bridge ceiling, which looked glassy and transparent. The plate was the sheet.\n   *\n   * A tighter threshold and a fifth of the weight: the net is bright, everything between\n   * it is almost nothing, and a soffit with no caustics on it is simply a soffit.\n   */\n  float sheen = clamp(1.0 / max(abs(det), 0.18) - 0.85, 0.0, 1.0);\n  float caustic = clamp(lines * 0.9 + sheen * 0.09, 0.0, 1.6);\n\n  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n\n  // Additive: this is light arriving at a surface that is already shaded.\n  /* Graded where nothing after this will grade it, as every pass is, light added included. */\n  outColor = vec4(applyOutputTransform(uTint * (caustic * uStrength * reach * (1.0 - fog))), 1.0);\n}\n";
+export declare const CAUSTICS_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorldPos;\nin vec2 vLocal;\nin vec2 vParams;\n\nuniform vec3 uCameraPos;\nuniform vec2 uWindDir;\nuniform float uWaveGain;\nuniform float uTime;\n/** Toward the dominant source, as everywhere else in the engine. */\nuniform vec3 uLightDir;\n/** Colour of the light the water is reflecting. */\nuniform vec3 uTint;\nuniform float uStrength;\n/** How far from the water, on either side, the effect has died out entirely. */\nuniform float uMaxDrop;\n\nuniform vec3 uFogColor;\n/**\n * The haze: its extinction per metre **at the camera's own height**, not at the base; its\n * reciprocal scale height per metre, 0 for a uniform medium; the camera's height, so a fragment's\n * own height is one subtraction away; and the water column's own density.\n *\n * **Four numbers in one vector rather than four uniforms**, and the reason is a phone: a scalar\n * costs a whole row of the uniform grid, and the lit stage at its eight-light rung must fit the 256\n * rows an Adreno 740 offers (uniformVectorBudget.ts). Packed, the haze's eight scalars cost two\n * rows where they cost eight, which is what paid for the second layer and the sun's glow below.\n */\nuniform vec4 uFogMedium;\n/** Where haze begins, where a linear ramp is total, and the mode: 0 a medium, 1 a ramp. */\nuniform vec4 uFogRange;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n/**\n * The second layer's extinction per metre at the camera's height and its falloff; then the least of\n * a surface the haze must leave, Atmosphere.fogMaxOpacity's complement, and the distance past which\n * it hides nothing (0 is none). **Every lane is none at zero**, and so are uFogGlow's: a program a\n * binder never wrote these into draws the haze it drew before they existed, rather than none.\n */\nuniform vec4 uFogLayer2;\n/** The sun's glow in the haze: its colour, black for none, and the exponent of its lobe. */\nuniform vec4 uFogGlow;\n/** Surface \u2192 the glow's light, and how far past the haze's start the glow begins. */\nuniform vec4 uFogGlowDir;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * The haze's optical depth from where it begins along the ray to a point at height pointY, dist\n * metres away: each layer's density at the eye carried over what is left of the ray, with the\n * second layer only where there is one. The fog and the sun's glow both integrate it.\n */\nfloat hazeDepth(float dist, float pointY) {\n  // Where the medium begins along the ray: uFogRange.x, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogRange.x, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogMedium.z) * uFogMedium.y;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float depth = uFogMedium.x * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom;\n  if (uFogLayer2.x > 0.0) {\n    float t2 = (pointY - uFogMedium.z) * uFogLayer2.y;\n    float rest2 = t2 * (1.0 - before);\n    float denom2 = abs(rest2) < 1e-4 ? 1e-4 : rest2;\n    depth += uFogLayer2.x * exp(-t2 * before) * (dist - start) * (1.0 - exp(-denom2)) / denom2;\n  }\n  return depth;\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /* Past the cutoff the air hides nothing, in either mode; the water column keeps its own law. */\n  bool cut = uFogLayer2.w > 0.0 && dist > uFogLayer2.w;\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogRange.z == 1.0) {\n    float span = max(uFogRange.y - uFogRange.x, 1e-4);\n    float ramp = cut ? 0.0 : min(clamp((dist - uFogRange.x) / span, 0.0, 1.0), 1.0 - uFogLayer2.z);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uFogMedium.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Beer-Lambert through both layers, leaving at least uFogLayer2.z of the surface: a floor on\n  // what survives rather than a ceiling on the depth, so the curve keeps its shape above it.\n  float air = cut ? 0.0 : 1.0 - max(exp(-hazeDepth(dist, pointY)), uFogLayer2.z);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uFogMedium.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/**\n * The sun's light the haze scatters toward the eye along a ray to a point at height pointY, dist\n * metres away in the direction toPoint: added to a surface after its fog, never mixed. A lobe of\n * cos^exponent about the light, by as much of the ray past the glow's own start as the haze hides \u2014\n * the haze's depth per metre carried over that stretch. None in a linear ramp, past the cutoff, or\n * under water, which keeps its own medium.\n */\nvec3 mediumGlow(float dist, float pointY, vec3 toPoint) {\n  if (uFogRange.z == 1.0 || max(max(uFogGlow.r, uFogGlow.g), uFogGlow.b) <= 0.0) return vec3(0.0);\n  if (uFogLayer2.w > 0.0 && dist > uFogLayer2.w) return vec3(0.0);\n  float span = dist - min(uFogRange.x, dist);\n  if (span <= 0.0) return vec3(0.0);\n  float perMetre = hazeDepth(dist, pointY) / span;\n  float hidden = 1.0 - exp(-perMetre * max(span - uFogGlowDir.w, 0.0));\n  float lobe = pow(clamp(dot(toPoint, uFogGlowDir.xyz), 0.0, 1.0), uFogGlow.a);\n  return uFogGlow.rgb * (lobe * hidden * (1.0 - uUnderwaterFactor));\n}\n\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\n\nconst int GERSTNER_COUNT = 4;\n/*\n * direction.xy, steepness, wavelength. Amplitude is steepness/k, so these sum to\n * roughly a 1m swell \u2014 enough to read as a living surface, low enough that crests\n * never wash over an island whose deck sits ~1.8m above sea level.\n */\nconst vec4 GERSTNER_WAVES[4] = vec4[4](\n  vec4( 1.0,  0.0,  0.115, 34.0),\n  vec4( 0.6,  0.8,  0.100, 18.0),\n  vec4(-0.7,  0.7,  0.080,  9.0),\n  vec4( 0.2, -0.98, 0.060,  5.0)\n);\n\n/*\n * Steer each wave toward the wind, but only partway. A real sea is a dominant\n * swell plus cross-chop; rotating all four onto one bearing gives corduroy,\n * which reads as a material rather than as water.\n */\nvec2 gerstnerDirection(int i, vec2 windDir) {\n  return normalize(mix(normalize(GERSTNER_WAVES[i].xy), windDir, 0.62));\n}\n\nfloat gerstnerWavenumber(int i) {\n  return 6.28318530718 / GERSTNER_WAVES[i].w;\n}\n\n/** Deep-water phase in radians at a point on the resting plane. */\nfloat gerstnerPhase(float k, vec2 dir, vec2 p, float time) {\n  float c = sqrt(9.81 / k);              // deep-water phase speed\n  return k * (dot(dir, p) - c * time);\n}\n\nstruct GerstnerSurface {\n  /** Displacement from the resting plane \u2014 horizontal as well as vertical. */\n  vec3 offset;\n  vec3 normal;\n  /** Height in units of steepness; positive near a crest. */\n  float crest;\n};\n\nGerstnerSurface gerstnerSurface(vec2 p, float time, vec2 windDir, float gain) {\n  GerstnerSurface s;\n  s.offset = vec3(0.0);\n  s.normal = vec3(0.0, 1.0, 0.0);\n  s.crest = 0.0;\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    float a = steepness / k;             // amplitude from steepness\n\n    s.offset.x += dir.x * a * cos(f);\n    s.offset.y += a * sin(f);\n    s.offset.z += dir.y * a * cos(f);\n\n    // Analytic normal: the partial derivatives of the displacement above.\n    s.normal.x -= dir.x * steepness * cos(f);\n    s.normal.z -= dir.y * steepness * cos(f);\n    s.normal.y -= steepness * sin(f);\n\n    s.crest += sin(f) * steepness;\n  }\n  return s;\n}\n\n/**\n * Second derivatives of the height field: (d2h/dx2, d2h/dz2, d2h/dxdz).\n *\n * How the surface *bends*, which is what decides where reflected light\n * converges. Analytic from the same sum, so it cannot disagree with the shape\n * the vertex stage displaced.\n */\nvec3 gerstnerCurvature(vec2 p, float time, vec2 windDir, float gain) {\n  vec3 h = vec3(0.0);\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    // Second derivative of (steepness/k)*sin(f) along the wave's own bearing.\n    float second = -steepness * k * sin(f);\n    h.x += second * dir.x * dir.x;\n    h.y += second * dir.y * dir.y;\n    h.z += second * dir.x * dir.y;\n  }\n  return h;\n}\n\n\n/**\n * Shallowest the source may be and still be treated as a source.\n *\n * The slant path goes as 1/sin(elevation), so a light on the horizon would send\n * the sampled water position kilometres away and the pattern would smear into\n * noise. Clamping keeps a sunset dramatic instead of broken.\n */\nconst float MIN_ELEVATION = 0.16;\n\nvoid main() {\n  float waterY = vParams.x;\n  float drop = vWorldPos.y - waterY;\n\n  /*\n   * Everything is masked rather than branched on, and fwidth() below is why:\n   * screen-space derivatives are undefined in non-uniform control flow, so a\n   * discard above them would make the antialiasing of the caustic lines a\n   * driver-dependent guess. Nothing is saved by branching either \u2014 a masked\n   * fragment adds zero under additive blending.\n   *\n   * Either side of the surface is lit, and the distance from it is what matters\n   * rather than the direction. This began as a soffit-only effect \u2014 light thrown\n   * *up* onto the underside of a bridge \u2014 on the reasoning that below the water\n   * there is nothing to light. That is only true when the water is a ceiling to\n   * you. A pool floor, a flooded corridor, a tank with a lamp over it: the water\n   * focuses light onto the bottom exactly as it does onto a soffit, and it is by\n   * far the more common of the two.\n   *\n   * Only the surface's own thin band is excluded, where the sheet and the water\n   * are coplanar and the pattern would be meaningless.\n   *\n   * Too far from it and the net has spread into nothing. And the sheet dissolves\n   * at its own boundary, so a lit surface does not end in a lit rectangle.\n   */\n  float distanceFromWater = abs(drop);\n  float clear = step(0.02, distanceFromWater);\n  float height = 1.0 - smoothstep(uMaxDrop * 0.45, uMaxDrop, distanceFromWater);\n  float rim = min(min(vLocal.x, 1.0 - vLocal.x), min(vLocal.y, 1.0 - vLocal.y));\n  float edge = smoothstep(0.0, 0.12, rim);\n  float reach = clear * height * edge;\n\n  /*\n   * Which water lights *this* point. For a flat surface the reflected ray leaves\n   * along the mirrored light direction, so walking back from the ceiling gives\n   * the water position and the path length in one step. This is why the net\n   * slides along the ground as the sun moves rather than sitting under itself.\n   */\n  float elevation = max(uLightDir.y, MIN_ELEVATION);\n  float slant = 1.0 / elevation;\n  float d = drop * slant;\n  vec2 water = vWorldPos.xz + uLightDir.xz * d;\n\n  vec3 h = gerstnerCurvature(water, uTime, uWindDir, uWaveGain);\n  float a = 1.0 - 2.0 * d * h.x;\n  float b = 1.0 - 2.0 * d * h.y;\n  float c = 2.0 * d * h.z;\n  float det = a * b - c * c;\n\n  /*\n   * The bright net is where the determinant crosses zero, so its width is a\n   * gradient question, not a constant. Widening the core by the screen-space\n   * derivative antialiases it for free \u2014 without that, a line thinner than a\n   * pixel strobes as the camera moves, which is the usual reason an effect like\n   * this ends up looking like noise.\n   */\n  float soft = max(0.05, fwidth(det) * 1.6);\n  float lines = soft / max(abs(det), soft);\n  /*\n   * Between the lines, the faint brightening of merely convergent water \u2014 and it has to\n   * stay faint. At 0.45 it lit the *whole* sheet, and since the sheet hangs a few\n   * centimetres under the soffit, the result read as a pale plate floating below the\n   * bridge rather than as light on its underside \u2014 reported as being able to see through\n   * the bridge ceiling, which looked glassy and transparent. The plate was the sheet.\n   *\n   * A tighter threshold and a fifth of the weight: the net is bright, everything between\n   * it is almost nothing, and a soffit with no caustics on it is simply a soffit.\n   */\n  float sheen = clamp(1.0 / max(abs(det), 0.18) - 0.85, 0.0, 1.0);\n  float caustic = clamp(lines * 0.9 + sheen * 0.09, 0.0, 1.6);\n\n  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n\n  // Additive: this is light arriving at a surface that is already shaded.\n  /* Graded where nothing after this will grade it, as every pass is, light added included. */\n  outColor = vec4(applyOutputTransform(uTint * (caustic * uStrength * reach * (1.0 - fog))), 1.0);\n}\n";

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

@@ -12,4 +12,4 @@
  * rainbow is generated rather than sampled.
  */
 export declare const FILM_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec3 aNormal;\nlayout(location = 2) in vec3 aColor;\n/*\n * Coverage, on the attribute the mesh format calls emissive.\n *\n * A film has no use for self-illumination, and it very much needs an edge that\n * dissolves: the first oil was flat squares, and a hard straight edge is what made\n * it read as a decal dropped on the world rather than a puddle lying in it. One\n * float per vertex, 1 in the middle of a slick and 0 at its rim.\n */\nlayout(location = 3) in float aCoverage;\n\nuniform mat4 uViewProj;\n/* The mirrored camera's projection, so a film can sample the planar target the way water does. */\nuniform mat4 uReflectionViewProj;\n\nout vec3 vWorld;\nout vec3 vNormal;\nout vec3 vTint;\nout vec4 vReflectionClip;\nout float vCoverage;\n\nvoid main() {\n  vWorld = aPosition;\n  vNormal = normalize(aNormal);\n  vTint = aColor;\n  vCoverage = aCoverage;\n  vReflectionClip = uReflectionViewProj * vec4(aPosition, 1.0);\n  gl_Position = uViewProj * vec4(aPosition, 1.0);\n}\n";
-export declare const FILM_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorld;\nin vec3 vNormal;\nin vec3 vTint;\nin vec4 vReflectionClip;\n/*\n * The scene mirrored across the plane this film lies on, and how much of it to show.\n *\n * **Sheen is iridescence and this is the image**, which is the split a consumer asked for after\n * finding that raising sheen to make a road wetter only made it oilier. A wet street at night is\n * defined by everything above it appearing twice, and no amount of interference pattern is that.\n *\n * The projection is the water shader's, unchanged and deliberately so: reproducing it outside the\n * engine is the piece most likely to be subtly wrong and least likely to be noticed, since a\n * mirror off by a small skew looks like a wet road until somebody puts a straight line across it.\n */\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform float uReflectionStrength;\nin float vCoverage;\n\nuniform vec3 uCameraPos;\nuniform float uTime;\n/*\n * The mirrored pass clips at the water plane, and it does so **in the fragment\n * shader** rather than with gl_ClipDistance.\n *\n * That is not a style choice. Clip distances in WebGL2 need\n * EXT_clip_cull_distance both enabled on the context and declared with an\n * #extension line, and without the declaration the shader fails to *compile* \u2014\n * which, since programs are built when the renderer is constructed, takes the\n * whole boot with it and leaves a black screen. This shader had never been\n * compiled when it was written, so the mistake sat harmlessly in the file until\n * the day it was wired to something. Discarding is what flat.ts does, it needs\n * no extension, and a film is a thin translucent layer where the cost of a\n * discarded fragment is nothing.\n */\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/** How strong the sheen is. Zero leaves a plain dark film. */\nuniform float uSheen;\n\n/**\n * How rough the film's own surface is, 0 to 1, and how coarse that roughness is.\n *\n * **A film had exactly one finish before this: mirror.** That is right for standing water and\n * wrong for the thing this pass is most used for, because a wet road is not a mirror \u2014 it is\n * water lying *in* aggregate, and the stone underneath breaks the reflection into a smear. With\n * no way to say so, a patch of film over a textured road met it at a hard rim: mirror on one\n * side, stone on the other, with nothing able to cross it. Feathering the coverage cannot fix\n * that, and it was tried \u2014 the alpha was never what the eye was reading.\n *\n * So the reflection is displaced by a noise field rather than blurred. **Displaced, because a\n * blur is the wrong phenomenon**: a rough surface does not soften what it reflects, it scatters\n * it, and a lamp on wet tarmac smears into a streak rather than becoming a soft disc. It is also\n * what a blur cannot afford here \u2014 the mirror has no mip chain (see the `textureLod` note\n * below), so softening it honestly would cost several taps where this costs none.\n *\n * `uFilmRoughnessCycles` is bumps to the metre, and it is the same quantity\n * `Renderer.setSurfaceRelief` takes. **Matching it to the surface underneath is the point**:\n * given the same field at the same scale, the water is broken up by the aggregate that the dry\n * road beside it is showing, and the two stop being different materials.\n *\n * Zero is the mirror this pass has always been, exactly, so nothing that does not ask for\n * roughness renders differently.\n */\nuniform float uFilmRoughness;\nuniform float uFilmRoughnessCycles;\n\nout vec4 fragColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\n/** A hue wheel, without a texture. Standard 6-segment ramp. */\nvec3 hue(float h) {\n  h = fract(h) * 6.0;\n  vec3 c = clamp(vec3(abs(h - 3.0) - 1.0, 2.0 - abs(h - 2.0), 2.0 - abs(h - 4.0)), 0.0, 1.0);\n  return c;\n}\n\n/**\n * The same value noise `flat.ts` builds its relief from, and deliberately the same.\n *\n * Copied rather than shared because these two shaders have no common include beyond the fog, and\n * a film that used a *different* field would defeat the whole purpose of taking a cycle count:\n * the water would be broken up by one pattern and the road by another, which is two materials\n * again with extra steps.\n */\nfloat filmHash(vec3 p) {\n  p = fract(p * 0.1031);\n  p += dot(p, p.zyx + 31.32);\n  return fract((p.x + p.y) * p.z);\n}\n\nfloat filmNoise(vec3 p) {\n  vec3 i = floor(p);\n  vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 0.0)), filmHash(i + vec3(1.0, 0.0, 0.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 0.0)), filmHash(i + vec3(1.0, 1.0, 0.0)), u.x),\n      u.y\n    ),\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 1.0)), filmHash(i + vec3(1.0, 0.0, 1.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 1.0)), filmHash(i + vec3(1.0, 1.0, 1.0)), u.x),\n      u.y\n    ),\n    u.z\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorld, 1.0), uClipPlane) < 0.0) discard;\n\n  vec3 view = normalize(uCameraPos - vWorld);\n  float facing = max(dot(normalize(vNormal), view), 0.0);\n  /*\n   * Fresnel-ish: dark looking straight down at it, bright at a grazing angle.\n   * This is the whole effect \u2014 it is what makes a wet patch look wet rather\n   * than looking like a patch of dark paint.\n   */\n  float grazing = pow(1.0 - facing, 3.0);\n\n  /*\n   * A slow travelling interference, so the sheen crawls rather than sitting\n   * still. Two frequencies that do not divide each other, or the pattern\n   * repeats visibly across a long slick.\n   */\n  float ripple =\n    sin(vWorld.x * 0.73 + vWorld.z * 0.41 + uTime * 0.55) *\n    cos(vWorld.z * 0.91 - vWorld.x * 0.29 - uTime * 0.37);\n\n  vec3 sheen = hue(grazing * 1.35 + ripple * 0.14 + 0.55);\n  /*\n   * Dark underneath, so the film always reads as *less* than the surface it lies on even where\n   * the sheen is strongest \u2014 but not so dark that it disappears.\n   *\n   * A slick that has just launched somebody has to be findable afterwards. It was rounded,\n   * feathered and iridescent \u2014 and at a fifth of an opaque tint on a pale deck at dusk,\n   * invisible. A hazard you cannot find is not a hazard, it is a trap.\n   *\n   * So the base is darker and the sheen has a floor: even looking straight down, where the\n   * Fresnel term is nearly nothing, a slick is a distinctly wet patch rather than a faint one.\n   */\n  vec3 base = vTint * 0.9;\n  vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);\n\n  /*\n   * **Graded before the mirror is mixed in**, as every pass grades what it draws when nothing after\n   * it will, because the mirror's own passes graded what it holds. The fog that used to follow the\n   * mirror distributes over the mix, so the film's own colour is fogged and graded here, and what\n   * the mirror shows is fogged toward the same air, graded, where it is mixed in below.\n   */\n  // The same fog every other pass applies \u2014 and now literally the same code, which\n  // it was not: this ran its own curve while claiming otherwise, so a slick receded\n  // at a different rate than the deck it was lying on.\n  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);\n  vec3 gradedAir = applyOutputTransform(mediumColor());\n  vec3 graded = applyOutputTransform(mix(color, mediumColor(), fog));\n\n  /*\n   * The mirrored scene, under the sheen rather than instead of it.\n   *\n   * Screen-space from the mirrored clip position, exactly as the water pass does it, with the\n   * same fade as the sample leaves the target: a reflection that stopped dead at the edge of its\n   * own buffer would draw a line across the road where nothing is.\n   *\n   * Weighted by the grazing term as well as by strength, because that is what a reflection does:\n   * a wet surface underfoot shows almost nothing and the same surface down the street shows the\n   * whole scene. Fogged as the film is, so the image recedes with everything else in the frame.\n   */\n  if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    float valid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    /*\n     * An explicit level, not an implicit one, and the branch above is the whole reason.\n     *\n     * An implicit derivative inside control flow that is not provably uniform is what lets a\n     * compiler flatten the branch and pay for every arm \u2014 AGENTS.md, 2026-08-07 \u2014 and WGSL\n     * does not merely warn: the module fails to compile with \"textureSample must only be\n     * called from uniform control flow\", which invalidates the pipeline, which invalidates\n     * the command buffer, and the frame still presents. The fifth time on this branch. The\n     * mirror has no mip chain, so level 0 is the only level there is; the water shader\n     * reaches the same conclusion for the same lookup.\n     */\n    /*\n     * The aggregate under the water, as a displacement of what the water shows.\n     *\n     * The gradient of the same field the road's relief uses, taken across the surface and used\n     * to push the lookup. **Stretched along the reflection rather than isotropic**, and that is\n     * the half that makes it read as a road: a reflection on a rough horizontal surface smears\n     * *towards the viewer*, because a bump tilts the ray in the plane it is already travelling\n     * in. Displacing in a circle gives frosted glass instead, which is a different wet thing.\n     *\n     * Scaled by the grazing term for the same reason the mirror is: looking straight down at a\n     * puddle the reflection is compressed into almost nothing and a displacement of it would be\n     * enormous, so the scatter has to fall off exactly where the image does.\n     */\n    if (uFilmRoughness > 0.0) {\n      vec3 at = vWorld * uFilmRoughnessCycles;\n      float here = filmNoise(at);\n      vec2 slope = vec2(\n        filmNoise(at + vec3(0.5, 0.0, 0.0)) - here,\n        filmNoise(at + vec3(0.0, 0.0, 0.5)) - here\n      );\n      /* Along the view, which on a horizontal film is where the image runs. */\n      vec2 along = normalize(vec2(view.x, view.z) + vec2(1e-5, 0.0));\n      vec2 smear = along * dot(slope, along) * 3.0 + slope * 0.35;\n      reflectionUv += smear * uFilmRoughness * 0.016 * (0.2 + grazing * 0.8);\n      /* Re-fade at the border: a displaced sample can leave the target the original did not. */\n      vec2 movedBorder = min(reflectionUv, 1.0 - reflectionUv);\n      valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));\n    }\n    vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;\n    graded = mix(\n      graded,\n      mix(mirrored, gradedAir, fog),\n      valid * uReflectionStrength * (0.25 + grazing * 0.75)\n    );\n  }\n\n  /*\n   * Alpha from coverage, squared.\n   *\n   * Squared because a linear ramp across the rim still reads as a visible band \u2014\n   * the eye finds the constant-gradient edge. Squaring pushes the falloff outward\n   * so the slick has a soft shoulder and no perceptible boundary. The sheen fades\n   * with it, which is right: the thinnest part of a film is the least iridescent.\n   */\n  /*\n   * Alpha from coverage, and the rim is what is squared \u2014 not the whole patch.\n   *\n   * Squaring the coverage outright made the *middle* translucent too, which is most of why a\n   * slick could not be found. The shoulder still needs to be soft, so the square is mixed in\n   * near the edge only: solid through the body, dissolving at the rim.\n   */\n  float coverage = clamp(vCoverage, 0.0, 1.0);\n  float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;\n  fragColor = vec4(graded, alpha);\n}\n";
+export declare const FILM_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorld;\nin vec3 vNormal;\nin vec3 vTint;\nin vec4 vReflectionClip;\n/*\n * The scene mirrored across the plane this film lies on, and how much of it to show.\n *\n * **Sheen is iridescence and this is the image**, which is the split a consumer asked for after\n * finding that raising sheen to make a road wetter only made it oilier. A wet street at night is\n * defined by everything above it appearing twice, and no amount of interference pattern is that.\n *\n * The projection is the water shader's, unchanged and deliberately so: reproducing it outside the\n * engine is the piece most likely to be subtly wrong and least likely to be noticed, since a\n * mirror off by a small skew looks like a wet road until somebody puts a straight line across it.\n */\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform float uReflectionStrength;\nin float vCoverage;\n\nuniform vec3 uCameraPos;\nuniform float uTime;\n/*\n * The mirrored pass clips at the water plane, and it does so **in the fragment\n * shader** rather than with gl_ClipDistance.\n *\n * That is not a style choice. Clip distances in WebGL2 need\n * EXT_clip_cull_distance both enabled on the context and declared with an\n * #extension line, and without the declaration the shader fails to *compile* \u2014\n * which, since programs are built when the renderer is constructed, takes the\n * whole boot with it and leaves a black screen. This shader had never been\n * compiled when it was written, so the mistake sat harmlessly in the file until\n * the day it was wired to something. Discarding is what flat.ts does, it needs\n * no extension, and a film is a thin translucent layer where the cost of a\n * discarded fragment is nothing.\n */\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n\nuniform vec3 uFogColor;\n/**\n * The haze: its extinction per metre **at the camera's own height**, not at the base; its\n * reciprocal scale height per metre, 0 for a uniform medium; the camera's height, so a fragment's\n * own height is one subtraction away; and the water column's own density.\n *\n * **Four numbers in one vector rather than four uniforms**, and the reason is a phone: a scalar\n * costs a whole row of the uniform grid, and the lit stage at its eight-light rung must fit the 256\n * rows an Adreno 740 offers (uniformVectorBudget.ts). Packed, the haze's eight scalars cost two\n * rows where they cost eight, which is what paid for the second layer and the sun's glow below.\n */\nuniform vec4 uFogMedium;\n/** Where haze begins, where a linear ramp is total, and the mode: 0 a medium, 1 a ramp. */\nuniform vec4 uFogRange;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n/**\n * The second layer's extinction per metre at the camera's height and its falloff; then the least of\n * a surface the haze must leave, Atmosphere.fogMaxOpacity's complement, and the distance past which\n * it hides nothing (0 is none). **Every lane is none at zero**, and so are uFogGlow's: a program a\n * binder never wrote these into draws the haze it drew before they existed, rather than none.\n */\nuniform vec4 uFogLayer2;\n/** The sun's glow in the haze: its colour, black for none, and the exponent of its lobe. */\nuniform vec4 uFogGlow;\n/** Surface \u2192 the glow's light, and how far past the haze's start the glow begins. */\nuniform vec4 uFogGlowDir;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * The haze's optical depth from where it begins along the ray to a point at height pointY, dist\n * metres away: each layer's density at the eye carried over what is left of the ray, with the\n * second layer only where there is one. The fog and the sun's glow both integrate it.\n */\nfloat hazeDepth(float dist, float pointY) {\n  // Where the medium begins along the ray: uFogRange.x, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogRange.x, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogMedium.z) * uFogMedium.y;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float depth = uFogMedium.x * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom;\n  if (uFogLayer2.x > 0.0) {\n    float t2 = (pointY - uFogMedium.z) * uFogLayer2.y;\n    float rest2 = t2 * (1.0 - before);\n    float denom2 = abs(rest2) < 1e-4 ? 1e-4 : rest2;\n    depth += uFogLayer2.x * exp(-t2 * before) * (dist - start) * (1.0 - exp(-denom2)) / denom2;\n  }\n  return depth;\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /* Past the cutoff the air hides nothing, in either mode; the water column keeps its own law. */\n  bool cut = uFogLayer2.w > 0.0 && dist > uFogLayer2.w;\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogRange.z == 1.0) {\n    float span = max(uFogRange.y - uFogRange.x, 1e-4);\n    float ramp = cut ? 0.0 : min(clamp((dist - uFogRange.x) / span, 0.0, 1.0), 1.0 - uFogLayer2.z);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uFogMedium.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Beer-Lambert through both layers, leaving at least uFogLayer2.z of the surface: a floor on\n  // what survives rather than a ceiling on the depth, so the curve keeps its shape above it.\n  float air = cut ? 0.0 : 1.0 - max(exp(-hazeDepth(dist, pointY)), uFogLayer2.z);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uFogMedium.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n/**\n * The sun's light the haze scatters toward the eye along a ray to a point at height pointY, dist\n * metres away in the direction toPoint: added to a surface after its fog, never mixed. A lobe of\n * cos^exponent about the light, by as much of the ray past the glow's own start as the haze hides \u2014\n * the haze's depth per metre carried over that stretch. None in a linear ramp, past the cutoff, or\n * under water, which keeps its own medium.\n */\nvec3 mediumGlow(float dist, float pointY, vec3 toPoint) {\n  if (uFogRange.z == 1.0 || max(max(uFogGlow.r, uFogGlow.g), uFogGlow.b) <= 0.0) return vec3(0.0);\n  if (uFogLayer2.w > 0.0 && dist > uFogLayer2.w) return vec3(0.0);\n  float span = dist - min(uFogRange.x, dist);\n  if (span <= 0.0) return vec3(0.0);\n  float perMetre = hazeDepth(dist, pointY) / span;\n  float hidden = 1.0 - exp(-perMetre * max(span - uFogGlowDir.w, 0.0));\n  float lobe = pow(clamp(dot(toPoint, uFogGlowDir.xyz), 0.0, 1.0), uFogGlow.a);\n  return uFogGlow.rgb * (lobe * hidden * (1.0 - uUnderwaterFactor));\n}\n\n/** How strong the sheen is. Zero leaves a plain dark film. */\nuniform float uSheen;\n\n/**\n * How rough the film's own surface is, 0 to 1, and how coarse that roughness is.\n *\n * **A film had exactly one finish before this: mirror.** That is right for standing water and\n * wrong for the thing this pass is most used for, because a wet road is not a mirror \u2014 it is\n * water lying *in* aggregate, and the stone underneath breaks the reflection into a smear. With\n * no way to say so, a patch of film over a textured road met it at a hard rim: mirror on one\n * side, stone on the other, with nothing able to cross it. Feathering the coverage cannot fix\n * that, and it was tried \u2014 the alpha was never what the eye was reading.\n *\n * So the reflection is displaced by a noise field rather than blurred. **Displaced, because a\n * blur is the wrong phenomenon**: a rough surface does not soften what it reflects, it scatters\n * it, and a lamp on wet tarmac smears into a streak rather than becoming a soft disc. It is also\n * what a blur cannot afford here \u2014 the mirror has no mip chain (see the `textureLod` note\n * below), so softening it honestly would cost several taps where this costs none.\n *\n * `uFilmRoughnessCycles` is bumps to the metre, and it is the same quantity\n * `Renderer.setSurfaceRelief` takes. **Matching it to the surface underneath is the point**:\n * given the same field at the same scale, the water is broken up by the aggregate that the dry\n * road beside it is showing, and the two stop being different materials.\n *\n * Zero is the mirror this pass has always been, exactly, so nothing that does not ask for\n * roughness renders differently.\n */\nuniform float uFilmRoughness;\nuniform float uFilmRoughnessCycles;\n\nout vec4 fragColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder 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/*\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\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\n/** A hue wheel, without a texture. Standard 6-segment ramp. */\nvec3 hue(float h) {\n  h = fract(h) * 6.0;\n  vec3 c = clamp(vec3(abs(h - 3.0) - 1.0, 2.0 - abs(h - 2.0), 2.0 - abs(h - 4.0)), 0.0, 1.0);\n  return c;\n}\n\n/**\n * The same value noise `flat.ts` builds its relief from, and deliberately the same.\n *\n * Copied rather than shared because these two shaders have no common include beyond the fog, and\n * a film that used a *different* field would defeat the whole purpose of taking a cycle count:\n * the water would be broken up by one pattern and the road by another, which is two materials\n * again with extra steps.\n */\nfloat filmHash(vec3 p) {\n  p = fract(p * 0.1031);\n  p += dot(p, p.zyx + 31.32);\n  return fract((p.x + p.y) * p.z);\n}\n\nfloat filmNoise(vec3 p) {\n  vec3 i = floor(p);\n  vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 0.0)), filmHash(i + vec3(1.0, 0.0, 0.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 0.0)), filmHash(i + vec3(1.0, 1.0, 0.0)), u.x),\n      u.y\n    ),\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 1.0)), filmHash(i + vec3(1.0, 0.0, 1.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 1.0)), filmHash(i + vec3(1.0, 1.0, 1.0)), u.x),\n      u.y\n    ),\n    u.z\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorld, 1.0), uClipPlane) < 0.0) discard;\n\n  vec3 view = normalize(uCameraPos - vWorld);\n  float facing = max(dot(normalize(vNormal), view), 0.0);\n  /*\n   * Fresnel-ish: dark looking straight down at it, bright at a grazing angle.\n   * This is the whole effect \u2014 it is what makes a wet patch look wet rather\n   * than looking like a patch of dark paint.\n   */\n  float grazing = pow(1.0 - facing, 3.0);\n\n  /*\n   * A slow travelling interference, so the sheen crawls rather than sitting\n   * still. Two frequencies that do not divide each other, or the pattern\n   * repeats visibly across a long slick.\n   */\n  float ripple =\n    sin(vWorld.x * 0.73 + vWorld.z * 0.41 + uTime * 0.55) *\n    cos(vWorld.z * 0.91 - vWorld.x * 0.29 - uTime * 0.37);\n\n  vec3 sheen = hue(grazing * 1.35 + ripple * 0.14 + 0.55);\n  /*\n   * Dark underneath, so the film always reads as *less* than the surface it lies on even where\n   * the sheen is strongest \u2014 but not so dark that it disappears.\n   *\n   * A slick that has just launched somebody has to be findable afterwards. It was rounded,\n   * feathered and iridescent \u2014 and at a fifth of an opaque tint on a pale deck at dusk,\n   * invisible. A hazard you cannot find is not a hazard, it is a trap.\n   *\n   * So the base is darker and the sheen has a floor: even looking straight down, where the\n   * Fresnel term is nearly nothing, a slick is a distinctly wet patch rather than a faint one.\n   */\n  vec3 base = vTint * 0.9;\n  vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);\n\n  /*\n   * **Graded before the mirror is mixed in**, as every pass grades what it draws when nothing after\n   * it will, because the mirror's own passes graded what it holds. The fog that used to follow the\n   * mirror distributes over the mix, so the film's own colour is fogged and graded here, and what\n   * the mirror shows is fogged toward the same air, graded, where it is mixed in below.\n   */\n  // The same fog every other pass applies \u2014 and now literally the same code, which\n  // it was not: this ran its own curve while claiming otherwise, so a slick receded\n  // at a different rate than the deck it was lying on.\n  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);\n  vec3 glow = mediumGlow(length(uCameraPos - vWorld), vWorld.y, normalize(vWorld - uCameraPos));\n  /* The air the mirror recedes into takes no glow: the mirror is mixed toward it by the fog, which\n     would lay the glow by the fog's share a second time over the surface's own. */\n  vec3 gradedAir = applyOutputTransform(mediumColor());\n  vec3 graded = applyOutputTransform(mix(color, mediumColor(), fog) + glow);\n\n  /*\n   * The mirrored scene, under the sheen rather than instead of it.\n   *\n   * Screen-space from the mirrored clip position, exactly as the water pass does it, with the\n   * same fade as the sample leaves the target: a reflection that stopped dead at the edge of its\n   * own buffer would draw a line across the road where nothing is.\n   *\n   * Weighted by the grazing term as well as by strength, because that is what a reflection does:\n   * a wet surface underfoot shows almost nothing and the same surface down the street shows the\n   * whole scene. Fogged as the film is, so the image recedes with everything else in the frame.\n   */\n  if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    float valid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    /*\n     * An explicit level, not an implicit one, and the branch above is the whole reason.\n     *\n     * An implicit derivative inside control flow that is not provably uniform is what lets a\n     * compiler flatten the branch and pay for every arm \u2014 AGENTS.md, 2026-08-07 \u2014 and WGSL\n     * does not merely warn: the module fails to compile with \"textureSample must only be\n     * called from uniform control flow\", which invalidates the pipeline, which invalidates\n     * the command buffer, and the frame still presents. The fifth time on this branch. The\n     * mirror has no mip chain, so level 0 is the only level there is; the water shader\n     * reaches the same conclusion for the same lookup.\n     */\n    /*\n     * The aggregate under the water, as a displacement of what the water shows.\n     *\n     * The gradient of the same field the road's relief uses, taken across the surface and used\n     * to push the lookup. **Stretched along the reflection rather than isotropic**, and that is\n     * the half that makes it read as a road: a reflection on a rough horizontal surface smears\n     * *towards the viewer*, because a bump tilts the ray in the plane it is already travelling\n     * in. Displacing in a circle gives frosted glass instead, which is a different wet thing.\n     *\n     * Scaled by the grazing term for the same reason the mirror is: looking straight down at a\n     * puddle the reflection is compressed into almost nothing and a displacement of it would be\n     * enormous, so the scatter has to fall off exactly where the image does.\n     */\n    if (uFilmRoughness > 0.0) {\n      vec3 at = vWorld * uFilmRoughnessCycles;\n      float here = filmNoise(at);\n      vec2 slope = vec2(\n        filmNoise(at + vec3(0.5, 0.0, 0.0)) - here,\n        filmNoise(at + vec3(0.0, 0.0, 0.5)) - here\n      );\n      /* Along the view, which on a horizontal film is where the image runs. */\n      vec2 along = normalize(vec2(view.x, view.z) + vec2(1e-5, 0.0));\n      vec2 smear = along * dot(slope, along) * 3.0 + slope * 0.35;\n      reflectionUv += smear * uFilmRoughness * 0.016 * (0.2 + grazing * 0.8);\n      /* Re-fade at the border: a displaced sample can leave the target the original did not. */\n      vec2 movedBorder = min(reflectionUv, 1.0 - reflectionUv);\n      valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));\n    }\n    vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;\n    graded = mix(\n      graded,\n      mix(mirrored, gradedAir, fog),\n      valid * uReflectionStrength * (0.25 + grazing * 0.75)\n    );\n  }\n\n  /*\n   * Alpha from coverage, squared.\n   *\n   * Squared because a linear ramp across the rim still reads as a visible band \u2014\n   * the eye finds the constant-gradient edge. Squaring pushes the falloff outward\n   * so the slick has a soft shoulder and no perceptible boundary. The sheen fades\n   * with it, which is right: the thinnest part of a film is the least iridescent.\n   */\n  /*\n   * Alpha from coverage, and the rim is what is squared \u2014 not the whole patch.\n   *\n   * Squaring the coverage outright made the *middle* translucent too, which is most of why a\n   * slick could not be found. The shoulder still needs to be soft, so the square is mixed in\n   * near the edge only: solid through the body, dissolving at the rim.\n   */\n  float coverage = clamp(vCoverage, 0.0, 1.0);\n  float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;\n  fragColor = vec4(graded, alpha);\n}\n";

package/dist/render/shaders/film.js

@@ -209,8 +209,11 @@ void main() {
   // it was not: this ran its own curve while claiming otherwise, so a slick receded
   // at a different rate than the deck it was lying on.
   float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);
+  vec3 glow = mediumGlow(length(uCameraPos - vWorld), vWorld.y, normalize(vWorld - uCameraPos));
+  /* The air the mirror recedes into takes no glow: the mirror is mixed toward it by the fog, which
+     would lay the glow by the fog's share a second time over the surface's own. */
   vec3 gradedAir = applyOutputTransform(mediumColor());
-  vec3 graded = applyOutputTransform(mix(color, mediumColor(), fog));
+  vec3 graded = applyOutputTransform(mix(color, mediumColor(), fog) + glow);
 
   /*
    * The mirrored scene, under the sheen rather than instead of it.