@driftengine/core 4.8.2 → 4.8.3

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

@@ -9,6 +9,7 @@ import { SSRTRACE_BINDINGS as SSR_BINDINGS, SSR_TRACE_FRAG_WGSL, } from '../../s
 import { SSRRESOLVE_BINDINGS as SSR_RESOLVE_BINDINGS, SSR_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/ssrResolve.wgsl.js';
 import { GLOBALMEDIUM_BINDINGS as MEDIUM_BINDINGS, MEDIUM_FRAG_WGSL, MEDIUM_UPSAMPLE_FRAG_WGSL, } from '../../shaders/generated/globalMedium.wgsl.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS } from '../../sceneCoverage.js';
 /**
  * The composite: everything that happens to the frame after the world is drawn.
  *
@@ -197,7 +198,7 @@ export function createPostStageLayout(device, uniformBinding, uniformSize, textu
  */
 export const OIT_COMPOSITE_BLEND = {
     color: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
-    alpha: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
+    alpha: SCENE_ALPHA_TRANSMITS,
 };
 /**
  * What a drawn decal does to the pixel under it: `dst * src`.
@@ -215,16 +216,18 @@ export const OIT_COMPOSITE_BLEND = {
  * 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 const MEDIUM_TRANSMIT_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'src-alpha', operation: 'add' },
-    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+    alpha: SCENE_ALPHA_TRANSMITS,
 };
 export const DECAL_MULTIPLY_BLEND = {
     color: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
-    alpha: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
+    alpha: SCENE_ALPHA_KEEPS,
 };
 /**
  * `over`, against colour a pass has already multiplied by its own coverage.
@@ -238,6 +241,17 @@ export const PREMULTIPLIED_OVER_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
     alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
 };
+/**
+ * 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 const REFLECTION_OVER_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: SCENE_ALPHA_KEEPS,
+};
 export const ADDITIVE_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
     alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },

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

@@ -1113,6 +1113,13 @@ export declare class WebGPURenderer implements RendererApi {
     private blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
     private readonly uvScale;
+    /** Where the texture starts, after the scale. Per draw, beside `uvScale`. */
+    private readonly uvOffset;
+    /**
+     * 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;
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     private materialDoubleSided;
     /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
@@ -1198,6 +1205,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
     setEnvironmentGain(gain: number): void;
     setSurfaceGrain(amount: number): void;
+    /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
+    setSurfaceFog(enabled: boolean): void;
     /**
      * How much of the surfaces drawn next survives a screen-door dither. See `renderer.ts`.
      *
@@ -1816,7 +1825,7 @@ export declare class WebGPURenderer implements RendererApi {
      */
     /** The cutout bind group for `texture` in the open layer, built the first time it casts there. */
     private cutoutGroup;
-    /** The cutoff and UV scale into a cutout draw's slot, at the offsets its own variant declares. */
+    /** The cutoff and UV scale and offset into a cutout draw's slot, at its own variant's offsets. */
     private writeCutout;
     private shadowGroup;
     /**

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

@@ -61,7 +61,7 @@ import { ExposurePass } from './exposurePass.js';
 import { AO_STORE } from '../../shaders/ambientOcclusion.js';
 import { clampAutoExposure } from '../../shaders/exposure.js';
 import { clampLocalExposure } from '../../shaders/localExposure.js';
-import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, postPipelineTargets, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
+import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, postPipelineTargets, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, REFLECTION_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
 import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from '../../colourGrade.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE, clampGrain, clampVignette, grainSeed, } from '../../shaders/filmLook.js';
 import { createProbeMipBindGroupLayout, createProbePrefilterBindGroupLayout, PREFILTER_UNIFORM_OFFSETS, probeLevels, probeMipPipeline, probePrefilterPipeline, PROBE_FACES, PROBE_FACE_BASIS, PROBE_FAR_M, PROBE_FOV_DEG, PROBE_MIP_UNIFORM_SIZE, PROBE_NEAR_M, } from './probePass.js';
@@ -100,7 +100,7 @@ import { LIGHT_VOLUME_VERT_FIELDS, LIGHT_VOLUME_VERT_SIZE, createLightVolumeBind
 import { aimReflection, createGpuReflection } from './reflectionPass.js';
 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 { DYNAMIC_ALIGNMENT as DYNAMIC_UNIFORM_ALIGNMENT, UniformRing } from './uniformRing.js';
 import { DecalQueue, MAX_DRAWN_DECALS } from '../../decalQueue.js';
 import { DistanceFieldScene } from '../../gi/fieldScene.js';
@@ -2131,6 +2131,13 @@ export class WebGPURenderer {
     blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
     uvScale = new Float32Array([1, 1]);
+    /** Where the texture starts, after the scale. Per draw, beside `uvScale`. */
+    uvOffset = new Float32Array([0, 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;
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     materialDoubleSided = false;
     /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
@@ -2260,6 +2267,8 @@ export class WebGPURenderer {
         const albedo = material?.albedo ?? null;
         this.uvScale[0] = material?.uScale ?? 1;
         this.uvScale[1] = material?.vScale ?? 1;
+        this.uvOffset[0] = material?.uOffset ?? 0;
+        this.uvOffset[1] = material?.vOffset ?? 0;
         this.materialDoubleSided = material?.doubleSided === true;
         this.materialHasMaps = materialHasMaps(material);
         const normal = (material?.normal ?? null);
@@ -2408,6 +2417,13 @@ export class WebGPURenderer {
             f[this.materialField('uGrain')] = Math.min(1, Math.max(0, amount));
         });
     }
+    /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
+    setSurfaceFog(enabled) {
+        this.surfaceFog = enabled ? FOG_RECEDE : FOG_OFF;
+        this.material((_f, i) => {
+            i[this.materialField('uFogEnabled')] = this.surfaceFog;
+        });
+    }
     /**
      * How much of the surfaces drawn next survives a screen-door dither. See `renderer.ts`.
      *
@@ -4363,10 +4379,12 @@ export class WebGPURenderer {
         groups.set(texture, group);
         return group;
     }
-    /** The cutoff and UV scale into a cutout draw's slot, at the offsets its own variant declares. */
+    /** The cutoff and UV scale and offset into a cutout draw's slot, at its own variant's offsets. */
     writeCutout(slot, cutout, fields) {
         this.shadowDraws.writeFloat(slot, fields.uUvScale.offset, cutout.u);
         this.shadowDraws.writeFloat(slot, fields.uUvScale.offset + 4, cutout.v);
+        this.shadowDraws.writeFloat(slot, fields.uUvOffset.offset, cutout.uOffset);
+        this.shadowDraws.writeFloat(slot, fields.uUvOffset.offset + 4, cutout.vOffset);
         this.shadowDraws.writeFloat(slot, fields.uAlphaCutout.offset, cutout.cutoff);
     }
     shadowGroup() {
@@ -6248,7 +6266,8 @@ export class WebGPURenderer {
          * these per draw through the material block, the same shape `uOpacity` already uses.
          */
         i[at('uLightingEnabled')] = 1;
-        i[at('uFogEnabled')] = 1;
+        i[at('uFogEnabled')] = FOG_RECEDE;
+        this.surfaceFog = FOG_RECEDE;
         i[at('uAlbedoEnabled')] = 0;
         this.materialHasMaps = false;
         /*
@@ -6666,6 +6685,8 @@ export class WebGPURenderer {
         this.bindGroup = this.blankAlbedoBindGroup;
         this.uvScale[0] = 1;
         this.uvScale[1] = 1;
+        this.uvOffset[0] = 0;
+        this.uvOffset[1] = 0;
     }
     /**
      * The slot the next draw's material lives in, taking a new one when something dirtied it.
@@ -6744,7 +6765,10 @@ export class WebGPURenderer {
         if (this.tracksMotionNow())
             this.recordDrawMotion(mesh, model, previousModel);
         noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
-        this.submitMesh(mesh, model, tint, 1, false, { depthLayer });
+        /* An opaque draw meets the medium as the dial says: `submitMesh` reads an absent `fog` as
+           true, which is a translucent draw's default and would put every opaque draw back in the fog
+           `setSurfaceFog(false)` took it out of. */
+        this.submitMesh(mesh, model, tint, 1, false, { depthLayer, fog: this.surfaceFog !== FOG_OFF });
     }
     /**
      * Draw a mesh that lets the world through, at `opacity`.
@@ -6894,6 +6918,7 @@ export class WebGPURenderer {
         /* The material's repeats, not a constant: geometry authored in metres is textured at
            whatever density the material asks for without rebuilding it. */
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvScale.offset, this.uvScale);
+        this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvOffset.offset, this.uvOffset);
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uLightViewProj.offset, this.lightViewProj);
         /*
          * Whether this mesh's tangent frame is real. WebGPU has no disabled attribute, so location 10
@@ -6926,7 +6951,7 @@ export class WebGPURenderer {
         /* Added light fades in the medium rather than receding into it. See `drawFog.ts`. */
         const fog = fogModeOf(options.fog ?? true, blend && options.additive === true);
         const toneMapped = options.toneMapped ?? true;
-        const unlitOrUnfogged = !lit || fog !== FOG_RECEDE;
+        const unlitOrUnfogged = !lit || fog !== this.surfaceFog;
         if (unlitOrUnfogged) {
             if (!lit)
                 this.perFrameInts[this.materialField('uLightingEnabled')] = 0;
@@ -6949,7 +6974,7 @@ export class WebGPURenderer {
         const refracting = this.bindSeeThrough(options);
         /* Taken for itself when any of those 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();
         const base = mesh.key ?? 'flat:s0:u0';
@@ -7079,7 +7104,7 @@ export class WebGPURenderer {
         if (unlitOrUnfogged) {
             if (!lit)
                 this.perFrameInts[this.materialField('uLightingEnabled')] = 1;
-            this.perFrameInts[this.materialField('uFogEnabled')] = FOG_RECEDE;
+            this.perFrameInts[this.materialField('uFogEnabled')] = this.surfaceFog;
         }
         /* Back to off for every other draw in the frame, exactly as `uOpacity` is: this scratch is
            shared, so a strength left set is worn by everything drawn after it. */
@@ -7284,6 +7309,7 @@ export class WebGPURenderer {
         const lands = blend && options.reconstructed !== true && this.drawsLate();
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uViewProj.offset, lands ? this.correctedViewProj : this.viewProj);
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvScale.offset, this.uvScale);
+        this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvOffset.offset, this.uvOffset);
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uLightViewProj.offset, this.lightViewProj);
         this.perDraw.writeInt(slot, FLAT_VERT_FIELDS.uHasTangents.offset, mesh.hasTangents ? 1 : 0);
         const dimmed = opacity < 1;
@@ -7293,7 +7319,7 @@ export class WebGPURenderer {
         const lit = options.lit ?? true;
         const fog = fogModeOf(options.fog ?? true, blend && options.additive === true);
         const toneMapped = options.toneMapped ?? true;
-        const unlitOrUnfogged = !lit || fog !== FOG_RECEDE;
+        const unlitOrUnfogged = !lit || fog !== this.surfaceFog;
         if (unlitOrUnfogged) {
             if (!lit)
                 this.perFrameInts[this.materialField('uLightingEnabled')] = 0;
@@ -7306,7 +7332,7 @@ export class WebGPURenderer {
         const layer = Math.min(Math.max(Math.round(options.depthLayer ?? 0), 0), MAX_DEPTH_LAYER);
         /* A blended batch shows what is behind it — refraction or glass — as a single draw does. */
         const refracting = blend && this.bindSeeThrough(options);
-        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
         if (own)
             this.materials.dirty();
         const base = mesh.key ?? 'flat:s0:u0';
@@ -7375,7 +7401,7 @@ export class WebGPURenderer {
         }
         if (unlitOrUnfogged) {
             this.perFrameInts[this.materialField('uLightingEnabled')] = 1;
-            this.perFrameInts[this.materialField('uFogEnabled')] = FOG_RECEDE;
+            this.perFrameInts[this.materialField('uFogEnabled')] = this.surfaceFog;
         }
         if (!toneMapped) {
             this.perFrameInts[this.materialField('uOutputTransform')] = this.gradeCode();
@@ -9583,7 +9609,7 @@ export class WebGPURenderer {
             label: 'post.ssr.resolve',
             colorAttachments: [{ view: scene, loadOp: 'load', storeOp: 'store' }],
         });
-        resolve.setPipeline(postPipeline(this.pipelines, device, this.ssrResolveLayout, 'post.ssrResolve', SSR_RESOLVE_FRAG_WGSL, this.pipelines.format, PREMULTIPLIED_OVER_BLEND));
+        resolve.setPipeline(postPipeline(this.pipelines, device, this.ssrResolveLayout, 'post.ssrResolve', SSR_RESOLVE_FRAG_WGSL, this.pipelines.format, REFLECTION_OVER_BLEND));
         resolve.setBindGroup(0, resolveGroup);
         resolve.draw(3);
         resolve.end();

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

@@ -3,6 +3,7 @@ import { SDFTEXT_BINDINGS, SDF_TEXT_FRAG_WGSL, SDF_TEXT_VERT_WGSL, } from '../..
 import { DEPTH_FORMAT } from './flatPass.js';
 import { SdfTextLayout } from '../../sdfTextLayout.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The SDF text pass: a string as flat, textured quads, drawn into the scene.
  *
@@ -183,7 +184,7 @@ export function sdfTextPipeline(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/textPass.js

@@ -3,6 +3,7 @@ import { TEXT_BINDINGS, TEXT_FRAG_WGSL, TEXT_VERT_WGSL, } from '../../shaders/ge
 import { MAX_CELLS, TEXT_CUBE, TextLayout } from '../../textLayout.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The text pass: a string as instanced glyph cubes, drawn over the scene.
  *
@@ -174,7 +175,7 @@ export function textPipeline(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/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/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. */

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;
     /**

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;