@driftengine/core 3.61.0

package/src/render/pointShadowArray.ts

@@ -0,0 +1,276 @@
+import { mat3 } from 'gl-matrix';
+
+import { createEmptyTexture2D } from './emptyTexture.ts';
+import { LIVE_POINT_SHADOW_MAPS, POINT_SHADOW_POOL } from './lightBudget.ts';
+import { pointShadowFaceRotation } from './pointShadowImage.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { OCTAHEDRAL_RESOLVE_FRAG, OCTAHEDRAL_RESOLVE_VERT } from './shaders/octahedralResolve.ts';
+
+/**
+ * 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();
+
+/**
+ * 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 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: WebGLFramebuffer;
+  private readonly scratchTexture: WebGLTexture;
+  private readonly scratchFramebuffer: WebGLFramebuffer;
+  /** Parked on the resolve's unit while the scratch is a render target. See `beginFace`. */
+  private readonly parked: WebGLTexture;
+  private readonly faceSize: number;
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation>;
+  private readonly vao: WebGLVertexArrayObject;
+
+  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 = 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: WebGL2RenderingContext): void {
+    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: WebGL2RenderingContext,
+    layer: number,
+    face: number,
+    far: number,
+    near: number,
+  ): void {
+    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) as number;
+    gl.depthFunc(gl.ALWAYS);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.depthFunc(wasDepthFunc);
+
+    gl.bindVertexArray(null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    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);
+  }
+}

package/src/render/pointShadowBudget.ts

@@ -0,0 +1,305 @@
+/**
+ * Which point-shadow maps get to bake this frame, and in what order.
+ *
+ * Baking is six full passes over the static world per light, and the renderer used to
+ * do every stale one in the frame it noticed. That is fine in the steady state, where
+ * nothing is stale, and catastrophic on the frame it stops being true: walking into a
+ * courtyard makes eight lights stale at once, which is 48 passes in one frame. Measured on
+ * a fast machine at boot, that was two consecutive frames of 89 ms and 99 ms against an
+ * 8.3 ms budget — the hitch about a second after a page load, and a smaller one each
+ * time a new cluster of lamps comes into range.
+ *
+ * Spreading the same work over more frames costs nothing anybody can see. Eight lights
+ * at two faces a frame is 24 frames, a fifth of a second at 120 Hz, during which
+ * shadows resolve progressively instead of the whole game stopping.
+ *
+ * This module only decides the *order*. The renderer spends a face budget walking it,
+ * because lights need different numbers of faces depending on how far through a bake
+ * they already are.
+ */
+
+/**
+ * Order the stale maps so the ones with nothing to show go first.
+ *
+ * A light whose map has never been baked contributes no shadow at all until it has one
+ * (see `PointShadowSystem.bind`), so every frame it waits is a frame with a visibly
+ * unlit lamp. A light that has merely drifted past the rebake tolerance is still
+ * sampling a perfectly reasonable map from a few centimetres away, and can wait.
+ * Serving the second kind first would hold a missing shadow hostage to a nearly
+ * invisible correction.
+ *
+ * Within each group the caller's order is preserved, which is the shading pass's own
+ * light order and therefore already sorted by how much each light matters.
+ *
+ * Writes into `out` and returns how many entries it wrote; allocation-free because this
+ * runs every frame.
+ */
+export function planPointShadowBakes(
+  /** 1 where the map at that slot needs baking. */
+  stale: Uint8Array,
+  /** 1 where the map at that slot already holds a usable image. */
+  ready: Uint8Array,
+  count: number,
+  out: Int32Array,
+  /**
+   * 1 where this slot's map has gone stale on every recent frame.
+   *
+   * Optional: a caller that omits it gets the two-group order this had before.
+   */
+  chronic?: Uint8Array,
+): number {
+  let written = 0;
+  // Never baked: nothing to sample until this lands.
+  for (let slot = 0; slot < count && written < out.length; slot++) {
+    if (stale[slot] === 1 && ready[slot] !== 1) out[written++] = slot;
+  }
+  // Baked but drifted: correcting an image that is already close to right.
+  for (let slot = 0; slot < count && written < out.length; slot++) {
+    if (stale[slot] === 1 && ready[slot] === 1 && chronic?.[slot] !== 1) out[written++] = slot;
+  }
+  /*
+   * Last: the maps that will be stale again next frame whatever is done for them.
+   *
+   * A light that moves, or breathes its radius, invalidates its own map every frame — so
+   * a bake buys it one frame and is owed again immediately. Ordered by the caller's
+   * importance alone, which is all the drifted group above uses, such a light sits
+   * permanently ahead of a static one that drifted once and would then stay correct for
+   * an hour; it takes the spread budget forever and the static one never gets its
+   * correction. Importance is the right tie-break between two maps that will *keep* what
+   * they are given, and the wrong one when only one of them will.
+   *
+   * They are still served, and served in full when budget is left over, so a light that
+   * settles catches up on the next frame. They simply cannot hold a settling light
+   * hostage any more.
+   *
+   * This is the scheduling half of the problem only. Whether a light is *worth* a cubemap
+   * at all — a floor-level marker, a lamp riding a camera, a creature standing inside
+   * its own glow — is a question about the content, and `castsShadow` is where a consumer
+   * answers it. No ordering can.
+   */
+  if (chronic !== undefined) {
+    for (let slot = 0; slot < count && written < out.length; slot++) {
+      if (stale[slot] === 1 && ready[slot] === 1 && chronic[slot] === 1) out[written++] = slot;
+    }
+  }
+  return written;
+}
+
+/**
+ * The shaded lights that also cast, in the order they were shaded.
+ *
+ * `castsShadow: false` says a light is not worth a cubemap. `selectPointLights` honours
+ * that when it builds the *eligible* list, and that was taken for the whole promise — but
+ * the shaded set is a different list, a caller hands it to `updatePointShadows` as the set
+ * to bind, and a light in it was given a pool slot and baked whatever it had declared. So
+ * the flag held for a lamp out of range and quietly failed for the one in front of you,
+ * which is the only one whose bake is visible.
+ *
+ * It showed up as a shadow with nothing to throw it — a lamp that rides the camera
+ * declines to cast for exactly that reason, and cast anyway.
+ *
+ * Writes into `out` and returns how many it wrote; allocation-free, because this runs
+ * every frame.
+ */
+export function selectCastingLights(
+  lights: readonly { castsShadow?: boolean }[],
+  activeWorldIndices: Int32Array,
+  activeCount: number,
+  out: Int32Array,
+): number {
+  let written = 0;
+  for (let i = 0; i < activeCount && written < out.length; i++) {
+    const worldIndex = activeWorldIndices[i] ?? -1;
+    if (worldIndex < 0) continue;
+    if (lights[worldIndex]?.castsShadow === false) continue;
+    out[written++] = worldIndex;
+  }
+  return written;
+}
+
+/**
+ * How many consecutive frames a slot must be stale before it is treated as chronically so.
+ *
+ * A light that drifts past the rebake tolerance every frame — a wandering flame — would
+ * otherwise take a bake every frame and starve everything else. Three frames is long enough
+ * that a genuine move still rebakes promptly and short enough that a chronic one is demoted
+ * before it has cost much.
+ */
+const CHRONIC_STALE_FRAMES = 3;
+
+/** The per-slot scratch a bake round needs. Caller-owned; this runs every frame. */
+export interface BakeScratch {
+  readonly stale: Uint8Array;
+  readonly ready: Uint8Array;
+  readonly order: Int32Array;
+  readonly chronic: Uint8Array;
+  readonly staleRun: Uint8Array;
+  readonly staleOwner: Int32Array;
+}
+
+export function createBakeScratch(pool: number): BakeScratch {
+  return {
+    stale: new Uint8Array(pool),
+    ready: new Uint8Array(pool),
+    order: new Int32Array(pool),
+    chronic: new Uint8Array(pool),
+    staleRun: new Uint8Array(pool),
+    staleOwner: new Int32Array(pool).fill(-1),
+  };
+}
+
+/** What a pool must expose for a bake round to be planned over it. */
+export interface BakeablePool<M> {
+  readonly pooledCount: number;
+  readonly sampledCount: number;
+  readonly liveMapCount: number;
+  pooledLight(slot: number): number;
+  mapForLight(lightIndex: number): M | undefined;
+  liveOwner(slot: number): number;
+  liveMap(slot: number): M | undefined;
+}
+
+/** The one thing a bake round cannot do itself: put six faces of a world into a cubemap. */
+export type BakeFaces<M, L> = (map: M, light: L, casters: unknown, maxFaces: number) => number;
+
+/** What a map must answer for staleness to be decided. */
+export interface StaleCheck {
+  hasBaked: boolean;
+  matchesSource(
+    x: number,
+    y: number,
+    z: number,
+    range: number,
+    near: number,
+    sourceRadius: number,
+    tolerance: number,
+  ): boolean;
+}
+
+/** The light fields a bake round reads. */
+export interface BakeableLight {
+  x: number;
+  y: number;
+  z: number;
+  radius: number;
+  shadowNear: number;
+  sourceRadius: number;
+}
+
+/**
+ * Spend a frame's face budget across the pool, then refresh the live maps.
+ *
+ * **Every rule in here was bought with a measured frame and none of it is about a device.**
+ * Bakes are spread rather than done the instant they are noticed, because walking into a courtyard
+ * makes eight lights go stale at once — 48 passes over the static world in one frame, measured
+ * at 89 ms and 99 ms in two consecutive frames against an 8.3 ms budget. A slot that has never
+ * baked and is being *sampled* jumps the queue with the whole six, because a light with no
+ * image contributes nothing and a partial cubemap is worse than none; one such jump a frame, so
+ * a cluster coming into range cannot spend the whole budget at once. A slot that is stale every
+ * frame is demoted after three, because a wandering flame would otherwise starve the queue.
+ *
+ * A second implementation of any of that is a backend whose shadows arrive at different moments
+ * — which is not something a parity capture would attribute, because both frames look plausible.
+ * Hence one function, and `bake` as the only thing either backend supplies.
+ */
+export function runPointShadowBakes<M extends StaleCheck, L extends BakeableLight>(
+  pool: BakeablePool<M>,
+  lights: readonly L[],
+  facesPerFrame: number,
+  liveFacesPerFrame: number,
+  rebakeDistance: number,
+  faceCount: number,
+  scratch: BakeScratch,
+  staticCasters: unknown,
+  dynamicCasters: unknown,
+  bake: BakeFaces<M, L>,
+): void {
+  /*
+   * Across everything holding a slot, not only what is being shaded. A warm light baked now is
+   * a light that joins the sampled set without a six-face bill — which is the on/off a lamp
+   * used to make as it came into range.
+   */
+  const count = Math.min(pool.pooledCount, scratch.stale.length);
+  for (let slot = 0; slot < count; slot++) {
+    const lightIndex = pool.pooledLight(slot);
+    const light = lightIndex >= 0 ? lights[lightIndex] : undefined;
+    const map = lightIndex >= 0 ? pool.mapForLight(lightIndex) : undefined;
+    const stale =
+      light !== undefined &&
+      map !== undefined &&
+      !map.matchesSource(
+        light.x,
+        light.y,
+        light.z,
+        light.radius,
+        light.shadowNear,
+        light.sourceRadius,
+        rebakeDistance,
+      );
+    scratch.stale[slot] = stale ? 1 : 0;
+    scratch.ready[slot] = map !== undefined && map.hasBaked ? 1 : 0;
+
+    /* The run is per borrower: a slot changing hands starts its patience over. */
+    if (scratch.staleOwner[slot] !== lightIndex) {
+      scratch.staleOwner[slot] = lightIndex;
+      scratch.staleRun[slot] = 0;
+    }
+    const run = stale ? Math.min((scratch.staleRun[slot] ?? 0) + 1, CHRONIC_STALE_FRAMES) : 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;
+  for (let i = 0; i < planned && faces > 0; i++) {
+    const slot = scratch.order[i] ?? -1;
+    /*
+     * `pooledLight`, matching the loop that filled `stale`: resolving through the sampled list
+     * here would bake the wrong light for every warm slot.
+     */
+    const lightIndex = slot >= 0 ? pool.pooledLight(slot) : -1;
+    const light = lightIndex >= 0 ? lights[lightIndex] : undefined;
+    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);
+  }
+
+  /*
+   * Live maps contain movers only and are composed with the static maps in the shader. A second
+   * map exists only during an ownership crossfade.
+   *
+   * **Unlike a static map there is no staleness test to make** — the caster moved, that is what
+   * makes it live — **but there does have to be a ceiling, and there was not one.** This loop
+   * asked for the whole cubemap, per live map, every frame, outside `facesPerFrame` entirely.
+   * Measured on the consumer and on three of the engine's seven demos: `pointShadow.face`
+   * six times a frame, for ever, in scenes that were otherwise nine to fourteen passes. And
+   * `LIVE_POINT_SHADOW_MAPS` is two with the second waking up during an ownership handoff, which
+   * is precisely what running past a row of lamps is — so a courtyard paid twelve full passes over
+   * the dynamic casters a frame, which is where "it is only slow in the courtyard" came from.
+   *
+   * The faces round-robin under the budget instead, so a mover's shadow finishes over two or
+   * three frames rather than all inside one. What that costs is a shadow a frame or two behind
+   * a character. What it bought back was the frame rate to see it at all.
+   */
+  let liveFaces = Math.max(1, liveFacesPerFrame);
+  for (let slot = 0; slot < pool.liveMapCount && liveFaces > 0; slot++) {
+    const owner = pool.liveOwner(slot);
+    const light = owner >= 0 ? lights[owner] : undefined;
+    const map = pool.liveMap(slot);
+    if (light === undefined || map === undefined) continue;
+    /* Never wider than the cube itself: asking for more is asking for faces that do not exist. */
+    liveFaces -= bake(map, light, dynamicCasters, Math.min(liveFaces, faceCount));
+  }
+}