@driftengine/core 4.8.1 → 4.8.3

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

@@ -3,6 +3,7 @@ import { WATER_BINDINGS, WATER_FRAG_WGSL, WATER_VERT_WGSL, } from '../../shaders
 import { PATCH_RESOLUTION, buildUnitSheet, buildWaterGrid } from '../../waterGrid.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The water pass: two sheets and a patch, displaced by a wave field in the vertex stage.
  *
@@ -148,7 +149,7 @@ export function waterPipeline(cache, device, layout) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

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

@@ -3,6 +3,7 @@ import { WINDSTREAKS_BINDINGS, WIND_STREAK_FRAG_WGSL, WIND_STREAK_VERT_WGSL, } f
 import { buildWindStreakLattice } from '../../windStreakDraw.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The wind-streak pass: a lattice of debris that follows the camera and wraps.
  *
@@ -141,7 +142,7 @@ export function windStreakPipeline(cache, device, layout) {
                             dstFactor: 'one-minus-src-alpha',
                             operation: 'add',
                         },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

package/dist/render/boltBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { BOLT_FRAG, BOLT_VERT } from './shaders/bolt.js';
 import { buildSegmentQuads, expandBoltSegments } from './segmentQuads.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * One draw call for a pool of electrical arcs.
  *
@@ -80,7 +81,7 @@ export class BoltBatch {
         if (segmentCount === 0)
             return;
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/causticsRenderer.js

@@ -3,6 +3,7 @@ import { CAUSTICS_FRAG, CAUSTICS_VERT } from './shaders/caustics.js';
 import { bindAtmosphere } from './atmosphere.js';
 import { buildSheets } from './surfaceSheet.js';
 import { seaStateForWind } from './seaState.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * How far from the water the effect has died out.
  *
@@ -97,7 +98,7 @@ export class CausticsRenderer {
         gl.uniform1f(u['uWaveGain'] ?? null, sea.steepness);
         bindAtmosphere(gl, u, atmosphere, camera.position[1] ?? 0, underwaterEnabled);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE, gl.ONE);
+        blendKeeping(gl, gl.ONE, gl.ONE);
         /*
          * No depth write, but depth *testing* stays on: the sheet sits a couple of
          * centimetres under the surface it lights, so geometry in front of it — the

package/dist/render/cutoutCaster.d.ts

@@ -12,12 +12,14 @@
  * reads it and binds before it asks again.
  */
 import type { SurfaceMaterial } from './surfaceTexture.ts';
-/** A cutout caster's texture, its cutoff and its UV scale. */
+/** A cutout caster's texture, its cutoff and its UV scale and offset. */
 export interface CutoutCaster<Texture> {
     readonly albedo: Texture;
     readonly cutoff: number;
     readonly u: number;
     readonly v: number;
+    readonly uOffset: number;
+    readonly vOffset: number;
 }
 /** The cutout `material` casts, or null for an ordinary caster. */
 export declare function cutoutOf<Texture>(material: SurfaceMaterial<Texture> | null | undefined): CutoutCaster<Texture> | null;

package/dist/render/cutoutCaster.js

@@ -3,6 +3,8 @@ const answer = {
     cutoff: 0,
     u: 1,
     v: 1,
+    uOffset: 0,
+    vOffset: 0,
 };
 /** The cutout `material` casts, or null for an ordinary caster. */
 export function cutoutOf(material) {
@@ -16,5 +18,7 @@ export function cutoutOf(material) {
     answer.cutoff = cutoff;
     answer.u = material.uScale ?? 1;
     answer.v = material.vScale ?? 1;
+    answer.uOffset = material.uOffset ?? 0;
+    answer.vOffset = material.vOffset ?? 0;
     return answer;
 }

package/dist/render/decalPass.js

@@ -4,6 +4,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { DECAL_PROJECT_FRAG } from './shaders/decalProject.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
  *
@@ -54,7 +55,7 @@ export class DecalPass {
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ZERO, gl.SRC_COLOR);
+        blendKeeping(gl, gl.ZERO, gl.SRC_COLOR);
         gl.enable(gl.SCISSOR_TEST);
         /* Unit 0, chosen rather than inherited: `bindTexture` binds to whichever unit is active, and
            the renderer leaves that wherever its last pass finished. `OitPass` records what leaving it

package/dist/render/globalMediumPass.js

@@ -4,6 +4,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
 import { MEDIUM_FRAG, MEDIUM_UPSAMPLE_FRAG } from './shaders/globalMedium.js';
+import { blendCovering, blendTransmitting } from './sceneCoverage.js';
 /**
  * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
  *
@@ -200,7 +201,7 @@ export class GlobalMediumPass {
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFuncSeparate(gl.ONE, gl.SRC_ALPHA, gl.ZERO, gl.ONE);
+        blendTransmitting(gl, gl.ONE, gl.SRC_ALPHA);
         gl.useProgram(this.upsample);
         gl.bindVertexArray(this.vao);
         gl.activeTexture(gl.TEXTURE0);
@@ -220,7 +221,7 @@ export class GlobalMediumPass {
         gl.activeTexture(gl.TEXTURE0);
         gl.bindTexture(gl.TEXTURE_2D, null);
         /* Back to the blend every other pass in this renderer assumes it inherits. */
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.disable(gl.BLEND);
         gl.depthMask(true);
         gl.enable(gl.DEPTH_TEST);

package/dist/render/lineBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { LINE_FRAG, LINE_VERT } from './shaders/line.js';
 import { buildSegmentQuads, expandLineSegments } from './segmentQuads.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /**
  * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
  * curve, anything that is a stroke rather than a surface.
@@ -96,7 +97,10 @@ export class LineBatch {
         if (segmentCount === 0)
             return;
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, additive ? gl.ONE : gl.ONE_MINUS_SRC_ALPHA);
+        if (additive)
+            blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
+        else
+            blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         // The quad billboards toward the view direction the same way a bolt's does — see
         // `line.ts`'s own `cross(dir, view)` — so its winding can flip with the camera exactly

package/dist/render/mapsWithoutUvs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Saying, once a mesh, that a material's maps cannot be read on it.
+ *
+ * **A mesh with no texture coordinates reads one constant coordinate**, so every map bound to it
+ * samples a single texel: an emissive map makes nothing glow, a normal map tilts nothing, and the
+ * frame is identical pixel for pixel with and without the material's images. Found when an example's
+ * burning logs never glowed — `MeshBuilder` writes no coordinates unless `build({ planarUvs: true })`
+ * asks — and nothing said why. One decision for both backends, each calling it from its draw.
+ *
+ * Once per mesh, held weakly: a mesh drawn every frame is said once, and a disposed one is
+ * forgotten. **What it gives up** is a material shared between a textured mesh and an untextured one
+ * on purpose, which is said once for the untextured one and is then quiet.
+ */
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+/**
+ * Whether a material binds a map that is a picture: albedo, normal or emissive.
+ *
+ * **Not ORM**, because a one-colour ORM map is how a draw sets a constant roughness and metalness,
+ * and read at one texel it is exactly that constant — the materials example draws its spheres so.
+ * The three counted here are pictures nobody binds to be read at one point.
+ */
+export declare function materialHasMaps(material: SurfaceMaterial<unknown> | null): boolean;
+/** Warn the first time `mesh`, which has no coordinates, is drawn with a picture map bound. */
+export declare function noteMapsWithoutUvs(mesh: object, hasUvs: boolean, materialHasMaps: boolean): void;

package/dist/render/mapsWithoutUvs.js

@@ -0,0 +1,24 @@
+const told = new WeakSet();
+/**
+ * Whether a material binds a map that is a picture: albedo, normal or emissive.
+ *
+ * **Not ORM**, because a one-colour ORM map is how a draw sets a constant roughness and metalness,
+ * and read at one texel it is exactly that constant — the materials example draws its spheres so.
+ * The three counted here are pictures nobody binds to be read at one point.
+ */
+export function materialHasMaps(material) {
+    if (material === null)
+        return false;
+    return ((material.albedo ?? null) !== null ||
+        (material.normal ?? null) !== null ||
+        (material.emissive ?? null) !== null);
+}
+/** Warn the first time `mesh`, which has no coordinates, is drawn with a picture map bound. */
+export function noteMapsWithoutUvs(mesh, hasUvs, materialHasMaps) {
+    if (hasUvs || !materialHasMaps || told.has(mesh))
+        return;
+    told.add(mesh);
+    console.warn('[driftengine] a mesh with no texture coordinates is drawn with an albedo, normal or emissive ' +
+        'map, which it cannot read: every map samples one texel. Give the mesh `uvs` — ' +
+        '`MeshBuilder.build({ planarUvs: true })` writes them — or draw it without the maps.');
+}

package/dist/render/mesh.d.ts

@@ -56,6 +56,8 @@ export declare class Mesh {
     readonly bounds: Bounds;
     /** Whether this mesh carries a rig, which decides which flat program draws it. */
     readonly isSkinned: boolean;
+    /** Whether it has texture coordinates, without which a material's maps read one texel. */
+    readonly hasUvs: boolean;
     /**
      * This mesh's morph deltas, or null for geometry that does not deform.
      *

package/dist/render/mesh.js

@@ -123,6 +123,8 @@ export class Mesh {
     bounds = createBounds();
     /** Whether this mesh carries a rig, which decides which flat program draws it. */
     isSkinned;
+    /** Whether it has texture coordinates, without which a material's maps read one texel. */
+    hasUvs;
     /**
      * This mesh's morph deltas, or null for geometry that does not deform.
      *
@@ -171,6 +173,7 @@ export class Mesh {
     constructor(gl, data, dynamic = false, spread = false) {
         validateMeshData(data);
         this.spread = spread;
+        this.hasUvs = data.uvs !== undefined;
         boundsOfPositions(data.positions, this.bounds);
         this.positionFloats = data.positions.length;
         const vao = gl.createVertexArray();

package/dist/render/oitPass.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
 import { OIT_RESOLVE_FRAG } from './shaders/oitResolve.js';
+import { blendTransmitting } from './sceneCoverage.js';
 /**
  * Order-independent transparency on WebGL2: two targets, two passes over the same geometry, and a
  * resolve.
@@ -163,7 +164,7 @@ export class OitPass {
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
+        blendTransmitting(gl, gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
         gl.useProgram(this.program);
         gl.activeTexture(gl.TEXTURE0);
         gl.bindTexture(gl.TEXTURE_2D, this.accum);

package/dist/render/particleBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { particleShaders } from './particleMaterial.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /** Corners of one blade, as a triangle-strip-friendly quad. */
 const CORNERS = [
     [-1, -1],
@@ -138,9 +139,9 @@ export class ParticleBatch {
             return;
         gl.enable(gl.BLEND);
         if (this.blend === 'additive')
-            gl.blendFunc(gl.SRC_ALPHA, 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);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/particlePool.d.ts

@@ -19,7 +19,11 @@ import type { Vec3 } from '../math/color.ts';
 export interface ParticleInstances {
     /** World position, three floats each. */
     positions: Float32Array;
-    /** Metres across, and radians of roll about the particle's own axis. */
+    /**
+     * Metres from the centre to an edge, a half-width: the quad spans twice this. Then radians of
+     * roll about the particle's own axis. This said metres across until 4.8.3, and a caller who took
+     * it at its word drew every particle twice as wide as meant.
+     */
     sizes: Float32Array;
     spins: Float32Array;
     /** Linear colour, three floats each. */
@@ -54,7 +58,7 @@ export interface ParticlePoolOptions {
     capacity: number;
     /** Seconds a particle lives. */
     lifeSec: number;
-    /** Size at birth and at death, metres. */
+    /** Size at birth and at death: metres from the centre to an edge, so the quad is twice as wide. */
     sizeStart: number;
     sizeEnd: number;
     /** Colour at birth and at death. */
@@ -98,6 +102,15 @@ export declare class ParticlePool {
      * together.
      */
     private readonly seedOf;
+    /**
+     * Where each slot's particle sits in the drawn streams, or -1 where it sits nowhere.
+     *
+     * **What lets `emit` draw a particle the frame it is born.** The streams are compacted, so a
+     * slot's entry is wherever `update` last put it; an emit into a slot that has one overwrites
+     * that entry, and an emit into one that has none appends. Without it a new particle waited for
+     * the next `update` to be drawn at all.
+     */
+    private readonly drawnAt;
     private next;
     constructor(options: ParticlePoolOptions);
     /** How many particles are alive. */
@@ -119,6 +132,12 @@ export declare class ParticlePool {
      * particles cost nothing but the loop iteration.
      */
     update(dt: number): void;
+    /**
+     * One particle's entry in both drawn streams, at `t` of its life: what `update` writes for every
+     * live particle and `emit` for a new one, so the two cannot disagree about what a particle looks
+     * like.
+     */
+    private writeDrawn;
     /** Drop everything, for a respawn or a scene change. */
     clear(): void;
 }

package/dist/render/particlePool.js

@@ -38,6 +38,15 @@ export class ParticlePool {
      * together.
      */
     seedOf;
+    /**
+     * Where each slot's particle sits in the drawn streams, or -1 where it sits nowhere.
+     *
+     * **What lets `emit` draw a particle the frame it is born.** The streams are compacted, so a
+     * slot's entry is wherever `update` last put it; an emit into a slot that has one overwrites
+     * that entry, and an emit into one that has none appends. Without it a new particle waited for
+     * the next `update` to be drawn at all.
+     */
+    drawnAt;
     next = 0;
     constructor(options) {
         this.options = options;
@@ -60,6 +69,7 @@ export class ParticlePool {
         this.spin = new Float32Array(capacity);
         this.scale = new Float32Array(capacity).fill(1);
         this.seedOf = new Float32Array(capacity);
+        this.drawnAt = new Int32Array(capacity).fill(-1);
     }
     /** How many particles are alive. */
     get live() {
@@ -95,6 +105,18 @@ export class ParticlePool {
         this.spin[i] = (hash - Math.floor(hash)) * Math.PI * 2;
         this.scale[i] = sizeScale;
         this.seedOf[i] = seed;
+        /*
+         * Drawn now, at birth, rather than at the next `update`: into the entry this slot already
+         * has when it is taking over a particle that was drawn, and onto the end otherwise.
+         */
+        const held = this.drawnAt[i];
+        const at = held >= 0 ? held : this.particles.count;
+        this.writeDrawn(i, at, 0, x, y, z, vx, vy, vz);
+        if (held < 0) {
+            this.drawnAt[i] = at;
+            this.instances.count = at + 1;
+            this.particles.count = at + 1;
+        }
     }
     /**
      * Advance every particle and rebuild the instance buffer.
@@ -108,12 +130,15 @@ export class ParticlePool {
         let count = 0;
         for (let i = 0; i < this.age.length; i++) {
             const age = this.age[i];
-            if (age === Infinity)
+            if (age === Infinity) {
+                this.drawnAt[i] = -1;
                 continue;
+            }
             const life = this.life[i];
             const next = age + dt;
             if (next >= life) {
                 this.age[i] = Infinity;
+                this.drawnAt[i] = -1;
                 continue;
             }
             this.age[i] = next;
@@ -131,50 +156,60 @@ export class ParticlePool {
             this.x[i] = px;
             this.y[i] = py;
             this.z[i] = pz;
-            const t = next / life;
-            const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * this.scale[i];
-            const r = o.colorStart[0] + (o.colorEnd[0] - o.colorStart[0]) * t;
-            const g = o.colorStart[1] + (o.colorEnd[1] - o.colorStart[1]) * t;
-            const b = o.colorStart[2] + (o.colorEnd[2] - o.colorStart[2]) * t;
-            /*
-             * Colour carries the fade rather than an alpha channel: the instanced
-             * path multiplies a tint into the base mesh and has no per-instance
-             * opacity, and for an additive puff darkening to nothing *is* fading out.
-             * It also means the effect needs no blend-state change.
-             */
-            const fade = 1 - t * t;
-            writeInstance(this.instances, count, px, py, pz, size, this.spin[i], r * fade, g * fade, b * fade, 0, 0, 0);
-            /*
-             * The same particle for a material that has a real opacity channel. Colour
-             * is written *unfaded* here, because dimming it is the scatter path's
-             * workaround and doing both would fade twice — a puff that vanished at half
-             * its life while still occluding what was behind it.
-             */
-            const p = this.particles;
-            const alphaStart = o.alphaStart ?? 1;
-            const alphaEnd = o.alphaEnd ?? 0;
-            p.positions[count * 3] = px;
-            p.positions[count * 3 + 1] = py;
-            p.positions[count * 3 + 2] = pz;
-            p.sizes[count] = size;
-            p.spins[count] = this.spin[i];
-            p.colors[count * 3] = r;
-            p.colors[count * 3 + 1] = g;
-            p.colors[count * 3 + 2] = b;
-            p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
-            p.ages[count] = t;
-            p.seeds[count] = this.seedOf[i];
-            p.velocities[count * 3] = vx;
-            p.velocities[count * 3 + 1] = vy;
-            p.velocities[count * 3 + 2] = vz;
+            this.drawnAt[i] = count;
+            this.writeDrawn(i, count, next / life, px, py, pz, vx, vy, vz);
             count++;
         }
         this.instances.count = count;
         this.particles.count = count;
     }
+    /**
+     * One particle's entry in both drawn streams, at `t` of its life: what `update` writes for every
+     * live particle and `emit` for a new one, so the two cannot disagree about what a particle looks
+     * like.
+     */
+    writeDrawn(i, count, t, px, py, pz, vx, vy, vz) {
+        const o = this.options;
+        const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * this.scale[i];
+        const r = o.colorStart[0] + (o.colorEnd[0] - o.colorStart[0]) * t;
+        const g = o.colorStart[1] + (o.colorEnd[1] - o.colorStart[1]) * t;
+        const b = o.colorStart[2] + (o.colorEnd[2] - o.colorStart[2]) * t;
+        /*
+         * Colour carries the fade rather than an alpha channel: the instanced
+         * path multiplies a tint into the base mesh and has no per-instance
+         * opacity, and for an additive puff darkening to nothing *is* fading out.
+         * It also means the effect needs no blend-state change.
+         */
+        const fade = 1 - t * t;
+        writeInstance(this.instances, count, px, py, pz, size, this.spin[i], r * fade, g * fade, b * fade, 0, 0, 0);
+        /*
+         * The same particle for a material that has a real opacity channel. Colour
+         * is written *unfaded* here, because dimming it is the scatter path's
+         * workaround and doing both would fade twice — a puff that vanished at half
+         * its life while still occluding what was behind it.
+         */
+        const p = this.particles;
+        const alphaStart = o.alphaStart ?? 1;
+        const alphaEnd = o.alphaEnd ?? 0;
+        p.positions[count * 3] = px;
+        p.positions[count * 3 + 1] = py;
+        p.positions[count * 3 + 2] = pz;
+        p.sizes[count] = size;
+        p.spins[count] = this.spin[i];
+        p.colors[count * 3] = r;
+        p.colors[count * 3 + 1] = g;
+        p.colors[count * 3 + 2] = b;
+        p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
+        p.ages[count] = t;
+        p.seeds[count] = this.seedOf[i];
+        p.velocities[count * 3] = vx;
+        p.velocities[count * 3 + 1] = vy;
+        p.velocities[count * 3 + 2] = vz;
+    }
     /** Drop everything, for a respawn or a scene change. */
     clear() {
         this.age.fill(Infinity);
+        this.drawnAt.fill(-1);
         this.instances.count = 0;
         this.particles.count = 0;
         this.next = 0;

package/dist/render/pass.d.ts

@@ -122,6 +122,18 @@ export type PassContext = {
     readonly pass: GPURenderPassEncoder;
     /** The frame's jitter, the same array `PrepareContext.jitter` held. */
     readonly jitter: Float32Array;
+    /**
+     * The colour format, depth format and sample count of the pass this draw lands in, which a
+     * pipeline set on it must match exactly.
+     *
+     * **Not always the device's.** `PassDevice` says what the frame is; a pass drawn after
+     * `endFrame` lands on the canvas, at the canvas's format and one sample, where the frame is
+     * the scene target at the scene's samples. A pass that is drawn in both places keeps a
+     * pipeline for each and chooses here; one built only from the device is refused by the other.
+     */
+    readonly format: GPUTextureFormat;
+    readonly depthFormat: GPUTextureFormat;
+    readonly samples: number;
 });
 /**
  * What a pass is handed once a frame, before the frame's own target exists.

package/dist/render/plumeRenderer.js

@@ -3,6 +3,7 @@ import { compileProgram, uniformLocations } from './shader.js';
 import { bindAtmosphere } from './atmosphere.js';
 import { plumeShaders } from './plumeMaterial.js';
 import { buildPlumeGeometry } from './plumeGeometry.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /* The shared count, so both backends step a plume's vertices the same way. */
 const VERTS_PER_PLUME = PLUME_VERTS;
 export class PlumeRenderer {
@@ -123,9 +124,9 @@ export class PlumeRenderer {
         bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
         gl.enable(gl.BLEND);
         if (this.blend === 'additive')
-            gl.blendFunc(gl.SRC_ALPHA, 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);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/renderQuality.d.ts

@@ -14,8 +14,14 @@
  * `aces` adds filmic tone mapping before that, rolling highlights off instead of
  * clipping them flat. Together they are what three.js does by default, which is why a
  * world ported from it looks wrong until this exists.
+ *
+ * `shoulder` keeps sRGB's midtones exactly and eases only the highlights: past 0.8 the brightest
+ * channel rolls toward 1 and the other two are scaled with it, so an overbright red spark stays
+ * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
+ * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
+ * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
 /**
  * The three settings whose accepted values are a closed set, written as one.
  *
@@ -60,7 +66,8 @@ export interface RenderQuality {
      * chooses is a look rather than a standard — three.js uses 1/0.6 and says so. This
      * engine holds no opinion and takes the number from whoever is authoring the world, so
      * that matching another renderer, or simply preferring a different grade, is a setting
-     * rather than a patch. Ignored when `outputTransform` is not `aces`.
+     * rather than a patch. Scales into `aces` and into `shoulder`, the two curves; ignored by
+     * `none` and `srgb`, which have none.
      */
     readonly outputExposure: number;
     /**
@@ -185,12 +192,13 @@ export interface RenderQuality {
      * existed: a pane casts nothing at all.
      *
      * Nothing is allocated until a glass caster first reaches a shadow, so a scene with no glass pays
-     * no memory and no pass whatever this says. **The lit shader is the exception**: `'full'` and
-     * `'half'` compile the glass lookup into it, and a lookup that finds no glass and returns at its
-     * first line still costs the lit pass its registers — measured on the courtyard at night, 0.27 ms
-     * at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K. `'off'` compiles none of it, so a world
-     * that never casts through glass is that much faster for saying so. What would make `'full'` wrong
-     * is a phone budget with a lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
+     * no memory and no pass whatever this says. **Nor any shader, since 4.8.2**: the lit shader is
+     * built without the glass lookup and rebuilt with it when the first glass caster reaches a shadow.
+     * A lookup that finds no glass still cost the lit pass its registers — measured on the courtyard at
+     * night, 0.27 ms at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K — and from 4.5.0 to 4.8.1
+     * every scene paid it, glass or none: about 30% of the lit shader's instructions, which on a phone
+     * was the lit pass. `'off'` never rebuilds. What would make `'full'` wrong is a phone budget with a
+     * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
      */
     readonly glassShadows: GlassShadows;
     /** Horizontal world-space reach over which a directional shadow dissolves. */

package/dist/render/sceneCoverage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What a blended draw into the scene does to its alpha, which holds how much of each pixel is still
+ * the opaque surface — the share ambient occlusion is allowed to darken.
+ *
+ * **Occlusion is applied in the composite, from the depth the opaque world left**, 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 from a game as walls and two figures
+ * standing behind a cloud showing through it as outlines, and nothing at all with occlusion off.
+ *
+ * So the scene's alpha is a running share. The frame clears it to 1 and an opaque draw writes 1,
+ * which is the whole of the surface; then each draw blended in front of it says which of three
+ * things it is, and the composite darkens `share` of the pixel and leaves the rest:
+ *
+ * - **It covers**: glass, smoke, water, a line, text in the world, a panel. The share falls by what
+ *   the draw lets through, `share * (1 - a)`.
+ * - **It transmits**: the medium, the order-independent composite. Its alpha already *is* what gets
+ *   through, `share * a`.
+ * - **It keeps**: light added to the surface or a layer of the surface itself — caustics, a light
+ *   volume, a bolt, a wet film, a decal, a reflection. The share is unchanged.
+ *
+ * **What it gives up** is added light in front of an occluded corner: a glow or a spark adds to the
+ * pixel and keeps the share, so the composite darkens what it added along with the surface — which
+ * is how every blended draw behaved before this, and one multiply cannot tell the two apart. **What
+ * would make it wrong** is an opaque pass writing an alpha below 1: its surface would then take less
+ * occlusion than it should, which is the safe direction, and is the lit shader's own case at a
+ * cutout's edge or under a per-vertex alpha lane.
+ *
+ * **It survives the temporal passes.** A temporal resolve passes the frame's alpha through, since
+ * it is a fact about this frame and takes no history; a reconstruction reads it from the scene it
+ * rebuilt into the picture it shows, and the blended draws that land after it cover that picture.
+ *
+ * **One pipeline does not take part**: the GPU-driven pass blends its own surfaces into a target
+ * whose alpha is the mask its blit reads to tell a drawn pixel from an undrawn one, and that blit
+ * writes the share back to 1. Its panes still take the occlusion of what they cover. What would
+ * close it is a channel for that mask other than alpha.
+ *
+ * A contributed pass drawing something blended into the scene states the same thing for its own
+ * pipeline with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS`.
+ */
+/** A blended draw that covers the surface by its alpha: `share * (1 - a)`. */
+export declare const SCENE_ALPHA_COVERS: GPUBlendComponent;
+/** A draw whose alpha is what gets through it, a transmittance or a revealage: `share * a`. */
+export declare const SCENE_ALPHA_TRANSMITS: GPUBlendComponent;
+/** Light added to the surface, or a layer of it: the share unchanged. */
+export declare const SCENE_ALPHA_KEEPS: GPUBlendComponent;
+/**
+ * The same three on WebGL2, as the alpha half of `blendFuncSeparate` beside the colour half a
+ * caller already had. `src` and `dst` are the colour factors.
+ */
+export declare function blendCovering(gl: WebGL2RenderingContext, src: number, dst: number): void;
+/** `SCENE_ALPHA_TRANSMITS` on WebGL2, beside the colour factors `src` and `dst`. */
+export declare function blendTransmitting(gl: WebGL2RenderingContext, src: number, dst: number): void;
+/** `SCENE_ALPHA_KEEPS` on WebGL2, beside the colour factors `src` and `dst`. */
+export declare function blendKeeping(gl: WebGL2RenderingContext, src: number, dst: number): void;