@driftengine/core 4.5.0 → 4.6.0

package/dist/index.js

@@ -180,6 +180,9 @@ export { countSplatTiles, fillSplatTiles, splatPixelBox, splatTileGrid, splatTil
 export { GI_SOURCE_FIELD, GI_SOURCE_PROBES, GI_SOURCE_SCREEN, newIndirectResult, traceIndirect, } from './render/gi/chain.js';
 export { GLOBAL_FIELD_BLEND, composeGlobalField, createGlobalField, sampleGlobalField, } from './render/gi/globalField.js';
 export { FIELD_FADE_SEC, LightField } from './render/driftLight/lightField.js';
+export { DENSE_MAX_AXIS, DENSE_MAX_HEIGHT, bakeDenseField, } from './render/driftLight/denseField.js';
+export { WorldLightField } from './render/driftLight/worldLightField.js';
+export { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './render/surfaceEffects.js';
 export { GI_SCREEN_MARCH, SCREEN_TRACE_BIAS_M, screenRayOrigin, traceScreen, } from './render/gi/traceScreen.js';
 export { FIELD_MARCH, coneRadiusAt, newFieldHit, traceField } from './render/gi/traceField.js';
 export { PROBE_VISIBILITY_SHARPNESS, bakeProbeVisibility, createProbeVisibility, probeUpdateSchedule, probeVisibilityWeight, sampleProbeVolume, visibleProbes, } from './render/gi/probeVolume.js';
@@ -266,7 +269,8 @@ export { isWeakGpuFamily } from './render/gpuCapability.js';
  * which is the right time for a boot log and too late for a decision.
  */
 export { describeGpu } from './render/gpuCapability.js';
-export { DEFAULT_POINT_LIGHT_VIEW_RANGE, createPointLightBuffer, selectPointLights, } from './render/pointLightSelection.js';
+export { DEFAULT_POINT_LIGHT_VIEW_RANGE, createPointLightBuffer, selectGridLights, selectPointLights, } from './render/pointLightSelection.js';
+export { LIGHT_GRID_MAX_CELLS, createLightGrid, gatherLights } from './render/lightGrid.js';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.js';
 export { computeLightMatrix } from './render/lightMatrix.js';
 export { PlumeRenderer } from './render/plumeRenderer.js';
@@ -306,6 +310,12 @@ export { SMOKE_FRAG } from './render/shaders/smoke.js';
 export { WaterRenderer } from './render/waterRenderer.js';
 export { MeshBuilder } from './geometry/meshBuilder.js';
 export { concatMeshes, placeMesh } from './geometry/meshConcat.js';
+export { emptySolid, mergeSolids, solidToMesh, solidVolume, transformSolid, } from './geometry/solid.js';
+export { solidBox, solidExtrude, solidPrism, solidQuad, solidRoundedBox, solidSweep, } from './geometry/solidFlat.js';
+export { solidCapsule, solidCone, solidCylinder, solidFrustum, solidHemisphere, solidIcosphere, solidLathe, solidSphere, solidTorus, solidTube, } from './geometry/solidRound.js';
+export { solidIntersect, solidSubtract, solidUnion } from './geometry/csg.js';
+export { boxBooleanCells, solidBoxBoolean } from './geometry/boxCsg.js';
+export { smoothSolidNormals } from './geometry/solidNormals.js';
 /* A tangent frame, which every map in the material track reads. */
 export { generateTangents } from './geometry/tangents.js';
 export { Spline, createSplineSample } from './geometry/spline.js';
@@ -474,6 +484,7 @@ export { parseSdfFont } from './render/sdfFont.js';
 export { DEFAULT_SDF_TEXT_STYLE, SdfTextLayout } from './render/sdfTextLayout.js';
 export { WindStreakRenderer } from './render/windStreakRenderer.js';
 export { buildTree } from './geometry/treeBuilder.js';
+export { batchBoxVisible, cullInstances, instancesBox } from './render/instanceCull.js';
 /*
  * Large worlds: the cell grid that streams and freezes, and the origin that rendering rebases
  * against while the simulation never does. See `world/rebase.ts` for why that asymmetry is the
@@ -483,3 +494,4 @@ export { cellBounds, cellCoord, cellCoordInRange, cellCoordsOf, cellIdFor, cellI
 export { renderOrigin, toRenderSpace, toWorldSpace } from './world/rebase.js';
 export { cameraPositionFrom, cellPredictor, createCellStream, pumpCellStream, setCellStreamOrigin, } from './world/cellStream.js';
 export { createFrozenCells, freezeCell, frozenEntities, frozenFingerprintContribution, isCellFrozen, thawCell, } from './world/freeze.js';
+export { HLOD_NONE, HlodSet, createHlodDraws, projectionScaleOf } from './world/hlod.js';

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

@@ -4,7 +4,7 @@ import type { ReadonlyMat4 } from 'gl-matrix';
 import type { MeshData } from '../mesh.ts';
 import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
-import type { MeshInstances } from '../instances.ts';
+import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -175,9 +175,23 @@ 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' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial'> & {
+}, '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' | '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' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial'> & {
     /** Upload a caller's image. See `SurfaceTextureHandle` for the boundary this guards. */
     createSurfaceTexture(source: TexImageSource, options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
+    /**
+     * Upload several images of one size as the layers of one array texture.
+     *
+     * The same handle a single image returns — every surface texture is an array, and a plain image
+     * is an array of one — so it goes wherever a texture goes: any map of `setMaterial`. A mesh picks
+     * its image per vertex with `MeshData.layers`, and every map of the material is read at that
+     * layer, so an albedo array and an emissive array built in one order pair image with glow by
+     * index. **A merged mesh wearing many images is then one draw and one material change.**
+     *
+     * Every image must be the same size: the device allocates one size for every layer, and the
+     * refusal names the first image that differs. A layer past the end reads the last one.
+     * `updateSurfaceTexture` refuses an array.
+     */
+    createSurfaceTextureArray(sources: readonly TexImageSource[], options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
     /**
      * Replace a texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -324,7 +338,7 @@ export type RendererApi = Omit<{
      * would wear one expression. Both are refused where the variant is built rather than dropped
      * quietly.
      */
-    createInstanced(mesh: MeshHandle, capacity: number): InstancedHandle;
+    createInstanced(mesh: MeshHandle, capacity: number, options?: InstancedOptions): InstancedHandle;
     /**
      * Push placement and colour to the device. Only `data.count` instances are written.
      *

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

@@ -0,0 +1,26 @@
+/**
+ * How a draw meets the medium between it and the eye: the value of the mesh shader's
+ * `uFogEnabled`, which both backends write from this one rule.
+ *
+ * **A surface recedes into the medium; light added to the frame fades in it.** A surface that
+ * covers what is behind it is mixed toward the medium's colour with distance, which is the haze
+ * standing in front of it. An additive draw covers nothing: what is behind it has already been
+ * fogged, and mixing the draw toward the medium's colour and then *adding* it puts that haze into
+ * the frame a second time. So a glow by day added the sky's grey in the shape of the glow, and
+ * added more of it the thicker the air — reported as solid grey cones under every street lamp on
+ * a hazy morning. Faded instead, added light loses what the medium scatters out of it and adds
+ * nothing of its own, which is how the same shader already treats the glow behind frosted glass.
+ *
+ * What fading gives up is the one thing mixing did for a glow: at great distance it disappears
+ * into the air instead of greying into it. That is what light in fog does. What would make it
+ * wrong is an additive draw standing for *lit air* rather than light — and that is what
+ * `drawLightVolume` is for, which is fogged by neither rule.
+ */
+/** Out of the medium entirely: `TranslucentMeshOptions.fog` set to false. */
+export declare const FOG_OFF = 0;
+/** Mixed toward the medium's colour with distance: every surface, and the pass's default. */
+export declare const FOG_RECEDE = 1;
+/** Scaled down by what the medium scatters and given none of its colour: added light. */
+export declare const FOG_FADE = 2;
+/** The medium rule for a draw that asked for fog or not, and adds its light or covers. */
+export declare function fogModeOf(fog: boolean, additive: boolean): number;

package/dist/render/backend/drawFog.js

@@ -0,0 +1,30 @@
+/**
+ * How a draw meets the medium between it and the eye: the value of the mesh shader's
+ * `uFogEnabled`, which both backends write from this one rule.
+ *
+ * **A surface recedes into the medium; light added to the frame fades in it.** A surface that
+ * covers what is behind it is mixed toward the medium's colour with distance, which is the haze
+ * standing in front of it. An additive draw covers nothing: what is behind it has already been
+ * fogged, and mixing the draw toward the medium's colour and then *adding* it puts that haze into
+ * the frame a second time. So a glow by day added the sky's grey in the shape of the glow, and
+ * added more of it the thicker the air — reported as solid grey cones under every street lamp on
+ * a hazy morning. Faded instead, added light loses what the medium scatters out of it and adds
+ * nothing of its own, which is how the same shader already treats the glow behind frosted glass.
+ *
+ * What fading gives up is the one thing mixing did for a glow: at great distance it disappears
+ * into the air instead of greying into it. That is what light in fog does. What would make it
+ * wrong is an additive draw standing for *lit air* rather than light — and that is what
+ * `drawLightVolume` is for, which is fogged by neither rule.
+ */
+/** Out of the medium entirely: `TranslucentMeshOptions.fog` set to false. */
+export const FOG_OFF = 0;
+/** Mixed toward the medium's colour with distance: every surface, and the pass's default. */
+export const FOG_RECEDE = 1;
+/** Scaled down by what the medium scatters and given none of its colour: added light. */
+export const FOG_FADE = 2;
+/** The medium rule for a draw that asked for fog or not, and adds its light or covers. */
+export function fogModeOf(fog, additive) {
+    if (!fog)
+        return FOG_OFF;
+    return additive ? FOG_FADE : FOG_RECEDE;
+}

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

@@ -21,7 +21,8 @@
 export interface DrawMaterialOptions {
     readonly opacity: number;
     readonly lit: boolean;
-    readonly fog: boolean;
+    /** How it meets the medium, as `fogModeOf` says; the pass's own is `FOG_RECEDE`. */
+    readonly fog: number;
     readonly toneMapped: boolean;
     /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
     readonly refracting: boolean;

package/dist/render/backend/materialChanges.js

@@ -17,9 +17,14 @@
  * What it gives up: a setter called with the value already set still counts, because it takes a
  * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
  */
+import { FOG_RECEDE } from './drawFog.js';
 /** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
 export function ownsMaterial(options) {
-    return (options.opacity < 1 || !options.lit || !options.fog || !options.toneMapped || options.refracting);
+    return (options.opacity < 1 ||
+        !options.lit ||
+        options.fog !== FOG_RECEDE ||
+        !options.toneMapped ||
+        options.refracting);
 }
 /** Whether the next draw shares the open material or opens a new one. */
 export class MaterialChanges {

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

@@ -1,21 +1,40 @@
 import type { MeshInstances } from '../../instances.ts';
 import type { Mesh } from '../../mesh.ts';
+import type { FrustumPlanes } from '../../../math/frustum.ts';
 /**
- * One mesh's per-instance buffer, bound to that mesh's own vertex array.
+ * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
  * The twin of the WebGPU batch and deliberately the same shape, because which floats go where is
- * a decision shared through `instances.ts` and only the binding is per-backend.
+ * a decision shared through `instances.ts` and only the binding is per-backend. The vertex array is
+ * the batch's rather than the mesh's (`Mesh.createInstanceArray`), which is what lets one mesh carry
+ * a batch per region.
  *
- * The staging array is allocated here and rewritten in place, so a frame re-uploading a moving
+ * **A culling batch holds a second buffer and array**, for the instances `cullInstances` keeps each
+ * camera draw. The full set stays in the first, because a shadow pass, a mirror and a probe each
+ * see a different part of the batch than the camera does, and they draw from it.
+ *
+ * Staging arrays are allocated here and rewritten in place, so a frame re-uploading or re-culling a
  * batch allocates nothing.
  */
 export declare class InstancedBatch {
     readonly mesh: Mesh;
     readonly capacity: number;
+    /** Whether the camera draw culls this batch. See `InstancedOptions.cull`. */
+    readonly cull: boolean;
+    /** The world box around every live instance, fitted at upload. See `instancesBox`. */
+    readonly box: Float32Array<ArrayBuffer>;
     private readonly buffer;
+    private readonly vao;
     private readonly staging;
-    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number);
-    /** Pack and push the live prefix, in one call. */
+    private readonly kept;
+    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean);
     upload(gl: WebGL2RenderingContext, data: MeshInstances): void;
+    /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
+    draw(gl: WebGL2RenderingContext, count: number): void;
+    /**
+     * Cull `data` against `frustum`, upload what survives into the second buffer and draw it. Returns
+     * how many were drawn — 0 draws nothing. Only for a batch made with `cull`.
+     */
+    drawCulled(gl: WebGL2RenderingContext, data: MeshInstances, frustum: FrustumPlanes): number;
     dispose(gl: WebGL2RenderingContext): void;
 }

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

@@ -1,34 +1,53 @@
-import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.js';
+import { cullInstances, instancesBox } from '../../instanceCull.js';
+import { INSTANCE_FLOATS, INSTANCE_STRIDE, createMeshInstances, packInstances, } from '../../instances.js';
 /**
- * One mesh's per-instance buffer, bound to that mesh's own vertex array.
+ * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
  * The twin of the WebGPU batch and deliberately the same shape, because which floats go where is
- * a decision shared through `instances.ts` and only the binding is per-backend.
+ * a decision shared through `instances.ts` and only the binding is per-backend. The vertex array is
+ * the batch's rather than the mesh's (`Mesh.createInstanceArray`), which is what lets one mesh carry
+ * a batch per region.
  *
- * The staging array is allocated here and rewritten in place, so a frame re-uploading a moving
+ * **A culling batch holds a second buffer and array**, for the instances `cullInstances` keeps each
+ * camera draw. The full set stays in the first, because a shadow pass, a mirror and a probe each
+ * see a different part of the batch than the camera does, and they draw from it.
+ *
+ * Staging arrays are allocated here and rewritten in place, so a frame re-uploading or re-culling a
  * batch allocates nothing.
  */
 export class InstancedBatch {
     mesh;
     capacity;
+    /** Whether the camera draw culls this batch. See `InstancedOptions.cull`. */
+    cull;
+    /** The world box around every live instance, fitted at upload. See `instancesBox`. */
+    box = new Float32Array([1, 1, 1, -1, -1, -1]);
     buffer;
+    vao;
     staging;
-    constructor(gl, mesh, capacity) {
-        const buffer = gl.createBuffer();
-        if (buffer === null)
-            throw new Error('InstancedBatch: createBuffer failed');
+    kept;
+    constructor(gl, mesh, capacity, cull = false) {
         this.mesh = mesh;
         this.capacity = capacity;
-        this.buffer = buffer;
+        this.cull = cull;
         this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
-        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-        gl.bufferData(gl.ARRAY_BUFFER, capacity * INSTANCE_STRIDE, gl.DYNAMIC_DRAW);
-        /* `DYNAMIC_DRAW` because a batch of vehicles is rewritten every frame — advisory, but a
-           driver told the truth can place the buffer where a rewrite is cheap. */
-        mesh.attachInstances(gl, buffer, INSTANCE_STRIDE);
+        this.buffer = allocate(gl, capacity);
+        this.vao = mesh.createInstanceArray(gl, this.buffer, INSTANCE_STRIDE);
+        if (cull) {
+            const buffer = allocate(gl, capacity);
+            this.kept = {
+                buffer,
+                vao: mesh.createInstanceArray(gl, buffer, INSTANCE_STRIDE),
+                instances: createMeshInstances(capacity),
+            };
+        }
+        else {
+            this.kept = null;
+        }
     }
-    /** Pack and push the live prefix, in one call. */
     upload(gl, data) {
+        if (this.cull)
+            instancesBox(data, this.mesh.bounds, this.box);
         const count = Math.min(data.count, this.capacity);
         if (count === 0)
             return;
@@ -36,7 +55,45 @@ export class InstancedBatch {
         gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
         gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
     }
+    /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
+    draw(gl, count) {
+        this.mesh.drawInstancesThrough(gl, this.vao, count);
+    }
+    /**
+     * Cull `data` against `frustum`, upload what survives into the second buffer and draw it. Returns
+     * how many were drawn — 0 draws nothing. Only for a batch made with `cull`.
+     */
+    drawCulled(gl, data, frustum) {
+        const kept = this.kept;
+        if (kept === null)
+            return 0;
+        const count = cullInstances(data, this.mesh.bounds, frustum, kept.instances);
+        if (count === 0)
+            return 0;
+        packInstances(kept.instances, this.staging);
+        gl.bindBuffer(gl.ARRAY_BUFFER, kept.buffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
+        this.mesh.drawInstancesThrough(gl, kept.vao, count);
+        return count;
+    }
     dispose(gl) {
+        gl.deleteVertexArray(this.vao);
         gl.deleteBuffer(this.buffer);
+        if (this.kept !== null) {
+            gl.deleteVertexArray(this.kept.vao);
+            gl.deleteBuffer(this.kept.buffer);
+        }
     }
 }
+/**
+ * An instance buffer sized to capacity. `DYNAMIC_DRAW` because a batch of vehicles is rewritten
+ * every frame — advisory, but a driver told the truth can place the buffer where a rewrite is cheap.
+ */
+function allocate(gl, capacity) {
+    const buffer = gl.createBuffer();
+    if (buffer === null)
+        throw new Error('InstancedBatch: createBuffer failed');
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, Math.max(1, capacity) * INSTANCE_STRIDE, gl.DYNAMIC_DRAW);
+    return buffer;
+}

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

@@ -15,6 +15,9 @@ import { GpuTimer } from '../../gpuTimer.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
 import { LightField } from '../../driftLight/lightField.ts';
 import type { LightFieldOptions, LightFieldSource } from '../../driftLight/lightField.ts';
+import type { DenseLightVolume } from '../../driftLight/denseField.ts';
+import { WorldLightField } from '../../driftLight/worldLightField.ts';
+import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts';
 /**
  * How far the rush's outermost tap reaches at full strength, in UV.
  *
@@ -71,7 +74,7 @@ import type { WindStreakOptions } from '../../windStreakRenderer.ts';
 import type { WindField } from '../../windField.ts';
 import type { FlockParams } from '../../flockRenderer.ts';
 import { InstancedBatch } from './instanced.ts';
-import type { MeshInstances } from '../../instances.ts';
+import type { InstancedOptions, MeshInstances } from '../../instances.ts';
 /** Reused each frame: which shader light slot each bound cubemap serves. */
 export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
 /** Lighting and atmosphere for a frame. The game decides what goes in it. */
@@ -108,6 +111,29 @@ export interface Environment extends Atmosphere {
      * how strongly.
      */
     nightFactor: number;
+    /**
+     * Seconds on the caller's clock, for the surfaces that animate — a sign's pulse, a ticker's
+     * scroll, a flipbook. The caller's rather than a clock read here, so a held clock holds every
+     * surface still and a replay replays them. 0 unless stated.
+     */
+    surfaceTime?: number;
+    /**
+     * How wet the world is, 0 to 1: upward surfaces darken and polish, except materials that say
+     * they stay dry. The scene-wide counterpart of `drawFilm`, which stays for a puddle. 0 unless
+     * stated.
+     */
+    wetness?: number;
+    /**
+     * The share of facade windows lit, 0 to 1, which a scene sets from its time of day. Windows switch
+     * on in steps by a per-window hash, so a rising share lights more windows rather than brightening
+     * the ones already lit. 0 unless stated.
+     */
+    litWindows?: number;
+    /**
+     * The share of windows that stay lit however late it gets, 0 to 1, so the small hours are not a
+     * dark city. 0 unless stated.
+     */
+    lateWindows?: number;
     /**
      * Emission that only shows where the dominant light does not reach, 0 and off by default.
      *
@@ -441,6 +467,31 @@ export interface LightVolumeDrawOptions {
  * boolean is refused everywhere else in this file.
  */
 export interface TranslucentMeshOptions {
+    /**
+     * Add this surface's light to what is behind it instead of covering it: a glow, a beam, a pool
+     * of light under a lamp. Its colour times its opacity is added and nothing is darkened, so black
+     * is invisible and overlapping glows brighten — which is why such surfaces are authored nearly
+     * black where they fade. **Order does not matter** to a sum, so an additive draw is never held
+     * for the order-independent pass; it is drawn where it is asked for. Write depth off with it
+     * (`depthWrite: false`) or a glow hides the glows behind it.
+     */
+    /**
+     * Drawn into the picture a reconstruction resolves, rather than after it. For a surface that
+     * moves with what it lies on — a glow on a wall, a pane in a window — whose one motion is that
+     * surface's, so the resolve can carry it with the surface.
+     *
+     * **Late is the default, and it is right for anything else.** A translucent surface writes no
+     * depth the motion pass could test and may move apart from what shows through it — a caption
+     * over a moving car — so a history can only smear it; after the upscale it is sharp and has none.
+     * **What late gives up** is the edge: drawn unjittered against a depth the jittered render
+     * covered, it meets a silhouette the render drew differently every frame, and a glow along an
+     * edge is let through on one frame and not the next. Reconstructed, it is resolved with the edge.
+     *
+     * Only a reconstructing frame draws anything late, so this changes nothing on WebGL2 or with
+     * `reconstruction` off. An order-independent blended set replays where it replays.
+     */
+    readonly reconstructed?: boolean;
+    readonly additive?: boolean;
     /**
      * `false` draws the mesh exactly its own vertex colour times its own texture, with no
      * ambient, sun, point lights, specular, reflectivity, grain or emissive touching it —
@@ -881,6 +932,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private oitActive;
     /** True while the queue is being replayed, so a replayed draw does not record itself again. */
     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. */
+    private oitWeight;
+    private ditherFade;
     /** 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`. */
@@ -963,6 +1019,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly taaDepthToViewZ;
     private readonly aoInvProjection;
     private readonly aoProjScale;
+    /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
+    private readonly aoOffset;
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -1054,12 +1112,15 @@ export declare class WebGL2Renderer implements RendererApi {
      * world. See `prepareStaticPointShadows`.
      */
     private pointShadowArray;
-    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
-    private iesTexture;
-    /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
+    /** The fixture atlas — cookies over profiles — allocated on first use. See `fixtureAtlas.ts`. */
+    private fixtureTexture;
+    /** The profiles as packed, kept so a new set of cookies can rebuild the atlas around them. */
+    private iesAtlas;
+    /** The cookie images, kept so a new set of profiles can rebuild the atlas around them. */
+    private cookieImages;
+    /** Rows of profile in the atlas. One until a consumer loads a profile, which is the row of ones. */
     private iesRows;
-    private cookieTexture;
-    /** Tiles in the cookie atlas. 0 is the white placeholder and the whole off path. */
+    /** Cookie tiles in the atlas. 0 is none, and the whole off path. */
     private cookieTiles;
     /** Horizontal planes each profile occupies. 1 unless something asymmetric was loaded. */
     private iesPlanes;
@@ -1358,6 +1419,11 @@ export declare class WebGL2Renderer implements RendererApi {
      * other half of the same question.
      */
     occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * Whether a world-space box is wholly behind the declared occluders — the tighter question for
+     * something that is a box, such as a region. False with no occlusion buffer. See `occluded`.
+     */
+    occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
     private readonly passes;
     /** Built once so invoking somebody else's pass allocates nothing. See `PassDefinition.draw`. */
     /**
@@ -1473,7 +1539,17 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setSpotCookies(images: readonly TexImageSource[]): void;
     setIesProfiles(profiles: readonly PhotometricProfile[]): void;
-    /** Bind the atlas and say how many rows it has. Always, for the reason `bindClusters` gives. */
+    /**
+     * The fixture atlas from the profiles and cookies in hand: the profiles' rows at the bottom, the
+     * cookies' tiles on top, one `RGBA16F` texture. See `fixtureAtlas.ts` for the layout.
+     *
+     * **Half float, matching what the other backend must use**: a 32-bit float texture is not
+     * filterable in core WebGPU, and both tables are curves and images that want linear filtering.
+     * Linear and clamped: a profile is sampled between two angles, and a cookie's own inset is what
+     * keeps a tile from its neighbour — clamping alone cannot, the seam being interior to the row.
+     */
+    private buildFixtureAtlas;
+    /** Bind the fixture atlas and say what is in it. Always, for the reason `bindClusters` gives. */
     private bindIesAtlas;
     private bindClusters;
     /**
@@ -1633,6 +1709,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * the consumer's decision. What it gains is a GPU object with sane sampler state.
      */
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): SurfaceTexture;
+    /**
+     * Upload several images of one size as the layers of one array, for a merged mesh that names a
+     * layer per vertex (`MeshData.layers`). One material binding then covers every image, which is
+     * what makes a block wearing forty facades one draw. Every layer must be the same size, and the
+     * refusal names the first that is not.
+     */
+    createSurfaceTextureArray(sources: readonly TexImageSource[], options?: SurfaceTextureOptions): SurfaceTexture;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1762,6 +1845,29 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setEnvironmentAmbient(_amount: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * One float of material state, into every flat program.
+     *
+     * **Every one, for `setMaterial`'s reason**: an instanced or skinned draw runs a program of its
+     * own and is entitled to the material its caller set before it. These setters wrote the plain
+     * program alone until 2026-09-30, so on this backend a batch drew with the pass defaults — grain
+     * full, no reflection, no relief — while the other backend, whose material block every variant
+     * reads, drew what was asked.
+     */
+    private writeFlatFloat;
+    /**
+     * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
+     * of detail of one thing.
+     *
+     * 0 is off and is what `bindMeshPass` restores. A positive amount keeps that share of the
+     * pattern's cells, a negative one keeps the complement, so the level fading in drawn at `t` and
+     * the one fading out at `-t` cover every pixel exactly once — no hole, no pixel drawn twice.
+     * Material state like `setSurfaceGrain`; instanced draws read it too, and shadow casters, which
+     * 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. */
+    private writeMode;
     /**
      * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
      *
@@ -1852,7 +1958,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * One batch per mesh: the attributes bind to the mesh's own vertex array, of which a mesh has
      * one. `Mesh.attachInstances` is what refuses a second, and says why.
      */
-    createInstanced(mesh: Mesh, capacity: number): InstancedBatch;
+    createInstanced(mesh: Mesh, capacity: number, options?: InstancedOptions): InstancedBatch;
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch: InstancedBatch, data: MeshInstances): void;
     /** Draw every live instance, opaque. */
@@ -3051,6 +3157,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * the volume is summed into the frame once every brick has landed.
      */
     createLightField(lights: readonly LightFieldSource[], options?: Omit<LightFieldOptions, 'falloff'>): LightField;
+    /**
+     * Hand a world's DriftLight volume to the renderer: every fixed light of a city, summed offline by
+     * `bakeDenseField`, standing in past the frame's exact choice. Replaces any field made before, of
+     * either kind; the scene calls `field.follow(buffer.complete, ...)` each frame as it would for
+     * `createLightField`, and marks the lights the volume summed `inLightField` so none is counted
+     * twice. See `driftLight/worldLightField.ts`.
+     */
+    createWorldLightField(volume: DenseLightVolume, options?: WorldLightFieldOptions): WorldLightField;
     /** Let go of the field and its volumes; the scene's lights are all exact again. */
     disposeLightField(): void;
     private forgetLightFieldVolumes;