@driftengine/core 3.61.0

package/dist/render/pointLightSelection.js

@@ -0,0 +1,301 @@
+/** Allocation-free selection and packing of point lights for a fixed shader budget. */
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.js';
+import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.js';
+export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
+/**
+ * How far out a light fades to nothing, in metres before its cull distance.
+ *
+ * One of the two boundaries a light can cross. The range is deliberately vast, so that
+ * a light never surprises the player by switching on in front of them — and a vaster
+ * range only helps if arriving at it is a ramp.
+ */
+const FADE_BAND_M = 40;
+/**
+ * How near the first excluded light has to be before the last chosen ones dim.
+ *
+ * The other boundary, and the one that actually flickers. A world carries more lights
+ * than `MAX_POINT_LIGHTS`, so somebody is always last, and membership used to be a
+ * step: the light holding the final slot contributed everything and the one behind it
+ * nothing. Ordinary camera drift traded them, and both the light and its shadow
+ * switched — reported, plainly, as lights that behave like on/off switches.
+ *
+ * Measured in a lamp-lit courtyard: six lamps and a brazier sit inside 8.7 m
+ * against a budget of eight, and a gate's two lights are 12.52 m away *each*,
+ * equidistant by construction. They straddle the cut, so exactly one of them was ever
+ * rendered and which one flipped as the camera orbited: one post shadowed, the
+ * identical one beside it bare.
+ *
+ * Hysteresis was tried here first and cannot fix this. A slower swap is still a swap
+ * and the loser is still hard off, and worse, an incumbent's advantage puts the
+ * newcomer's arrival *inside* the band rather than at its edge, so the crossfade it
+ * was paired with reintroduced the pop it exists to remove. Fading against the
+ * boundary subsumes it: at the tie both contenders are at nothing, so the trade is
+ * free, and nothing is sticky because nothing visible is at stake.
+ *
+ * Three metres dims only what is genuinely contested. A row of lamps every twelve
+ * metres never notices; two lights the same distance away always do. It is also long
+ * enough at running pace to cover a six-face bake, so a light finishes its shadow map
+ * while it is still too dim to show one.
+ */
+const CONTENTION_BAND_M = 3;
+/** Sort keys for the shadow list, which is ordered independently of the shaded one. */
+const shadowRank = new Float32Array(POINT_SHADOW_POOL);
+/**
+ * A buffer for the selection to fill, sized to what the caller can actually bind.
+ *
+ * **`capacity` exists because clustered lighting can carry far more than the shader's uniform
+ * arrays.** The froxel table takes up to `MAX_CLUSTERED_LIGHTS`, and this helper used to hand it
+ * sixteen whatever a world offered — so the capability was real and unreachable through the one
+ * path every consumer uses. A consumer with `RenderQuality.clusteredLights` on asks for a wider
+ * buffer; everything else takes the default and is unchanged.
+ *
+ * **`scratchDistance` grows with it**, and that is not incidental: the shaded list is kept sorted
+ * in it, so a buffer wider than the array holding its distances writes past the end. It was sized
+ * from `POINT_SHADOW_POOL` because the pool happened to be the larger of the two.
+ */
+export function createPointLightBuffer(capacity = MAX_POINT_LIGHTS) {
+    const shaded = Math.max(1, Math.floor(capacity));
+    return {
+        positions: new Float32Array(shaded * 3),
+        colors: new Float32Array(shaded * 3),
+        radii: new Float32Array(shaded),
+        sourceRadii: new Float32Array(shaded),
+        considered: 0,
+        count: 0,
+        sourceIndex: new Int32Array(shaded),
+        weights: new Float32Array(shaded),
+        directions: new Float32Array(shaded * 3),
+        coneCos: new Float32Array(shaded * 2),
+        /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
+           be shaped by whichever profile happened to load first. */
+        iesProfiles: new Float32Array(shaded).fill(-1),
+        scratchDistance: new Float32Array(Math.max(shaded, POINT_SHADOW_POOL)),
+        shadowIndex: new Int32Array(POINT_SHADOW_POOL),
+        shadowCount: 0,
+    };
+}
+/**
+ * Select nearest lights whose influence may still be visible and pack them in
+ * shader order. The caller owns `out`; no sort arrays or temporary objects are
+ * created in this per-frame path.
+ *
+ * **Two points, because the two lists answer two questions.** `x, y, z` is where the frame is
+ * being *shaded* from — the camera — and it orders and culls the shaded list. `castX, castY,
+ * castZ` is where whatever might *cast* is standing, and it orders and culls the shadow pool.
+ * `AGENTS.md` had already decided which point the pool belongs to: *"a character's shadow only
+ * has to exist near the light they are standing at"* — they, not the viewer.
+ *
+ * They were one argument until 2026-08-25, and a third-person camera is exactly where that
+ * hurts: it sits behind its subject, so a fire the subject is standing next to got **no map at
+ * all** whenever the camera was further from it than the fire's radius. The scene stayed
+ * perfectly lit, which is why nobody could tell it from a bake that never ran.
+ *
+ * What it gives up: three more numbers on an already-long parameter list, spelled as numbers
+ * rather than a vector to match the point above it. What would make it wrong: a consumer with
+ * several casters far apart, which one point cannot describe — the pool would then want a set of
+ * reference points and a rank over the nearest of them, which is a bigger change than this one
+ * and is not what any consumer here has.
+ *
+ * The default is the shading point, so an existing caller selects bit-identically: `castX = x`
+ * makes the distance the *same arithmetic on the same operands*, not merely a close number.
+ */
+export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRange = DEFAULT_POINT_LIGHT_VIEW_RANGE, castX = x, castY = y, castZ = z) {
+    out.count = 0;
+    out.shadowCount = 0;
+    /*
+     * How many the shaded list holds, read off the buffer rather than from the shader's budget.
+     * A caller that asked for a wider one gets it; the default is `MAX_POINT_LIGHTS` exactly.
+     */
+    const shadedCapacity = out.radii.length;
+    /* Everything offered, whether or not it wins a slot or is even in range. See `considered`. */
+    out.considered = sources.length;
+    /*
+     * The nearest light that did not make the set: the boundary the last chosen ones
+     * fade against. `Infinity` while the world has fewer lights in range than the
+     * shader binds, which is the case where nothing is contested and nothing dims.
+     */
+    let cutSq = Infinity;
+    for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+        const light = sources[sourceIndex];
+        if (light === undefined)
+            continue;
+        /*
+         * A light with no radius illuminates nothing, and it must not take a slot from
+         * one that does. Consumers switch sources on and off by their radius — an oil
+         * slick is dark until it catches, a floor marker until it is stood on — so a world
+         * carries far more sources than it ever lights at once, and without this a
+         * character standing among forty dark markers would have the braziers around them
+         * pushed out of the buffer by markers emitting nothing.
+         */
+        if (light.radius <= 0)
+            continue;
+        const dx = light.x - x;
+        const dy = light.y - y;
+        const dz = light.z - z;
+        const distanceSq = dx * dx + dy * dy + dz * dz;
+        const cullDistance = viewRange + light.radius;
+        if (distanceSq > cullDistance * cullDistance)
+            continue;
+        /*
+         * Two lists, kept apart on purpose.
+         *
+         * The **shaded** list is the shader's nearest `MAX_POINT_LIGHTS`, culled at
+         * `viewRange + radius` so a light fades out rather than cutting at its own edge.
+         *
+         * The **shadow** list is who gets a cubemap, and it uses a different, stricter
+         * test: a light only qualifies inside its own radius, where the falloff
+         * `1 - dist / radius` means it is actually lighting anything. That is `decb3a2`'s
+         * rule — *"Acquisition now uses the same range test as release"* — which the pool
+         * rewrite lost by driving slots from the shaded list instead. A lamp a hundred
+         * metres away then takes a pool slot, thrashes it, and starves the lamp overhead
+         * of the map it needs: flashing squares when that bug first shipped, shadows that
+         * exist only near an emitter now.
+         *
+         * Sharing one sorted list is what made them drift apart, so they do not share one.
+         */
+        let slot = out.count;
+        while (slot > 0 && (out.scratchDistance[slot - 1] ?? 0) > distanceSq)
+            slot--;
+        if (slot >= shadedCapacity) {
+            // Rejected outright, so it is a candidate for the boundary the set fades against.
+            if (distanceSq < cutSq)
+                cutSq = distanceSq;
+        }
+        else {
+            // Full, so making room drops whoever was last off the end — and that is the
+            // nearest light not in the set unless something nearer is rejected later.
+            if (out.count >= shadedCapacity) {
+                const displaced = out.scratchDistance[shadedCapacity - 1] ?? Infinity;
+                if (displaced < cutSq)
+                    cutSq = displaced;
+            }
+            const last = Math.min(out.count, shadedCapacity - 1);
+            for (let index = last; index > slot; index--) {
+                out.scratchDistance[index] = out.scratchDistance[index - 1] ?? 0;
+                out.radii[index] = out.radii[index - 1] ?? 0;
+                out.sourceRadii[index] = out.sourceRadii[index - 1] ?? 0;
+                out.sourceIndex[index] = out.sourceIndex[index - 1] ?? -1;
+                for (let component = 0; component < 3; component++) {
+                    out.positions[index * 3 + component] = out.positions[(index - 1) * 3 + component] ?? 0;
+                    out.colors[index * 3 + component] = out.colors[(index - 1) * 3 + component] ?? 0;
+                    out.directions[index * 3 + component] = out.directions[(index - 1) * 3 + component] ?? 0;
+                }
+                out.coneCos[index * 2] = out.coneCos[(index - 1) * 2] ?? 0;
+                out.coneCos[index * 2 + 1] = out.coneCos[(index - 1) * 2 + 1] ?? 0;
+                out.iesProfiles[index] = out.iesProfiles[index - 1] ?? -1;
+            }
+            out.scratchDistance[slot] = distanceSq;
+            out.sourceIndex[slot] = sourceIndex;
+            out.radii[slot] = light.radius;
+            out.sourceRadii[slot] = Math.max(light.sourceRadius, 0);
+            out.positions[slot * 3] = light.x;
+            out.positions[slot * 3 + 1] = light.y;
+            out.positions[slot * 3 + 2] = light.z;
+            const scale = flickerScale(light, timeSeconds);
+            out.colors[slot * 3] = light.r * scale;
+            out.colors[slot * 3 + 1] = light.g * scale;
+            out.colors[slot * 3 + 2] = light.b * scale;
+            /*
+             * **Normalised here rather than trusted**, because the cone is a comparison against a cosine
+             * and an un-normalised direction scales that cosine — so a vector of length 2 gives a cone of
+             * the wrong width, which reads as the angle having been set wrong rather than the vector.
+             * A zero-length direction is a light that declared no cone, and it takes the open pair.
+             */
+            const dx = light.dirX ?? 0;
+            const dy = light.dirY ?? 0;
+            const dz = light.dirZ ?? 0;
+            const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            const aimed = length > 1e-6 && light.coneOuterDeg !== undefined;
+            const inverse = aimed ? 1 / length : 0;
+            out.directions[slot * 3] = dx * inverse;
+            out.directions[slot * 3 + 1] = dy * inverse;
+            out.directions[slot * 3 + 2] = dz * inverse;
+            if (aimed) {
+                /*
+                 * Clamped so the inner edge never passes the outer. A caller that swaps them would
+                 * otherwise get `smoothstep` with its edges inverted, which is a cone that is dark in the
+                 * middle and bright at the rim — a picture nobody would attribute to two numbers being the
+                 * wrong way round.
+                 */
+                const outerDeg = Math.min(89.9, Math.max(0, light.coneOuterDeg ?? 45));
+                const innerDeg = Math.min(outerDeg, Math.max(0, light.coneInnerDeg ?? outerDeg * 0.75));
+                out.coneCos[slot * 2] = Math.cos((innerDeg * Math.PI) / 180);
+                out.coneCos[slot * 2 + 1] = Math.cos((outerDeg * Math.PI) / 180);
+            }
+            else {
+                out.coneCos[slot * 2] = POINT_LIGHT_COS_INNER;
+                out.coneCos[slot * 2 + 1] = POINT_LIGHT_COS_OUTER;
+            }
+            /*
+             * The profile applies to a point light as readily as to a spot: a bare bulb has a measured
+             * distribution too, and the arithmetic does not care whether a cone is also being applied.
+             * Restricting it to spots would be a smaller feature for no saving.
+             */
+            out.iesProfiles[slot] = light.iesProfile ?? -1;
+            if (out.count < shadedCapacity)
+                out.count++;
+        }
+        /*
+         * Inside its own radius, so it is lighting something and therefore has something
+         * to cast. Nearest first, capped at the pool, and independent of whether the
+         * shader had a slot left for it.
+         *
+         * **Measured from the caster and not from the camera**, and the guard and the rank read the
+         * same point on purpose: reading two would fill the pool nearest-to-camera and then evict
+         * the very lamp the subject is standing under, which is the shape of every pool bug this
+         * file already carries a paragraph about.
+         *
+         * Computed unconditionally rather than behind `castX === x`. At the default the operands are
+         * identical, so this is the same product of the same subtractions and the result is bit
+         * identical — a branch would buy a few flops per light and cost the guarantee that a caller
+         * who says nothing gets exactly what it got before.
+         */
+        // A light that animates its radius, or is simply not meant to cast, never takes
+        // a slot: it would be stale every frame and starve the lamps that do cast.
+        if (light.castsShadow === false)
+            continue;
+        const cx = light.x - castX;
+        const cy = light.y - castY;
+        const cz = light.z - castZ;
+        const castDistanceSq = cx * cx + cy * cy + cz * cz;
+        if (castDistanceSq >= light.radius * light.radius)
+            continue;
+        let shadowSlot = out.shadowCount;
+        while (shadowSlot > 0 && (shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq)
+            shadowSlot--;
+        if (shadowSlot >= POINT_SHADOW_POOL)
+            continue;
+        const lastShadow = Math.min(out.shadowCount, POINT_SHADOW_POOL - 1);
+        for (let index = lastShadow; index > shadowSlot; index--) {
+            shadowRank[index] = shadowRank[index - 1] ?? 0;
+            out.shadowIndex[index] = out.shadowIndex[index - 1] ?? -1;
+        }
+        shadowRank[shadowSlot] = castDistanceSq;
+        out.shadowIndex[shadowSlot] = sourceIndex;
+        if (out.shadowCount < POINT_SHADOW_POOL)
+            out.shadowCount++;
+    }
+    /*
+     * How present each of them is, now that the set — and with it the boundary — is
+     * known. A second pass over at most eight entries, which is why the cut can be a
+     * fact about the whole frame rather than a guess made light by light.
+     *
+     * The two boundaries are independent and a light can be near both, so it takes
+     * whichever says it is fainter.
+     */
+    const cut = Math.sqrt(cutSq);
+    for (let index = 0; index < out.count; index++) {
+        const distance = Math.sqrt(out.scratchDistance[index] ?? 0);
+        const cullDistance = viewRange + (out.radii[index] ?? 0);
+        const arriving = (cullDistance - distance) / FADE_BAND_M;
+        const contested = (cut - distance) / CONTENTION_BAND_M;
+        out.weights[index] = Math.max(0, Math.min(1, arriving, contested));
+    }
+}
+function flickerScale(light, timeSeconds) {
+    if (light.flicker <= 0)
+        return 1;
+    const phase = light.x * 0.7 + light.z * 1.3;
+    const wobble = Math.sin(timeSeconds * 11.3 + phase) * 0.55 + Math.sin(timeSeconds * 27.7 + phase * 2.1) * 0.45;
+    return 1 + light.flicker * wobble;
+}

package/dist/render/pointShadowArray.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The edge of one light's octahedral map.
+ *
+ * Matching a 512 cube face's angular density would need `512 * sqrt(6)`, about 1254, because a
+ * cube face covers a sixth of the sphere inside its own square. This is 1024, so texels are about
+ * 1.2x coarser in the worst direction — chosen because the wider filter this whole change unlocks
+ * is blurring the result anyway, and because 1024 costs 4.19 MB a layer against a cube's 6.29 MB.
+ */
+export declare const OCTAHEDRAL_EDGE = 1024;
+/**
+ * What a `PointShadowMap` needs of the array: somewhere to render a face, and somewhere to put it.
+ *
+ * An interface rather than the class, so a map can be built without a device at all — the pooling
+ * rules are worth testing on their own and none of them is about a texture.
+ */
+export interface PointShadowTarget {
+    beginFace(gl: WebGL2RenderingContext): void;
+    resolveFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+}
+/**
+ * Every point light's shadow as one array texture, and the scratch that fills it.
+ *
+ * **One scratch for the whole engine rather than one cube per pool slot**, which is the economy
+ * the whole design turns on. Each octahedral texel has exactly one dominant axis, so a cube face's
+ * region of the map is disjoint from the other five and is written in full the moment that face is
+ * resolved. A face is therefore consumed immediately, and a bake spread across frames — which is
+ * how bakes work here, a couple of faces at a time against `pointShadowBudget.ts` — never needs a
+ * second face to still be around.
+ *
+ * **The scratch is a separate texture and that is not tidiness.** WebGL2's rendering-feedback-loop
+ * check is per texture object rather than per image: a draw that samples the array while any layer
+ * of it is attached is `INVALID_OPERATION`, on a layer it does not even write. Measured on a probe
+ * before this file existed. So the resolve reads the scratch and writes the array, and the two are
+ * never the same object.
+ */
+export declare class PointShadowArray implements PointShadowTarget {
+    readonly texture: WebGLTexture;
+    /**
+     * How many layers this array holds: the point pool, the two live transition maps, and two more
+     * for each rectangle a world said would cast. See the constructor's `extraLayers`.
+     */
+    readonly layers: number;
+    private readonly framebuffer;
+    private readonly scratchTexture;
+    private readonly scratchFramebuffer;
+    /** Parked on the resolve's unit while the scratch is a render target. See `beginFace`. */
+    private readonly parked;
+    private readonly faceSize;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    constructor(gl: WebGL2RenderingContext, faceSize: number, lightCount: number, 
+    /**
+     * Layers above the point pool, for the rectangles a world says will cast.
+     *
+     * **Sized from the declaration for the same reason the point half is**, and it is the whole of
+     * what an area light costs in storage: `areaShadowLayerCount` counts two per casting rectangle
+     * and zero for a world whose rectangles do not cast, so a consumer that has not asked for this
+     * allocates exactly what it allocated before. Where they land is `firstAreaShadowLayer`, which
+     * is the same expression as the line below — one function, because the array sizing itself and
+     * the set handing out indices disagreeing by one would have every rectangle sampling a lamp's
+     * map.
+     */
+    extraLayers?: number);
+    /**
+     * Bind the scratch as the render target for one face of one bake, and clear it.
+     *
+     * **The previous face's resolve left the scratch bound for sampling, and it is about to be the
+     * target.** That is a rendering feedback loop, and WebGL2 answers a draw in one with
+     * `INVALID_OPERATION` and no pixels — which is not the resolve's own draw but the *casters*,
+     * because `depth.ts` declares `uPreviousShadowMap` on that unit and an active sampler is
+     * enough whether the shader branch reads it or not. Found by capturing `night-court` and
+     * `day-clock`, which bake while the shot is taken; `gilded-chamber` was silent, because it had
+     * nothing stale to bake.
+     *
+     * `beginShadowPass` carries the identical fix for the directional maps, and this is the same
+     * rule one level down. A complete 1x1 texture rather than `null`, because an unbound sampler
+     * is *incomplete* and a driver may fetch its descriptor before evaluating the branch that
+     * would have skipped it — see `emptyTexture.ts` for the card that page-faulted over it.
+     */
+    beginFace(gl: WebGL2RenderingContext): void;
+    /**
+     * Write the scratch's contents into `layer`'s region for `face`.
+     *
+     * `depthFunc(ALWAYS)` because this is a copy and not a render. The layer already holds whatever
+     * the previous bake of this light left in it, so a fragment that lost a comparison would leave
+     * half of one image and half of another — a shadow baked around two different places at once,
+     * which is the failure `PointShadowImage.planBake` exists to prevent one level up.
+     *
+     * Allocates nothing: the rotation is a module-scope scratch, and the pass draws three vertices
+     * from an empty vertex array.
+     */
+    resolveFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/pointShadowArray.js

@@ -0,0 +1,219 @@
+import { mat3 } from 'gl-matrix';
+import { createEmptyTexture2D } from './emptyTexture.js';
+import { LIVE_POINT_SHADOW_MAPS, POINT_SHADOW_POOL } from './lightBudget.js';
+import { pointShadowFaceRotation } from './pointShadowImage.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { OCTAHEDRAL_RESOLVE_FRAG, OCTAHEDRAL_RESOLVE_VERT } from './shaders/octahedralResolve.js';
+/**
+ * The edge of one light's octahedral map.
+ *
+ * Matching a 512 cube face's angular density would need `512 * sqrt(6)`, about 1254, because a
+ * cube face covers a sixth of the sphere inside its own square. This is 1024, so texels are about
+ * 1.2x coarser in the worst direction — chosen because the wider filter this whole change unlocks
+ * is blurring the result anyway, and because 1024 costs 4.19 MB a layer against a cube's 6.29 MB.
+ */
+export const OCTAHEDRAL_EDGE = 1024;
+/** Filled per resolved face, at module scope, because a bake runs inside the frame's budget. */
+const faceRotation = mat3.create();
+/**
+ * Every point light's shadow as one array texture, and the scratch that fills it.
+ *
+ * **One scratch for the whole engine rather than one cube per pool slot**, which is the economy
+ * the whole design turns on. Each octahedral texel has exactly one dominant axis, so a cube face's
+ * region of the map is disjoint from the other five and is written in full the moment that face is
+ * resolved. A face is therefore consumed immediately, and a bake spread across frames — which is
+ * how bakes work here, a couple of faces at a time against `pointShadowBudget.ts` — never needs a
+ * second face to still be around.
+ *
+ * **The scratch is a separate texture and that is not tidiness.** WebGL2's rendering-feedback-loop
+ * check is per texture object rather than per image: a draw that samples the array while any layer
+ * of it is attached is `INVALID_OPERATION`, on a layer it does not even write. Measured on a probe
+ * before this file existed. So the resolve reads the scratch and writes the array, and the two are
+ * never the same object.
+ */
+export class PointShadowArray {
+    texture;
+    /**
+     * How many layers this array holds: the point pool, the two live transition maps, and two more
+     * for each rectangle a world said would cast. See the constructor's `extraLayers`.
+     */
+    layers;
+    framebuffer;
+    scratchTexture;
+    scratchFramebuffer;
+    /** Parked on the resolve's unit while the scratch is a render target. See `beginFace`. */
+    parked;
+    faceSize;
+    program;
+    uniforms;
+    vao;
+    constructor(gl, faceSize, lightCount, 
+    /**
+     * Layers above the point pool, for the rectangles a world says will cast.
+     *
+     * **Sized from the declaration for the same reason the point half is**, and it is the whole of
+     * what an area light costs in storage: `areaShadowLayerCount` counts two per casting rectangle
+     * and zero for a world whose rectangles do not cast, so a consumer that has not asked for this
+     * allocates exactly what it allocated before. Where they land is `firstAreaShadowLayer`, which
+     * is the same expression as the line below — one function, because the array sizing itself and
+     * the set handing out indices disagreeing by one would have every rectangle sampling a lamp's
+     * map.
+     */
+    extraLayers = 0) {
+        this.faceSize = faceSize;
+        /*
+         * Sized from the world rather than from the maximum. `texStorage3D` is immutable, so the
+         * alternative is handing a three-light world the storage for twenty-two — which is the mistake
+         * `lightBudget.ts` calls the most expensive the renderer has made, wearing a new shape.
+         */
+        this.layers =
+            Math.min(lightCount, POINT_SHADOW_POOL) + LIVE_POINT_SHADOW_MAPS + Math.max(0, extraLayers);
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('PointShadowArray: createTexture failed');
+        this.texture = texture;
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+        gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.DEPTH_COMPONENT24, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, this.layers);
+        /* One storage level and no filtering, so textureLod(..., 0.0) is the only fetch there is. */
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        const scratchTexture = gl.createTexture();
+        if (scratchTexture === null)
+            throw new Error('PointShadowArray: createTexture failed');
+        this.scratchTexture = scratchTexture;
+        gl.bindTexture(gl.TEXTURE_2D, scratchTexture);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, faceSize, faceSize);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        this.parked = createEmptyTexture2D(gl);
+        const scratchFramebuffer = gl.createFramebuffer();
+        if (scratchFramebuffer === null)
+            throw new Error('PointShadowArray: createFramebuffer failed');
+        this.scratchFramebuffer = scratchFramebuffer;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, scratchFramebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, scratchTexture, 0);
+        /* Depth-only: without this WebGL expects a colour attachment. */
+        gl.drawBuffers([gl.NONE]);
+        gl.readBuffer(gl.NONE);
+        /*
+         * The resolve program, built **before** the completeness check below, because that check may
+         * return early on a lost context and every field has to be assigned by then. `PointShadowMap`
+         * and `ShadowMap` both hold that shape; here it is load-bearing rather than incidental, since
+         * `program`, `uniforms` and `vao` are all `readonly`.
+         */
+        this.program = compileProgram(gl, OCTAHEDRAL_RESOLVE_VERT, OCTAHEDRAL_RESOLVE_FRAG, 'octahedralResolve');
+        this.uniforms = uniformLocations(gl, this.program, 'octahedralResolve');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('PointShadowArray: createVertexArray failed');
+        this.vao = vao;
+        const framebuffer = gl.createFramebuffer();
+        if (framebuffer === null)
+            throw new Error('PointShadowArray: createFramebuffer failed');
+        this.framebuffer = framebuffer;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, 0);
+        gl.drawBuffers([gl.NONE]);
+        gl.readBuffer(gl.NONE);
+        /*
+         * Asked once, here, for the reason `pointShadowMap.ts` records at length: it is a synchronous
+         * query, so the driver must drain what it has queued before it can answer, and asking it per
+         * face put a pipeline flush inside the render loop for the life of the session — 95.6% of a
+         * 69 ms frame. Every layer shares one texture, one size and one format, so a configuration
+         * complete for layer 0 is complete for all of them, and nothing about that can change later.
+         */
+        const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+        if (status !== gl.FRAMEBUFFER_COMPLETE) {
+            /*
+             * A lost context reports every attachment unusable, and that is not a misconfiguration the
+             * caller can fix — see `planarReflection.ts`. Init still throws, because the context cannot
+             * be lost before it exists.
+             */
+            if (gl.isContextLost())
+                return;
+            throw new Error(`PointShadowArray: framebuffer incomplete (0x${status.toString(16)})`);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+    }
+    /**
+     * Bind the scratch as the render target for one face of one bake, and clear it.
+     *
+     * **The previous face's resolve left the scratch bound for sampling, and it is about to be the
+     * target.** That is a rendering feedback loop, and WebGL2 answers a draw in one with
+     * `INVALID_OPERATION` and no pixels — which is not the resolve's own draw but the *casters*,
+     * because `depth.ts` declares `uPreviousShadowMap` on that unit and an active sampler is
+     * enough whether the shader branch reads it or not. Found by capturing `night-court` and
+     * `day-clock`, which bake while the shot is taken; `gilded-chamber` was silent, because it had
+     * nothing stale to bake.
+     *
+     * `beginShadowPass` carries the identical fix for the directional maps, and this is the same
+     * rule one level down. A complete 1x1 texture rather than `null`, because an unbound sampler
+     * is *incomplete* and a driver may fetch its descriptor before evaluating the branch that
+     * would have skipped it — see `emptyTexture.ts` for the card that page-faulted over it.
+     */
+    beginFace(gl) {
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.parked);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+        gl.viewport(0, 0, this.faceSize, this.faceSize);
+        gl.clear(gl.DEPTH_BUFFER_BIT);
+    }
+    /**
+     * Write the scratch's contents into `layer`'s region for `face`.
+     *
+     * `depthFunc(ALWAYS)` because this is a copy and not a render. The layer already holds whatever
+     * the previous bake of this light left in it, so a fragment that lost a comparison would leave
+     * half of one image and half of another — a shadow baked around two different places at once,
+     * which is the failure `PointShadowImage.planBake` exists to prevent one level up.
+     *
+     * Allocates nothing: the rotation is a module-scope scratch, and the pass draws three vertices
+     * from an empty vertex array.
+     */
+    resolveFace(gl, layer, face, far, near) {
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.texture, 0, layer);
+        gl.viewport(0, 0, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE);
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.scratchTexture);
+        gl.uniform1i(this.uniforms['uFace'] ?? null, 0);
+        gl.uniform1i(this.uniforms['uFaceIndex'] ?? null, face);
+        gl.uniformMatrix3fv(this.uniforms['uFaceRotation'] ?? null, false, pointShadowFaceRotation(face, faceRotation));
+        gl.uniform1f(this.uniforms['uFar'] ?? null, far);
+        gl.uniform1f(this.uniforms['uNear'] ?? null, near);
+        gl.uniform1f(this.uniforms['uEdge'] ?? null, OCTAHEDRAL_EDGE);
+        gl.disable(gl.CULL_FACE);
+        gl.enable(gl.DEPTH_TEST);
+        gl.depthMask(true);
+        /*
+         * **Saved and restored rather than put back to a named compare.** This used to end with
+         * `depthFunc(LESS)`, which was the frame's compare when it was written and stopped being it
+         * the moment the engine could draw reversed: after one point-shadow copy the whole rest of the
+         * frame tested the wrong way, and a scene with point shadows lost most of its pixels. Reading
+         * the state back costs one `getParameter` on a path that already binds a framebuffer, and it
+         * cannot go stale the way a constant can.
+         */
+        const wasDepthFunc = gl.getParameter(gl.DEPTH_FUNC);
+        gl.depthFunc(gl.ALWAYS);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.depthFunc(wasDepthFunc);
+        gl.bindVertexArray(null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    dispose(gl) {
+        gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteFramebuffer(this.scratchFramebuffer);
+        gl.deleteTexture(this.texture);
+        gl.deleteTexture(this.scratchTexture);
+        gl.deleteTexture(this.parked);
+        gl.deleteProgram(this.program);
+        gl.deleteVertexArray(this.vao);
+    }
+}