@driftengine/core 4.11.0 → 4.11.1

package/CHANGELOG.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "4.11.1",
+    "date": "2026-10-10",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.layers` takes its mask from the ORM array or the vertex colour, sums layers, places them by the world, lays one by facing up, and lays a normal under them.",
+        "text": "`layers` covers more of the ways a layered surface is blended. `mask: 'orm'` reads the mask from the ORM array's layer past the material's layers, which leaves the model's slot to a lightmap's page, so a lightmapped surface blends its layers; `mask: 'vertex'` takes the weights from the vertex colour, which then tints nothing. `blend: 'sum'` mixes the base toward each layer times its weight, by the weights' sum held to 1, besides laying each over the ones before it. Under a `projection` the layers are placed by the world, each at its own repeats a metre, and `addMask` adds a mask placed the same way to one layer's weight. `facing` weighs one layer by how much the surface faces up, and `meshNormal` lays a normal map read at the mesh's own coordinates under the layers' blended normal. A triplanar projection lays layers on the horizontal plane, and says so once. On `demo/dev/layerFamilies.html` a mask carried by the ORM array draws exactly as the same mask as a map, keeps its layers under a lightmap's page, and every mode draws the same on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.transmissionColor` names the colour light through a thin surface takes, where it was always the surface's own.",
+        "text": "`transmissionColor`, linear, is the colour the light from behind a thin surface (`diffuseTransmission`) takes through it, in place of the surface's own colour: a printed banner glowing a flat red behind its print rather than lit through in the print's colours. Absent, the surface's colour, as before. It rides the glass tint's colour lanes, which no opaque material reads, and a pane drawn between two draws of the material puts it back. On `demo/dev/thinLight.html?color=0,0.4,1` a red banner lit from behind went from 163, 24, 19 to 16, 74, 171 under the sun with no red let through, the same to the pixel on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`setAmbientOcclusionFade(distance, radius)` fades ambient occlusion out with distance, so a sky dome or a far range is not shaded in rings.",
+        "text": "Ambient occlusion is whole up to `distance` metres from the eye and gone `radius` metres past it, held until changed; a negative distance, the default, fades nothing. Far off, the depth buffer's steps are metres apart and the estimate shaded them in bands across a sky dome or a mountain range; past the fade those pixels are left open and skip the estimate's walk. Bound in DriftScript as `drift/render`'s `occlusionFade`. On `demo/dev/aoFade.html` a ridge 3 km off went from 66,267 banded pixels to none, while the feet of the near boxes darkened exactly as before, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "A lightmapped instance fades by `setDitherOpacity` too: its opacity rides its page region in sixty-fourths, where it had none.",
+        "text": "A lightmapped batch carries its page regions in the lane `MeshInstances.alphas` would take, so its instances could not fade. Their opacity now travels as whole steps added to the region's U offset, 64 of them, the screen door's own resolution, and the vertex stage takes them back off. An opaque instance's region is written to the bit as before; a fading one's offset keeps 16 bits of fraction, a sixteenth of a texel on a 4,096 page. On `demo/dev/lightmap.html?mode=tiles&fade=0.5` the faded tiles keep 50.0% of their pixels, each lit exactly as unfaded, and nothing else changes, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`prepareMesh` and `prepareInstanced` compile a draw's pipelines in its material before its first frame, so a scene drawn under `pipelineCompile: 'skip'` shows whole.",
+        "text": "`prepareMesh(mesh, material)` and `prepareInstanced(batch, material)` compile, off the main thread, every pipeline a draw of that mesh or batch in that material takes that making it did not: a two-sided, cut-out or surface-model variant, a skin's halves under the screen-space blur, and the material's lit switches; `{ translucent: true }` adds the blended ones. `ready()` resolves once they have. Under `pipelineCompile: 'skip'` a draw whose pipeline is new is left out until it lands, so a figure brought on screen came without its skin and hair for a few frames; prepared, it is drawn whole in its first frame. On WebGPU a prepared key is the one the draw asks for, worked out by the same function; on WebGL2 a surface model's programs are what a draw can wait for, and are what it prepares."
+      },
+      {
+        "kind": "added",
+        "short": "`holdSplash(promise, { capMs })` keeps the engine's badge up until the game's own first screen has loaded, under a cap of its own.",
+        "text": "The badge left three seconds after the first frame, twenty at most, so a game whose first screen loads for longer was seen loading. `holdSplash` keeps it up until the promise settles, either way, as well as until the first frame; frames run behind it while the game loads, since a load may need them, and are held once it has settled for what is left of the minimum. `capMs` is the game's ceiling in place of the engine's twenty seconds, the longest of several holds, and the call answers whether there was a badge to hold. On `demo/dev/splashHold.html` a load settling at 6.2 s took the badge down at 6.7 s with 361 frames run under it, a rejected load the same, and an 8-second cap at 8.4 s."
+      }
+    ]
+  },
   {
     "version": "4.11.0",
     "date": "2026-10-10",

package/README.md

@@ -6,7 +6,7 @@ WebGL2 everywhere else, behind one API, and carries the fixed-step loop, the ren
 input, the scene graph, geometry, text and the whole of `@driftengine/physics`, which it re-exports.
 Everything else is a separate package a game adds when it reaches for it.
 
-**Cost: 898.2 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 904.6 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

@@ -155,7 +155,7 @@ export { BLOOM_LEVELS } from './render/bloomChain.ts';
 export type { BloomResponse } from './render/bloomChain.ts';
 export { probeDevice } from './render/backend/probe.ts';
 export type { ProbeVerdict } from './render/backend/probe.ts';
-export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
+export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, PrepareOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
 export type { ClothBindingData } from './render/clothBindingData.ts';
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.ts';
 export type { AnisotropicModel, EyeModel, HairModel, LightmapModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.ts';
@@ -344,7 +344,7 @@ export type { TouchControlsOptions } from './input/touchControls.ts';
 export { pixelCursor } from './ui/pixelCursor.ts';
 export { fullscreenWanted, requestFullscreenOnGesture } from './ui/fullscreen.ts';
 export type { FullscreenConditions } from './ui/fullscreen.ts';
-export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.ts';
+export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, holdSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.ts';
 export type { MountedSplash, SplashConditions, SplashDecision, SplashOptions, } from './ui/splash.ts';
 export { DEFAULT_CLIP_FPS, FrameRecorder, offerClip } from './ui/frameRecorder.ts';
 export { stillFrame } from './ui/stillFrame.ts';

package/dist/index.js

@@ -439,7 +439,7 @@ export { fullscreenWanted, requestFullscreenOnGesture } from './ui/fullscreen.js
  * they are here for the consumer that declines the automatic one and places its own, and because
  * the two decisions behind it are worth reading before overriding either.
  */
-export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.js';
+export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, holdSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.js';
 export { DEFAULT_CLIP_FPS, FrameRecorder, offerClip } from './ui/frameRecorder.js';
 // Not on `FrameRecorder`, so a screenshot does not cost a clip pipeline. See the module.
 export { stillFrame } from './ui/stillFrame.js';

package/dist/render/ambientOcclusionPass.d.ts

@@ -46,8 +46,9 @@ export declare class AmbientOcclusionPass {
      * by, or null if this pass could not run, which the caller must read as "no occlusion"
      * rather than as black.
      *
-     * `invProjection` is column-major, as `gl-matrix` produces it.
+     * `invProjection` is column-major, as `gl-matrix` produces it. `fade` is `uFade`, where the
+     * occlusion fades out with distance (`occlusionFade.ts`).
      */
-    run(depth: WebGLTexture, width: number, height: number, radius: number, projScale: Float32Array, invProjection: Float32Array): WebGLTexture | null;
+    run(depth: WebGLTexture, width: number, height: number, radius: number, projScale: Float32Array, invProjection: Float32Array, fade: Float32Array): WebGLTexture | null;
     dispose(): void;
 }

package/dist/render/ambientOcclusionPass.js

@@ -102,9 +102,10 @@ export class AmbientOcclusionPass {
      * by, or null if this pass could not run, which the caller must read as "no occlusion"
      * rather than as black.
      *
-     * `invProjection` is column-major, as `gl-matrix` produces it.
+     * `invProjection` is column-major, as `gl-matrix` produces it. `fade` is `uFade`, where the
+     * occlusion fades out with distance (`occlusionFade.ts`).
      */
-    run(depth, width, height, radius, projScale, invProjection) {
+    run(depth, width, height, radius, projScale, invProjection, fade) {
         if (!this.ensureSize(width, height))
             return null;
         const { gl } = this;
@@ -123,6 +124,7 @@ export class AmbientOcclusionPass {
         gl.uniform1i(this.estimateUniforms['uDepth'] ?? null, 0);
         gl.uniform2fv(this.estimateUniforms['uProjScale'] ?? null, projScale);
         gl.uniform1f(this.estimateUniforms['uRadius'] ?? null, radius);
+        gl.uniform2fv(this.estimateUniforms['uFade'] ?? null, fade);
         gl.uniformMatrix4fv(this.estimateUniforms['uInvProjection'] ?? null, false, invProjection);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         /*

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

@@ -177,6 +177,14 @@ export interface SurfaceTextureHandle {
  * `WebGLBuffer` in a private field, so no WebGPU object can satisfy it however identical its
  * shape. It is not meant to be read; it is meant to be enforced.
  */
+/** Which of a draw's pipelines `prepareMesh` and `prepareInstanced` compile beside the opaque ones. */
+export interface PrepareOptions {
+    /**
+     * The blended ones too, for a draw made with `drawTranslucentMesh` or `drawTranslucentInstanced`.
+     * Off by default: an opaque surface would pay a compile it never draws with.
+     */
+    readonly translucent?: boolean;
+}
 /** What a mesh needs to be told at creation that its geometry cannot say. */
 export interface MeshOptions {
     /**
@@ -190,7 +198,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'prepareMesh' | 'prepareInstanced' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -299,6 +307,18 @@ export type RendererApi = Omit<{
      * setter each — and `setSurfaceTexture` is now a wrapper over it.
      */
     setMaterial(material: SurfaceMaterial<SurfaceTextureHandle> | null): void;
+    /**
+     * Compile, off the main thread, every pipeline a draw of `mesh` in `material` takes that making
+     * the mesh did not — a two-sided, cut-out or shaded-by-a-model variant, a material's lit switches,
+     * a skin's halves — so the first frame that draws it waits on none; `ready()` resolves once they
+     * have. For `pipelineCompile: 'skip'` above all, where a draw whose pipeline is new is left out
+     * until it lands: a figure brought on screen whole rather than without its face for a few frames.
+     * A rigged mesh is prepared as drawn with a palette, and one with targets both with weights and
+     * without. Call it between frames: it sets `material` to read it and leaves none set after.
+     */
+    prepareMesh(mesh: MeshHandle, material: SurfaceMaterial<SurfaceTextureHandle> | null, options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch drawn in `material`, its own pipelines being its own. */
+    prepareInstanced(batch: InstancedHandle, material: SurfaceMaterial<SurfaceTextureHandle> | null, options?: PrepareOptions): void;
     /**
      * A 3D text object: one string, drawn as instanced glyph cubes over the scene.
      *

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

@@ -49,7 +49,7 @@ import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts
 import { Mesh } from '../../mesh.ts';
 import type { IncrementalMesh } from '../../mesh.ts';
 import type { MeshData } from '../../mesh.ts';
-import type { MeshOptions } from '../api.ts';
+import type { MeshOptions, PrepareOptions } from '../api.ts';
 import { SurfaceTexture } from '../../surfaceTexture.ts';
 import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
@@ -1114,6 +1114,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly aoProjScale;
     /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
     private readonly aoOffset;
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    private readonly aoFade;
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -1281,14 +1283,18 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedProjectionRoom;
     /** `uWorldUv`, the current material's projection packed. See `surfaceProjection.ts`. */
     private readonly projection;
-    /** The current material's `diffuseTransmission`, `uGlassTint.w`, 0 to 1. */
-    private diffuseTransmission;
+    /**
+     * `uGlassTint` as the current material leaves it: its light from behind and that light's colour,
+     * which a pane overwrites for its own draw and `unbindSeeThrough` puts back. See `transmission.ts`.
+     */
+    private readonly transmission;
     /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
     private readonly layerFloats;
     /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
     private layersRoom;
     private warnedLayersRoom;
     private warnedLayersModelMap;
+    private warnedLayersTriplanar;
     private warnedOverlayRoom;
     private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
@@ -1959,6 +1965,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * `uScale`/`vScale` are repeats across the mesh's own UV range: geometry authored in
      * metres is textured at whatever density the material wants without rebuilding it.
      */
+    /**
+     * Compile, off the frame, every program a draw of `mesh` in `material` takes that making the mesh
+     * did not, so the first frame that draws it waits on none: the program of the material's shading
+     * model for each vertex variant the mesh can be drawn with (its rig, with a palette; its targets,
+     * with weights and without), a skin's halves under the screen-space blur, and the lit switches
+     * the material turns on. `ready()` resolves once they have.
+     *
+     * **For `pipelineCompile: 'skip'` above all**, where a draw whose program is new is left out until
+     * it lands: a figure brought on screen whole rather than without its face and hair for the frames
+     * those take. Where draws wait, the programs compile here, at the call, rather than in a frame.
+     * Two-sided and cut-out surfaces are draw state on this backend and need nothing; on WebGPU they
+     * are pipelines of their own, prepared the same way.
+     *
+     * **Call it between frames**: it sets `material` to read it and leaves no material set after, as
+     * `setMaterial(null)` does. `options` is the other backend's; blended draws share a program here.
+     */
+    prepareMesh(mesh: Mesh, material: SurfaceMaterial | null, _options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch: its own programs, and its model's for its variant. */
+    prepareInstanced(batch: InstancedBatch, material: SurfaceMaterial | null, _options?: PrepareOptions): void;
     /**
      * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
      *
@@ -2140,6 +2165,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * no room for their two vectors each leave one layer, the last two said once each.
      */
     private layersOf;
+    /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
+    private warnLayersTriplanar;
     /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
     private switchFits;
     /**
@@ -2236,7 +2263,8 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * What it gives up: a fade reads as grain while it lasts, which a temporal resolve smooths and a
      * plain frame does not; a blended draw that asks spends its opacity here and blends none of it;
-     * and a lightmapped batch carries regions where the opacities would be, so it has none to fade.
+     * and a lightmapped batch's opacities ride its page regions, so they fade in steps of a
+     * sixty-fourth, which is the pattern's own resolution (`MeshInstances.lightmapRegions`).
      */
     setDitherOpacity(on: boolean): void;
     /**
@@ -2404,6 +2432,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * taking it mid-bake is how a probe's next face came to be attached to the scene's framebuffer.
      */
     private bindSeeThrough;
+    /** `uGlassTint` as the current material leaves it. See `transmission`. */
+    private writeTransmission;
     /** Put back what `bindSeeThrough` bound: the binding outlives its frame (the 2026-08-27 rule). */
     private unbindSeeThrough;
     disposeMesh(mesh: Mesh): void;
@@ -3293,6 +3323,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * once rather than doing nothing. See `shaders/localExposure.ts`.
      */
     setLocalExposure(strength: number): void;
+    /**
+     * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
+     * gone `radius` metres past it, so the far depth buffer's steps — a sky dome kilometres off, a
+     * mountain range — are not shaded in rings, and those pixels skip the occlusion's sampling.
+     *
+     * A distance that is not a finite number at or above zero is no fade, which is the default, and
+     * `Infinity` reads as "never fades"; a radius below zero is a cut at `distance`. Set before
+     * `endFrame` and held until changed, like `setDepthOfField`. Nothing at all when
+     * `ambientOcclusion` is 0. See `occlusionFade.ts` for what it gives up.
+     */
+    setAmbientOcclusionFade(distance: number, radius: number): void;
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take.

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

@@ -37,8 +37,10 @@ import { compileProgram, finishProgram, startProgram, uniformLocations } from '.
 import { countUniformVectors, FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../uniformVectorBudget.js';
 import { OVERLAY_FLOATS, overlayLays, packSurfaceOverlay, } from '../../surfaceOverlay.js';
 import { PROJECTION_FLOATS, packSurfaceProjection, projects } from '../../surfaceProjection.js';
+import { resolveTransmission } from '../../transmission.js';
+import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
-import { LAYER_FLOATS, packSurfaceLayers } from '../../surfaceLayers.js';
+import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
@@ -785,6 +787,8 @@ export class WebGL2Renderer {
     aoProjScale = new Float32Array(2);
     /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
     aoOffset = new Float32Array(2);
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    aoFade = new Float32Array([-1, 0]);
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -952,14 +956,18 @@ export class WebGL2Renderer {
     warnedProjectionRoom = false;
     /** `uWorldUv`, the current material's projection packed. See `surfaceProjection.ts`. */
     projection = new Float32Array(PROJECTION_FLOATS);
-    /** The current material's `diffuseTransmission`, `uGlassTint.w`, 0 to 1. */
-    diffuseTransmission = 0;
+    /**
+     * `uGlassTint` as the current material leaves it: its light from behind and that light's colour,
+     * which a pane overwrites for its own draw and `unbindSeeThrough` puts back. See `transmission.ts`.
+     */
+    transmission = new Float32Array([-1, -1, -1, 0]);
     /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
     layerFloats = new Float32Array(LAYER_FLOATS);
     /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
     layersRoom = null;
     warnedLayersRoom = false;
     warnedLayersModelMap = false;
+    warnedLayersTriplanar = false;
     warnedOverlayRoom = false;
     warnedOverlayBlocks = false;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
@@ -2861,6 +2869,57 @@ export class WebGL2Renderer {
      * `uScale`/`vScale` are repeats across the mesh's own UV range: geometry authored in
      * metres is textured at whatever density the material wants without rebuilding it.
      */
+    /**
+     * Compile, off the frame, every program a draw of `mesh` in `material` takes that making the mesh
+     * did not, so the first frame that draws it waits on none: the program of the material's shading
+     * model for each vertex variant the mesh can be drawn with (its rig, with a palette; its targets,
+     * with weights and without), a skin's halves under the screen-space blur, and the lit switches
+     * the material turns on. `ready()` resolves once they have.
+     *
+     * **For `pipelineCompile: 'skip'` above all**, where a draw whose program is new is left out until
+     * it lands: a figure brought on screen whole rather than without its face and hair for the frames
+     * those take. Where draws wait, the programs compile here, at the call, rather than in a frame.
+     * Two-sided and cut-out surfaces are draw state on this backend and need nothing; on WebGPU they
+     * are pipelines of their own, prepared the same way.
+     *
+     * **Call it between frames**: it sets `material` to read it and leaves no material set after, as
+     * `setMaterial(null)` does. `options` is the other backend's; blended draws share a program here.
+     */
+    prepareMesh(mesh, material, _options = {}) {
+        if (this.contextLost)
+            return;
+        this.setMaterial(material);
+        const kind = material?.model?.kind ?? null;
+        if (kind !== null) {
+            const eight = mesh.isSkinnedEight;
+            const morphs = mesh.morph !== null;
+            const plain = mesh.isSkinned ? (eight ? 'skinned8' : 'skinned') : 'plain';
+            const morphed = mesh.isSkinned ? (eight ? 'both8' : 'both') : 'morphed';
+            for (const variant of morphs ? [plain, morphed] : [plain]) {
+                this.modelProgram(variant, kind);
+                /* A skin under the screen-space blur draws three halves, each a program of its own. */
+                if (kind === 'skin' && this.skinScatter !== null && this.sceneTarget !== null) {
+                    for (const half of SPLIT_SKIN_HALVES)
+                        this.modelProgram(variant, kind, half);
+                }
+            }
+        }
+        this.setMaterial(null);
+    }
+    /** `prepareMesh` for an instanced batch: its own programs, and its model's for its variant. */
+    prepareInstanced(batch, material, _options = {}) {
+        if (this.contextLost)
+            return;
+        this.setMaterial(material);
+        const animated = batch.animation !== null;
+        this.ensureInstancedProgram();
+        if (animated)
+            this.ensureAnimatedProgram();
+        const kind = material?.model?.kind ?? null;
+        if (kind !== null)
+            this.modelProgram(animated ? 'animated' : 'instanced', kind);
+        this.setMaterial(null);
+    }
     /**
      * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
      *
@@ -3197,9 +3256,9 @@ export class WebGL2Renderer {
          * and read neither — one decision for every program, as `setMaterial` says.
          */
         const modelMap = material?.modelMap ?? null;
-        /* A layered material's mask goes where a model's map would: see `SurfaceMaterial.layers`. */
+        /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
         const layers = this.layersOf(material);
-        const boundMap = modelMap ?? layers?.mask ?? null;
+        const boundMap = modelMap ?? layerMaskMap(layers);
         gl.activeTexture(gl.TEXTURE0 + MODEL_MAP_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (boundMap !== null)
@@ -3217,11 +3276,13 @@ export class WebGL2Renderer {
         /* The draw's overlay, which a program born mid-pass must wear too: see `setSurfaceOverlay`. */
         gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
-        /* How much light from behind the surface lets through, in the glass tint's spare lane. */
-        this.diffuseTransmission = Math.min(Math.max(material?.diffuseTransmission ?? 0, 0), 1) || 0;
-        gl.uniform4f(u['uGlassTint'] ?? null, 1, 1, 1, this.diffuseTransmission);
+        /* How much light from behind the surface lets through, and its colour: transmission.ts. */
+        resolveTransmission(material, this.transmission);
+        this.writeTransmission(u);
         /* Maps placed by the world, where the material asks and the lit stage has room: worldUv.ts. */
-        const projection = material?.projection ?? null;
+        const projection = layeredProjection(material?.projection, layers);
+        if (projection !== (material?.projection ?? null))
+            this.warnLayersTriplanar();
         packSurfaceProjection(this.projectionFits(projection) ? projection : null, this.projection);
         if (this.projection[0] > 0)
             this.askLit('WORLD_UVS');
@@ -3455,14 +3516,15 @@ export class WebGL2Renderer {
      * no room for their two vectors each leave one layer, the last two said once each.
      */
     layersOf(material) {
-        const layers = material?.layers ?? null;
+        const layers = (material?.layers ?? null);
         if (layers === null || layers.repeats.length === 0)
             return null;
-        if ((material?.modelMap ?? null) !== null) {
+        if (!layersFitBeside(layers, material?.modelMap)) {
             if (!this.warnedLayersModelMap) {
                 this.warnedLayersModelMap = true;
-                console.warn("Renderer: a material's layers are drawn as one: its mask is read where a model's map " +
-                    'goes, and this material carries a `modelMap` too.');
+                console.warn("Renderer: a material's layers are drawn as one: its mask is a map, read where a " +
+                    "model's map goes, and this material carries a `modelMap` too. A mask in the ORM " +
+                    "array (`mask: 'orm'`) or the vertex colour (`mask: 'vertex'`) leaves the slot free.");
             }
             return null;
         }
@@ -3471,12 +3533,20 @@ export class WebGL2Renderer {
             return layers;
         if (!this.warnedLayersRoom) {
             this.warnedLayersRoom = true;
-            console.warn("Renderer: a material's layers are refused on this device. They take two fragment uniform " +
+            console.warn("Renderer: a material's layers are refused on this device. They take four fragment uniform " +
                 'vectors the lit shader does not have; the material is drawn as its base layer. A lower ' +
                 '`maxLights` makes the room, or WebGPU has it.');
         }
         return null;
     }
+    /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
+    warnLayersTriplanar() {
+        if (this.warnedLayersTriplanar)
+            return;
+        this.warnedLayersTriplanar = true;
+        console.warn("Renderer: a layered material's triplanar projection is laid on the horizontal plane: every " +
+            "layer's maps on three planes would be three times the reads. See `SurfaceMaterial.layers`.");
+    }
     /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
     switchFits(feature) {
         const asIf = { [feature]: true };
@@ -3635,7 +3705,8 @@ export class WebGL2Renderer {
      *
      * What it gives up: a fade reads as grain while it lasts, which a temporal resolve smooths and a
      * plain frame does not; a blended draw that asks spends its opacity here and blends none of it;
-     * and a lightmapped batch carries regions where the opacities would be, so it has none to fade.
+     * and a lightmapped batch's opacities ride its page regions, so they fade in steps of a
+     * sixty-fourth, which is the pattern's own resolution (`MeshInstances.lightmapRegions`).
      */
     setDitherOpacity(on) {
         if (this.contextLost)
@@ -4106,13 +4177,20 @@ export class WebGL2Renderer {
         const tint = options.refractTint ?? WHITE_TINT;
         gl.uniform4f(u['uRefractTint'] ?? null, tint[0] ?? 1, tint[1] ?? 1, tint[2] ?? 1, 1);
         /* The pane's colour; w is the material's light through from behind, which glass never reads. */
-        gl.uniform4f(u['uGlassTint'] ?? null, glass.tint[0] ?? 1, glass.tint[1] ?? 1, glass.tint[2] ?? 1, this.diffuseTransmission);
+        gl.uniform4f(u['uGlassTint'] ?? null, glass.tint[0] ?? 1, glass.tint[1] ?? 1, glass.tint[2] ?? 1, this.transmission[3]);
         return true;
     }
+    /** `uGlassTint` as the current material leaves it. See `transmission`. */
+    writeTransmission(u) {
+        const t = this.transmission;
+        this.gl.uniform4f(u['uGlassTint'] ?? null, t[0] ?? -1, t[1] ?? -1, t[2] ?? -1, t[3] ?? 0);
+    }
     /** Put back what `bindSeeThrough` bound: the binding outlives its frame (the 2026-08-27 rule). */
     unbindSeeThrough(u) {
         const { gl } = this;
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
+        /* The material's light through, over the pane's tint: transmission.ts. */
+        this.writeTransmission(u);
         gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
         /* The overlay's atlas, where one is held: it shares the unit. See `setSurfaceOverlay`. */
         gl.bindTexture(gl.TEXTURE_2D, this.overlayTexture ?? this.emptyTexture2D);
@@ -6177,6 +6255,19 @@ export class WebGL2Renderer {
         }
         this.sceneTarget.setLocalExposure(strength);
     }
+    /**
+     * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
+     * gone `radius` metres past it, so the far depth buffer's steps — a sky dome kilometres off, a
+     * mountain range — are not shaded in rings, and those pixels skip the occlusion's sampling.
+     *
+     * A distance that is not a finite number at or above zero is no fade, which is the default, and
+     * `Infinity` reads as "never fades"; a radius below zero is a cut at `distance`. Set before
+     * `endFrame` and held until changed, like `setDepthOfField`. Nothing at all when
+     * `ambientOcclusion` is 0. See `occlusionFade.ts` for what it gives up.
+     */
+    setAmbientOcclusionFade(distance, radius) {
+        resolveOcclusionFade(distance, radius, this.aoFade);
+    }
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take.
@@ -6804,6 +6895,7 @@ export class WebGL2Renderer {
                 radius: this.quality.ambientOcclusionRadius,
                 projScale: this.aoProjScale,
                 invProjection: this.aoInvProjection,
+                fade: this.aoFade,
                 offset: this.aoOffset,
             };
         }
@@ -7256,7 +7348,7 @@ export class WebGL2Renderer {
         /* Nor a projection: maps follow the mesh's coordinates until a material asks otherwise. */
         this.projection.fill(0);
         /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
-        this.diffuseTransmission = 0;
+        resolveTransmission(null, this.transmission);
         /* Nor layers: one layer until a material asks for more. */
         this.layerFloats.fill(0);
         this.overlayMaps = null;
@@ -7406,8 +7498,9 @@ export class WebGL2Renderer {
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
         gl.uniform4f(u['uRefractTint'] ?? null, 1, 1, 1, 1);
-        /* White, and no light through from behind: no material at a pass's start. */
-        gl.uniform4f(u['uGlassTint'] ?? null, 1, 1, 1, this.diffuseTransmission);
+        /* No light through from behind: no material at a pass's start. See `writeTransmission`. */
+        const through = this.transmission;
+        gl.uniform4f(u['uGlassTint'] ?? null, through[0] ?? -1, through[1] ?? -1, through[2] ?? -1, through[3] ?? 0);
         gl.uniform3fv(u['uDirectionalDir'] ?? null, env.directionalDir);
         gl.uniform3fv(u['uDirectionalColor'] ?? null, env.directionalColor);
         gl.uniform3fv(u['uAmbient'] ?? null, env.ambient);

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

@@ -7,7 +7,7 @@ import type { PickHit, PickableSource } from '../../pickable.ts';
 import type { RendererApi } from '../api.ts';
 import { GpuTimestamps } from './gpuTimestamps.ts';
 import type { Environment, FilmOptions, InsetRect, LightVolumeDrawOptions, SkyColors, TranslucentMeshOptions } from '../webgl2/renderer.ts';
-import type { IncrementalMeshHandle, MeshOptions } from '../api.ts';
+import type { IncrementalMeshHandle, MeshOptions, PrepareOptions } from '../api.ts';
 import type { LightmapPage } from '../../lightmap.ts';
 import { type BloomResponse } from '../../bloomChain.ts';
 import type { WaterBody } from '../../waterRenderer.ts';
@@ -851,6 +851,8 @@ export declare class WebGPURenderer implements RendererApi {
     private temporalHistoryUsable;
     private readonly aoStaging;
     private readonly aoFloats;
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    private readonly aoFade;
     private aoBindGroup;
     private readonly aoBlurLayout;
     /**
@@ -1187,7 +1189,13 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly projection;
     /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
     private readonly layerFloats;
+    /**
+     * `uGlassTint` as the material leaves it, its light from behind and that light's colour, which a
+     * pane overwrites for its own draw and `releaseSeeThrough` puts back. See `transmission.ts`.
+     */
+    private readonly transmission;
     private warnedLayersModelMap;
+    private warnedLayersTriplanar;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     private readonly modelParams;
     /**
@@ -2093,6 +2101,8 @@ export declare class WebGPURenderer implements RendererApi {
      * said once, leave one layer.
      */
     private layersOf;
+    /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
+    private warnLayersTriplanar;
     /**
      * What the sun's moving layer is read through: the matrix its shadow pass was last drawn with,
      * where the lit pipelines carry one (`MOVING_SUN`); the environment's otherwise, which every caller
@@ -2478,6 +2488,35 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private refuseOitMultisampled;
     drawTranslucentMesh(mesh: GpuMesh, model: ReadonlyMat4, opacity: number, options?: TranslucentMeshOptions): void;
+    /**
+     * Compile off the main thread every pipeline a draw of `mesh` in `material` takes. **The other
+     * backend's `prepareMesh` carries the contract**; here a draw's key is `meshShape`'s, so a prepared
+     * key is exactly the one the draw asks for, and the compiles are started as a skipping draw starts
+     * them (`PipelineCache.lit`) whatever `pipelineCompile` says, into the frame's own caches.
+     */
+    prepareMesh(mesh: GpuMesh, material: SurfaceMaterial<GpuSurfaceTexture> | null, options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch. See the other backend's `prepareInstanced`. */
+    prepareInstanced(batch: GpuInstancedBatch, material: SurfaceMaterial<GpuSurfaceTexture> | null, options?: PrepareOptions): void;
+    /**
+     * `material` set, every cache a draw in it may build into passed to `start` with whether that draw
+     * blends, compiles started rather than built (`PipelineCache.lit`), and then no material set and
+     * each cache back to what `pipelineCompile` says.
+     */
+    private preparing;
+    /** What `meshShape` worked out for the mesh draw at hand. Reused, so a draw allocates no record. */
+    private readonly drawShape;
+    /**
+     * The key a mesh draw's pipeline is cached under, and the pipeline state that key encodes, under
+     * the current material and these options, into `drawShape`. **The one statement of it**:
+     * `submitMesh` draws by it and `prepareMesh` compiles by it, so the two cannot disagree about a key.
+     */
+    private meshShape;
+    /**
+     * The pipeline `drawShape` names: the one built, one built here, or none where draws skip a
+     * compile and this one has not landed (`PipelineCache.lit`) — and none for a split skin until all
+     * of its halves have.
+     */
+    private meshPipeline;
     /**
      * @param blend Which of the two entry points above this came through, and **not** something to
      * infer from `opacity`.
@@ -2568,6 +2607,13 @@ export declare class WebGPURenderer implements RendererApi {
      * **What it gives up** against `drawMesh` is skinning and morphing, refused where the variant
      * is built, and a per-instance opacity: `opacity` here dims the whole batch.
      */
+    /**
+     * An instanced draw's pipeline under the current material and these options: the one built, one
+     * built here, or none while it compiles (`PipelineCache.lit`), its key, base and model left in
+     * `drawShape`. **The one statement of an instanced key**: `submitInstanced` draws by it and
+     * `prepareInstanced` compiles by it.
+     */
+    private instancedPipeline;
     /**
      * The next of a batch's cull slots this frame, with its cull queued against the current view; null
      * when the batch has drawn from `MAX_CULL_SLOTS` views already or the frame's job ring is full,
@@ -3994,6 +4040,11 @@ export declare class WebGPURenderer implements RendererApi {
     setLocalExposure(strength: number): void;
     /** The exposure pass, built once; the composite's group holds placeholders until it exists. */
     private ensureExposurePass;
+    /**
+     * Where ambient occlusion fades out with distance. **The other backend's
+     * `setAmbientOcclusionFade` carries the reasoning**; this is the same setter over the same state.
+     */
+    setAmbientOcclusionFade(distance: number, radius: number): void;
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take. **The other backend's `setDepthOfField` carries the reasoning**, whole: the