@driftengine/core 4.8.7 → 4.10.0

package/dist/render/pointLightSelection.d.ts

@@ -71,10 +71,10 @@ export interface PointLightSource {
     inLightField?: boolean;
     /**
      * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
-     * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
-     * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
-     * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
-     * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+     * term, `R` its radius and `n` this. The usual falloff for a light without inverse-square
+     * falloff, so a rig authored that way — a fill of brightness 160 across 164 m, a key at exponent
+     * 8 — lights the space it was authored for rather than one that ends a few metres out. Absent or
+     * 0, the frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
      */
     falloffExponent?: number;
 }

package/dist/render/reflectionSurfaceTargets.d.ts

@@ -0,0 +1,28 @@
+export declare class ReflectionSurfaceTargets {
+    private readonly gl;
+    private probe;
+    private tint;
+    private width;
+    private height;
+    private readonly all;
+    private readonly colourAlone;
+    constructor(gl: WebGL2RenderingContext);
+    /** The environment as the frame shows it, and the roughness in alpha. */
+    get probeTexture(): WebGLTexture | null;
+    /** What a found reflection is multiplied by. */
+    get tintTexture(): WebGLTexture | null;
+    /**
+     * At the frame's start, with the scene's framebuffer bound: both at its size, attached, cleared to
+     * nothing reflected, and left disabled.
+     */
+    begin(width: number, height: number): void;
+    /** Around an opaque lit draw into the frame: its two extra outputs land. */
+    on(): void;
+    /** And after it: only the colour does. */
+    off(): void;
+    /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+    detach(): void;
+    dispose(): void;
+    private make;
+    private release;
+}

package/dist/render/reflectionSurfaceTargets.js

@@ -0,0 +1,99 @@
+/**
+ * The frame's materials' reflection maps on WebGL2: two half-float textures on the scene's own
+ * framebuffer, beside its colour, written by the opaque lit draws as they are drawn. What the two
+ * hold is `shaders/flat/reflectionSurface.ts`'s to say; this is where they live on this backend.
+ *
+ * **Written in the frame's own pass, where WebGPU replays the draws in a second one.** A WebGL2
+ * program writing an output its framebuffer has no buffer enabled for loses that output and nothing
+ * else, so the maps are enabled around an opaque lit draw (`on`, `off`) and stay disabled for every
+ * other: the sky, glass, text and particles write no material, and a draw into a mirror, a probe or
+ * a capture is into another framebuffer, whose draw buffers this never touches.
+ *
+ * **Detached once the trace has read them** (`detach`), because the resolve then draws into the
+ * scene's framebuffer while sampling both, and a texture sampled while attached to the framebuffer
+ * being drawn is a feedback loop whether or not its buffer is enabled. `begin` attaches them again.
+ */
+const ZERO = new Float32Array(4);
+export class ReflectionSurfaceTargets {
+    gl;
+    probe = null;
+    tint = null;
+    width = 0;
+    height = 0;
+    all;
+    colourAlone;
+    constructor(gl) {
+        this.gl = gl;
+        this.all = [gl.COLOR_ATTACHMENT0, gl.COLOR_ATTACHMENT1, gl.COLOR_ATTACHMENT2];
+        this.colourAlone = [gl.COLOR_ATTACHMENT0];
+    }
+    /** The environment as the frame shows it, and the roughness in alpha. */
+    get probeTexture() {
+        return this.probe;
+    }
+    /** What a found reflection is multiplied by. */
+    get tintTexture() {
+        return this.tint;
+    }
+    /**
+     * At the frame's start, with the scene's framebuffer bound: both at its size, attached, cleared to
+     * nothing reflected, and left disabled.
+     */
+    begin(width, height) {
+        const { gl } = this;
+        if (this.probe === null || this.width !== width || this.height !== height) {
+            this.release();
+            this.probe = this.make(width, height);
+            this.tint = this.make(width, height);
+            this.width = width;
+            this.height = height;
+        }
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, this.probe, 0);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, this.tint, 0);
+        gl.drawBuffers(this.all);
+        gl.clearBufferfv(gl.COLOR, 1, ZERO);
+        gl.clearBufferfv(gl.COLOR, 2, ZERO);
+        gl.drawBuffers(this.colourAlone);
+    }
+    /** Around an opaque lit draw into the frame: its two extra outputs land. */
+    on() {
+        this.gl.drawBuffers(this.all);
+    }
+    /** And after it: only the colour does. */
+    off() {
+        this.gl.drawBuffers(this.colourAlone);
+    }
+    /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+    detach() {
+        const { gl } = this;
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, null, 0);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, null, 0);
+    }
+    dispose() {
+        this.release();
+    }
+    make(width, height) {
+        const { gl } = this;
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('ReflectionSurfaceTargets: createTexture failed');
+        /* Unit 0, chosen rather than inherited, for the reason `SsrPass` gives. */
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA16F, width, height);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        return texture;
+    }
+    release() {
+        if (this.probe !== null)
+            this.gl.deleteTexture(this.probe);
+        if (this.tint !== null)
+            this.gl.deleteTexture(this.tint);
+        this.probe = null;
+        this.tint = null;
+    }
+}

package/dist/render/renderQuality.d.ts

@@ -1,4 +1,5 @@
 /** Construction-time GPU quality controls shared by every renderer resource. */
+import type { FrameReflections } from './frameReflections.ts';
 /**
  * What happens to a shaded colour on its way to the framebuffer.
  *
@@ -20,8 +21,14 @@
  * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
  * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
  * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
+ *
+ * `filmic` is a film curve shaped by five numbers — a slope, a toe, a shoulder and how far black
+ * and white clip — that holds a mid grey of 0.18 at 0.18 where `aces` gives about 0.11, so a look
+ * graded against such a curve is matched by its numbers (`setFilmicCurve`) rather than by a lookup
+ * table. Applied by the composite alone, so it needs `screenEffects` and `hdrScene`; without them
+ * every pass grades with `aces` and the renderer says so once. See `filmicCurve.ts`.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder' | 'filmic';
 /**
  * The three settings whose accepted values are a closed set, written as one.
  *
@@ -345,6 +352,18 @@ export interface RenderQuality {
      * eight-bit and this buys only the consistent grading.
      */
     readonly hdrScene: boolean;
+    /**
+     * Ask for a high dynamic range display: a canvas whose highlights run past paper white to as
+     * far as the display allows, where it reports one. Off by default.
+     *
+     * **Asked for, not assumed.** It needs WebGPU, a display reporting a high dynamic range, and a
+     * composite that holds the light to give it (`screenEffects` and `hdrScene`); where any of those
+     * is missing the frame goes out as it always did and the renderer says which in
+     * `displayRangeReason`. `displayRange` is the answer a game reads to choose a look graded for the
+     * output it got. `setDisplayLuminance` sets how far above paper white the highlights may reach.
+     * WebGL2 has no extended-range canvas to draw into, so there it is always the standard range.
+     */
+    readonly highDynamicRange: boolean;
     /** Camera-depth water tint and scattering across every visible pass. */
     readonly underwaterAtmosphere: boolean;
     /** Procedural noise octaves evaluated by plume shaders. */
@@ -512,14 +531,14 @@ export interface RenderQuality {
      */
     readonly sceneSamples: number;
     /**
-     * Camera motion blur, 0 to 1. Off by default.
+     * Motion blur, 0 to 1. Off by default.
      *
-     * Camera rather than per-object, and that is a decision rather than a stage. Per-object
-     * blur needs a velocity buffer: every mesh writing its own screen-space motion into a
-     * second render target, so a second set of matrices per draw and a wider G-buffer, which
-     * is a structural change to a forward renderer that writes one colour target. Camera blur
-     * needs only the previous view-projection, which is one matrix, and it covers the case
-     * that actually matters — a camera whipping round a turntable or through a world.
+     * By the camera's motion everywhere, and **by each drawn object's own motion where a
+     * reconstruction draws one** (DriftTR, WebGPU): a mover's pixels smear along its path while a
+     * still stage stays sharp. Elsewhere a velocity buffer would be every mesh writing its motion into
+     * a second target — a structural change to a forward renderer — so those frames blur by the
+     * camera alone, which needs only the previous view-projection, and say so once when a draw names
+     * where it was. `setCameraMotionBlur` is the per-frame dial and the longest smear.
      *
      * Runs inside the composite pass, so it costs a depth sample and eight taps on the pixels
      * that are moving and nothing on a still frame. Needs `screenEffects`, since without the
@@ -570,6 +589,18 @@ export interface RenderQuality {
      * Needs `screenEffects`, since the resolve composites over the finished scene.
      */
     readonly orderIndependent: boolean;
+    /**
+     * Every opaque lit surface reflects the frame by its own material: a ray marched against the
+     * frame's depth swaps the probes' share of each pixel for what it finds, at the pixel's own
+     * roughness and reflectance, and a surface past `maxRoughness` keeps the probes alone. Off by
+     * default; `true` for the defaults, or the numbers. See `frameReflections.ts`.
+     *
+     * Needs `screenEffects` and `hdrScene`, since the swap is made in scene light, and a frame of one
+     * sample; it says once where it cannot be drawn. What it costs on WebGPU is every opaque lit draw
+     * a second time without its lamps, into two half-float targets, and a march per reflective pixel;
+     * on WebGL2 the same two targets, written beside the colour by the opaque lit draws themselves.
+     */
+    readonly screenSpaceReflections: boolean | FrameReflections;
     /**
      * Depth of field: how wide the blur may reach, as a fraction of the frame's height. Off by
      * default.

package/dist/render/renderQuality.js

@@ -85,9 +85,11 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     sceneSamples: 1,
     planarReflections: false,
     hdrScene: false,
+    highDynamicRange: false,
     cameraMotionBlur: 0,
     temporalAa: false,
     orderIndependent: false,
+    screenSpaceReflections: false,
     depthOfField: 0,
     reconstruction: 0,
     indirectLight: false,
@@ -227,9 +229,11 @@ export function resolveRenderQuality(options = {}) {
         sceneSamples: Math.max(1, Math.round(options.sceneSamples ?? DEFAULT_RENDER_QUALITY.sceneSamples)),
         planarReflections: options.planarReflections ?? DEFAULT_RENDER_QUALITY.planarReflections,
         hdrScene: options.hdrScene ?? DEFAULT_RENDER_QUALITY.hdrScene,
+        highDynamicRange: options.highDynamicRange ?? DEFAULT_RENDER_QUALITY.highDynamicRange,
         cameraMotionBlur: Math.min(1, Math.max(0, options.cameraMotionBlur ?? DEFAULT_RENDER_QUALITY.cameraMotionBlur)),
         temporalAa: options.temporalAa ?? DEFAULT_RENDER_QUALITY.temporalAa,
         orderIndependent: options.orderIndependent ?? DEFAULT_RENDER_QUALITY.orderIndependent,
+        screenSpaceReflections: options.screenSpaceReflections ?? DEFAULT_RENDER_QUALITY.screenSpaceReflections,
         /* Off, or a ratio at least 1.3 and at most 2 — never a number between zero and the range. */
         reconstruction: resolveReconstruction(options.reconstruction),
         indirectLight: options.indirectLight ?? DEFAULT_RENDER_QUALITY.indirectLight,

package/dist/render/sceneTarget.d.ts

@@ -89,6 +89,8 @@ export declare class SceneTarget {
     private gradeStrength;
     /** The lens and the print, held like the grade. See `filmLook.ts`. */
     private vignette;
+    /** The lens's colour fringe: red's and green's pull and where it begins. See `fringe.ts`. */
+    private readonly fringe;
     private grain;
     private grainSeed;
     /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
@@ -277,6 +279,8 @@ export declare class SceneTarget {
      */
     /** The lens's corner falloff, held until changed. See `Renderer.setVignette`. */
     setVignette(strength: number): void;
+    /** The lens's colour fringe, held until changed. See `Renderer.setChromaticAberration`. */
+    setChromaticAberration(intensity: number, start: number): void;
     /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
     setFilmGrain(strength: number, seed: number): void;
     /** How far the eye adapts, and the time since the last frame. See `Renderer.setAutoExposure`. */
@@ -298,6 +302,7 @@ export declare class SceneTarget {
     resolve(strength: number, reachUv: number, grade?: {
         readonly transform: number;
         readonly exposure: number;
+        readonly film?: Float32Array;
     }, motion?: {
         readonly reprojection: Float32Array;
         readonly strength: number;

package/dist/render/sceneTarget.js

@@ -1,5 +1,6 @@
 import { glSceneDepthFormat } from './depthConvention.js';
 import { clampGrain, clampVignette, grainSeed } from './shaders/filmLook.js';
+import { FRINGE_FLOATS, resolveFringe } from './shaders/fringe.js';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.js';
 import { ExposurePass } from './exposurePass.js';
 import { clampAutoExposure } from './shaders/exposure.js';
@@ -93,6 +94,8 @@ export class SceneTarget {
     gradeStrength = 0;
     /** The lens and the print, held like the grade. See `filmLook.ts`. */
     vignette = 0;
+    /** The lens's colour fringe: red's and green's pull and where it begins. See `fringe.ts`. */
+    fringe = new Float32Array(FRINGE_FLOATS);
     grain = 0;
     grainSeed = 0;
     /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
@@ -605,6 +608,10 @@ export class SceneTarget {
     setVignette(strength) {
         this.vignette = clampVignette(strength);
     }
+    /** The lens's colour fringe, held until changed. See `Renderer.setChromaticAberration`. */
+    setChromaticAberration(intensity, start) {
+        resolveFringe(intensity, start, this.fringe);
+    }
     /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
     setFilmGrain(strength, seed) {
         this.grain = clampGrain(strength);
@@ -654,7 +661,10 @@ export class SceneTarget {
         this.gradeSize = lut.size;
     }
     resolve(strength, reachUv, 
-    /* The grade, applied here because this is the last pass. See RUSH_FRAG's own note. */
+    /*
+     * The grade, applied here because this is the last pass. See RUSH_FRAG's own note. `film` is
+     * the `filmic` curve's eight constants (`resolveFilmicCurve`), read only under transform 4.
+     */
     grade = {
         transform: 0,
         exposure: 1,
@@ -809,6 +819,12 @@ export class SceneTarget {
         gl.uniform1f(this.uniforms['uReach'] ?? null, reachUv);
         gl.uniform1i(this.uniforms['uOutputTransform'] ?? null, grade.transform);
         gl.uniform1f(this.uniforms['uOutputExposure'] ?? null, grade.exposure);
+        if (grade.film !== undefined) {
+            gl.uniform4fv(this.uniforms['uFilmA'] ?? null, grade.film, 0, 4);
+            gl.uniform4fv(this.uniforms['uFilmB'] ?? null, grade.film, 4, 4);
+        }
+        /* A standard range always here: see `Renderer.displayRange`. */
+        gl.uniform1f(this.uniforms['uDisplayHeadroom'] ?? null, 1);
         /*
          * Depth on its own unit, and the reprojection with it. Bound every frame rather than
          * once, because a texture unit is context state and any pass between two frames is free
@@ -894,6 +910,12 @@ export class SceneTarget {
         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);
+        /* 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);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(this.uniforms['uMotion'] ?? null, 7);
+        gl.uniform1f(this.uniforms['uObjectMotion'] ?? null, 0);
         gl.activeTexture(gl.TEXTURE0);
         /* No unit and no texture: a flat colour, not a sample. Uploaded unconditionally — two
            floats and a triplet cost nothing next to the triangle this pass already draws — and it
@@ -902,6 +924,7 @@ export class SceneTarget {
         gl.uniform3fv(this.uniforms['uVeilColor'] ?? null, veilColor);
         gl.uniform1f(this.uniforms['uVeilAlpha'] ?? null, veilAlpha);
         gl.uniform1f(this.uniforms['uVignette'] ?? null, this.vignette);
+        gl.uniform3fv(this.uniforms['uFringe'] ?? null, this.fringe);
         gl.uniform2f(this.uniforms['uGrain'] ?? null, this.grain, this.grainSeed);
         gl.bindVertexArray(this.vao);
         gl.drawArrays(gl.TRIANGLES, 0, 3);

package/dist/render/screenSpaceReflection.d.ts

@@ -24,6 +24,11 @@ import type { DecalBox } from './decalProjector.ts';
  * which is the same price the temporal row declined for a velocity buffer. A caller declares a
  * `ReflectiveSurface` instead: a box, and a facing rule for which surfaces inside it reflect. It is
  * the shape `DecalProjector` already has, for the same reason.
+ *
+ * **Or every surface by its own material**, where the renderer was built with
+ * `screenSpaceReflections`: the lit stage leaves two maps of what it reflected — not a G-buffer, the
+ * environment's share and its tint, which is all a swap needs — and the same trace runs in a
+ * material mode over every pixel. See `frameReflections.ts`.
  */
 /**
  * Clip Y negated, for a backend whose framebuffer rows run downward.
@@ -174,7 +179,8 @@ export interface ReflectiveSurfaceOptions extends DecalBox {
      * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
      * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
      * by — so a floor returns more toward the horizon than underfoot, and the share follows the
-     * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+     * camera as a physically based renderer weighs its reflections. **False by default**, the one
+     * share as before.
      *
      * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
      * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion

package/dist/render/screenSpaceReflection.js

@@ -23,6 +23,11 @@ import { decalToWorldMatrix, worldToDecalMatrix } from './decalProjector.js';
  * which is the same price the temporal row declined for a velocity buffer. A caller declares a
  * `ReflectiveSurface` instead: a box, and a facing rule for which surfaces inside it reflect. It is
  * the shape `DecalProjector` already has, for the same reason.
+ *
+ * **Or every surface by its own material**, where the renderer was built with
+ * `screenSpaceReflections`: the lit stage leaves two maps of what it reflected — not a G-buffer, the
+ * environment's share and its tint, which is all a swap needs — and the same trace runs in a
+ * material mode over every pixel. See `frameReflections.ts`.
  */
 /**
  * Clip Y negated, for a backend whose framebuffer rows run downward.

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  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\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(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (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/** 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  outColor = vec4(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/** 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/** 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  outColor = vec4(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  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\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(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (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\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  outColor = vec4(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/** 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\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  outColor = vec4(lit * energy * (1.0 - fog), 1.0);\n}\n";

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

@@ -0,0 +1,19 @@
+/**
+ * The vertex-stage bone animation: a crowd instance's vertex turned and placed by its bone, at its
+ * instance's moment of the clip — the GLSL of `boneAnimation.ts`'s `animateBoneVertex`, line for
+ * line. Shared by the lit stage and the depth stage, so a crowd's shadow moves with it.
+ *
+ * **Three textures, read by index and never filtered**: the places and the turns, a texel a bone a
+ * frame (bones across, frames down, sizes read with `textureSize` so no uniform says them), and the
+ * batch's clocks, two floats an instance wrapped onto rows, read at `gl_InstanceID`. The clip's speed
+ * and its bone scale are the one uniform, `uBoneClip`; the scene's time is the pass's `uSceneTime`.
+ *
+ * **The bone is read from the grain lane**, which is where a mesh's second coordinates ride, stored
+ * as `-1 - u` (`lightmap.ts`). An instanced batch reads no grain of its own from that lane: a crowd's
+ * mesh carries second coordinates, which is what makes it one.
+ *
+ * Integer arithmetic for the lattice, by the 2026-09-20 rule, except where a float is clamped onto
+ * it: the first frame is `min(floor(wrapped), frames - 1)`, so the wrap that division-by-reciprocal
+ * lands on `frames` is the last frame fully blended into the first — the first, which is right.
+ */
+export declare const BONE_ANIMATION_GLSL = "\nuniform highp sampler2D uBonePlaces;\nuniform highp sampler2D uBoneTurns;\nuniform highp sampler2D uInstanceClocks;\n/** x the clip's frames a second, y how many bones one unit of the second coordinates' u counts. */\nuniform vec2 uBoneClip;\n\n/** v turned by the unit quaternion q. */\nvec3 boneTurn(vec4 q, vec3 v) {\n  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);\n}\n\n/**\n * Where the clip puts this vertex, from its place at rest; its normal and tangent turned with it.\n */\nvec3 boneAnimate(vec3 position, inout vec3 normal, inout vec3 tangent) {\n  ivec2 size = textureSize(uBonePlaces, 0);\n  int clocksWidth = textureSize(uInstanceClocks, 0).x;\n  vec2 clock = texelFetch(\n    uInstanceClocks,\n    ivec2(gl_InstanceID % clocksWidth, gl_InstanceID / clocksWidth),\n    0\n  ).xy;\n  float moment = (uSceneTime * clock.y + clock.x) * uBoneClip.x;\n  float frames = float(size.y);\n  float wrapped = moment - frames * floor(moment / frames);\n  int first = min(int(floor(wrapped)), size.y - 1);\n  int second = first + 1 == size.y ? 0 : first + 1;\n  float blend = clamp(wrapped - float(first), 0.0, 1.0);\n  int bone = clamp(int(floor((-1.0 - aGrain) * uBoneClip.y + 0.5)), 0, size.x - 1);\n  vec4 q0 = texelFetch(uBoneTurns, ivec2(bone, first), 0);\n  vec4 q1 = texelFetch(uBoneTurns, ivec2(bone, second), 0);\n  /* The shorter arc: a quaternion and its negation are one turn. */\n  if (dot(q0, q1) < 0.0) q1 = -q1;\n  vec4 q = normalize(mix(q0, q1, blend));\n  vec3 place = mix(\n    texelFetch(uBonePlaces, ivec2(bone, first), 0).xyz,\n    texelFetch(uBonePlaces, ivec2(bone, second), 0).xyz,\n    blend\n  );\n  normal = boneTurn(q, normal);\n  tangent = boneTurn(q, tangent);\n  return boneTurn(q, position) + place;\n}\n";

package/dist/render/shaders/boneAnimation.js

@@ -0,0 +1,63 @@
+/**
+ * The vertex-stage bone animation: a crowd instance's vertex turned and placed by its bone, at its
+ * instance's moment of the clip — the GLSL of `boneAnimation.ts`'s `animateBoneVertex`, line for
+ * line. Shared by the lit stage and the depth stage, so a crowd's shadow moves with it.
+ *
+ * **Three textures, read by index and never filtered**: the places and the turns, a texel a bone a
+ * frame (bones across, frames down, sizes read with `textureSize` so no uniform says them), and the
+ * batch's clocks, two floats an instance wrapped onto rows, read at `gl_InstanceID`. The clip's speed
+ * and its bone scale are the one uniform, `uBoneClip`; the scene's time is the pass's `uSceneTime`.
+ *
+ * **The bone is read from the grain lane**, which is where a mesh's second coordinates ride, stored
+ * as `-1 - u` (`lightmap.ts`). An instanced batch reads no grain of its own from that lane: a crowd's
+ * mesh carries second coordinates, which is what makes it one.
+ *
+ * Integer arithmetic for the lattice, by the 2026-09-20 rule, except where a float is clamped onto
+ * it: the first frame is `min(floor(wrapped), frames - 1)`, so the wrap that division-by-reciprocal
+ * lands on `frames` is the last frame fully blended into the first — the first, which is right.
+ */
+export const BONE_ANIMATION_GLSL = `
+uniform highp sampler2D uBonePlaces;
+uniform highp sampler2D uBoneTurns;
+uniform highp sampler2D uInstanceClocks;
+/** x the clip's frames a second, y how many bones one unit of the second coordinates' u counts. */
+uniform vec2 uBoneClip;
+
+/** v turned by the unit quaternion q. */
+vec3 boneTurn(vec4 q, vec3 v) {
+  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);
+}
+
+/**
+ * Where the clip puts this vertex, from its place at rest; its normal and tangent turned with it.
+ */
+vec3 boneAnimate(vec3 position, inout vec3 normal, inout vec3 tangent) {
+  ivec2 size = textureSize(uBonePlaces, 0);
+  int clocksWidth = textureSize(uInstanceClocks, 0).x;
+  vec2 clock = texelFetch(
+    uInstanceClocks,
+    ivec2(gl_InstanceID % clocksWidth, gl_InstanceID / clocksWidth),
+    0
+  ).xy;
+  float moment = (uSceneTime * clock.y + clock.x) * uBoneClip.x;
+  float frames = float(size.y);
+  float wrapped = moment - frames * floor(moment / frames);
+  int first = min(int(floor(wrapped)), size.y - 1);
+  int second = first + 1 == size.y ? 0 : first + 1;
+  float blend = clamp(wrapped - float(first), 0.0, 1.0);
+  int bone = clamp(int(floor((-1.0 - aGrain) * uBoneClip.y + 0.5)), 0, size.x - 1);
+  vec4 q0 = texelFetch(uBoneTurns, ivec2(bone, first), 0);
+  vec4 q1 = texelFetch(uBoneTurns, ivec2(bone, second), 0);
+  /* The shorter arc: a quaternion and its negation are one turn. */
+  if (dot(q0, q1) < 0.0) q1 = -q1;
+  vec4 q = normalize(mix(q0, q1, blend));
+  vec3 place = mix(
+    texelFetch(uBonePlaces, ivec2(bone, first), 0).xyz,
+    texelFetch(uBonePlaces, ivec2(bone, second), 0).xyz,
+    blend
+  );
+  normal = boneTurn(q, normal);
+  tangent = boneTurn(q, tangent);
+  return boneTurn(q, position) + place;
+}
+`;

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  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\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(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (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\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  outColor = vec4(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/** 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\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  outColor = vec4(uTint * (caustic * uStrength * reach * (1.0 - fog)), 1.0);\n}\n";

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

@@ -23,6 +23,13 @@ export declare const DEPTH_INSTANCED_VERT: string;
  */
 export declare const DEPTH_CUTOUT_VERT: string;
 export declare const DEPTH_INSTANCED_CUTOUT_VERT: string;
+/**
+ * The variants a crowd casts through: an instanced batch playing a bone animation, its vertices
+ * where the clip puts them at each instance's moment. See `shaders/boneAnimation.ts`. No glass
+ * variant: a crowd is not glass, and a glass batch that animates casts its tint from rest.
+ */
+export declare const DEPTH_INSTANCED_ANIMATED_VERT: string;
+export declare const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT: string;
 export declare const DEPTH_FRAG = "#version 300 es\nprecision highp float;\nin vec4 vLightPosition;\n\nuniform highp sampler2DArray uPreviousShadowMap;\nuniform int uPeelShadowLayer;\n\nvoid main() {\n  if (uPeelShadowLayer != 0) {\n    vec3 p = vLightPosition.xyz / vLightPosition.w;\n    vec2 uv = p.xy * 0.5 + 0.5;\n    float previousDepth = texture(uPreviousShadowMap, vec3(uv, 0.0)).r;\n    // Discard the already-recorded surface and everything in front of it. The\n    // ordinary depth test then stores the next independently fading occluder.\n    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;\n  }\n}\n";
 /**
  * The cutout caster's depth: the plain pass, and a texel of alpha under the cutoff writes nothing.