@driftengine/core 4.8.2 → 4.8.3

package/CHANGELOG.json

@@ -1,4 +1,60 @@
 [
+  {
+    "version": "4.8.3",
+    "date": "2026-10-04",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "Ambient occlusion no longer darkens smoke, glass, water or text by the corner behind them: it darkens only the part of a pixel they let through, on both backends.",
+        "text": "Occlusion is applied in the composite from the depth the opaque world leaves, after every translucent draw has landed, and a particle or a pane writes no depth, so a puff of smoke in front of a wall was darkened by the corner behind it: reported as walls and figures behind a cloud showing through it as dark outlines, and nothing at all with occlusion off. The scene's alpha now carries how much of each pixel is still the opaque surface. The frame clears it to 1, an opaque draw writes 1, and every blended draw states what it does to it: what covers (glass, smoke, water, lines, text, panels, sprites, splats) multiplies it by what it lets through, what transmits (the global medium, the order-independent composite) by its own transmittance, and what adds light or is a layer of the surface (caustics, light volumes, bolts, a wet film, decals, reflections) leaves it alone. The composite darkens that share and no more, and the temporal resolve and the reconstruction carry it through. Measured on both backends, plain, with temporal antialiasing and with DriftTR, against a darkened join: a pane at 0.85 opacity keeps 0.15 of the darkening behind it and a cluster of smoke none, while the open join and every frame with occlusion off are unchanged to the pixel. What it gives up is light added in front of an occluded corner, which is darkened with the surface it lands on as before, and the GPU-driven pipeline's own blended surfaces, which still take the occlusion behind them because its blit's alpha is the mask that says where it drew. A pass of your own states its blending with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS` on WebGPU, and `blendCovering`, `blendTransmitting` or `blendKeeping` on WebGL2."
+      },
+      {
+        "kind": "fixed",
+        "short": "A particle's size is documented as what it always was, a half-width from the centre to an edge: a particle of size 0.5 is a metre across.",
+        "text": "`ParticleInstances.sizes` and a pool's `sizeStart` and `sizeEnd` were documented as metres across, and the quad spans twice the size, a corner at minus and plus one on each axis, so a caller who sized by the documentation drew every particle twice as wide as meant. The drawing is unchanged, because every effect already tuned against it would have halved; the type, the pool's options and the manual now say half-width."
+      },
+      {
+        "kind": "fixed",
+        "short": "A bone too short for a body no longer cuts a ragdoll in two: what hangs below it is jointed to the bone above, and stops colliding with the bones it meets there.",
+        "text": "A rig often puts one joint exactly on another, a collar on the chest joint or a helper on the hips, and a bone shorter than `minLength` gets no body. What hung below such a bone was jointed to nothing, because a bone was jointed to the bone ending at its parent joint and that joint had none: in a limp fall the spine above a collar flew 3.9 m off the hips. And it collided with every bone it met at that point, because the shared-end rule compared parent joints by index, so capsules out of one point separated whichever way rounding said and a reaction depended on which way the character faced. A short bone is now transparent: each joint resolves to the nearest one above it that a body ends at, for jointing and for collision alike, and where a short bone lies between, the joint is anchored where the two bones meet at rest, so a still doll does not move on its first tick."
+      },
+      {
+        "kind": "fixed",
+        "short": "A ragdoll draws every bone under a joint on its own body, so after a fall a second thigh or a clavicle no longer hangs off the body beside it.",
+        "text": "`writePose` turned a joint by its first bone below and placed every child by the rig's offset from that turn, so at a joint with several bones below it, hips over a spine and two thighs, a chest over a neck and two clavicles, every branch but the first was swung by the first one's rotation and drawn off its own body. Reported from a game as a foot 0.24 m and an arm 0.17 m from their bodies after a fall; a test fall measured a thigh 97.5 cm out. Each joint is now placed along its own bone as that bone's body holds it, at the rig's length and in the parent's frame, which for the first branch is the rig's offset exactly. Lengths never stretch. A joint with no bone of its own keeps the rig's offset."
+      },
+      {
+        "kind": "added",
+        "short": "`setSurfaceFog(false)` takes the next opaque draws out of the fog, so a floor can recede into the medium while figures standing on it keep their colour.",
+        "text": "Opaque draws could not opt out of the medium: `drawTranslucentMesh` had `fog: false` and the shader a per-draw switch, and nothing reached it for `drawMesh`. A ported game darkening its floor with distance had to darken its figures with it, or leave the far floor 18% too bright. `setSurfaceFog(enabled)` is a surface dial like `setSurfaceGrain`: material state for the draws that follow, read by instanced and skinned draws too, and restored by `bindMeshPass`. A translucent draw's own `fog` is measured against it and puts it back. Verified on both backends with two identical far pillars, one fogged and one not, and a pane between them asking for fog under the dial."
+      },
+      {
+        "kind": "added",
+        "short": "`outputTransform: 'shoulder'` keeps sRGB's midtones and eases only the highlights, by their brightest channel, so an overbright red stays red instead of turning pink.",
+        "text": "A fourth output transform. `'srgb'` clips each channel at 1, so an overbright colour shifts hue on its way to white: `(1.6, 0.4, 0.2)` clips to `(1, 0.4, 0.2)`, pinker and wider. `'shoulder'` leaves everything below 0.8 alone and eases the brightest channel toward 1, as `0.8 + 0.2e / (e + 0.2)` of an excess `e`, scaling the other two with it, so the same colour becomes `(0.96, 0.24, 0.12)`. It is the curve a ported game's own resolve applies, and it has none of ACES's toe or desaturation. One definition shared by the forward passes and the resolve, measured on both backends with the composite on and off: `(250, 134, 97)` against sRGB's `(255, 170, 124)`."
+      },
+      {
+        "kind": "added",
+        "short": "Materials take `uOffset` and `vOffset`, so one quad draws any cell of a flipbook or an atlas, and a cutout's shadow is cut from the same cell.",
+        "text": "`SurfaceMaterial` had a UV scale and no offset, so a flipbook could not choose its cell through the material and a game built one quad mesh per cell, 106 meshes for four strips. `uOffset` and `vOffset` are added after the scale, `uv * scale + offset`, for every map of the material, and they reach the cutout depth and shadow passes, so a card's shadow has the holes of the cell its colour shows. Both backends, mesh and instanced draws."
+      },
+      {
+        "kind": "added",
+        "short": "`AudioGraph.restart(fromSec)` starts every stem from a point in the track, locked together, for music held to a game's own clock.",
+        "text": "The transport could only go back to the top, so music held to a frame counter, which has to resume where that counter is after a skip, ran its own source into the music bus outside every stem's lock. `restart(fromSec)` stops the stems and starts them all from that point at one instant, wrapped by each stem's length, and returns how long until it is heard. `restart()` is unchanged."
+      },
+      {
+        "kind": "changed",
+        "short": "A sound slot registered without a synth is required: if none of its files loads, `load` rejects naming it, after every other slot has loaded.",
+        "text": "Every slot had to carry a synthesised stand-in, which is right for a footstep and wrong for a score that has to be the file or nothing, so such a score was decoded outside the registry. `SoundSource.synth` is optional now. A slot without one is required: when none of its candidates loads it is listed in `unbuilt`, and `load` still settles every other slot before rejecting with an error naming each missing required slot and the files it tried. A slot with a synth behaves as before."
+      },
+      {
+        "kind": "fixed",
+        "short": "A WebSocket or WebRTC transport reads a text frame as its UTF-8 bytes, and counts a frame it cannot read as dropped, where both vanished in silence.",
+        "text": "`WebSocketTransport` and `WebRtcTransport` discarded any message that arrived as a string, without counting it in `dropped`, on the ground that a payload through UTF-8 loses its high bytes. That is true of binary data sent as text and not of a peer that speaks text: a text frame is lossless UTF-8 by the protocol, and a client against a server sending text received nothing at all. Text now arrives as exactly the bytes the sender wrote, anything else unreadable is counted, and both transports share the one rule."
+      }
+    ]
+  },
   {
     "version": "4.8.2",
     "date": "2026-10-03",

package/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 710.5 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

@@ -277,6 +277,7 @@ export type { GroundSurface, RibbonSurfaceOptions, SurfaceHit } from './physics/
 export { CompositeSurface } from './physics/compositeSurface.ts';
 export { colliderSurface } from './physics/colliderSurface.ts';
 export { DEPTH_CLEAR, DEPTH_COMPARE, DEPTH_COMPARE_EQUAL, DEPTH_FORMAT, DEPTH_OFFSET_SIGN, REVERSED_DEPTH, conventionalDepth, } from './render/depthConvention.ts';
+export { SCENE_ALPHA_COVERS, SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS, blendCovering, blendKeeping, blendTransmitting, } from './render/sceneCoverage.ts';
 export { VIEW_MODEL_DEPTH_SHARE } from './render/viewModel.ts';
 export type { ColliderSurfaceOptions } from './physics/colliderSurface.ts';
 export { BoxSurface } from './physics/boxSurface.ts';

package/dist/index.js

@@ -338,6 +338,12 @@ export { colliderSurface } from './physics/colliderSurface.js';
  * `EXT_clip_control`.
  */
 export { DEPTH_CLEAR, DEPTH_COMPARE, DEPTH_COMPARE_EQUAL, DEPTH_FORMAT, DEPTH_OFFSET_SIGN, REVERSED_DEPTH, conventionalDepth, } from './render/depthConvention.js';
+/*
+ * **What a contributed pass's blended draw does to the scene's alpha**, which carries how much of
+ * each pixel is still the opaque surface: the share the composite's ambient occlusion may darken.
+ * A pass blending into the scene states one of these for its alpha. See `sceneCoverage.ts`.
+ */
+export { SCENE_ALPHA_COVERS, SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS, blendCovering, blendKeeping, blendTransmitting, } from './render/sceneCoverage.js';
 /* How much of the depth range `beginViewModel` takes when it is given no share. See `viewModel.ts`. */
 export { VIEW_MODEL_DEPTH_SHARE } from './render/viewModel.js';
 export { BoxSurface } from './physics/boxSurface.js';

package/dist/render/backend/materialChanges.d.ts

@@ -27,8 +27,13 @@ export interface DrawMaterialOptions {
     /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
     readonly refracting: boolean;
 }
-/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
-export declare function ownsMaterial(options: DrawMaterialOptions): boolean;
+/**
+ * Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore.
+ *
+ * `passFog` is how the surfaces around it meet the medium — `FOG_RECEDE` unless `setSurfaceFog`
+ * turned it off — so a translucent draw asking for what the pass already has takes nothing.
+ */
+export declare function ownsMaterial(options: DrawMaterialOptions, passFog?: number): boolean;
 /** Whether the next draw shares the open material or opens a new one. */
 export declare class MaterialChanges {
     /**

package/dist/render/backend/materialChanges.js

@@ -18,11 +18,16 @@
  * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
  */
 import { FOG_RECEDE } from './drawFog.js';
-/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
-export function ownsMaterial(options) {
+/**
+ * Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore.
+ *
+ * `passFog` is how the surfaces around it meet the medium — `FOG_RECEDE` unless `setSurfaceFog`
+ * turned it off — so a translucent draw asking for what the pass already has takes nothing.
+ */
+export function ownsMaterial(options, passFog = FOG_RECEDE) {
     return (options.opacity < 1 ||
         !options.lit ||
-        options.fog !== FOG_RECEDE ||
+        options.fog !== passFog ||
         !options.toneMapped ||
         options.refracting);
 }

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

@@ -936,6 +936,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly surfaceScene;
     /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
     private oitWeight;
+    /**
+     * How the surfaces drawn next meet the medium: what `setSurfaceFog` set, and `FOG_RECEDE` from
+     * each `bindMeshPass`. A translucent draw's own fog is measured against this and puts it back.
+     */
+    private surfaceFog;
     private ditherFade;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     private oitRefused;
@@ -1866,6 +1871,22 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setEnvironmentAmbient(_amount: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
+     * True is the default, and what `bindMeshPass` restores.
+     *
+     * **The opaque counterpart of `TranslucentMeshOptions.fog`**, which a translucent draw has had
+     * all along; the shader's per-draw switch was there, and nothing reached it for an ordinary mesh.
+     * What it is for is a medium that darkens one thing and not another — a floor receding into the
+     * distance under figures that must keep their full value however far from the camera they stand.
+     * Material state like `setSurfaceGrain`: instanced and skinned draws read it too, and a
+     * translucent draw's own `fog` is measured against it and puts it back.
+     *
+     * **What it gives up** is the medium's honesty: a surface out of the fog is drawn as though the
+     * air between it and the eye were empty, so it should be a surface the scene means to stand
+     * apart, not one whose distance is the point.
+     */
+    setSurfaceFog(enabled: boolean): void;
     /**
      * One float of material state, into every flat program.
      *
@@ -1876,6 +1897,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * reads, drew what was asked.
      */
     private writeFlatFloat;
+    /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
+    private writeFlatInt;
     /**
      * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
      * of detail of one thing.

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

@@ -1,6 +1,7 @@
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
-import { FOG_RECEDE, fogModeOf } from '../drawFog.js';
+import { FOG_OFF, FOG_RECEDE, fogModeOf } from '../drawFog.js';
+import { blendCovering, blendKeeping } from '../../sceneCoverage.js';
 import { mat4 } from 'gl-matrix';
 import { GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { resolveGlass } from '../../glass.js';
@@ -560,6 +561,11 @@ export class WebGL2Renderer {
     surfaceScene = new Float32Array(4);
     /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
     oitWeight = 0;
+    /**
+     * How the surfaces drawn next meet the medium: what `setSurfaceFog` set, and `FOG_RECEDE` from
+     * each `bindMeshPass`. A translucent draw's own fog is measured against this and puts it back.
+     */
+    surfaceFog = FOG_RECEDE;
     ditherFade = 0;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     oitRefused = false;
@@ -1169,6 +1175,7 @@ export class WebGL2Renderer {
         if (this.activeDepthPeel)
             gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
         gl.uniform2f(u['uUvScale'] ?? null, cutout.u, cutout.v);
+        gl.uniform2f(u['uUvOffset'] ?? null, cutout.uOffset, cutout.vOffset);
         gl.uniform1f(u['uAlphaCutout'] ?? null, cutout.cutoff);
         /* Narrowed for the reason the sink's own `mesh` gives: this renderer only hands out its own. */
         cutout.albedo.bind(gl, SURFACE_TEXTURE_UNIT);
@@ -2541,6 +2548,7 @@ export class WebGL2Renderer {
          * how big a dome was — WebGPU writes it before its own early return and WebGL2 did not.
          */
         gl.uniform2f(u['uUvScale'] ?? null, material?.uScale ?? 1, material?.vScale ?? 1);
+        gl.uniform2f(u['uUvOffset'] ?? null, material?.uOffset ?? 0, material?.vOffset ?? 0);
         gl.uniform1i(u['uDoubleSided'] ?? null, material?.doubleSided === true ? 1 : 0);
         /* The albedo's effects table, or the stand-in the shader reads as none. Before the early
            return, so a material with no albedo still leaves a complete texture on the unit. */
@@ -2669,6 +2677,28 @@ export class WebGL2Renderer {
         this.materials.dirty();
         this.writeFlatFloat('uGrain', Math.min(1, Math.max(0, amount)));
     }
+    /**
+     * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
+     * True is the default, and what `bindMeshPass` restores.
+     *
+     * **The opaque counterpart of `TranslucentMeshOptions.fog`**, which a translucent draw has had
+     * all along; the shader's per-draw switch was there, and nothing reached it for an ordinary mesh.
+     * What it is for is a medium that darkens one thing and not another — a floor receding into the
+     * distance under figures that must keep their full value however far from the camera they stand.
+     * Material state like `setSurfaceGrain`: instanced and skinned draws read it too, and a
+     * translucent draw's own `fog` is measured against it and puts it back.
+     *
+     * **What it gives up** is the medium's honesty: a surface out of the fog is drawn as though the
+     * air between it and the eye were empty, so it should be a surface the scene means to stand
+     * apart, not one whose distance is the point.
+     */
+    setSurfaceFog(enabled) {
+        if (this.contextLost)
+            return;
+        this.materials.dirty();
+        this.surfaceFog = enabled ? FOG_RECEDE : FOG_OFF;
+        this.writeFlatInt('uFogEnabled', this.surfaceFog);
+    }
     /**
      * One float of material state, into every flat program.
      *
@@ -2685,6 +2715,14 @@ export class WebGL2Renderer {
         }
         this.useFlatProgram();
     }
+    /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
+    writeFlatInt(name, value) {
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.gl.uniform1i(target.uniforms[name] ?? null, value);
+        }
+        this.useFlatProgram();
+    }
     /**
      * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
      * of detail of one thing.
@@ -2913,7 +2951,7 @@ export class WebGL2Renderer {
         /* A blended batch shows what is behind it — refraction or glass — as a single draw does, and
            counts a material of its own for it by the rule both backends share (`materialChanges.ts`). */
         const refracting = blend && this.bindSeeThrough(u, options);
-        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
         if (own)
             this.materials.dirty();
         this.takeMaterial();
@@ -2939,16 +2977,16 @@ export class WebGL2Renderer {
          */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (fog !== FOG_RECEDE)
+        if (fog !== this.surfaceFog)
             gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.gradeCode(), 1));
         if (blend) {
             gl.enable(gl.BLEND);
             if (options.additive === true)
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+                blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
             else
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+                blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
             if (!depthWrite)
                 gl.depthMask(false);
         }
@@ -2988,8 +3026,8 @@ export class WebGL2Renderer {
             this.unbindSeeThrough(u);
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (fog !== FOG_RECEDE)
-            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        if (fog !== this.surfaceFog)
+            gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)
@@ -4068,6 +4106,7 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uGlassLight'] ?? null, this.glassLight);
         if (cutout !== null) {
             gl.uniform2f(u['uUvScale'] ?? null, cutout.u, cutout.v);
+            gl.uniform2f(u['uUvOffset'] ?? null, cutout.uOffset, cutout.vOffset);
             gl.uniform1f(u['uAlphaCutout'] ?? null, cutout.cutoff);
             cutout.albedo.bind(gl, SURFACE_TEXTURE_UNIT);
             gl.uniform1i(u['uCutoutMap'] ?? null, SURFACE_TEXTURE_UNIT);
@@ -4757,7 +4796,7 @@ export class WebGL2Renderer {
          */
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.uniform4f(this.panelUniforms['uRect'] ?? null, rect.left, rect.top, rect.width, rect.height);
         gl.uniform2f(this.panelUniforms['uViewport'] ?? null, Math.max(this.canvas.clientWidth, 1), Math.max(this.canvas.clientHeight, 1));
         /* Identity: this backend's clip space is the one the shader was written against. */
@@ -6048,7 +6087,8 @@ export class WebGL2Renderer {
          * shape `uOpacity` and `uTint` already use.
          */
         gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        gl.uniform1i(u['uFogEnabled'] ?? null, 1);
+        gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        this.surfaceFog = FOG_RECEDE;
         /* Grain on by default, so every scene written before it was a choice looks unchanged. */
         gl.uniform1f(u['uGrain'] ?? null, 1);
         /* No dither and no weighting: every draw whole, until a crossfade asks. See `setDitherFade`. */
@@ -6233,6 +6273,7 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
         gl.uniform1i(u['uSurfaceEffects'] ?? null, SURFACE_EFFECTS_TEXTURE_UNIT);
         gl.uniform2f(u['uUvScale'] ?? null, 1, 1);
+        gl.uniform2f(u['uUvOffset'] ?? null, 0, 0);
         gl.uniform1f(u['uAlbedoCutout'] ?? null, 0);
         gl.uniform1i(u['uDoubleSided'] ?? null, 0);
         this.materialDoubleSided = false;
@@ -6581,7 +6622,7 @@ export class WebGL2Renderer {
         const toneMapped = options.toneMapped ?? true;
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (fog !== FOG_RECEDE)
+        if (fog !== this.surfaceFog)
             gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         /* `1` is sRGB alone: the conversion without the curve, which is what dropping the tone map
            means rather than dropping the whole transform. `Math.min` rather than a literal, so a
@@ -6616,7 +6657,7 @@ export class WebGL2Renderer {
          */
         /* Taken for itself when any option differs from the pass, and put back below: the rule both
            backends count material changes by. See `materialChanges.ts`. */
-        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
         if (own)
             this.materials.dirty();
         this.takeMaterial();
@@ -6625,9 +6666,9 @@ export class WebGL2Renderer {
             gl.enable(gl.BLEND);
             /* Added, where asked: colour times alpha onto what is there, and the target's alpha kept. */
             if (options.additive === true)
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+                blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
             else
-                gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+                blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         }
         /*
          * The two depth options, both scoped to this draw and handed straight back — the same
@@ -6667,8 +6708,8 @@ export class WebGL2Renderer {
            cannot inherit a material from the draw before it. */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (fog !== FOG_RECEDE)
-            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        if (fog !== this.surfaceFog)
+            gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)
@@ -7036,7 +7077,7 @@ export class WebGL2Renderer {
             gl.uniform1i(u['uSceneDepth'] ?? null, 3);
         }
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         gl.depthMask(false);
         gl.cullFace(inside ? gl.FRONT : gl.BACK);
         mesh.draw(gl);
@@ -7104,7 +7145,7 @@ export class WebGL2Renderer {
         }
         bindAtmosphere(gl, u, env, this.reflectionPassActive ? this.reflectionAtmosphereY : (camera.position[1] ?? 0), this.quality.underwaterAtmosphere);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         mesh.draw(gl);
         gl.depthMask(true);

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

@@ -2,6 +2,7 @@ import { DEPTH_COMPARE } from '../../depthConvention.js';
 import { CAUSTICS_BINDINGS, CAUSTICS_FRAG_WGSL, CAUSTICS_VERT_WGSL, } from '../../shaders/generated/caustics.wgsl.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.js';
 /**
  * The caustics pass: a surface lit by nearby water.
  *
@@ -126,7 +127,7 @@ export function causticsPipeline(cache, device, layout) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                        alpha: SCENE_ALPHA_KEEPS,
                     },
                 },
             ],

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

@@ -87,13 +87,18 @@ export declare const DEPTH_CUTOUT_VERT_FIELDS: {
         readonly size: 8;
         readonly type: "vec2";
     };
-    readonly uAlphaCutout: {
+    readonly uUvOffset: {
         readonly offset: 168;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uAlphaCutout: {
+        readonly offset: 176;
         readonly size: 4;
         readonly type: "float";
     };
 };
-export declare const DEPTH_CUTOUT_VERT_SIZE: 176;
+export declare const DEPTH_CUTOUT_VERT_SIZE: 192;
 export declare const DEPTH_INSTANCED_CUTOUT_VERT_FIELDS: {
     readonly uLightViewProj: {
         readonly offset: 0;
@@ -105,8 +110,13 @@ export declare const DEPTH_INSTANCED_CUTOUT_VERT_FIELDS: {
         readonly size: 8;
         readonly type: "vec2";
     };
-    readonly uAlphaCutout: {
+    readonly uUvOffset: {
         readonly offset: 72;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uAlphaCutout: {
+        readonly offset: 80;
         readonly size: 4;
         readonly type: "float";
     };

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

@@ -12,9 +12,10 @@ export const DEPTH_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_VERT.fields;
 export const DEPTH_VERT_SIZE = DEPTH_BINDINGS.DEPTH_VERT.uniformSize;
 export const DEPTH_FRAG_SIZE = DEPTH_BINDINGS.DEPTH_FRAG.uniformSize;
 /*
- * The cutout variants' vertex blocks. The rigid one is the plain block with `uUvScale` and
- * `uAlphaCutout` after every other field, so a slot written for it is written with the plain
- * offsets plus these two; the instanced one has no model and no wind, so its two sit earlier.
+ * The cutout variants' vertex blocks. The rigid one is the plain block with `uUvScale`,
+ * `uUvOffset` and `uAlphaCutout` after every other field, so a slot written for it is written with
+ * the plain offsets plus these three; the instanced one has no model and no wind, so its three sit
+ * earlier.
  */
 export const DEPTH_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.fields;
 export const DEPTH_CUTOUT_VERT_SIZE = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.uniformSize;

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

@@ -3,6 +3,7 @@ import { FILM_BINDINGS, FILM_FRAG_WGSL, FILM_VERT_WGSL, } from '../../shaders/ge
 import { vertexBufferLayouts } from './buffers.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.js';
 /**
  * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
  *
@@ -85,7 +86,7 @@ export function filmPipeline(cache, device, layout, key, present) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_KEEPS,
                     },
                 },
             ],

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

@@ -86,6 +86,11 @@ export declare const FLAT_VERT_FIELDS: {
         readonly size: 8;
         readonly type: "vec2";
     };
+    readonly uUvOffset: {
+        readonly offset: 152;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
     readonly uModel: {
         readonly offset: 160;
         readonly size: 64;

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

@@ -2,6 +2,7 @@ import { DEPTH_COMPARE, DEPTH_FORMAT, depthOffsetForLayer } from '../../depthCon
 import { FLAT_BINDINGS, FLAT_FRAG_WGSL, FLAT_VERT_WGSL, } from '../../shaders/generated/flat.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS = new Set([
     'uAlbedo',
@@ -517,7 +518,7 @@ doubleSided = false) {
                                         dstFactor: 'one-minus-src-alpha',
                                         operation: 'add',
                                     },
-                                    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                                    alpha: SCENE_ALPHA_COVERS,
                                 },
                             }
                             : { format: cache.format }),

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

@@ -3,6 +3,7 @@ import { LINE_BINDINGS, LINE_FRAG_WGSL, LINE_VERT_WGSL, } from '../../shaders/ge
 import { buildSegmentQuads } from '../../segmentQuads.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The line pass: a polyline with a real width, four vertices a segment.
  *
@@ -179,7 +180,7 @@ additive = false) {
                                 dstFactor: 'one-minus-src-alpha',
                                 operation: 'add',
                             },
-                            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                            alpha: SCENE_ALPHA_COVERS,
                         },
                 },
             ],

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

@@ -1,6 +1,7 @@
 import { PANEL_BINDINGS, PANEL_FRAG_WGSL, PANEL_VERT_WGSL, } from '../../shaders/generated/panel.wgsl.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The panel pass: two triangles in screen space, one colour, one alpha.
  *
@@ -97,7 +98,7 @@ export function panelPipeline(cache, device, layout) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

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

@@ -4,6 +4,7 @@ import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The particle pass: a crossed pair of quads per live particle, rebuilt every frame.
  *
@@ -269,7 +270,7 @@ export function particlePipeline(cache, device, layout, material, blend) {
                                 dstFactor: 'one-minus-src-alpha',
                                 operation: 'add',
                             },
-                            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                            alpha: SCENE_ALPHA_COVERS,
                         },
                 },
             ],

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

@@ -6,6 +6,7 @@ import { FIRE_BINDINGS } from '../../shaders/generated/fire.wgsl.js';
 import { SMOKE_BINDINGS } from '../../shaders/generated/smoke.wgsl.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The plume pass: crossed quads per plume, displaced and faded in the shaders.
  *
@@ -179,7 +180,7 @@ function blendState(blend) {
         }
         : {
             color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
         };
 }
 /**

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

@@ -156,8 +156,10 @@ export declare const OIT_COMPOSITE_BLEND: GPUBlendState;
  * exactly the integral — and the composite therefore never samples the colour it is modifying,
  * which is the read both backends are entitled to call undefined.
  *
- * Alpha is `(zero, one)`: the frame's own alpha is not the medium's to spend. The scene target
- * carries it to the canvas, and a medium that wrote there would make a foggy frame translucent.
+ * Alpha is the transmittance again, `share * a`: the scene's alpha is how much of the pixel is
+ * still the opaque surface, which is what the composite lets ambient occlusion darken, and a
+ * medium thick enough to hide a corner hides its occlusion too (`sceneCoverage.ts`). It reaches
+ * no canvas: both are opaque, and the composite writes 1.
  */
 export declare const MEDIUM_TRANSMIT_BLEND: GPUBlendState;
 export declare const DECAL_MULTIPLY_BLEND: GPUBlendState;
@@ -170,6 +172,14 @@ export declare const DECAL_MULTIPLY_BLEND: GPUBlendState;
  * sample the colour it is compositing onto.
  */
 export declare const PREMULTIPLIED_OVER_BLEND: GPUBlendState;
+/**
+ * The same `over` for the resolve that lands a reflection on the scene, keeping the scene's alpha.
+ *
+ * A reflection is a layer of the surface it is seen in, so the surface's share of the pixel is
+ * unchanged (`sceneCoverage.ts`). The trace keeps `PREMULTIPLIED_OVER_BLEND`, because its target is
+ * the reflection's own and its alpha is the coverage this resolve reads.
+ */
+export declare const REFLECTION_OVER_BLEND: GPUBlendState;
 export declare const ADDITIVE_BLEND: GPUBlendState;
 /** A fullscreen pass over one or more inputs, writing to one colour target. */
 export declare function postPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, fragment: string, format: GPUTextureFormat, blend?: GPUBlendState): GPURenderPipeline;