@driftengine/core 4.13.3 → 4.13.5

package/CHANGELOG.json

@@ -1,4 +1,56 @@
 [
+  {
+    "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",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "Hair takes the sky, a probe's light and DriftLight through its own highlights, for the eye's side of each strand, and reflects none of the environment, so a fibre keeps its colour in shade.",
+        "text": "Hair is lit from every side through its own lobes. The sky, a probe's irradiance and DriftLight reached a hair surface through its scatter alone, and the environment's reflection was laid over it, white, at the strand's Fresnel: a consumer's golden hair, base colour (1, 0.43, 0.115) and scatter 0.2, was reported drawing as platinum where its source draws it gold. Now the lobes are evaluated once for a light along the eye flattened across the strand, unshadowed, with no transmitted lobe because that direction stands for the eye's side, and every lobe widened by 0.2 radians as a source that large would widen it; twice their sum, at most 1, multiplies the light from every side, under the model map's occlusion as before. The scatter's half of that is exactly what the scatter alone gave, its own average over the sphere, so what is new is the reflected and the internally reflected lobes, which carry the fibre's colour into the shade. Hair reflects none of the environment, the probe, the sky's gradient and screen-space reflections alike, because the reflected lobe already holds that light. Measured on `demo/dev/models.html?view=hair&sky=only`, strands under an even white sky: a strand's middle drew (149, 127, 102) and draws (235, 189, 142), where the reference in `hairLobes.ts` gives (234, 189, 142) for the same geometry; the row of five models moves 8,340 pixels, every one of them the hair sphere's; and WebGPU and WebGL2, on Vulkan and on OpenGL, agree as closely as they did. **What it gives up**: hair lit from behind by an open sky shows no rim from the sky, which the lamps still give it, and the share moves with the eye as the lobes do rather than holding still as an average would."
+      },
+      {
+        "kind": "added",
+        "short": "A skinned cloth's pull is weighed particle by particle, so a strap is held at its root and hangs free at its tip: `SkinnedClothSetup.pullWeights`.",
+        "text": "`SkinnedClothSetup.pullWeights` weighs a skinned cloth's pull particle by particle, one a particle from 0 to 1: each keeps `1 / (1 + w · pull · h²)` of its offset from its skinned place a substep, and hangs `9.81 / (w · pull)` metres below it at rest. One pull for a whole garment had to choose, as a consumer reported: held at its mean, a belt's tips stood out from the waist they hang against; held at none, a styled fringe fell past the jaw it is swept up from. Now a strap is held at its root and hangs free at its tip, a fringe is held nearly whole and a coat's body swings free, in one garment. Absent, every particle takes the whole pull, as before; a weight of 0 is no pull at all, a free particle rather than a pinned one, and a weight outside 0 to 1 is refused by its index. The device carries the weights as a section of its statics and the pull as a substep's stiffness, `pull · h²`, and divides as the CPU does. Measured on `demo/dev/skinnedCloth.html?pull=400&weights=ramp`, a cape weighed 1 at its shoulders to 0 at its hem: it moves 39,267 pixels from the same cape under the whole pull; weights of 1 everywhere draw the unweighted cape to the pixel; WebGPU and WebGL2 agree to 159 pixels; and the device parts from the CPU by 1.8 mm at most and 0.03 mm by the 150th frame, inside what an unweighted pull of 100 parted by on the build before (1.8 mm, 0.07 mm), a hem that hangs free being as sensitive as a weak pull. An unweighted pull draws within 11 pixels of what it drew, the device now dividing in single precision where it was handed the share."
+      }
+    ]
+  },
   {
     "version": "4.13.3",
     "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: 929.4 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/clothSetPack.js

@@ -31,6 +31,7 @@ const SECTIONS = [
     [7, 3],
     [10, 3],
     [13, 16],
+    [29, 1],
 ];
 /** Where the influences start, and where the garment's index sits, in particle counts. */
 const INFLUENCES = 13;

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

@@ -1,13 +1,16 @@
 import type { SkinnedClothSetup } from '@driftengine/physics';
 /** Floats of statics a particle, across its sections. */
-export declare const CLOTH_STATIC_FLOATS = 29;
+export declare const CLOTH_STATIC_FLOATS = 30;
 /** Bit flags of the limits a set-up has: a max distance, a backstop, a frontstop. */
 export declare const CLOTH_LIMIT_MAX = 1;
 export declare const CLOTH_LIMIT_BACK = 2;
 export declare const CLOTH_LIMIT_FRONT = 4;
 export interface PackedCloth {
     readonly count: number;
-    /** inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3, influences ×16. */
+    /**
+     * inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3,
+     * influences ×16, pull weight.
+     */
     readonly statics: Float32Array;
     /** Distance records (a, b, rest, compliance), bending (four ids, rest, compliance), tethers (particle, anchor, length). */
     readonly constraints: Uint32Array;

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

@@ -18,7 +18,7 @@
  */
 import { batchesOf } from '@driftengine/physics';
 /** Floats of statics a particle, across its sections. */
-export const CLOTH_STATIC_FLOATS = 29;
+export const CLOTH_STATIC_FLOATS = 30;
 /** Bit flags of the limits a set-up has: a max distance, a backstop, a frontstop. */
 export const CLOTH_LIMIT_MAX = 1;
 export const CLOTH_LIMIT_BACK = 2;
@@ -50,6 +50,7 @@ export function packCloth(setup) {
             statics[at + i * 2 + 1] = real ? radius : 0;
         }
         statics[6 * n + i] = limits.thickness?.[i] ?? 0;
+        statics[29 * n + i] = setup.pullWeights?.[i] ?? 1;
         for (let k = 0; k < 3; k++) {
             statics[7 * n + i * 3 + k] = setup.positions[i * 3 + k];
             statics[10 * n + i * 3 + k] = setup.normals?.[i * 3 + k] ?? (k === 2 ? 1 : 0);

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;