@driftengine/core 4.1.4 → 4.1.5

package/dist/render/shaders/sky.d.ts

@@ -1,10 +1,14 @@
 /**
- * Procedural gradient sky drawn as a single attribute-less fullscreen triangle.
- * Ray direction is reconstructed per-fragment from the inverse view-projection,
- * so the sky is correct under any camera. Drawn last at the far plane, so early-z wins —
- * and the far plane is 0 under reversed depth and 1 otherwise, which is why the value is
- * interpolated rather than written. A sky that says 1.0 in a reversed engine is drawn at the
- * *near* plane and covers the world; measured, that was 743,669 changed pixels of 921,600.
+ * The engine's own convention, which is what WebGPU always gets and what the WGSL is generated
+ * from. `scripts/wgsl.ts` reads this constant, so it stays a constant.
  */
 export declare const SKY_VERT: string;
+/**
+ * The same shader for a context that may not have been granted reversed depth.
+ *
+ * WebGL2 compiles GLSL directly and is the only backend that can run either way, so it asks for
+ * the one matching what it got. WebGPU never calls this: it uses the generated WGSL, where the far
+ * plane is reversed by construction.
+ */
+export declare function skyVertFor(reversed: boolean): string;
 export declare const SKY_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vNdc;\n\nuniform mat4 uInvViewProj;\nuniform vec3 uCameraPos;\nuniform vec3 uTopColor;\nuniform vec3 uHorizonColor;\nuniform vec3 uDeepColor;\nuniform vec3 uSunDir;\nuniform vec3 uSunColor;\nuniform float uSunDiscExponent;\nuniform vec3 uMoonDir;\nuniform vec3 uMoonColor;\nuniform float uMoonAngularRadius;\nuniform float uMoonPhase;\nuniform float uNightFactor;\nuniform vec2 uCloudOffset;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = hash21(i);\n  float b = hash21(i + vec2(1.0, 0.0));\n  float c = hash21(i + vec2(0.0, 1.0));\n  float d = hash21(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\n/** Three octaves is the ceiling \u2014 drop to two before cutting anything else. */\nfloat fbm(vec2 p) {\n  float v = valueNoise(p) * 0.5;\n  v += valueNoise(p * 2.03) * 0.3;\n  v += valueNoise(p * 4.01) * 0.2;\n  return v;\n}\n\nvoid main() {\n  vec4 world = uInvViewProj * vec4(vNdc, 1.0, 1.0);\n  vec3 dir = normalize(world.xyz / world.w - uCameraPos);\n\n  float t = dir.y;\n  vec3 col = t >= 0.0\n    ? mix(uHorizonColor, uTopColor, pow(min(t, 1.0), 0.55))\n    : mix(uHorizonColor, uDeepColor, min(-t * 1.8, 1.0));\n\n  // Celestial bodies belong to the sky, not to the void underneath. Seeing the\n  // sun below the horizon made the world read as unbounded in every direction;\n  // fading them out at the horizon leaves the deep reading as depth instead.\n  float aboveHorizon = smoothstep(-0.04, 0.06, dir.y);\n\n  /*\n   * Sunset.\n   *\n   * Low sunlight crosses far more atmosphere than high sunlight, and that path\n   * scatters the blue out of it \u2014 which is why the sun reddens as it drops and\n   * why the glow around it spreads into a band rather than staying a disc. Both\n   * effects peak right at the horizon and are gone within a few degrees of it,\n   * so they are driven by the sun's own elevation rather than by the clock.\n   *\n   * TWO EDGES, BECAUSE A SUNSET ENDS. This shipped with only the upper one, so every\n   * sun below the horizon read as maximum sunset and stayed there all the way to\n   * straight down \u2014 and a sun direction of (0, -1, 0) is what a night world writes to\n   * mean \"there is no sun in this sky\". A consumer measured the result on a black\n   * sun: 87% more red in the sky than the same frame with the sun pointing up, a warm\n   * band over a third of the picture in an arctic snowfield, and the world's own\n   * blue-grey horizon arriving with its channel order reversed. Four night worlds were\n   * not started over it, and this repository's own storm sea shipped it. The lower\n   * edge is where astronomical twilight ends, near -0.31, so the term now fades out\n   * over the same range the sky it models does.\n   *\n   * What it gives up: the glow is a function of the sun's elevation and nothing else,\n   * so a caller cannot place one where its own sun is not. That is deliberate \u2014 a knob\n   * here would let a world disagree with itself \u2014 but it is also what makes this wrong\n   * for a body that is not our sun in our atmosphere. A world lit by something that\n   * scatters differently needs its own term, not a wider edge here.\n   *\n   * Written ascending-and-inverted rather than as a descending smoothstep, whose\n   * result GLSL ES leaves undefined when edge0 >= edge1. Every implementation seen so\n   * far computes the ramp anybody would expect, which is why the descending form\n   * survived this long, but the spec does not owe us that.\n   */\n  float sunset = (1.0 - smoothstep(-0.03, 0.30, uSunDir.y)) *\n    smoothstep(-0.35, -0.05, uSunDir.y);\n  vec3 ember = vec3(1.0, 0.36, 0.13);\n\n  float s = max(dot(dir, uSunDir), 0.0);\n  // The disc itself reddens; the last sliver above the horizon is nearly blood\n  // orange, which is the moment the whole effect is remembered for.\n  vec3 discColor = mix(uSunColor, uSunColor * ember, sunset * 0.85);\n  col += discColor * (\n    pow(s, uSunDiscExponent) * 1.2 +\n    pow(s, max(uSunDiscExponent / 75.0, 1.0)) * 0.12\n  ) * aboveHorizon;\n\n  /*\n   * The band. Brightest toward the sun's bearing and hugging the horizon,\n   * falling off both with angle around the compass and with height \u2014 a sunset\n   * is a direction, not a uniform warm wash, and washing the whole dome is what\n   * makes a fake one look like a colour filter.\n   */\n  vec2 sunBearing = normalize(uSunDir.xz + vec2(1e-5));\n  vec2 viewBearing = normalize(dir.xz + vec2(1e-5));\n  float toward = max(dot(viewBearing, sunBearing), 0.0);\n  /*\n   * Measured from the horizon, and falling three times faster below it than above.\n   *\n   * This was abs(dir.y), which is symmetric, so the band was mirrored twenty-seven\n   * degrees down into the deep \u2014 visible in any world whose ground does not cover\n   * the lower half of the frame, and captured in the -Y face of every environment\n   * probe, where it tinted reflections warm. Nothing in the sky mirrors a sunset\n   * below the horizon; what is down there is ground, and the ground is drawn by\n   * somebody else.\n   *\n   * Not gated by aboveHorizon like the sun disc and the moon are: that factor is\n   * only 0.4 at a dir.y of zero, which is exactly where this term is brightest, so\n   * multiplying by it would cut the band's core to a third and change every sunset\n   * to fix a night. Falling faster below instead leaves everything at or above the\n   * horizon bit-for-bit as it was, and the horizon line itself unbroken. What it\n   * gives up: a camera under the world, or above a planet seen from outside its\n   * atmosphere, sees the glow end sooner than the geometry does.\n   */\n  float fromHorizon = dir.y >= 0.0 ? dir.y : -dir.y * 3.0;\n  float band = pow(1.0 - min(fromHorizon * 2.2, 1.0), 2.6);\n  col += ember * sunset * band * (0.18 + 0.75 * pow(toward, 2.2));\n\n  /*\n   * Belt of Venus: the sky opposite a setting sun takes a cool pink-violet from\n   * light already reddened on its way past. Subtle, but its absence is why an\n   * artificial sunset feels like it is only happening on one side.\n   */\n  float away = max(-dot(viewBearing, sunBearing), 0.0);\n  col += vec3(0.42, 0.28, 0.45) * sunset * band * away * 0.22;\n\n  /*\n   * Moon: a shaded procedural sphere-disc, not one dot subtracted from another.\n   * The local sphere normal gives a curved terminator and limb; lunar phase\n   * supplies the light direction around that sphere. Low-frequency noise adds\n   * maria without a texture file, while a faint earthshine keeps the dark limb\n   * just legible instead of cutting a mathematically black hole in the sky.\n   */\n  vec3 moonReference = abs(uMoonDir.y) < 0.98\n    ? vec3(0.0, 1.0, 0.0)\n    : vec3(1.0, 0.0, 0.0);\n  vec3 moonRight = normalize(cross(moonReference, uMoonDir));\n  vec3 moonUp = cross(uMoonDir, moonRight);\n  float moonRadius = clamp(uMoonAngularRadius, 0.001, 0.5);\n  vec2 moonUv = vec2(dot(dir, moonRight), dot(dir, moonUp)) / moonRadius;\n  float moonRadiusSq = dot(moonUv, moonUv);\n  float moonFacing = step(0.0, dot(dir, uMoonDir));\n  float moonDisc = (1.0 - smoothstep(0.90, 1.0, moonRadiusSq)) * moonFacing;\n  if (moonDisc > 0.0) {\n    float sphereZ = sqrt(max(1.0 - moonRadiusSq, 0.0));\n    vec3 surfaceNormal = normalize(vec3(moonUv, sphereZ));\n    float phaseAngle = uMoonPhase * 6.28318530718;\n    vec3 phaseLight = vec3(sin(phaseAngle), 0.0, -cos(phaseAngle));\n    float phaseShade = max(dot(surfaceNormal, phaseLight), 0.0);\n    float maria = valueNoise(moonUv * 3.2 + vec2(4.7, 9.1)) * 0.68 +\n      valueNoise(moonUv * 9.3 - vec2(7.4, 2.6)) * 0.32;\n    float albedo = mix(0.56, 1.02, maria);\n    float limb = mix(0.72, 1.0, sphereZ);\n    float earthshine = 0.035;\n    float lunarLight = earthshine + (1.0 - earthshine) * phaseShade;\n    col += uMoonColor * albedo * limb * lunarLight * moonDisc *\n      1.35 * uNightFactor * aboveHorizon;\n  }\n  float phaseIllumination = 0.5 - cos(uMoonPhase * 6.28318530718) * 0.5;\n  float moonHalo = (1.0 - smoothstep(1.0, 3.0, length(moonUv))) * moonFacing;\n  col += uMoonColor * moonHalo * 0.08 * phaseIllumination *\n    uNightFactor * aboveHorizon;\n\n  if (dir.y > 0.0) {\n    // Stars. Stereographic projection: unlike dir.xz/dir.y it stays finite and\n    // near-uniform all the way to the horizon, so stars don't smear into grain.\n    // Each cell holds one jittered *point* \u2014 lighting the whole cell would draw\n    // square blocks, which is what \"random pixels\" looks like.\n    if (uNightFactor > 0.0) {\n      vec2 p = dir.xz / (1.0 + dir.y) * 26.0;\n      vec2 cell = floor(p);\n      float h = hash21(cell);\n      if (h > 0.93) {\n        vec2 jitter = vec2(hash21(cell + 17.3), hash21(cell + 41.7));\n        float d = length(fract(p) - jitter);\n        float star = smoothstep(0.10, 0.0, d) * (0.4 + h * 0.6);\n        // Fade out near the horizon, where haze would swallow them anyway.\n        col += vec3(0.86, 0.91, 1.0) * star * uNightFactor * smoothstep(0.03, 0.3, dir.y);\n      }\n    }\n\n    // Clouds: banded value noise on a layer above the camera, carried by the\n    // world's wind \u2014 the same signal the smoke and the grass answer to, so the\n    // largest moving thing in frame agrees with the smallest.\n    // The floor on dir.y bounds the perspective stretch near the horizon.\n    if (dir.y > 0.02) {\n      vec2 uv = dir.xz / max(dir.y, 0.16) * 0.09 + uCloudOffset * 0.012;\n      float band = smoothstep(0.46, 0.60, fbm(uv));\n      float fade = smoothstep(0.02, 0.30, dir.y);\n      vec3 cloudCol = mix(uHorizonColor, vec3(1.0), 0.45) * mix(1.0, 0.32, uNightFactor);\n      col = mix(col, cloudCol, band * fade * 0.8);\n    }\n  }\n\n  // There is no outdoor sky inside a water column. Retain a little vertical\n  // gradient so the surface remains legible above and depth reads darker\n  // below, while celestial bodies and clouds disappear with the same smooth\n  // surface transition used by the geometry passes.\n  float waterLight = mix(0.62, 1.08, clamp(dir.y * 0.5 + 0.5, 0.0, 1.0));\n  col = mix(col, uUnderwaterColor * waterLight, uUnderwaterFactor);\n\n  outColor = vec4(col, 1.0);\n}\n";

package/dist/render/shaders/sky.js

@@ -7,7 +7,24 @@ import { glslFarDepth } from '../depthConvention.js';
  * interpolated rather than written. A sky that says 1.0 in a reversed engine is drawn at the
  * *near* plane and covers the world; measured, that was 743,669 changed pixels of 921,600.
  */
-export const SKY_VERT = `#version 300 es
+/**
+ * The source, as a function of which way depth actually runs.
+ *
+ * **Because on WebGL2 that is a runtime fact and this file is imported once.** Reversed depth there
+ * needs `EXT_clip_control`; a context that is not granted it runs conventional depth, and the
+ * renderer has a `reversedDepth` field saying so precisely because the two can disagree. This
+ * template used to bake `glslFarDepth()` at import, which reads the compile-time `REVERSED_DEPTH` —
+ * so on such a context the sky was written at `0.0` while the depth test ran conventionally, where
+ * `0.0` is the middle of the range rather than the far plane. The sky then beat everything in the
+ * far half of the scene.
+ *
+ * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**: the voxel sandbox drew
+ * only sky, the gilded chamber a single orange frame, and a consumer's world one flat colour with
+ * its interface still on top. Three symptoms, one cause, and the docstring above already named the
+ * mechanism in the other direction.
+ */
+function skySource(farDepth) {
+    return `#version 300 es
 const vec2 POS[3] = vec2[3](vec2(-1., -1.), vec2(3., -1.), vec2(-1., 3.));
 
 out vec2 vNdc;
@@ -15,9 +32,25 @@ out vec2 vNdc;
 void main() {
   vNdc = POS[gl_VertexID];
   /* The far plane, whichever way depth runs: see glslFarDepth. */
-  gl_Position = vec4(vNdc, ${glslFarDepth()}, 1.0);
+  gl_Position = vec4(vNdc, ${farDepth}, 1.0);
 }
 `;
+}
+/**
+ * The engine's own convention, which is what WebGPU always gets and what the WGSL is generated
+ * from. `scripts/wgsl.ts` reads this constant, so it stays a constant.
+ */
+export const SKY_VERT = skySource(glslFarDepth());
+/**
+ * The same shader for a context that may not have been granted reversed depth.
+ *
+ * WebGL2 compiles GLSL directly and is the only backend that can run either way, so it asks for
+ * the one matching what it got. WebGPU never calls this: it uses the generated WGSL, where the far
+ * plane is reversed by construction.
+ */
+export function skyVertFor(reversed) {
+    return reversed ? SKY_VERT : skySource('1.0');
+}
 export const SKY_FRAG = `#version 300 es
 precision highp float;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.1.4",
-    "@driftengine/physics": "4.1.4",
+    "@driftengine/drft": "4.1.5",
+    "@driftengine/physics": "4.1.5",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.1.4",
-    "@driftengine/network": "4.1.4",
-    "@driftengine/texture": "4.1.4"
+    "@driftengine/nav": "4.1.5",
+    "@driftengine/network": "4.1.5",
+    "@driftengine/texture": "4.1.5"
   }
 }

package/src/render/backend/webgl2/renderer.ts

@@ -2,10 +2,10 @@ import { FrameBudget } from '../budget.ts';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.ts';
 import { mat4 } from 'gl-matrix';
 import {
-  DEPTH_CLEAR,
   DEPTH_OFFSET_SIGN,
   GL_DEPTH_REMAP,
   MAX_DEPTH_LAYER,
+  depthClearFor,
   depthOffsetForLayer,
   GL_SHADOW_REMAP,
   REVERSED_DEPTH,
@@ -133,7 +133,7 @@ import {
 import type { PhotometricProfile } from '../../iesProfile.ts';
 import { equirectToCubeFaces } from '../../equirectToCube.ts';
 
-import { SKY_FRAG, SKY_VERT } from '../../shaders/sky.ts';
+import { SKY_FRAG, skyVertFor } from '../../shaders/sky.ts';
 import {
   DEPTH_FRAG,
   DEPTH_INSTANCED_VERT,
@@ -1370,6 +1370,23 @@ export class WebGL2Renderer implements RendererApi {
    * 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.
+   */
+  private get depthClear(): number {
+    return depthClearFor(this.reversedDepth);
+  }
   /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
   private readonly sceneViewProj = new Float32Array(16);
   /**
@@ -2520,7 +2537,10 @@ export class WebGL2Renderer implements RendererApi {
       }
     }
     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');
@@ -4134,12 +4154,13 @@ export class WebGL2Renderer implements RendererApi {
     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);
@@ -4669,7 +4690,7 @@ export class WebGL2Renderer implements RendererApi {
     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;
@@ -5117,7 +5138,7 @@ export class WebGL2Renderer implements RendererApi {
     } 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/src/render/backend/webgpu/pointShadowPass.ts

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

package/src/render/backend/webgpu/renderer.ts

@@ -7720,7 +7720,12 @@ export class WebGPURenderer implements RendererApi {
         this.clearShadowSelection(f, i, 'uLivePointShadowLayer', 'uLivePointShadowWeight');
       } 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(
@@ -7730,7 +7735,12 @@ export class WebGPURenderer implements RendererApi {
           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/src/render/depthConvention.ts

@@ -104,6 +104,28 @@ 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: boolean): number {
+  return reversed ? 0 : 1;
+}
+
 /** The WebGPU compare for "nearer than what is there". */
 export const DEPTH_COMPARE: GPUCompareFunction = REVERSED_DEPTH ? 'greater' : 'less';
 

package/src/render/livePointShadowSet.ts

@@ -182,6 +182,8 @@ export class LivePointShadowSet<M extends PointShadowSource> {
     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
@@ -214,6 +216,11 @@ export class LivePointShadowSet<M extends PointShadowSource> {
       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/src/render/pointShadowBudget.ts

@@ -244,7 +244,24 @@ export function runPointShadowBakes<M extends StaleCheck, L extends BakeableLigh
       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;
   }
@@ -259,6 +276,38 @@ export function runPointShadowBakes<M extends StaleCheck, L extends BakeableLigh
 
   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;
     /*
@@ -270,10 +319,14 @@ export function runPointShadowBakes<M extends StaleCheck, L extends BakeableLigh
     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) urgentSpent = true;
-    faces -= bake(map, light, staticCasters, budget);
+    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;
+    if (tracking) trackingSpent = true;
+    faces -= bake(map, light, staticCasters, urgent || tracking ? faceCount : faces);
   }
 
   /*

package/src/render/pointShadowImage.ts

@@ -202,6 +202,27 @@ export class PointShadowImage {
   private pendingNear = 0;
   private 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(): number {
+    return this.x;
+  }
+
+  get originY(): number {
+    return this.y;
+  }
+
+  get originZ(): number {
+    return this.z;
+  }
+
   /** Whether this map holds an image worth sampling. False until a bake completes. */
   get hasBaked(): boolean {
     return this.baked;
@@ -401,6 +422,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. */
@@ -433,6 +458,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. */
@@ -440,6 +487,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;
 }
 
@@ -460,11 +509,13 @@ export function createResolvedPointShadows(lights: number): ResolvedPointShadows
     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/src/render/pointShadowMap.ts

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

package/src/render/pointShadowSystem.ts

@@ -343,6 +343,9 @@ export class PointShadowSystem<M extends PointShadowSource> {
     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++) {
@@ -369,6 +372,11 @@ export class PointShadowSystem<M extends PointShadowSource> {
       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/src/render/renderQuality.ts

@@ -162,10 +162,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;
   /**
@@ -815,7 +838,7 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = 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

package/src/render/shaders/flat/main.ts

@@ -990,7 +990,7 @@ export const MAIN_GLSL = `void main() {
 #if POINT_SHADOWS
       float grazing = 1.0 - ndl;
       float normalOffset = (0.06 + dist * 0.05) * grazing * grazing + 0.02;
-      vec3 shadowFrom = (vWorldPos + n * normalOffset) - lightPos;
+      vec3 receiverPoint = vWorldPos + n * normalOffset;
 
       /*
        * uPointShadowWeight is how present the cubemap is, and it is the difference
@@ -1031,8 +1031,15 @@ export const MAIN_GLSL = `void main() {
           pointShadow(
             uPointShadows,
             float(layer),
-            shadowFrom,
-            uPointShadowFar[shadowRead],
+            /*
+             * **From where the map was baked, not from where the light is.** The two are apart
+             * by up to \`pointShadowRebakeDistance\` for anything that wanders, and both things
+             * this asks the picture move with that gap: the distance it compares against the
+             * stored one, and which texel the single-tap blocker search lands in. See
+             * \`uPointShadowOrigin\`.
+             */
+            receiverPoint - uPointShadowProjection[shadowRead].xyz,
+            uPointShadowProjection[shadowRead].w,
             uPointShadowNear[shadowRead],
             uPointShadowSize[shadowRead]
           ),
@@ -1051,8 +1058,9 @@ export const MAIN_GLSL = `void main() {
         liveOccl = pointShadow(
           uPointShadows,
           float(liveLayer),
-          shadowFrom,
-          uLivePointShadowFar[shadowRead],
+          /* Its own bake origin, for the reason the static layer above gives. */
+          receiverPoint - uLivePointShadowProjection[shadowRead].xyz,
+          uLivePointShadowProjection[shadowRead].w,
           uLivePointShadowNear[shadowRead],
           uLivePointShadowSize[shadowRead]
         );