@driftengine/core 4.10.0 → 4.11.1

package/CHANGELOG.json

@@ -1,4 +1,111 @@
 [
+  {
+    "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",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`SurfaceRim.mode: 'blend'` pulls a surface's colour toward the rim colour at its edges before it is lit, where a rim used to add glow over it.",
+        "text": "A surface overlay's rim takes `mode: 'blend'`: the base colour is mixed toward the rim colour by the edge's weight, raised to its contrast and scaled by its alpha, before lighting, so the edge is lit, shadowed and fogged as the rest of the surface is rather than glowing over it, and a colour channel weighted above 1 is held at 1. `'add'`, the default, is the rim as it was. On `demo/dev/surfaceOverlay.html?rim=blend` an edge out of the light moved by −1.9 in luminance where adding moved it by +41, and the two backends draw the same picture."
+      },
+      {
+        "kind": "added",
+        "short": "`setDitherOpacity(true)` spends each opaque draw's own opacity, an instance's alpha included, on a screen door, so an instance fades without blending or a pop.",
+        "text": "With `setDitherOpacity(true)` the draws that follow keep a pixel only where the opacity it carries (a mesh's own, or `MeshInstances.alphas` for an instance of a batch) lies above an 8x8 ordered threshold, the pattern `setDitherFade` uses, so an opaque instance fades in or out over a few frames instead of popping, still writes depth and needs no sorting; two instances crossfading cover each pixel once. On `demo/dev/hlodFade.html?opacity=` the share of pixels kept matches the opacity to 1/64 on both backends. What it gives up: a screen door shows as a pattern up close, which the temporal resolve smooths where it runs."
+      },
+      {
+        "kind": "added",
+        "short": "`createSkinnedClothSet` solves every garment together, one dispatch per batch of constraints across all of them, and `maxSteps` caps the steps one frame runs.",
+        "text": "`createSkinnedClothSet(renderer, setups)` solves several garments together: on WebGPU one pass a step, each constraint batch of every garment merged by colour into one dispatch, where each garment had its own encoder, pass and submit. Garments are named by their index, in `setPose(g, …)`, `setWind(g, …)`, `reset(g)` and `particles[g]` for `setCloth`, and `step(dt)` runs them all; `createSkinnedCloth` is a set of one, and a backend without compute runs the set on the CPU. Garments in a set share `substeps`, `iterations` and `maxSteps`, and are refused by the first they disagree on. `SkinnedClothParameters.maxSteps` caps the whole steps one `advance` runs and drops the time past it, so a slow frame no longer hands the next one more steps; unset, it is unbounded as before. On `demo/dev/skinnedCloth.html?bench=1&garments=15`, fifteen garments step in 0.793 ms as one set against 8.903 ms as fifteen solvers, and a set agrees with separate solvers within the spread of a nudged control."
+      },
+      {
+        "kind": "added",
+        "short": "`RenderQuality.pipelineCompile: 'skip'` leaves a draw out while its new pipeline compiles off the main thread, rather than holding the frame for the compile.",
+        "text": "A lit pipeline first needed inside a frame, for a material's surface model or a lit switch met mid-scene, was compiled where it was asked for, which holds the GPU process for the compile, reported at 130 to 400 ms on a phone. With `pipelineCompile: 'skip'` the compile starts off the main thread and the draw is left out until it lands; `'wait'`, the default, is as before. `ready()` waits for every compile started either way. On WebGL2 a model program compiles through `KHR_parallel_shader_compile` where the context offers it and waits where it does not. On `demo/dev/pipelineCompile.html`, eight new variants at once held a WebGPU frame 700 to 3,700 ms waiting and 17 ms skipping, the draws landing 21 to 26 frames later; through ANGLE on OpenGL the longest WebGL2 frame went from 820–1,120 ms to 630–700 ms, the driver finishing its own compile at the program's first draw. What it gives up is the draw, for the frames its compile takes."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.projection` places a material's maps by the world, planar across the ground or triplanar on three planes, at so many repeats a metre.",
+        "text": "`projection: { kind: 'planar' | 'triplanar', scale, sharpness? }` reads a material's maps at a point's place in the world rather than at the mesh's texture coordinates: `'planar'` across the two horizontal axes, `'triplanar'` on three planes blended by how squarely the surface faces each, with the normal map turned into the world by the whiteout blend, so no tangent frame is needed. A lit switch, compiled in the first time a material asks. On `demo/dev/worldUv.html` a triplanar cube matches the same map read through each face's own coordinates and tangents, on both backends. What it gives up: a projection belongs to the world, so a mesh that moves slides under it; triplanar reads each map three times; a texture is mirrored on a plane's far side; and a cutout material's shadow is still cut by the mesh's coordinates."
+      },
+      {
+        "kind": "added",
+        "short": "The sun's moving shadow layer is read through the matrix its own pass was drawn with, so what moves can have a tight, sharp square inside the static layer's wide one.",
+        "text": "A frame's `beginShadowPass(matrix, 'dynamic')` drawn with a matrix other than the environment's `lightViewProj` is now read through that matrix: the static layer keeps one square over the whole of what stands still, and the moving layer a tight one around what moves, at its own texel size, filter and depth span. The lit stage, the global medium and light volumes all read it, behind a lit switch that turns on the first frame a dynamic pass's matrix differs. On `demo/dev/sunLayers.html?moving=tight` a moving caster's shadow core went from 144 to 202 pixels and its penumbra from 886 to 739, and everything outside the tight square was unchanged to the pixel, on both backends. What it gives up: a receiver outside the static layer's square takes no sun shadow at all, so the tight square belongs inside the wide one."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.diffuseTransmission` lets light from behind a thin surface through, coloured by it: a banner, a leaf or a lampshade lit from behind.",
+        "text": "`diffuseTransmission`, 0 to 1, brings the light falling on a surface's far side (the sun, lamps, area lights and DriftLight) to the eye through it, coloured by the surface's own colour; a metal lets none through, and 0, the default, is every material as it was. A lamp's shadow is read from the side the lamp is on, so a thin surface does not stand in its own shadow. On `demo/dev/thinLight.html` a sheet lit only from behind went from 16 to 163 in luminance under the sun and to 104 under a lamp, with no light behind it unchanged, on both backends. What it gives up: a thin surface rather than a volume, so a thick one lets as much through as a sheet; the light behind is not blurred; and glass lets light through by its own rule."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.layers` blends up to five layers by a mask, each at its own repeat, colour, normal and roughness alike, out of one texture array per map.",
+        "text": "`layers: { mask, repeats, emissiveLayer? }` lays up to four layers over a base by an RGBA mask read at the mesh's coordinates, red laying layer 1 through alpha laying layer 4, each over every one before it. Layer `i` is layer `i` of the material's albedo, normal and ORM arrays, read at the coordinates times its own repeat, and the tangent-space normals are blended before the frame turns them into the world; `emissiveLayer` makes the emissive map glow only where that layer shows. A lit switch, compiled in the first time a material asks, and the mask is read where `modelMap` goes, so it takes no texture binding of its own. On `demo/dev/layers.html` three layers at three repeats draw the same on both backends, and a material without layers draws as before. What it gives up: every layer is read at every pixel whatever its share; a material carries a mask or a surface model's map, not both."
+      },
+      {
+        "kind": "changed",
+        "short": "A mesh's indices are sixteen bits where its vertices fit, and its normals, tangents, colours and weights sixteen-bit fixed point: 29% less mesh memory in the published scenes.",
+        "text": "Every attribute of a mesh travelled as 32-bit floats and every index as 32 bits. Indices are 16 bits now wherever a mesh has 65,536 vertices or fewer; normals and tangents travel as 16-bit signed fixed point, colours and skin weights inside [0, 1] as unsigned; and a colour or an emissive every vertex shares is a constant rather than a stream. Both backends decide it the same way, from the data, when a mesh is made, and positions and texture coordinates stay floats. Measured on WebGPU across the eight published scenes, mesh vertex and index buffers went from 210 to 150 MB: the voxel sandbox's vertices from 38.4 to 28.5 MB and its indices from 4.8 to 2.4, the showroom's from 113.8 to 78.2 and from 34.9 to 25.2. Eight of the nine scenes are the same to the pixel on WebGPU, and one moves 12 pixels by 2 of 255 on average, which is normals at 1/32767. What it gives up: texture coordinates stay floats because sixteen bits move a pixel on an atlas tile's edge onto the next tile, measured as 29 pixels in the voxel sandbox; a dynamic mesh's normals stay floats; and an attribute outside its range stays a float rather than being clamped."
+      },
+      {
+        "kind": "fixed",
+        "short": "A normal map on a mesh with no tangents and a mirrored mapping is no longer turned half a circle by the frame derived for it, which lit it from the far side.",
+        "text": "Where a mesh carries no tangents, the frame its normal map is read in is derived from screen-space derivatives, and its handedness was taken from the texture coordinates' determinant alone, which cannot see a mapping mirrored about the normal: such a surface had its bumps lit from the side opposite the light. The handedness is the surface's orientation on screen against its normal now, which is the determinant's sign wherever a mapping is not mirrored. On `demo/dev/worldUv.html` a mirrored ground read 74.8 derived against 110.8 through its tangents, and 110.8 both ways after; every published scene is unchanged to the pixel."
+      },
+      {
+        "kind": "fixed",
+        "short": "On WebGPU a lit surface reads the sun's static layer through the environment's light matrix, not through whichever matrix the last shadow pass used.",
+        "text": "The WebGPU lit vertex stage projected a receiver into the sun's map through the matrix of the frame's last shadow pass. Where every pass shared one matrix nothing showed; where a dynamic pass was drawn with a tighter one, the static layer was read through it and its shadows landed in the wrong place. It projects through `env.lightViewProj` now, as WebGL2 always did."
+      },
+      {
+        "kind": "fixed",
+        "short": "`ready()` no longer waits for ever on a pipeline whose compile off the main thread failed, and it waits for a lit switch's rebuild as well.",
+        "text": "A pipeline whose `createRenderPipelineAsync` rejected stayed among the compiles `ready()` waits on, so a boot awaiting it never resolved; it is taken out, and built where it is next asked for so the device says why. And `ready()` now waits for a lit switch's rebuild, so the first frame after it has every pipeline with the feature that turned the switch on, where a capture taken then photographed the frames before."
+      },
+      {
+        "kind": "fixed",
+        "short": "On WebGL2 a surface model's program first made in the middle of a mesh pass keeps the pass's dither fade, where its draws used to ignore it.",
+        "text": "A program for a surface model first made between `bindMeshPass` and the draws after it was handed the pass's state with the dither fade cleared, so the draws through it ignored `setDitherFade` until the next pass. WebGL2 only: WebGPU carries the fade in each draw's block."
+      }
+    ]
+  },
   {
     "version": "4.10.0",
     "date": "2026-10-07",

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: 873.3 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';
@@ -164,8 +164,8 @@ export type { FrameReflections } from './render/frameReflections.ts';
 export type { OverlayRegion, SurfaceDissolve, SurfaceOverlay, SurfaceRim, SurfaceWrinkle, } from './render/surfaceOverlay.ts';
 export { WHOLE_PAGE } from './render/lightmap.ts';
 export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
-export { createSkinnedCloth } from './render/skinnedClothRun.ts';
-export type { SkinnedClothSolver } from './render/skinnedClothRun.ts';
+export { createSkinnedCloth, createSkinnedClothSet } from './render/skinnedClothRun.ts';
+export type { SkinnedClothSet, SkinnedClothSolver } from './render/skinnedClothRun.ts';
 /**
  * What a frame asked of a backend, against the ceilings that backend imposes.
  *
@@ -223,11 +223,12 @@ export type { PrefilterQuality } from './render/prefilterEnvMap.ts';
  * `ProbeBakeOptions`, which is the whole of the reasoning.
  */
 export type { ProbeBakeOptions } from './render/reflectionProbe.ts';
-export type { DirectionalShadowDepthLayers, GlassShadows, OutputTransform, RenderQuality, RenderQualityOptions, ShadowFilterTaps, SkinScattering, WaterReflectionFilterTaps, } from './render/renderQuality.ts';
+export type { DirectionalShadowDepthLayers, GlassShadows, OutputTransform, PipelineCompile, RenderQuality, RenderQualityOptions, ShadowFilterTaps, SkinScattering, WaterReflectionFilterTaps, } from './render/renderQuality.ts';
 export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.ts';
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
+export type { SurfaceProjection } from './render/surfaceProjection.ts';
 export { compressedFormatName, isCompressedSource, levelBytes, uploadsCompressed, } from './render/compressedSource.ts';
 export type { BlockFormat, CompressedTextureFormat, CompressedTextureSource, SurfaceSource, } from './render/compressedSource.ts';
 export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.ts';
@@ -343,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

@@ -237,7 +237,7 @@ export { WHOLE_PAGE } from './render/lightmap.js';
  * A skinned cloth solved where the renderer can: compute on WebGPU, the CPU under WebGL2. A function
  * rather than a renderer method so only a game that imports it carries the solver.
  */
-export { createSkinnedCloth } from './render/skinnedClothRun.js';
+export { createSkinnedCloth, createSkinnedClothSet } from './render/skinnedClothRun.js';
 /*
  * Reading an image's texels back exactly, which no canvas and no `VideoFrame` will do.
  *
@@ -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';
@@ -931,6 +931,15 @@ export declare class WebGL2Renderer implements RendererApi {
      * compiled the first time a draw asks for one. See `modelProgram`.
      */
     private readonly modelFlat;
+    /**
+     * Model programs still compiling, where draws skip a compile (`pipelineCompile: 'skip'`) and the
+     * context offers `KHR_parallel_shader_compile`; `parallelCompile` is its completion query then,
+     * and null where draws wait for a program here instead. See `modelProgram`.
+     */
+    private readonly modelPending;
+    /** What `drawVariantOf` answers, rewritten each draw rather than made. */
+    private readonly drawVariant;
+    private readonly parallelCompile;
     /** The last palette chosen, which an eye's axis is turned by. See `setSkinPalette`. */
     private paletteData;
     private readonly emptyTexture2D;
@@ -993,7 +1002,7 @@ export declare class WebGL2Renderer implements RendererApi {
     private oitReplaying;
     /** `uSurfaceScene`, resolved once a pass. See `surfaceScene.ts`. */
     private readonly surfaceScene;
-    /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
+    /** The three lanes of `uWriteMode`, kept here because a `vec3` is written whole. */
     private oitWeight;
     /**
      * How the surfaces drawn next meet the medium: what `setSurfaceFog` set, and `FOG_RECEDE` from
@@ -1001,6 +1010,7 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private surfaceFog;
     private ditherFade;
+    private ditherOpacity;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     private oitRefused;
     /** Said once for the whole renderer. See `refuseOitMultisampled`. */
@@ -1104,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.
      *
@@ -1257,6 +1269,32 @@ export declare class WebGL2Renderer implements RendererApi {
     private overlayTexture;
     /** Whether this device's lit stage has room for the overlay's vectors: asked once. */
     private overlayRoom;
+    /**
+     * The matrix the sun's dynamic shadow pass was last drawn with, uncorrected, and whether one has
+     * been: what the moving layer is read through. See `movingLightFor`.
+     */
+    private readonly movingLightViewProj;
+    private movingLightKnown;
+    /** Whether the lit stage has room for the moving layer's matrix, and whether its refusal was said. */
+    private movingRoom;
+    private warnedMovingRoom;
+    /** The same answer for a material's projection, and whether its refusal was said. */
+    private projectionRoom;
+    private warnedProjectionRoom;
+    /** `uWorldUv`, the current material's projection packed. See `surfaceProjection.ts`. */
+    private readonly projection;
+    /**
+     * `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. */
@@ -1786,6 +1824,15 @@ export declare class WebGL2Renderer implements RendererApi {
      * this before its first frame gets the right behaviour on both without asking which backend
      * it has, which is the contract `RendererApi` exists to keep.
      */
+    /**
+     * Resolve once every program a draw has started compiling has finished, adopting each: what a
+     * loading screen awaits after drawing what its scene will use, where draws skip a compile. See
+     * `RenderQuality.pipelineCompile`; nothing is started anywhere else here, so otherwise it is now.
+     *
+     * **It waits without holding the thread**, as the other backend's does: it asks the driver
+     * whether each is done, which does not wait, and yields between asks. A driver that never says
+     * done is asked the way that waits after `READY_MAX_POLLS`, so this cannot hang a loading screen.
+     */
     ready(): Promise<void>;
     dispose(options?: {
         releaseContext?: boolean;
@@ -1918,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.
      *
@@ -1936,6 +2002,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * material at once, as `ensureClothPrograms` feeds its own.
      */
     private modelProgram;
+    /** A model program compiled: kept, written to by every material setter, and fed the pass. */
+    private adoptModel;
     /**
      * An eye's axis in the world for this draw, into its program's `uModelParams`: the material's
      * own numbers with the axis turned by the draw's model matrix and the eye's joint. See
@@ -2073,6 +2141,34 @@ export declare class WebGL2Renderer implements RendererApi {
     private overlayRoomLeft;
     /** Whether the lit shader with the overlay compiled in fits this GPU: counted once. */
     private overlayFits;
+    /**
+     * Whether a material's projection can be drawn: none asked, or the lit stage has the room for its
+     * one vector. **Refused, said once, where it has not**, as the overlay is, and the material's
+     * maps are then laid by the mesh's coordinates, as they were before it existed.
+     */
+    private projectionFits;
+    /**
+     * What the sun's moving layer is read through: the matrix its shadow pass was last drawn with,
+     * where the lit stage carries one (`MOVING_SUN`); the environment's otherwise, which every caller
+     * drawing both layers with one matrix hands it anyway.
+     */
+    private movingLightFor;
+    /**
+     * Turn the moving layer's own matrix on the first time a frame draws that layer with one the
+     * environment's does not share. **Refused, said once, where the lit stage has no room for its five
+     * vectors**: the layer is then read through the environment's matrix, so its shadows land where
+     * that matrix puts them, and a caller there draws both layers with one.
+     */
+    private askMovingSun;
+    /**
+     * A material's layers where they can be drawn: none asked, a model's map in the mask's place, or
+     * 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;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
      *
@@ -2155,7 +2251,26 @@ export declare class WebGL2Renderer implements RendererApi {
      * are a pass of their own, do not. See `uDither` in `flat/preamble.ts` for what it costs.
      */
     setDitherFade(amount: number): void;
-    /** `uWriteMode`: the order-independent weight and the dither, which share one uniform row. */
+    /**
+     * Whether the draws that follow spend their own opacity on a screen door rather than on blending:
+     * an instance's `MeshInstances.alphas`, or a vertex's channel alpha, keeps that share of the
+     * pixels `setDitherFade` would and draws the rest not at all. So an opaque or cut-out batch fades
+     * one instance at a time, with no sorting and no blend, and an instance at 1 is drawn whole.
+     *
+     * Off is what `bindMeshPass` restores. It shares the fade's pattern, so a crossfade at `t` and
+     * `-t` of an instance at opacity `a` covers that instance's share once, without holes. Material
+     * state like `setDitherFade`; instanced draws read it, and shadow casters do not.
+     *
+     * 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'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;
+    /**
+     * `uWriteMode`: the order-independent weight, the fade and whether the opacity is dithered, which
+     * share one uniform row.
+     */
     private writeMode;
     /**
      * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
@@ -2317,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;
@@ -3206,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.
@@ -3709,6 +3837,16 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private scatterSkin;
     /** One draw of a mesh, as `drawMesh` describes, of the half of a skin `half` names. */
+    /**
+     * Whether every half a split skin draws has its program, starting any that has not: a skin drawn
+     * without its kept halves would lose its diffuse light for the frames they take to compile.
+     */
+    private skinHalvesReady;
+    /**
+     * The vertex variant a draw of `mesh` takes now, and its program and uniforms where it is not the
+     * plain one: what a model's program is keyed by, and what `drawMeshHalf` draws with.
+     */
+    private drawVariantOf;
     private drawMeshHalf;
     /**
      * Draw a mesh you can see through, in the same material as everything else by default.