@driftengine/core 4.1.4 → 4.1.5

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

@@ -1066,6 +1066,21 @@ export declare class WebGL2Renderer implements RendererApi {
      * near plane needs the granted answer and not the wished-for one.
      */
     reversedDepth: boolean;
+    /**
+     * What to clear depth to, for the convention this context was actually granted.
+     *
+     * **`DEPTH_CLEAR` is compile-time and this must not be.** That constant is `REVERSED_DEPTH ? 0 :
+     * 1`, and `REVERSED_DEPTH` is what the engine wants rather than what a context gave — so on a
+     * context without `EXT_clip_control` the buffer was cleared to 0 while `depthFunc` was correctly
+     * set to `LEQUAL`, and **nothing in the scene could ever pass**: every fragment is at depth >= 0,
+     * and only depth <= 0 passes. The frame that reaches the screen is the colour clear.
+     *
+     * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**, as every consumer
+     * drawing one flat colour with its interface still on top, at a healthy 60 fps. The compare
+     * beside it was already runtime; this was the half that was not, and the asymmetry is what made
+     * it total rather than subtle.
+     */
+    private get depthClear();
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     private readonly sceneViewProj;
     /**

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

@@ -1,7 +1,7 @@
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
 import { mat4 } from 'gl-matrix';
-import { DEPTH_CLEAR, DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
+import { DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { PickableSet } from '../../pickable.js';
 import { TEMPORAL_HISTORY_BLEND, TemporalHistory, jitterOffset, jitterProjection, } from '../../temporalAa.js';
 import { DecalPass } from '../../decalPass.js';
@@ -45,7 +45,7 @@ import { packIesAtlas } from '../../iesProfile.js';
 import { MAX_AREA_LIGHTS } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { equirectToCubeFaces } from '../../equirectToCube.js';
-import { SKY_FRAG, SKY_VERT } from '../../shaders/sky.js';
+import { SKY_FRAG, skyVertFor } from '../../shaders/sky.js';
 import { DEPTH_FRAG, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
 import { PointShadowArray } from '../../pointShadowArray.js';
 import { ShadowMap } from '../../shadowMap.js';
@@ -749,6 +749,23 @@ export class WebGL2Renderer {
      * near plane needs the granted answer and not the wished-for one.
      */
     reversedDepth = false;
+    /**
+     * What to clear depth to, for the convention this context was actually granted.
+     *
+     * **`DEPTH_CLEAR` is compile-time and this must not be.** That constant is `REVERSED_DEPTH ? 0 :
+     * 1`, and `REVERSED_DEPTH` is what the engine wants rather than what a context gave — so on a
+     * context without `EXT_clip_control` the buffer was cleared to 0 while `depthFunc` was correctly
+     * set to `LEQUAL`, and **nothing in the scene could ever pass**: every fragment is at depth >= 0,
+     * and only depth <= 0 passes. The frame that reaches the screen is the colour clear.
+     *
+     * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**, as every consumer
+     * drawing one flat colour with its interface still on top, at a healthy 60 fps. The compare
+     * beside it was already runtime; this was the half that was not, and the asymmetry is what made
+     * it total rather than subtle.
+     */
+    get depthClear() {
+        return depthClearFor(this.reversedDepth);
+    }
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     sceneViewProj = new Float32Array(16);
     /**
@@ -1745,7 +1762,10 @@ export class WebGL2Renderer {
             }
         }
         this.filmUniforms = uniformLocations(gl, this.filmProgram, 'film');
-        this.skyProgram = compileProgram(gl, SKY_VERT, SKY_FRAG, 'sky');
+        /* The variant matching what this context was granted, not what the engine wants. See
+           `skyVertFor`: a sky written at the reversed far plane on a conventional context sits in the
+           middle of the depth range and paints over everything behind it. */
+        this.skyProgram = compileProgram(gl, skyVertFor(this.reversedDepth), SKY_FRAG, 'sky');
         this.skyUniforms = uniformLocations(gl, this.skyProgram, 'sky');
         this.scatterProgram = compileProgram(gl, SCATTER_VERT, SCATTER_FRAG, 'scatter');
         this.scatterUniforms = uniformLocations(gl, this.scatterProgram, 'scatter');
@@ -3139,12 +3159,13 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.pointShadowArray?.texture ?? this.emptyTexture2DArray);
         gl.uniform1i(uniforms[POINT_SHADOW_SAMPLER] ?? null, firstUnit);
         gl.uniform1iv(uniforms['uPointShadowLayer[0]'] ?? null, resolved.layers);
-        gl.uniform1fv(uniforms['uPointShadowFar[0]'] ?? null, resolved.far);
+        /* Origin and far plane in one row; see `uPointShadowProjection` in the preamble. */
+        gl.uniform4fv(uniforms['uPointShadowProjection[0]'] ?? null, resolved.projections);
         gl.uniform1fv(uniforms['uPointShadowNear[0]'] ?? null, resolved.near);
         gl.uniform1fv(uniforms['uPointShadowSize[0]'] ?? null, resolved.sourceRadius);
         gl.uniform1fv(uniforms['uPointShadowWeight[0]'] ?? null, resolved.presence);
         gl.uniform1iv(uniforms['uLivePointShadowLayer[0]'] ?? null, resolved.liveLayers);
-        gl.uniform1fv(uniforms['uLivePointShadowFar[0]'] ?? null, resolved.liveFar);
+        gl.uniform4fv(uniforms['uLivePointShadowProjection[0]'] ?? null, resolved.liveProjections);
         gl.uniform1fv(uniforms['uLivePointShadowNear[0]'] ?? null, resolved.liveNear);
         gl.uniform1fv(uniforms['uLivePointShadowSize[0]'] ?? null, resolved.liveSourceRadius);
         gl.uniform1fv(uniforms['uLivePointShadowWeight[0]'] ?? null, resolved.liveWeights);
@@ -3573,7 +3594,7 @@ export class WebGL2Renderer {
         shadowMap.end(this.gl);
         /* Back to the frame's sense; see `beginShadowPass` for why it left it. */
         this.gl.depthFunc(glDepthFuncEqual(this.gl));
-        this.gl.clearDepth(DEPTH_CLEAR);
+        this.gl.clearDepth(this.depthClear);
         this.gpuTimer.end();
         this.shadowPassActive = false;
         this.activeShadowMap = null;
@@ -3949,7 +3970,7 @@ export class WebGL2Renderer {
         finally {
             /* Back to the frame's sense, which `beginShadowPass` leaves the same way. */
             gl.depthFunc(glDepthFuncEqual(gl));
-            gl.clearDepth(DEPTH_CLEAR);
+            gl.clearDepth(this.depthClear);
             this.pointShadowCasters = null;
             this.depthPassCullsFaces = true;
         }

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

@@ -67,6 +67,10 @@ export declare class GpuPointShadowMap implements PointShadowSource {
     get far(): number;
     get near(): number;
     get sourceRadius(): number;
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX(): number;
+    get originY(): number;
+    get originZ(): number;
     get hasBaked(): boolean;
     get presence(): number;
     matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius?: number, tolerance?: number): boolean;

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

@@ -229,6 +229,16 @@ export class GpuPointShadowMap {
     get sourceRadius() {
         return this.image.sourceRadius;
     }
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX() {
+        return this.image.originX;
+    }
+    get originY() {
+        return this.image.originY;
+    }
+    get originZ() {
+        return this.image.originZ;
+    }
     get hasBaked() {
         return this.image.hasBaked;
     }

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

@@ -6233,11 +6233,16 @@ export class WebGPURenderer {
             }
             else {
                 this.writeShadowSelection(f, i, 'uPointShadow', resolved.layers, resolved.presence);
-                this.writeShadowParams(f, 'uPointShadowFar', resolved.far);
+                /*
+                 * A `vec4` row carrying the bake origin and the far plane, so `scatterInto` rather than
+                 * `writeShadowParams` — it reads the stride out of the generated layout instead of
+                 * counting rows, which is what AGENTS.md's 2026-09-20 alignment rule asks for.
+                 */
+                scatterInto(f, this.fragment.fields['uPointShadowProjection'], resolved.projections, 4);
                 this.writeShadowParams(f, 'uPointShadowNear', resolved.near);
                 this.writeShadowParams(f, 'uPointShadowSize', resolved.sourceRadius);
                 this.writeShadowSelection(f, i, 'uLivePointShadow', resolved.liveLayers, resolved.liveWeights);
-                this.writeShadowParams(f, 'uLivePointShadowFar', resolved.liveFar);
+                scatterInto(f, this.fragment.fields['uLivePointShadowProjection'], resolved.liveProjections, 4);
                 this.writeShadowParams(f, 'uLivePointShadowNear', resolved.liveNear);
                 this.writeShadowParams(f, 'uLivePointShadowSize', resolved.liveSourceRadius);
             }

package/dist/render/depthConvention.d.ts

@@ -101,6 +101,25 @@
 export declare const REVERSED_DEPTH = true;
 /** What a scene depth attachment is cleared to: the far plane. */
 export declare const DEPTH_CLEAR: number;
+/**
+ * The same value for a backend that learned its convention at runtime rather than at compile time.
+ *
+ * **`DEPTH_CLEAR` above says what the engine wants; this says what a context got.** Reversed depth
+ * on WebGL2 needs `EXT_clip_control`, and a context not granted it runs conventional depth while
+ * the constant still reads 0. Clearing to 0 with a `LEQUAL` compare rejects every fragment in the
+ * scene — every one sits at depth >= 0 and only depth <= 0 is admitted — so the frame that reaches
+ * the screen is the colour clear and nothing else.
+ *
+ * Reported from Firefox on Linux, which exposes no `EXT_clip_control`: every consumer drew one flat
+ * colour with its interface still on top, at a healthy sixty frames a second. The depth *compare*
+ * beside it was already chosen at runtime, and that asymmetry is what made this total rather than
+ * subtle — two halves of one convention would still have drawn a picture.
+ *
+ * **Here rather than in the backend** for the 2026-08-13 rule's first clause: the decision is
+ * backend-neutral and only the binding is per-backend. It is also what lets a test hold the clear
+ * and the compare to each other, which a private field on a renderer could not.
+ */
+export declare function depthClearFor(reversed: boolean): number;
 /** The WebGPU compare for "nearer than what is there". */
 export declare const DEPTH_COMPARE: GPUCompareFunction;
 /**

package/dist/render/depthConvention.js

@@ -101,6 +101,27 @@
 export const REVERSED_DEPTH = true;
 /** What a scene depth attachment is cleared to: the far plane. */
 export const DEPTH_CLEAR = REVERSED_DEPTH ? 0 : 1;
+/**
+ * The same value for a backend that learned its convention at runtime rather than at compile time.
+ *
+ * **`DEPTH_CLEAR` above says what the engine wants; this says what a context got.** Reversed depth
+ * on WebGL2 needs `EXT_clip_control`, and a context not granted it runs conventional depth while
+ * the constant still reads 0. Clearing to 0 with a `LEQUAL` compare rejects every fragment in the
+ * scene — every one sits at depth >= 0 and only depth <= 0 is admitted — so the frame that reaches
+ * the screen is the colour clear and nothing else.
+ *
+ * Reported from Firefox on Linux, which exposes no `EXT_clip_control`: every consumer drew one flat
+ * colour with its interface still on top, at a healthy sixty frames a second. The depth *compare*
+ * beside it was already chosen at runtime, and that asymmetry is what made this total rather than
+ * subtle — two halves of one convention would still have drawn a picture.
+ *
+ * **Here rather than in the backend** for the 2026-08-13 rule's first clause: the decision is
+ * backend-neutral and only the binding is per-backend. It is also what lets a test hold the clear
+ * and the compare to each other, which a private field on a renderer could not.
+ */
+export function depthClearFor(reversed) {
+    return reversed ? 0 : 1;
+}
 /** The WebGPU compare for "nearer than what is there". */
 export const DEPTH_COMPARE = REVERSED_DEPTH ? 'greater' : 'less';
 /**

package/dist/render/livePointShadowSet.js

@@ -155,6 +155,9 @@ export class LivePointShadowSet {
         out.liveFar.fill(1);
         out.liveNear.fill(0.01);
         out.liveSourceRadius.fill(0);
+        out.liveProjections.fill(0);
+        for (let k = 0; k < out.liveLayers.length; k++)
+            out.liveProjections[k * 4 + 3] = 1;
         /*
          * Zero, then written under the owning light below. The weights used to be a straight copy of
          * this set's own two, because the arrays were addressed by live slot; they are addressed by
@@ -188,6 +191,11 @@ export class LivePointShadowSet {
             out.liveFar[shaderSlot] = map.far;
             out.liveNear[shaderSlot] = map.near;
             out.liveSourceRadius[shaderSlot] = map.sourceRadius;
+            /* Where the image was rendered from, not where the light is now. See `projections`. */
+            out.liveProjections[shaderSlot * 4] = map.originX;
+            out.liveProjections[shaderSlot * 4 + 1] = map.originY;
+            out.liveProjections[shaderSlot * 4 + 2] = map.originZ;
+            out.liveProjections[shaderSlot * 4 + 3] = map.far;
             /*
              * The handover weight *and* the image's own arrival, multiplied.
              *

package/dist/render/pointShadowBudget.js

@@ -167,13 +167,62 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
             scratch.staleOwner[slot] = lightIndex;
             scratch.staleRun[slot] = 0;
         }
-        const run = stale ? Math.min((scratch.staleRun[slot] ?? 0) + 1, CHRONIC_STALE_FRAMES) : 0;
+        /*
+         * **The run decays rather than resetting, and it climbs past the threshold before it stops.**
+         *
+         * A light that wanders on a curve is not stale on *every* frame — near the turning points of
+         * its travel it moves less in a frame than the rebake tolerance, so a run that reset to zero
+         * lost the tracking allowance there and the map dropped back to two faces a frame. The shadow
+         * then travelled smoothly through the fast part of the wander and stepped through the slow
+         * part, which is not motion and not stillness: it reads as a vibration. Reported that way,
+         * against a brazier, once the tracking allowance was in.
+         *
+         * So the run is hysteresis. It climbs to twice the threshold, which buys a light that has
+         * earned the allowance three quiet frames before it loses it, and decays one frame at a time
+         * so a light that genuinely settles stops re-baking rather than holding a budget for ever.
+         */
+        const previous = scratch.staleRun[slot] ?? 0;
+        const run = stale
+            ? Math.min(previous + 1, CHRONIC_STALE_FRAMES * 2)
+            : Math.max(previous - 1, 0);
         scratch.staleRun[slot] = run;
         scratch.chronic[slot] = run >= CHRONIC_STALE_FRAMES ? 1 : 0;
     }
     const planned = planPointShadowBakes(scratch.stale, scratch.ready, count, scratch.order, scratch.chronic);
     let faces = facesPerFrame;
     let urgentSpent = false;
+    /*
+     * **One wandering light finishes its cube in the frame it started it**, the same allowance a
+     * light with no image at all gets, and for a reason that turns out to be the same one: a map
+     * dribbled out at two faces a frame is a map nobody can sample correctly until it lands.
+     *
+     * A cold light cannot be sampled *at all* until its six faces are in, so it takes the whole
+     * cube at once. A chronically stale one can be sampled throughout and is wrong in a quieter
+     * way: `planBake` pins the origin for the whole of a resumed bake, so six faces spread over
+     * three frames means the published origin steps once every third frame. The shader shoots from
+     * that origin, so the shadow it draws steps with it — reported on a brazier as motion that was
+     * "really fast, not smooth, snappy, and unrealistic", which is a 20 Hz sample of a flame that
+     * wanders about once a second.
+     *
+     * Given the cube in one frame the origin moves every frame and the shadow travels instead.
+     *
+     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
+     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. One is the light being shaded
+     * that most recently went stale, which is the one somebody is standing next to; the rest keep
+     * dribbling under the ordinary budget, and their shadows step rather than travel. That is the
+     * right way round: a shadow you are looking at moves, and a shadow across the square does not
+     * cost the frame.
+     *
+     * It is spent *after* the cold and settling groups, because `planPointShadowBakes` orders the
+     * chronic ones last — so a light arriving in range still gets its first image ahead of a flame
+     * refining one it already has.
+     *
+     * **What would make it wrong** is a caster set heavy enough that six passes over it does not
+     * fit the frame. Measured against a game whose whole static world is about 8,500 triangles in
+     * a handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
+     * raised or this given up, and `gpuTiming` is how to tell which.
+     */
+    let trackingSpent = false;
     for (let i = 0; i < planned && faces > 0; i++) {
         const slot = scratch.order[i] ?? -1;
         /*
@@ -185,11 +234,16 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
         const map = lightIndex >= 0 ? pool.mapForLight(lightIndex) : undefined;
         if (light === undefined || map === undefined)
             continue;
-        const cold = slot < pool.sampledCount && scratch.ready[slot] === 0;
-        const budget = cold && !urgentSpent ? faceCount : faces;
-        if (cold && !urgentSpent)
+        const sampled = slot < pool.sampledCount;
+        const cold = sampled && scratch.ready[slot] === 0;
+        const urgent = cold && !urgentSpent;
+        /* A light being shaded whose map will be stale again next frame however it is served. */
+        const tracking = !cold && sampled && scratch.chronic[slot] === 1 && !trackingSpent;
+        if (urgent)
             urgentSpent = true;
-        faces -= bake(map, light, staticCasters, budget);
+        if (tracking)
+            trackingSpent = true;
+        faces -= bake(map, light, staticCasters, urgent || tracking ? faceCount : faces);
     }
     /*
      * Live maps contain movers only and are composed with the static maps in the shader. A second

package/dist/render/pointShadowImage.d.ts

@@ -111,6 +111,18 @@ export declare class PointShadowImage {
     private pendingRange;
     private pendingNear;
     private pendingSourceRadius;
+    /**
+     * Where this image was rendered from, which is what a sampler has to shoot its ray from.
+     *
+     * **Not the light's position**, and the difference is the whole point: `matchesSource` lets a
+     * light drift up to the caller's rebake tolerance from here before the image is re-rendered,
+     * so for any light that wanders these two are apart on nearly every frame. A shader that
+     * builds its direction and its distance from the live light asks this picture a question the
+     * picture cannot answer. See `ResolvedPointShadows.origins`.
+     */
+    get originX(): number;
+    get originY(): number;
+    get originZ(): number;
     /** Whether this map holds an image worth sampling. False until a bake completes. */
     get hasBaked(): boolean;
     /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */
@@ -222,6 +234,10 @@ export interface PointShadowSource {
     readonly far: number;
     readonly near: number;
     readonly sourceRadius: number;
+    /** Where the image was rendered from. See `PointShadowImage.originX`. */
+    readonly originX: number;
+    readonly originY: number;
+    readonly originZ: number;
     /** Whether this map holds an image worth sampling. */
     readonly hasBaked: boolean;
     /** How present the image is, 0 to 1. */
@@ -253,6 +269,28 @@ export interface ResolvedPointShadows {
     readonly far: Float32Array;
     readonly near: Float32Array;
     readonly sourceRadius: Float32Array;
+    /**
+     * The projection each bound map was rendered under: origin in `xyz`, far plane in `w`, four
+     * floats a light. The origin is **not** the light's position.
+     *
+     * A light is allowed to drift `pointShadowRebakeDistance` from its image before the image is
+     * re-rendered — that tolerance is what stops a flame re-baking six faces of the static world
+     * every frame — so for anything that flickers these two are apart on nearly every frame. The
+     * shader builds both its sample direction and the distance it compares from this point, so the
+     * ray it shoots is the ray the picture was drawn along and the drift costs nothing.
+     *
+     * **It used to build them from the live light**, and the drift went straight into the
+     * comparison: `dist` moved one for one with it against a bias of a few centimetres, and the
+     * single-tap blocker search moved across the occluder's silhouette, swapping `occluderDistance`
+     * between the caster and nothing. Reported on a brazier at night as a hard square under the
+     * fire, flashing in time with the flame while the camera stood still.
+     *
+     * **The far plane rides in `w` rather than in an array of its own**, because a default-block
+     * `float[N]` spends a whole uniform vector per element: declared separately the origin cost
+     * sixteen rows on each of the two sets, which the budget ladder answers on a 256-vector
+     * device by halving `MAX_LIGHTS`. See `uPointShadowProjection` in the preamble.
+     */
+    readonly projections: Float32Array;
     /** How present each bound map is, so a re-baked one arrives rather than appears. */
     readonly presence: Float32Array;
     /** The live pair, by the same light index: a light owns at most one of the two. */
@@ -260,6 +298,8 @@ export interface ResolvedPointShadows {
     readonly liveFar: Float32Array;
     readonly liveNear: Float32Array;
     readonly liveSourceRadius: Float32Array;
+    /** The live pair's own, by the same rule and for the same reason. */
+    readonly liveProjections: Float32Array;
     readonly liveWeights: Float32Array;
 }
 export declare function createResolvedPointShadows(lights: number): ResolvedPointShadows;

package/dist/render/pointShadowImage.js

@@ -160,6 +160,24 @@ export class PointShadowImage {
     pendingRange = 0;
     pendingNear = 0;
     pendingSourceRadius = 0;
+    /**
+     * Where this image was rendered from, which is what a sampler has to shoot its ray from.
+     *
+     * **Not the light's position**, and the difference is the whole point: `matchesSource` lets a
+     * light drift up to the caller's rebake tolerance from here before the image is re-rendered,
+     * so for any light that wanders these two are apart on nearly every frame. A shader that
+     * builds its direction and its distance from the live light asks this picture a question the
+     * picture cannot answer. See `ResolvedPointShadows.origins`.
+     */
+    get originX() {
+        return this.x;
+    }
+    get originY() {
+        return this.y;
+    }
+    get originZ() {
+        return this.z;
+    }
     /** Whether this map holds an image worth sampling. False until a bake completes. */
     get hasBaked() {
         return this.baked;
@@ -329,11 +347,13 @@ export function createResolvedPointShadows(lights) {
         far: new Float32Array(lights),
         near: new Float32Array(lights),
         sourceRadius: new Float32Array(lights),
+        projections: new Float32Array(lights * 4),
         presence: new Float32Array(lights),
         liveLayers: new Int32Array(lights).fill(-1),
         liveFar: new Float32Array(lights),
         liveNear: new Float32Array(lights),
         liveSourceRadius: new Float32Array(lights),
+        liveProjections: new Float32Array(lights * 4),
         liveWeights: new Float32Array(lights),
     };
 }

package/dist/render/pointShadowMap.d.ts

@@ -46,6 +46,10 @@ export declare class PointShadowMap {
     get far(): number;
     get near(): number;
     get sourceRadius(): number;
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX(): number;
+    get originY(): number;
+    get originZ(): number;
     /** Whether this map holds an image worth sampling. False until a bake completes. */
     get hasBaked(): boolean;
     /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */

package/dist/render/pointShadowMap.js

@@ -54,6 +54,16 @@ export class PointShadowMap {
     get sourceRadius() {
         return this.image.sourceRadius;
     }
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX() {
+        return this.image.originX;
+    }
+    get originY() {
+        return this.image.originY;
+    }
+    get originZ() {
+        return this.image.originZ;
+    }
     /** Whether this map holds an image worth sampling. False until a bake completes. */
     get hasBaked() {
         return this.image.hasBaked;

package/dist/render/pointShadowSystem.js

@@ -272,6 +272,10 @@ export class PointShadowSystem {
         out.far.fill(1);
         out.near.fill(0.01);
         out.sourceRadius.fill(0);
+        /* Origin zero, far plane one: the same neutral the separate `far` array is filled with. */
+        out.projections.fill(0);
+        for (let k = 0; k < MAX_POINT_LIGHTS; k++)
+            out.projections[k * 4 + 3] = 1;
         out.presence.fill(0);
         for (let k = 0; k < MAX_POINT_LIGHTS; k++) {
             const map = this.mapForShaderSlot(k);
@@ -299,6 +303,11 @@ export class PointShadowSystem {
             out.far[light] = map.far;
             out.near[light] = map.near;
             out.sourceRadius[light] = map.sourceRadius;
+            /* Where the image was rendered from, not where the light is now. See `projections`. */
+            out.projections[light * 4] = map.originX;
+            out.projections[light * 4 + 1] = map.originY;
+            out.projections[light * 4 + 2] = map.originZ;
+            out.projections[light * 4 + 3] = map.far;
             out.presence[light] = map.presence;
             out.layers[light] = map.layer;
         }

package/dist/render/renderQuality.d.ts

@@ -154,10 +154,33 @@ export interface RenderQuality {
      * sampled lights flickering at once accounted for 174 of the frame's 296 draw
      * calls, and for the game being unplayable exactly where lamps cluster.
      *
-     * The default clears a flame's own wander with room to spare, because drift is
-     * measured from the baked origin and a wander can be caught at either extreme
-     * of its travel. A light that really moves still re-bakes; it just does so once
-     * per this much movement instead of once per frame.
+     * **It was 0.4 until 4.1.5, chosen to clear a flame's whole wander with room to spare** — so
+     * a flame never re-baked at all, and its shadow of the static world stood still while the live
+     * map under the same light, which is re-rendered every frame because it holds the movers, swung
+     * with the flame. One light, two shadows, visibly disagreeing about where it was. Reported as
+     * the runner's shadow following the fire and the brazier's not.
+     *
+     * **A millimetre instead, which is as near to "whenever it moved" as makes sense**, so a shadow
+     * travels with its light rather than freezing between re-bakes. A centimetre was tried first and
+     * left a visible vibration: a light wandering on a curve moves less than that in a frame near
+     * the turning points of its travel, so the shadow ran smoothly through the fast part and stepped
+     * through the slow part. What the tolerance is still for is not re-baking on arithmetic noise.
+     *
+     * A light that does not move never goes stale at any positive value, so the whole cost falls on
+     * the lights that need it, and it is bounded rather than proportional: one such light takes a
+     * whole cube in a frame and the rest dribble under the ordinary face budget.
+     *
+     * **What makes that affordable is not this number.** The 174-of-296 draw calls this paragraph
+     * used to cite was measured before `pointShadowFacesPerFrame` capped the whole static bake, and
+     * before `planPointShadowBakes` learned to put a chronically stale map behind every cold and
+     * settling one. A flame now spends leftover budget and can never hold another light's first
+     * image hostage. One such light also finishes its cube inside a single frame rather than
+     * dribbling it over three, which is what makes the motion smooth instead of stepped; see
+     * `pointShadowBudget.ts`.
+     *
+     * **What would make it wrong** is a caster set heavy enough that six passes over it does not
+     * fit the frame, where a stepped shadow is the better trade and this should go back up.
+     * `gpuTiming` is how to tell which, and it is a number rather than an opinion.
      */
     readonly pointShadowRebakeDistance: number;
     /**

package/dist/render/renderQuality.js

@@ -58,7 +58,7 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     directionalShadowDepthLayers: 2,
     directionalShadowMaxDistance: 6,
     directionalShadowMaxSlope: 3,
-    pointShadowRebakeDistance: 0.4,
+    pointShadowRebakeDistance: 0.001,
     pointShadowFacesPerFrame: 2,
     /*
      * Twelve, which is `LIVE_POINT_SHADOW_MAPS` cubemaps of six faces: exactly what the live