@driftengine/core 4.13.4 → 4.13.5

package/CHANGELOG.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "4.13.5",
+    "date": "2026-10-12",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "The haze takes a second layer, a most it may hide, a distance past which it hides nothing, and the sun glowing in it: `fogLayer2`, `fogMaxOpacity`, `fogCutoff` and `fogSunGlow`.",
+        "text": "The environment's haze takes four more fields, in every pass that fogs and in the GPU-driven pipeline. `fogLayer2` is a second layer, its own density at its own height thinning by its own falloff, summed with the first along every ray: a ground mist under a high summer haze, where one layer had to pick one of the two scale heights. `fogMaxOpacity` is the most of a surface the haze may hide, so a skyline keeps that much of itself however much air lies in front of it. `fogCutoff` is a distance past which the haze hides nothing, the sky included, for a backdrop that brings its own haze painted in. `fogSunGlow` is the sun's light the haze scatters toward the eye: a colour looking straight at the sun through haze that hides everything, falling off as the cosine of the angle from it to an exponent, beginning a distance past where the haze begins, and added after the fog rather than mixed in, so a far ridge seen into a low sun burns gold. Every new lane reads as none at zero, so a pass a binder never wrote them into draws the haze it drew before. A haze authored in base two converts to the engine's natural units as density `ρ · (ln 2)²` and falloff `f · ln 2`, which the manual states. The haze's eight scalar uniforms are packed into two vectors, which paid for the three new ones and freed two more of the lit stage's rows on a phone's 256. Measured on `demo/dev/fogStart.html`, eight white patches at known distances: each option reads its hand-derived value to a level on WebGPU and on WebGL2 over Vulkan and over OpenGL, and the GPU-driven pipeline's fog agrees with the reference in `fog.ts` to 7.8e-5 over 102 glowing channels. Every published scene draws what 4.13.4 drew, to the pixel on WebGPU."
+      },
+      {
+        "kind": "added",
+        "short": "The global medium thins with height in two layers, takes a coloured albedo, and scatters the sun, the sky and the lamps at strengths of their own, each lamp through its own shadows.",
+        "text": "`setGlobalMedium` takes an object beside its four numbers, with what the numbers cannot say: `heightFalloff` and `baseY`, so the medium thins with height as the environment's haze does, and `layer2`, a second layer, integrated over each step of the march rather than sampled; `albedo` as a colour, a share a channel; `sunScatter` and `skyScatter`, how strongly the sun and the sky's fill scatter, 1 as each lights a surface; and `lampScatter`, the lamps, 0 by default so a scene that never asks keeps its picture and its cost. A lamp is the lit stage's own, shaped by its falloff and its cone and cut by its own static and live shadow maps, so a lamp behind a post throws the post's shadow into the air, and `lightMediumScatter` in the environment scales each lamp's own. A medium standing for the near part of the environment's haze hands the rest of the ray to that haze by setting `fogStart` to its `maxDistance`: the reach is where the medium ends, which the documentation had wrongly said extinction went on past and the march never did. Measured: with the sun and the sky at 0 no pixel rises, a red albedo raises no green or blue, a falloff that empties the room draws the frame without the pass to the pixel, and turning a lamp's maps off brightens 12,722 pixels of air behind the post on `demo/dev/pointshadow.html`, where with the lamp out of the medium it moves 2,928, on WebGPU and WebGL2 alike. `scripts/medium-check.mjs` had gone red on three claims when 4.13.0 made the screen encoding the default, because its unshadowed runs clipped to white; it reads the linear output now, and all six claims hold on both backends with the numbers the build before this one gives."
+      },
+      {
+        "kind": "added",
+        "short": "Local exposure takes a shape: each region turned about middle grey at the frame’s exposure, a share kept above it and another below, and a pixel’s own detail kept apart.",
+        "text": "`setLocalExposure` takes a shape beside its one number: `{ highlightContrast, shadowContrast, detail, blurredBlend, middleGreyBias, range }`. Each region is turned about middle grey at the frame's exposure, the auto exposure's gain and the output exposure together, rather than about the frame's metered brightness: it keeps `highlightContrast` of its stops from grey where it is brighter and `shadowContrast` where it is darker, and each pixel keeps `detail` of its own stops from its region, so above 1 sharpens the texture a curve would flatten. `blurredBlend` leans a region's level toward its tile's mean, 0.4 as the engine has held it, `middleGreyBias` adds stops to grey, and `range` is the furthest a region moves. The one number is the shape it always was, both shares one less the strength about the held level, and it draws what it drew to the bit, measured on both backends. On `demo/dev/localExposure.html`, a sunlit wall half pale and half dark: keeping half the stops each side brings the clipped pale half down 0.79 of a stop, enough for its stripes to show again, and the dark half up 0.82, and a detail of 1.5 widens the stripes by half while the halves hold."
+      },
+      {
+        "kind": "added",
+        "short": "Every surface's reflection can be brought to the light where it stands, by a weight mixed in by roughness: a mirror keeps the capture, a rough surface takes its place's light.",
+        "text": "`setEnvironmentMixing(weight, roughnessLow, roughnessHigh)` scales what every surface reflects of the environment, metal or not, by `lerp(1, weight, smoothstep(roughnessLow, roughnessHigh, roughness))`, held until changed and put back at `bindMeshPass`. A probe is captured at one place and seen from many, so a figure standing where the indirect light is twice what the probe saw reflected the probe too dimly against everything lit around it, and `setEnvironmentGain` reached metals only while `setSurfaceReflectivity` stopped at 1. The weight is the place's indirect light over the probe's own average brightness, above 1 or below, and the roughnesses are where it is mixed in, 0.1 and 0.3 by default, so a mirror keeps its image. Measured on the models page: a weight of 1 is the frame without it to the pixel, a weight of 2 brightens 60,314 pixels of the row's reflections, and the backends agree to 7 pixels. It costs the lit stage one uniform row."
+      },
+      {
+        "kind": "added",
+        "short": "Hair reads each strand's specular and direction texel by texel: the model map's red scales the white highlight, and a layer of its own can lean strands out of the card.",
+        "text": "The hair model reads two things a texel that it took once a material or from the mesh. The model map's red is the strand's specular: the reflected lobe is scaled by twice it, in the lamps' lobes and in the light from every side alike, so 0.5 is the highlight as drawn and 0 a root that reflects nothing; a hair model map whose red was left at 0 now draws no white highlight, and 128 keeps the old look. And `hairModel({ directionOffset })` names a layer of the model map, that many past the texel's own, holding each strand's direction in the surface's tangent frame, packed as a normal map packs a normal: the strand runs along it rather than along the tangent, so a card's strands lean out of its plane each its own way. Measured on the models page's strands: no map draws what it drew, a red of 0 and of 1 move 83,451 and 82,138 pixels, strands leaned 30 degrees move 118,342, and the backends agree to 31 pixels."
+      },
+      {
+        "kind": "added",
+        "short": "A brushed surface's highlight can be lifted where it is bright, its strength texel by texel: `anisotropicModel({ lift })`, scaled by the model map's alpha.",
+        "text": "`anisotropicModel({ lift })` raises the anisotropic distribution where it is bright, `D + min(3, D^1.5) · lift`, the shape a brushed finish that reads as polished along its streak is authored with, applied as a factor of the distribution at the half vector so the peak-normalised lobe and the physical one lift alike. Where a model map is bound its alpha scales the lift texel by texel, so a map storing a tenth of each region's lift takes `lift: 10`. 0, the default, draws what it drew; on the models page's brushed discs a lift of 3 moves 55,287 pixels of their streaks and the backends agree to 11."
+      }
+    ]
+  },
   {
     "version": "4.13.4",
     "date": "2026-10-12",

package/README.md

@@ -6,7 +6,7 @@ WebGL2 everywhere else, behind one API, and carries the fixed-step loop, the ren
 input, the scene graph, geometry, text and the whole of `@driftengine/physics`, which it re-exports.
 Everything else is a separate package a game adds when it reaches for it.
 
-**Cost: 930.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 951.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -178,7 +178,7 @@ export type { FrameTimer } from './render/backend/timer.ts';
 export type { SceneCasterMaterial, SceneCasters, ShadowCasterCloth, ShadowCasterSink, ShadowCasters, } from './render/shadowCasters.ts';
 export type { StaticDrawsHandle } from './render/staticDraws.ts';
 export type { BoneAnimationClip, BoneAnimationHandle } from './render/boneAnimation.ts';
-export type { Atmosphere, UnderwaterAtmosphere } from './render/atmosphere.ts';
+export type { Atmosphere, FogLayer, FogSunGlow, UnderwaterAtmosphere, } from './render/atmosphere.ts';
 export { createImageTexelDecoder } from './render/imageTexels.ts';
 export type { ImageTexelDecoder, ImageTexels } from './render/imageTexels.ts';
 export { DEFAULT_RENDER_QUALITY, resolveRenderQuality } from './render/renderQuality.ts';
@@ -190,7 +190,8 @@ export { DEFAULT_RENDER_QUALITY, resolveRenderQuality } from './render/renderQua
  * is the type the setter takes and the two bounds a settings screen has to know about.
  */
 export { DEFAULT_GLOBAL_MEDIUM, MAX_GLOBAL_MEDIUM_STEPS, WEAK_GPU_MEDIUM_STEPS, resolveGlobalMedium, } from './render/globalMedium.ts';
-export type { GlobalMediumOptions } from './render/globalMedium.ts';
+export type { GlobalMediumOptions, GlobalMediumSettings, ResolvedGlobalMedium, } from './render/globalMedium.ts';
+export type { LocalExposureOptions } from './render/shaders/localExposure.ts';
 export { equirectToCubeFaces } from './render/equirectToCube.ts';
 export type { EquirectSource } from './render/equirectToCube.ts';
 export { IRRADIANCE_EDGE, PREFILTER_SAMPLE_COUNTS, ggxMaxLevelFor, irradianceLevelFor, octahedralEdgeFor, roughnessForLevel, } from './render/prefilterEnvMap.ts';

package/dist/render/anisotropicLobe.d.ts

@@ -4,6 +4,11 @@ export declare function anisotropicAlphas(roughness: number, strength: number, o
  * The lobe at a half vector whose components along the direction, across it and along the normal
  * are `th`, `bh` and `nh`. 1 at the mirror direction.
  */
+/**
+ * How much the lift brightens the stretched lobe at a half vector: `(D + min(3, D^1.5) · k) / D`,
+ * with D the distribution there, `1 / (π αT αB d²)`, as the shader's `anisotropicLift` has it.
+ */
+export declare function anisotropicLiftFactor(th: number, bh: number, nh: number, alphaT: number, alphaB: number, lift: number): number;
 export declare function anisotropicLobe(th: number, bh: number, nh: number, alphaT: number, alphaB: number): number;
 /** Three components in the lobe's frame: along the direction, across it, along the normal. */
 export type FrameVector = readonly [number, number, number];

package/dist/render/anisotropicLobe.js

@@ -25,6 +25,19 @@ export function anisotropicAlphas(roughness, strength, out) {
  * The lobe at a half vector whose components along the direction, across it and along the normal
  * are `th`, `bh` and `nh`. 1 at the mirror direction.
  */
+/**
+ * How much the lift brightens the stretched lobe at a half vector: `(D + min(3, D^1.5) · k) / D`,
+ * with D the distribution there, `1 / (π αT αB d²)`, as the shader's `anisotropicLift` has it.
+ */
+export function anisotropicLiftFactor(th, bh, nh, alphaT, alphaB, lift) {
+    if (lift <= 0)
+        return 1;
+    const x = th / alphaT;
+    const y = bh / alphaB;
+    const d = x * x + y * y + nh * nh;
+    const distribution = 1 / Math.max(Math.PI * alphaT * alphaB * d * d, 1e-8);
+    return 1 + lift * Math.min(3 / distribution, Math.sqrt(distribution));
+}
 export function anisotropicLobe(th, bh, nh, alphaT, alphaB) {
     const x = th / alphaT;
     const y = bh / alphaB;

package/dist/render/atmosphere.d.ts

@@ -10,6 +10,42 @@ export interface UnderwaterAtmosphere {
     /** Half-width of the smooth air↔water transition around the surface. */
     transitionDepth: number;
 }
+/**
+ * A layer of haze: how thick it is where it is thickest, and how fast it thins above that.
+ *
+ * In natural units, as `fogDensity` is: a haze authored in base two, its surviving light
+ * `2^(−∫ρ)` and its density falling as `2^(−f·Δy)`, is the layer `density: ρ · (ln 2)²`,
+ * `heightFalloff: f · ln 2` here — the integral of base two's exponential carries one `ln 2` of its
+ * own, and the transmittance's base the other.
+ */
+export interface FogLayer {
+    /** Extinction per metre at `baseY`. */
+    density: number;
+    /** Reciprocal scale height, per metre: 0 is a layer of even density. */
+    heightFalloff: number;
+    /** The height it is thickest at. */
+    baseY: number;
+}
+/**
+ * The sun's light scattered toward the eye by the haze: a glow in the sun's direction, as dust and
+ * droplets throw forward what they catch.
+ *
+ * Added to what the haze returns rather than mixed with it, by as much of the ray past `start` as
+ * the haze hides: a mountain range seen into a low sun burns gold at its distance, and the
+ * figures a few metres off do not. **What it gives up** is the light's own shape: the glow is a
+ * lobe about one direction, `cos^exponent` of the angle from it, not light scattered along the
+ * ray through the shadows the sun's map knows of — the global medium is that one.
+ */
+export interface FogSunGlow {
+    /** The glow looking straight along `direction` through haze that hides everything. */
+    color: Vec3;
+    /** How tight the glow is about the sun: the cosine of the angle from it, to this power. */
+    exponent: number;
+    /** Metres past the haze's own start before the glow begins. Default 0. */
+    start?: number;
+    /** Surface → the light the glow surrounds. Absent, the environment's `directionalDir`. */
+    direction?: Vec3;
+}
 /** Atmosphere fields shared by every visible render pass. */
 export interface Atmosphere {
     fogColor: Vec3;
@@ -58,6 +94,31 @@ export interface Atmosphere {
      * between the camera and the start, which a real medium has; that is the point of it.
      */
     fogStart?: number;
+    /**
+     * The medium only: a second layer of haze, summed with the first along every ray, each its own
+     * density, height and falloff. Absent, one layer.
+     *
+     * Two layers are what a valley with a ground mist under a high summer haze is: one thin and
+     * tall, one dense and hugging the floor. One layer must pick one of the two scale heights, and
+     * either gets the other's half of the picture wrong.
+     */
+    fogLayer2?: FogLayer | null;
+    /**
+     * The most of a surface the haze may hide, 0 to 1. Absent or 1, all of it.
+     *
+     * Below 1 a far mountain keeps that much of itself however much air lies between, which is how a
+     * scene keeps a skyline readable behind a haze that should hide everything nearer the ground.
+     * **What it gives up** is physics: no medium has a floor on what survives it.
+     */
+    fogMaxOpacity?: number;
+    /**
+     * Metres from the camera past which the haze hides nothing: a surface further away, the sky
+     * included, is drawn clear. Absent or 0, none. For a sky or a backdrop that brings its own
+     * haze painted in, which the medium would otherwise lay a second time.
+     */
+    fogCutoff?: number;
+    /** The medium only: the sun's light scattered toward the eye by the haze. Absent, none. */
+    fogSunGlow?: FogSunGlow | null;
     underwater: UnderwaterAtmosphere | null;
 }
 /**
@@ -80,6 +141,16 @@ export declare function fogDensityAtEye(atmosphere: Atmosphere, cameraY: number)
  */
 export interface ResolvedAtmosphere {
     readonly fogColor: Float32Array;
+    /**
+     * Four floats: the second layer's extinction per metre at the camera's height and its falloff,
+     * then the least of a surface the haze must leave, `fogMaxOpacity`'s complement, and the cutoff
+     * distance. **Every lane is none at zero**, so a pass that never wrote them draws as before.
+     */
+    readonly fogLayer2: Float32Array;
+    /** Four floats: the sun glow's colour, black for none, and its exponent. */
+    readonly fogGlow: Float32Array;
+    /** Four floats: surface → the glow's light, and how far past the haze's start the glow begins. */
+    readonly fogGlowDir: Float32Array;
     fogDensity: number;
     fogHeightFalloff: number;
     fogEyeY: number;
@@ -98,7 +169,14 @@ export interface ResolvedAtmosphere {
  * allows no allocation in one. Each backend keeps a single `ResolvedAtmosphere` and refills
  * it; nothing here allocates and nothing is shared between them.
  */
-export declare function resolveAtmosphere(atmosphere: Atmosphere, cameraY: number, underwaterEnabled: boolean, out: ResolvedAtmosphere): ResolvedAtmosphere;
+export declare function resolveAtmosphere(atmosphere: Atmosphere & {
+    readonly directionalDir?: ArrayLike<number>;
+}, cameraY: number, underwaterEnabled: boolean, out: ResolvedAtmosphere): ResolvedAtmosphere;
+/**
+ * A target for `resolveAtmosphere`, made once outside the frame loop: one factory, so a field added
+ * to the resolved medium is a field every holder of one gets rather than one each must remember.
+ */
+export declare function createResolvedAtmosphere(): ResolvedAtmosphere;
 /**
  * Bind the same camera medium to any shader that declares atmosphere uniforms.
  * Missing optional uniforms are harmless WebGL null locations, so mesh, sky,

package/dist/render/atmosphere.js

@@ -64,21 +64,69 @@ export function resolveAtmosphere(atmosphere, cameraY, underwaterEnabled, out) {
     out.underwaterColor.set(underwater === null ? atmosphere.fogColor : underwater.color);
     out.underwaterFogDensity = underwater === null ? atmosphere.fogDensity : underwater.fogDensity;
     out.underwaterFactor = factor;
+    resolveHazeExtras(atmosphere, cameraY, out);
     return out;
 }
+/**
+ * The second layer, the haze's limits and the sun's glow, into `out`: the layer and the glow only
+ * in the medium, since a linear ramp has neither a density nor a ray to integrate, and every slot
+ * written whatever is asked, so nothing a shader reads keeps what an earlier frame left in it.
+ */
+function resolveHazeExtras(atmosphere, cameraY, out) {
+    const medium = atmosphere.fogMode !== 'linear';
+    const layer = medium ? (atmosphere.fogLayer2 ?? null) : null;
+    const density = layer === null ? 0 : Math.max(0, layer.density);
+    /* The second layer at the camera's height, as `fogDensityAtEye` puts the first. */
+    out.fogLayer2[0] =
+        density > 0 && layer !== null
+            ? density * Math.exp(-(cameraY - layer.baseY) * layer.heightFalloff)
+            : 0;
+    out.fogLayer2[1] = density > 0 && layer !== null ? layer.heightFalloff : 0;
+    const most = atmosphere.fogMaxOpacity;
+    out.fogLayer2[2] =
+        most !== undefined && Number.isFinite(most) ? 1 - Math.min(1, Math.max(0, most)) : 0;
+    const cutoff = atmosphere.fogCutoff;
+    out.fogLayer2[3] = cutoff !== undefined && Number.isFinite(cutoff) && cutoff > 0 ? cutoff : 0;
+    const glow = medium ? (atmosphere.fogSunGlow ?? null) : null;
+    const toward = glow?.direction ?? atmosphere.directionalDir;
+    const x = toward?.[0] ?? 0;
+    const y = toward?.[1] ?? 1;
+    const z = toward?.[2] ?? 0;
+    const length = Math.hypot(x, y, z);
+    const lit = glow !== null && length > 1e-6;
+    for (let c = 0; c < 3; c++) {
+        out.fogGlow[c] = lit && glow !== null ? Math.max(0, glow.color[c]) : 0;
+    }
+    /* Above zero, so the shader's pow never meets 0 to the 0: a lobe that flat is the whole sky. */
+    out.fogGlow[3] = lit && glow !== null ? Math.max(1e-3, glow.exponent) : 1;
+    out.fogGlowDir[0] = lit ? x / length : 0;
+    out.fogGlowDir[1] = lit ? y / length : 1;
+    out.fogGlowDir[2] = lit ? z / length : 0;
+    out.fogGlowDir[3] = lit && glow !== null ? Math.max(0, glow.start ?? 0) : 0;
+}
+/**
+ * A target for `resolveAtmosphere`, made once outside the frame loop: one factory, so a field added
+ * to the resolved medium is a field every holder of one gets rather than one each must remember.
+ */
+export function createResolvedAtmosphere() {
+    return {
+        fogColor: new Float32Array(3),
+        fogLayer2: new Float32Array(4),
+        fogGlow: new Float32Array(4),
+        fogGlowDir: new Float32Array(4),
+        underwaterColor: new Float32Array(3),
+        fogDensity: 0,
+        fogHeightFalloff: 0,
+        fogEyeY: 0,
+        fogMode: 0,
+        fogNear: 0,
+        fogFar: 1,
+        underwaterFogDensity: 0,
+        underwaterFactor: 0,
+    };
+}
 /** One per GL binder, refilled per call. See `resolveAtmosphere` on why it is not allocated. */
-const glResolved = {
-    fogColor: new Float32Array(3),
-    underwaterColor: new Float32Array(3),
-    fogDensity: 0,
-    fogHeightFalloff: 0,
-    fogEyeY: 0,
-    fogMode: 0,
-    fogNear: 0,
-    fogFar: 1,
-    underwaterFogDensity: 0,
-    underwaterFactor: 0,
-};
+const glResolved = createResolvedAtmosphere();
 /**
  * Bind the same camera medium to any shader that declares atmosphere uniforms.
  * Missing optional uniforms are harmless WebGL null locations, so mesh, sky,
@@ -87,13 +135,12 @@ const glResolved = {
 export function bindAtmosphere(gl, uniforms, atmosphere, cameraY, underwaterEnabled) {
     const m = resolveAtmosphere(atmosphere, cameraY, underwaterEnabled, glResolved);
     gl.uniform3fv(uniforms['uFogColor'] ?? null, m.fogColor);
-    gl.uniform1f(uniforms['uFogDensity'] ?? null, m.fogDensity);
-    gl.uniform1f(uniforms['uFogHeightFalloff'] ?? null, m.fogHeightFalloff);
-    gl.uniform1f(uniforms['uFogEyeY'] ?? null, m.fogEyeY);
-    gl.uniform1i(uniforms['uFogMode'] ?? null, m.fogMode);
-    gl.uniform1f(uniforms['uFogNear'] ?? null, m.fogNear);
-    gl.uniform1f(uniforms['uFogFar'] ?? null, m.fogFar);
+    /* Packed as `shaders/fog.ts` declares them, four to a row: see `uFogMedium` there for why. */
+    gl.uniform4f(uniforms['uFogMedium'] ?? null, m.fogDensity, m.fogHeightFalloff, m.fogEyeY, m.underwaterFogDensity);
+    gl.uniform4f(uniforms['uFogRange'] ?? null, m.fogNear, m.fogFar, m.fogMode, 0);
     gl.uniform3fv(uniforms['uUnderwaterColor'] ?? null, m.underwaterColor);
-    gl.uniform1f(uniforms['uUnderwaterFogDensity'] ?? null, m.underwaterFogDensity);
     gl.uniform1f(uniforms['uUnderwaterFactor'] ?? null, m.underwaterFactor);
+    gl.uniform4fv(uniforms['uFogLayer2'] ?? null, m.fogLayer2);
+    gl.uniform4fv(uniforms['uFogGlow'] ?? null, m.fogGlow);
+    gl.uniform4fv(uniforms['uFogGlowDir'] ?? null, m.fogGlowDir);
 }

package/dist/render/backend/webgl2/renderer.d.ts

@@ -4,6 +4,7 @@ import type { GlassOptions } from '../../glass.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { Camera } from '../../camera.ts';
 import type { PickHit, PickableSource } from '../../pickable.ts';
+import type { GlobalMediumSettings } from '../../globalMedium.ts';
 import type { ReflectiveSurface } from '../../screenSpaceReflection.ts';
 import type { DecalProjector } from '../../decalProjector.ts';
 import type { FieldSource } from '../../gi/globalField.ts';
@@ -11,6 +12,7 @@ import type { Bounds } from '../../../math/bounds.ts';
 import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
 import type { PassDefinition, PassHandle } from '../../pass.ts';
 import type { Vec3 } from '../../../math/color.ts';
+import type { LocalExposureOptions } from '../../shaders/localExposure.ts';
 import { GpuTimer } from '../../gpuTimer.ts';
 import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
@@ -210,6 +212,12 @@ export interface Environment extends Atmosphere {
      * every light. See `PointLightSource.falloffExponent`.
      */
     lightFalloffExponents?: Float32Array;
+    /**
+     * One per active light: how strongly it scatters in the global medium, a share of how strongly it
+     * lights a surface, beside `setGlobalMedium`'s `lampScatter`. Optional: absent is 1 for every
+     * light. See `PointLightSet.lightMediumScatter`.
+     */
+    lightMediumScatter?: Float32Array;
     /** One per active light: a row of the photometric atlas, or −1 for none. */
     lightIesProfiles: Float32Array;
     /**
@@ -1041,6 +1049,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * vector on the device, so written whole, and kept here so a setter moving one keeps the others.
      */
     private readonly environmentDials;
+    /** `uEnvironmentMixing` as it stands: see `setEnvironmentMixing`. None until a draw asks. */
+    private readonly environmentMixing;
     /** `uEmission` as it stands: the emissive gain and the night factor. */
     private readonly emission;
     /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
@@ -2232,6 +2242,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * legitimate as one above. Held non-negative, because a negative environment is not a darker one.
      */
     setEnvironmentGain(gain: number): void;
+    /**
+     * How much of the light where the surfaces drawn next stand their reflection is brought to, for
+     * every surface, metal or not: what each reflects of the environment times
+     * `lerp(1, weight, smoothstep(roughnessLow, roughnessHigh, roughness))`. 1 is the default and
+     * identity; held until changed, and put back at `bindMeshPass`.
+     *
+     * **Why there is a weight at all**: a probe is captured at one place and seen from many, so a
+     * figure standing where the indirect light is twice what the probe saw reflects the probe at the
+     * probe's brightness and reads as dull against everything lit around it. `weight` is that
+     * ratio, the place's indirect light over the probe's own average, and a caller that knows both
+     * passes it; above 1 brightens, below dims. A mirror keeps the capture as it is, because its
+     * image is the point, and a rough surface, whose reflection is an average anyway, takes its
+     * place's light: the roughnesses say where between, 0.1 and 0.3 by default.
+     *
+     * Unlike `setEnvironmentGain`, which reaches metals only, and `setSurfaceReflectivity`, which
+     * stops at 1. **What it gives up** is a reflection that stays the probe's image on a rough
+     * surface: past the upper roughness it is the probe scaled to the light, not the place relit.
+     */
+    setEnvironmentMixing(weight: number, roughnessLow?: number, roughnessHigh?: number): void;
     /**
      * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
      *
@@ -3383,7 +3412,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * two regions of one brightness band differ. Needs `screenEffects` and `hdrScene`, and says so
      * once rather than doing nothing. See `shaders/localExposure.ts`.
      */
-    setLocalExposure(strength: number): void;
+    setLocalExposure(setting: number | LocalExposureOptions): void;
     /**
      * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
      * gone `radius` metres past it, so the far depth buffer's steps — a sky dome kilometres off, a
@@ -3477,9 +3506,12 @@ export declare class WebGL2Renderer implements RendererApi {
      * this is everything between the camera and whatever the frame already drew, and it is the one
      * of the two that can put the shape of a doorway on a floor.
      */
-    setGlobalMedium(density: number, albedo?: number, anisotropy?: number, maxDistance?: number): void;
+    setGlobalMedium(density: number | GlobalMediumSettings, albedo?: number | Vec3, anisotropy?: number, maxDistance?: number): void;
     /** This frame's medium. Off until a caller says otherwise. See `setGlobalMedium`. */
     private mediumOptions;
+    /** The lamps the medium is lit by, and the lit stage's lamps they come from, refilled a frame. */
+    private readonly mediumLamps;
+    private readonly mediumLights;
     /** Built on the first frame that asks for a medium, and never on one that does not. */
     private medium;
     /**

package/dist/render/backend/webgl2/renderer.js

@@ -15,8 +15,9 @@ import { DecalPass } from '../../decalPass.js';
 import { SsrPass } from '../../ssrPass.js';
 import { ReflectionSurfaceTargets } from '../../reflectionSurfaceTargets.js';
 import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
+import { noEnvironmentMixing, resolveEnvironmentMixing } from '../../environmentMixing.js';
 import { GlobalMediumPass } from '../../globalMediumPass.js';
-import { DEFAULT_GLOBAL_MEDIUM, WEAK_GPU_MEDIUM_STEPS, mediumActive, resolveGlobalMedium, } from '../../globalMedium.js';
+import { DEFAULT_GLOBAL_MEDIUM, WEAK_GPU_MEDIUM_STEPS, createResolvedMediumLamps, mediumActive, resolveGlobalMedium, resolveGlobalMediumSettings, resolveMediumLamps, } from '../../globalMedium.js';
 import { REFLECTION_EDGE_FADE, ReflectionQueue } from '../../screenSpaceReflection.js';
 import { DecalQueue } from '../../decalQueue.js';
 import { OitPass } from '../../oitPass.js';
@@ -54,7 +55,7 @@ import { WorldLightField } from '../../driftLight/worldLightField.js';
 import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.js';
 import { flatFrag, flatVert } from '../../shaders/flat/index.js';
 import { skinEight } from '../../shaders/skinning.js';
-import { MODEL_MAP_TEXTURE_UNIT, MORPH_DELTA_TEXTURE_UNIT, SKIN_PALETTE_TEXTURE_UNIT, } from '../../lightBudget.js';
+import { MODEL_MAP_TEXTURE_UNIT, MORPH_DELTA_TEXTURE_UNIT, SKIN_PALETTE_TEXTURE_UNIT, createResolvedPointLights, resolvePointLights, } from '../../lightBudget.js';
 import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel, skinProfileDistance, } from '../../surfaceModel.js';
 import { lightmapRegionsBound, modelBound, skinHalfBound } from '../../shaders/flat/models.js';
 import { lightmapTexels, warnRegionsWithoutPage, warnUnpagedLightmap, withLightmapUvs, } from '../../lightmap.js';
@@ -718,6 +719,8 @@ export class WebGL2Renderer {
      * vector on the device, so written whole, and kept here so a setter moving one keeps the others.
      */
     environmentDials = new Float32Array(3);
+    /** `uEnvironmentMixing` as it stands: see `setEnvironmentMixing`. None until a draw asks. */
+    environmentMixing = noEnvironmentMixing(new Float32Array(4));
     /** `uEmission` as it stands: the emissive gain and the night factor. */
     emission = new Float32Array([1, 0]);
     /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
@@ -3691,6 +3694,31 @@ export class WebGL2Renderer {
         this.passEnvironmentGain = Math.max(0, gain);
         this.writeEnvironmentDials();
     }
+    /**
+     * How much of the light where the surfaces drawn next stand their reflection is brought to, for
+     * every surface, metal or not: what each reflects of the environment times
+     * `lerp(1, weight, smoothstep(roughnessLow, roughnessHigh, roughness))`. 1 is the default and
+     * identity; held until changed, and put back at `bindMeshPass`.
+     *
+     * **Why there is a weight at all**: a probe is captured at one place and seen from many, so a
+     * figure standing where the indirect light is twice what the probe saw reflects the probe at the
+     * probe's brightness and reads as dull against everything lit around it. `weight` is that
+     * ratio, the place's indirect light over the probe's own average, and a caller that knows both
+     * passes it; above 1 brightens, below dims. A mirror keeps the capture as it is, because its
+     * image is the point, and a rough surface, whose reflection is an average anyway, takes its
+     * place's light: the roughnesses say where between, 0.1 and 0.3 by default.
+     *
+     * Unlike `setEnvironmentGain`, which reaches metals only, and `setSurfaceReflectivity`, which
+     * stops at 1. **What it gives up** is a reflection that stays the probe's image on a rough
+     * surface: past the upper roughness it is the probe scaled to the light, not the place relit.
+     */
+    setEnvironmentMixing(weight, roughnessLow = 0.1, roughnessHigh = 0.3) {
+        if (this.contextLost)
+            return;
+        resolveEnvironmentMixing(weight, roughnessLow, roughnessHigh, this.environmentMixing);
+        this.materials.dirty();
+        this.writeFlatVector('uEnvironmentMixing', this.environmentMixing);
+    }
     /**
      * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
      *
@@ -6395,12 +6423,12 @@ export class WebGL2Renderer {
      * two regions of one brightness band differ. Needs `screenEffects` and `hdrScene`, and says so
      * once rather than doing nothing. See `shaders/localExposure.ts`.
      */
-    setLocalExposure(strength) {
+    setLocalExposure(setting) {
         if (this.sceneTarget === null || !this.quality.hdrScene) {
-            this.warnLookWithoutComposite(strength);
+            this.warnLookWithoutComposite(typeof setting === 'number' ? setting : 1);
             return;
         }
-        this.sceneTarget.setLocalExposure(strength);
+        this.sceneTarget.setLocalExposure(setting);
     }
     /**
      * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
@@ -6508,15 +6536,13 @@ export class WebGL2Renderer {
      * of the two that can put the shape of a doorway on a floor.
      */
     setGlobalMedium(density, albedo, anisotropy, maxDistance) {
-        this.mediumOptions = resolveGlobalMedium({
-            density: Number.isFinite(density) ? density : 0,
-            albedo,
-            anisotropy,
-            maxDistance,
-        });
+        this.mediumOptions = resolveGlobalMediumSettings(density, albedo, anisotropy, maxDistance);
     }
     /** This frame's medium. Off until a caller says otherwise. See `setGlobalMedium`. */
-    mediumOptions = DEFAULT_GLOBAL_MEDIUM;
+    mediumOptions = resolveGlobalMedium(DEFAULT_GLOBAL_MEDIUM);
+    /** The lamps the medium is lit by, and the lit stage's lamps they come from, refilled a frame. */
+    mediumLamps = createResolvedMediumLamps();
+    mediumLights = createResolvedPointLights();
     /** Built on the first frame that asks for a medium, and never on one that does not. */
     medium = null;
     /**
@@ -7265,6 +7291,9 @@ export class WebGL2Renderer {
                        so it is safe only because `sunShadow` is 0 whenever these maps do not exist. */
                     sunShadows: this.sunShadows?.texture ?? this.emptyTexture2DArray,
                     peeledEnabled: this.peelFilled,
+                    /* The lit stage's lamps and the shadows it resolved for them, this frame's. */
+                    lamps: resolveMediumLamps(this.mediumOptions, resolvePointLights(env, this.quality.pointLightFalloff, this.mediumLights), this.pointShadows === null ? null : this.resolvedPointShadows, env?.lightMediumScatter, this.mediumLamps),
+                    pointShadows: this.pointShadowArray?.texture ?? this.emptyTexture2DArray,
                 });
                 if (marched) {
                     /* The march finished on the default framebuffer, which is not where the frame is being
@@ -7512,6 +7541,8 @@ export class WebGL2Renderer {
         this.materialEnvironmentGain = null;
         this.environmentDials[1] = 0;
         this.environmentDials[2] = 1;
+        /* And no mixing, for the same reason. See `setEnvironmentMixing`. */
+        noEnvironmentMixing(this.environmentMixing);
         this.emission[0] = env.emissiveGain;
         this.emission[1] = env.nightFactor;
         /* The moving layer's own matrix, the first time a frame draws that layer with one. */
@@ -7731,6 +7762,7 @@ export class WebGL2Renderer {
          * See `setSurfaceReflectivity` and `setEnvironmentGain`.
          */
         gl.uniform3fv(u['uEnvironmentDials'] ?? null, this.environmentDials);
+        gl.uniform4fv(u['uEnvironmentMixing'] ?? null, this.environmentMixing);
         /* And no relief unless a caller asks, for the same reason. */
         gl.uniform2f(u['uRelief'] ?? null, 0, 60);
         /* And no relief read off a surface texture either, for the same reason. */

package/dist/render/backend/webgpu/boltPass.d.ts

@@ -11,7 +11,7 @@ import type { PipelineCache } from './pipelineCache.ts';
 export declare const BOLT_VERT_FIELDS: UniformFields;
 export declare const BOLT_VERT_SIZE: 96;
 export declare const BOLT_FRAG_FIELDS: UniformFields;
-export declare const BOLT_FRAG_SIZE: 144;
+export declare const BOLT_FRAG_SIZE: 192;
 /** A batch of arcs on the device, behind the surface's opaque handle. */
 export interface GpuBolts {
     readonly fromBuffer: GPUBuffer;

package/dist/render/backend/webgpu/causticsPass.d.ts

@@ -10,7 +10,7 @@ import type { PipelineCache } from './pipelineCache.ts';
 export declare const CAUSTICS_VERT_FIELDS: UniformFields;
 export declare const CAUSTICS_VERT_SIZE: 64;
 export declare const CAUSTICS_FRAG_FIELDS: UniformFields;
-export declare const CAUSTICS_FRAG_SIZE: 160;
+export declare const CAUSTICS_FRAG_SIZE: 208;
 /** A lit surface on the device, behind the API's opaque handle. */
 export interface GpuCaustics {
     readonly vertexBuffers: readonly GPUBuffer[];

package/dist/render/backend/webgpu/filmPass.d.ts

@@ -14,7 +14,7 @@ import type { PipelineCache } from './pipelineCache.ts';
 export declare const FILM_VERT_FIELDS: UniformFields;
 export declare const FILM_VERT_SIZE: 128;
 export declare const FILM_FRAG_FIELDS: UniformFields;
-export declare const FILM_FRAG_SIZE: 160;
+export declare const FILM_FRAG_SIZE: 208;
 export declare function createFilmBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
 /** Bound once against both rings; a dynamic offset per film. See `createPanelBindGroup`. */
 export declare function createFilmBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer, reflection: GPUTextureView, sampler: GPUSampler): GPUBindGroup;

package/dist/render/backend/webgpu/gpuDrivenPass.js

@@ -123,11 +123,11 @@ export const VERTEX_FLOATS = GPU_DRIVEN_VERTEX_FLOATS;
 /**
  * Floats the shading pass's frame block holds. Matches `FRAME_BLOCK_WGSL`'s `Frame`.
  *
- * Two matrices and fifteen vectors: the camera's, the light's, then the eye, the light's direction
+ * Two matrices and eighteen vectors: the camera's, the light's, then the eye, the light's direction
  * and colour, the sky, the ground, the target's size, the shadow's settings in two, the probe's in
- * two, the medium's four, and the visibility buffer's row.
+ * two, the medium's four, the visibility buffer's row, and the medium's last three after it.
  */
-const FRAME_FLOATS = 92;
+const FRAME_FLOATS = 104;
 /** Where each block starts in it, so the writer and the shader cannot drift apart. */
 const FRAME_LIGHT_VIEW_PROJ = 16;
 const FRAME_EYE = 32;
@@ -145,6 +145,9 @@ const FRAME_FOG_UNDERWATER = 76;
 const FRAME_FOG_HEIGHT = 80;
 const FRAME_FOG_RANGE = 84;
 const FRAME_PITCH = 88;
+const FRAME_FOG_LIMITS = 92;
+const FRAME_FOG_GLOW = 96;
+const FRAME_FOG_GLOW_DIR = 100;
 /**
  * Pixels the internal width is rounded up to.
  *
@@ -2168,6 +2171,20 @@ export class GpuDrivenPass {
         params[FRAME_FOG_RANGE + 1] = fog?.far ?? 0;
         params[FRAME_FOG_RANGE + 2] = fog?.mode ?? MEDIUM_FOG;
         params[FRAME_FOG_RANGE + 3] = fog?.underwaterDensity ?? 0;
+        /* The second layer, the floor, the cutoff and the glow: every one none at zero, as a view
+           written before they existed asks. */
+        params[FRAME_FOG_HEIGHT + 2] = fog?.density2 ?? 0;
+        params[FRAME_FOG_HEIGHT + 3] = fog?.heightFalloff2 ?? 0;
+        params[FRAME_FOG_LIMITS] = fog?.floor ?? 0;
+        params[FRAME_FOG_LIMITS + 1] = fog?.cutoff ?? 0;
+        params[FRAME_FOG_GLOW] = fog?.glowColour?.[0] ?? 0;
+        params[FRAME_FOG_GLOW + 1] = fog?.glowColour?.[1] ?? 0;
+        params[FRAME_FOG_GLOW + 2] = fog?.glowColour?.[2] ?? 0;
+        params[FRAME_FOG_GLOW + 3] = fog?.glowExponent ?? 1;
+        params[FRAME_FOG_GLOW_DIR] = fog?.glowDirection?.[0] ?? 0;
+        params[FRAME_FOG_GLOW_DIR + 1] = fog?.glowDirection?.[1] ?? 1;
+        params[FRAME_FOG_GLOW_DIR + 2] = fog?.glowDirection?.[2] ?? 0;
+        params[FRAME_FOG_GLOW_DIR + 3] = fog?.glowStart ?? 0;
         /* The scene's own decision about whether its grid supplies the ambient, as it is on the
            forward path: `ProbeBakeOptions.irradiance` reaches here as `PassEnvironment.irradiance`. */
         params[FRAME_ENVIRONMENT_MIX] = room !== null && room.irradiance ? 1 : 0;

package/dist/render/backend/webgpu/linePass.d.ts

@@ -29,7 +29,7 @@ import type { PipelineCache } from './pipelineCache.ts';
 export declare const LINE_VERT_FIELDS: UniformFields;
 export declare const LINE_VERT_SIZE: 160;
 export declare const LINE_FRAG_FIELDS: UniformFields;
-export declare const LINE_FRAG_SIZE: 112;
+export declare const LINE_FRAG_SIZE: 160;
 /** A polyline batch on the device, behind the surface's opaque handle. */
 export interface GpuLines {
     readonly fromBuffer: GPUBuffer;

package/dist/render/backend/webgpu/mediumFields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The medium's fields, every uniform `shaders/fog.ts` declares, written into a pass's block by name
+ * from one resolved atmosphere.
+ *
+ * **One writer for every pass that fogs.** Ten passes wrote the same ten fields by hand, so a field
+ * the medium grows was ten places to remember and a pass that missed one read zero: the fourth
+ * point of the rule `AGENTS.md` dates 2026-08-13. A field a pass's shader never reads is compiled
+ * out of its block, so each is written only where the block holds it. An absent field is not an
+ * offset of zero, which is the first field of the block.
+ */
+import type { ResolvedAtmosphere } from '../../atmosphere.ts';
+import type { UniformFields } from './scatterPass.ts';
+import type { UniformRing } from './uniformRing.ts';
+/** Into a block staged as floats, indexed in four-byte words. */
+export declare function writeMediumFields(fields: UniformFields, f: Float32Array, m: ResolvedAtmosphere): void;
+/** Into one slot of a ring, at the fields' byte offsets. */
+export declare function writeMediumSlot(ring: UniformRing, slot: number, fields: UniformFields, m: ResolvedAtmosphere): void;