@driftengine/core 4.5.0 → 4.6.0

package/src/render/lightBudget.ts

@@ -143,22 +143,20 @@ export const ENVIRONMENT_TEXTURE_UNIT = EMISSIVE_TEXTURE_UNIT + 1;
 export const CLUSTER_TABLE_TEXTURE_UNIT = ENVIRONMENT_TEXTURE_UNIT + 1;
 
 /**
- * Where the photometric atlas binds: one row per IES profile, any number of them.
- *
- * **One unit for every profile a world holds, which is the whole reason it is an atlas.** A
- * fixture's distribution is a curve rather than an image, so a row of 128 floats holds one and a
- * texture holds as many as a consumer loads. Per-profile textures would have spent the remaining
- * units on the third fixture.
- *
- * **Spent unconditionally, for the same reason the froxel table is**, and the argument is at that
- * declaration: the lookup is a branch on a value rather than a permutation, so the sampler is
- * declared in every profile and a declared sampler needs a complete texture bound whether or not
- * the branch reads it. With no profile loaded that texture is a single row of ones, which is the
- * multiplicative identity — a row of zeros would switch off every light that reached it.
- *
- * The tenth of sixteen. `CAPABILITIES.md` §3 keeps the running count.
+ * Where the fixture atlas binds: a fixture's spot cookies and its photometric profiles, one texture.
+ *
+ * **Two tables in one binding since 2026-09-30**, which is the fold `textureUnitBudget.test.ts` asks
+ * the next sampler for: the widest lit shader bound fifteen of the sixteen fragment samplers WebGL2
+ * guarantees, and the cookie atlas and the photometric atlas were two small float tables read with
+ * `textureLod`, both 128 texels across. See `fixtureAtlas.ts` for the layout and why cookies sit on
+ * top.
+ *
+ * **Spent unconditionally, for the reason the froxel table is**: both lookups are branches on values
+ * rather than permutations, so the sampler is declared in every profile and a declared sampler needs
+ * a complete texture. With nothing loaded that is a single row of ones — the multiplicative
+ * identity, since a row of zeros would switch off every light that reached it.
  */
-export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
+export const FIXTURE_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
 
 /**
  * The joint palette, read by the **vertex** stage.
@@ -177,7 +175,7 @@ export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
  * What it costs is one of the five units left after the IES atlas. What would make it wrong is
  * the lit pass growing past sixteen, which `textureUnitBudget.test.ts` asserts against.
  */
-export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
+export const SKIN_PALETTE_TEXTURE_UNIT = FIXTURE_ATLAS_TEXTURE_UNIT + 1;
 
 /**
  * A mesh's morph deltas, also read by the vertex stage, and also out of this same sixteen.
@@ -188,22 +186,6 @@ export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
  */
 export const MORPH_DELTA_TEXTURE_UNIT = SKIN_PALETTE_TEXTURE_UNIT + 1;
 
-/**
- * Where the spot-light cookie atlas binds: one row of square tiles, one tile a cookie.
- *
- * **The fourteenth of sixteen, and two are left.** `CAPABILITIES.md` §3 keeps the running count —
- * and had been three units stale for as long as the IES atlas, the skin palette and the morph
- * deltas have existed, which is why the number is derived in `textureUnitBudget.test.ts` and only
- * quoted in prose.
- *
- * **Spent unconditionally, for the reason the froxel table and the IES atlas are**: a declared
- * sampler needs a complete texture bound whether or not the branch reads it, so a one-texel white
- * placeholder stands in it when no consumer has loaded a cookie. White rather than black, because
- * it multiplies a light's colour and a black stand-in would switch off every light that reached
- * it — the identity `packIesAtlas` chooses for the same reason.
- */
-export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
-
 /**
  * The colour the frame had already drawn, for a refracting surface to sample.
  *
@@ -217,7 +199,7 @@ export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
  * cubemaps became one array, which is what freed the units this one is spending.
  * `textureUnitBudget.test.ts` carries the phone that budget was written for.
  */
-export const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
+export const REFRACT_SCENE_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
 
 /**
  * DriftLight's brick index and atlas, the lit program's fourteenth and fifteenth fragment samplers.
@@ -238,12 +220,19 @@ export const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT = DRIFT_LIGHT_INDEX_TEXTURE_UNIT + 1
 export const SUN_GLASS_TINT_TEXTURE_UNIT = DRIFT_LIGHT_ATLAS_TEXTURE_UNIT + 1;
 
 /**
- * What each lamp keeps through glass (`pointGlassTint.ts`), the lit program's fifteenth fragment
- * sampler and the last one that leaves a sixteenth spare. Unit sixteen of the combined pool, which
- * WebGL2 guarantees thirty-two of; what a stage may declare is the sixteen, and this is fifteen.
+ * What each lamp keeps through glass (`pointGlassTint.ts`), a fragment sampler of the lit program.
+ * A unit of the combined pool, which WebGL2 guarantees thirty-two of; what a stage may declare is
+ * sixteen, which `textureUnitBudget.test.ts` counts from the shader source.
  */
 export const POINT_GLASS_TINT_TEXTURE_UNIT = SUN_GLASS_TINT_TEXTURE_UNIT + 1;
 
+/**
+ * Each surface layer's effects table (`surfaceEffects.ts`), bound beside the albedo array it
+ * describes. **Paid for by folding**: the cookie and photometric atlases became one fixture atlas
+ * to free the sampler this takes, so the lit stage still keeps one of its sixteen spare.
+ */
+export const SURFACE_EFFECTS_TEXTURE_UNIT = POINT_GLASS_TINT_TEXTURE_UNIT + 1;
+
 /**
  * A cookie's tile, in texels a side.
  *

package/src/render/lightGrid.ts

@@ -0,0 +1,130 @@
+/**
+ * A world's fixed lights bucketed once, so the frame's exact choice looks only at the lights near
+ * the eye rather than at every one of them.
+ *
+ * **The choice must be the full scan's, exactly, and needs no sort to be.** Both of the choice's
+ * lists break a tie in distance by source index, so the order the lights are met in cannot reach the
+ * result: what reaches it is the full scan's candidates minus only lights no query could keep —
+ * every light whose cell lies within `viewRange + maxRadius` of the eye is gathered, and the
+ * selection's own `viewRange + radius` test does the rest.
+ *
+ * **Cost stated**: built once, from where the lights stood. A light that moves or changes its reach
+ * must be re-bucketed by the caller — this is for the city's fixed thousands, and a scene's handful
+ * of movers stays with the plain scan.
+ *
+ * Nothing here allocates after construction; the gather writes into the grid's own scratch.
+ */
+import type { PointLightSource } from './pointLightSelection.ts';
+
+/** The most cells a grid may span, which keeps a stray light far away from costing a gigabyte. */
+export const LIGHT_GRID_MAX_CELLS = 1 << 22;
+
+export interface LightGrid {
+  readonly sources: readonly PointLightSource[];
+  /** Metres a cell spans on each axis. */
+  readonly cell: number;
+  /** The world position of cell (0, 0, 0)'s corner. */
+  readonly origin: readonly [number, number, number];
+  readonly dims: readonly [number, number, number];
+  /** Where cell `c`'s lights start in `lights`; `start[c + 1]` is where they end. */
+  readonly start: Uint32Array;
+  /** Source indices by cell, ascending within each. */
+  readonly lights: Uint32Array;
+  /** The largest reach of any source, which widens every query. */
+  readonly maxRadius: number;
+  /** The last gather, cell by cell: `gathered[0..count)`. */
+  readonly gathered: Int32Array;
+}
+
+/** Bucket `sources` into cells of `cell` metres. Built once; not a frame path. */
+export function createLightGrid(sources: readonly PointLightSource[], cell: number): LightGrid {
+  if (!(cell > 0)) throw new Error(`createLightGrid: a cell of ${String(cell)} metres`);
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  let maxRadius = 0;
+  for (const light of sources) {
+    minX = Math.min(minX, light.x);
+    minY = Math.min(minY, light.y);
+    minZ = Math.min(minZ, light.z);
+    maxX = Math.max(maxX, light.x);
+    maxY = Math.max(maxY, light.y);
+    maxZ = Math.max(maxZ, light.z);
+    maxRadius = Math.max(maxRadius, light.radius);
+  }
+  if (sources.length === 0) minX = minY = minZ = maxX = maxY = maxZ = 0;
+  const dims: [number, number, number] = [
+    Math.floor((maxX - minX) / cell) + 1,
+    Math.floor((maxY - minY) / cell) + 1,
+    Math.floor((maxZ - minZ) / cell) + 1,
+  ];
+  const cells = dims[0] * dims[1] * dims[2];
+  if (cells > LIGHT_GRID_MAX_CELLS) {
+    throw new Error(
+      `createLightGrid: these lights span ${dims.join(' × ')} cells of ${cell} m, past ` +
+        `${LIGHT_GRID_MAX_CELLS}; a larger cell fits them.`,
+    );
+  }
+  const cellOf = (light: PointLightSource): number =>
+    Math.floor((light.x - minX) / cell) +
+    dims[0] * (Math.floor((light.y - minY) / cell) + dims[1] * Math.floor((light.z - minZ) / cell));
+  const start = new Uint32Array(cells + 1);
+  for (const light of sources) {
+    const c = cellOf(light);
+    start[c + 1] = (start[c + 1] as number) + 1;
+  }
+  for (let c = 0; c < cells; c++) start[c + 1] = (start[c + 1] as number) + (start[c] as number);
+  const lights = new Uint32Array(sources.length);
+  const cursor = start.slice(0, cells);
+  for (let index = 0; index < sources.length; index++) {
+    const c = cellOf(sources[index] as PointLightSource);
+    lights[cursor[c] as number] = index;
+    cursor[c] = (cursor[c] as number) + 1;
+  }
+  return {
+    sources,
+    cell,
+    origin: [minX, minY, minZ],
+    dims,
+    start,
+    lights,
+    maxRadius,
+    gathered: new Int32Array(sources.length),
+  };
+}
+
+/**
+ * Gather into `grid.gathered`, cell by cell, every light whose cell lies within `reach` metres of
+ * (x, y, z) on each axis, and answer how many.
+ */
+export function gatherLights(
+  grid: LightGrid,
+  x: number,
+  y: number,
+  z: number,
+  reach: number,
+): number {
+  const { cell, origin, dims, start, lights, gathered } = grid;
+  const x0 = Math.max(0, Math.floor((x - reach - origin[0]) / cell));
+  const x1 = Math.min(dims[0] - 1, Math.floor((x + reach - origin[0]) / cell));
+  const y0 = Math.max(0, Math.floor((y - reach - origin[1]) / cell));
+  const y1 = Math.min(dims[1] - 1, Math.floor((y + reach - origin[1]) / cell));
+  const z0 = Math.max(0, Math.floor((z - reach - origin[2]) / cell));
+  const z1 = Math.min(dims[2] - 1, Math.floor((z + reach - origin[2]) / cell));
+  let count = 0;
+  for (let cz = z0; cz <= z1; cz++) {
+    for (let cy = y0; cy <= y1; cy++) {
+      const row = dims[0] * (cy + dims[1] * cz);
+      for (let cx = x0; cx <= x1; cx++) {
+        const c = row + cx;
+        for (let at = start[c] as number; at < (start[c + 1] as number); at++) {
+          gathered[count++] = lights[at] as number;
+        }
+      }
+    }
+  }
+  return count;
+}

package/src/render/mesh.ts

@@ -58,14 +58,6 @@ const ATTR_JOINTS = 11;
  */
 const ATTR_CHANNEL = 13;
 
-/**
- * The locations `attachInstances` claims, which a plain draw through the same array must not read.
- *
- * Eleven to fourteen are the model matrix's columns and fifteen is the tint. **Thirteen is also
- * the channel**, and eleven and twelve are the skinning pair — which cannot collide, because
- * `flatVert` refuses skinning with instancing. See `draw`.
- */
-const INSTANCE_COLUMNS = [11, 12, 13, 14, 15] as const;
 const ATTR_WEIGHTS = 12;
 
 /**
@@ -95,6 +87,9 @@ function applyConstant(
 export class Mesh {
   private readonly vao: WebGLVertexArrayObject;
   private readonly buffers: WebGLBuffer[] = [];
+  /** Every attribute bound from a buffer, so a batch can build a vertex array of its own. */
+  private readonly layout: { location: number; buffer: WebGLBuffer; size: number }[] = [];
+  private indexBuffer: WebGLBuffer | null = null;
   /**
    * The position and normal buffers, kept so `update` can rewrite them.
    *
@@ -104,7 +99,8 @@ export class Mesh {
   private readonly deformable: { positions: WebGLBuffer; normals: WebGLBuffer } | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
   private readonly positionFloats: number;
-  private readonly indexCount: number;
+  /** Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). */
+  readonly indexCount: number;
   /**
    * The constant values this mesh's *absent* attributes are shaded with, re-applied on
    * every draw.
@@ -227,7 +223,13 @@ export class Mesh {
     if (data.uvs === undefined) {
       gl.disableVertexAttribArray(ATTR_UV);
       this.constants.push({ location: ATTR_UV, value: ABSENT_ATTRIBUTE['uvs'] });
+    } else if (data.layers !== undefined) {
+      /* The texture-array layer rides as the third coordinate — every vertex location is spent —
+         so a layered mesh uploads (u, v, layer) packed. See `MeshData.layers`. */
+      this.attachAttribute(gl, ATTR_UV, packUvLayers(data.uvs, data.layers), 3);
     } else {
+      /* Two components; the shader's vec3 reads z as 0 by the GL rule for a missing component,
+         which is layer 0 — the only layer a plain texture has. */
       this.attachAttribute(gl, ATTR_UV, data.uvs, 2);
     }
 
@@ -313,6 +315,7 @@ export class Mesh {
     if (indexBuffer === null) throw new Error('createBuffer failed');
     this.buffers.push(indexBuffer);
     gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+    this.indexBuffer = indexBuffer;
     this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, data.indices, gl.STATIC_DRAW);
 
     gl.bindVertexArray(null);
@@ -322,28 +325,11 @@ export class Mesh {
   draw(gl: WebGL2RenderingContext): void {
     gl.bindVertexArray(this.vao);
     /*
-     * **A mesh with a batch has the instance columns enabled on this very array, and location 13
-     * is the channel.** `attachInstances` claims 11 to 14 for the model matrix and 15 for the
-     * tint; a `Mesh` owns one vertex array, so those bindings are still live for a *plain* draw
-     * through it — and `aChannel` then reads the third column of instance zero's matrix instead
-     * of the absent-attribute constant. For a placement with no rotation that column is
-     * `(0, 0, 1, 0)`, so `aChannel.y` is zero, `vSkyDirect = aChannel.y` scales the directional
-     * term to nothing, and the mesh renders lit by the hemispheric ambient alone — correct
-     * normals, correct albedo, no error, no warning.
-     *
-     * Found on `demo/instancing.ts`, which exists to draw two ranks of one box the two ways and
-     * compare them: the `drawMesh` rank's top face read (51, 30, 21) against the `drawInstanced`
-     * rank's (218, 110, 59), and 51 is exactly the ambient. WebGPU has no array to share and drew
-     * them alike, which is what made it visible at all.
-     *
-     * Disabled here and put back by `drawInstances`, rather than given the batch an array of its
-     * own: that is the larger change this class's own note about two batches already contemplates,
-     * and it wants one for a different reason. Three calls on a mesh that has a batch and none on
-     * a mesh that does not.
+     * No instance columns to disable: a batch draws through a vertex array of its own
+     * (`createInstanceArray`), so this array never carries them. It used to, and location 13 — the
+     * channel — then read the third column of instance zero's matrix on a plain draw, which lit a
+     * mesh by ambient alone on this backend and not the other.
      */
-    if (this.instanced) {
-      for (const location of INSTANCE_COLUMNS) gl.disableVertexAttribArray(location);
-    }
     // The VAO restores the arrays; these it cannot. See `constants`.
     for (const constant of this.constants) {
       const value = constant.value;
@@ -353,35 +339,30 @@ export class Mesh {
   }
 
   /**
-   * Bind one buffer's per-instance attributes to this mesh's vertex array.
+   * A vertex array for one instanced batch: every attribute this mesh binds from a buffer, its index
+   * buffer, and the batch's instance columns — the model matrix at 11 to 14, the tint at 15.
    *
-   * **One batch per mesh, and the vertex array is why.** A `Mesh` owns exactly one, so a second
-   * batch would rebind locations 11 to 15 on the array the first still draws through — and what
-   * comes out is one batch's instances placed by the other's matrices, which reads as a transform
-   * bug in the consumer's own code rather than as a misuse of this.
-   *
-   * **What would make it wrong** is a consumer legitimately wanting two batches of one mesh,
-   * which wants a vertex array per batch rather than a flag here.
+   * **A batch owns its own array**, which is what lets a mesh have more than one batch: a prop drawn
+   * once per region is one mesh and a batch per region. With one array a mesh had one batch, since a
+   * second would rebind the columns the first draws through and place one batch's instances by the
+   * other's matrices. The arrays share every buffer, so a batch costs its instances and nothing of
+   * the geometry. The caller deletes what this returns.
    */
-  attachInstances(gl: WebGL2RenderingContext, buffer: WebGLBuffer, stride: number): void {
-    if (this.instanced) {
-      throw new Error(
-        'Mesh: this mesh already has an instanced batch — a Mesh owns one vertex array, so a ' +
-          'second batch would rebind the attributes the first draws through.',
-      );
+  createInstanceArray(
+    gl: WebGL2RenderingContext,
+    instances: WebGLBuffer,
+    stride: number,
+  ): WebGLVertexArrayObject {
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('createVertexArray failed');
+    gl.bindVertexArray(vao);
+    for (const attribute of this.layout) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
+      gl.enableVertexAttribArray(attribute.location);
+      gl.vertexAttribPointer(attribute.location, attribute.size, gl.FLOAT, false, 0, 0);
     }
-    this.instanced = true;
-    this.instanceBuffer = buffer;
-    this.instanceStride = stride;
-    gl.bindVertexArray(this.vao);
-    this.bindInstanceColumns(gl, buffer);
-    gl.bindVertexArray(null);
-  }
-
-  /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
-  private bindInstanceColumns(gl: WebGL2RenderingContext, buffer: WebGLBuffer): void {
-    const stride = this.instanceStride;
-    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+    gl.bindBuffer(gl.ARRAY_BUFFER, instances);
     /* Four vec4 columns then a vec3 tint: a mat4 is not a vertex attribute in GLSL ES 300. */
     for (let column = 0; column < 4; column += 1) {
       const location = 11 + column;
@@ -392,24 +373,17 @@ export class Mesh {
     gl.enableVertexAttribArray(15);
     gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
     gl.vertexAttribDivisor(15, 1);
+    gl.bindVertexArray(null);
+    return vao;
   }
 
-  private instanceBuffer: WebGLBuffer | null = null;
-  private instanceStride = 0;
-
-  /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
-  private instanced = false;
-
-  /**
-   * Draw `count` instances through the attributes `attachInstances` bound.
-   *
-   * The constants are re-applied exactly as `draw` does — a vertex array restores the arrays and
-   * not the constant attributes, and an absent optional attribute is a constant here.
-   */
-  drawInstances(gl: WebGL2RenderingContext, count: number): void {
-    gl.bindVertexArray(this.vao);
-    /* Put back what `draw` disabled, if a plain draw of this mesh came first. See its note. */
-    if (this.instanceBuffer !== null) this.bindInstanceColumns(gl, this.instanceBuffer);
+  /** Draw `count` instances through a batch's own vertex array. See `createInstanceArray`. */
+  drawInstancesThrough(
+    gl: WebGL2RenderingContext,
+    vao: WebGLVertexArrayObject,
+    count: number,
+  ): void {
+    gl.bindVertexArray(vao);
     for (const constant of this.constants) {
       const value = constant.value;
       applyConstant(gl, constant.location, value);
@@ -472,6 +446,7 @@ export class Mesh {
     this.allocate(gl, gl.ARRAY_BUFFER, buffer, data, usage);
     gl.enableVertexAttribArray(location);
     gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    this.layout.push({ location, buffer, size });
     return buffer;
   }
 
@@ -579,3 +554,15 @@ export function createMeshIncremental(
   const mesh = new Mesh(gl, data, dynamic, true);
   return { mesh, upload: mesh.uploads(gl) };
 }
+
+/** Texture coordinates and layers interleaved as (u, v, layer), one row a vertex. */
+export function packUvLayers(uvs: Float32Array, layers: Float32Array): Float32Array {
+  const count = layers.length;
+  const packed = new Float32Array(count * 3);
+  for (let v = 0; v < count; v++) {
+    packed[v * 3] = uvs[v * 2] as number;
+    packed[v * 3 + 1] = uvs[v * 2 + 1] as number;
+    packed[v * 3 + 2] = layers[v] as number;
+  }
+  return packed;
+}

package/src/render/occlusion.ts

@@ -39,6 +39,9 @@ import type { Bounds } from '../math/bounds.ts';
 /** What an unwritten texel holds: the far plane, which occludes nothing. */
 const FAR = 1;
 
+/** Texels a tested rectangle may span at the level it is read from. See `boxBehind`. */
+const TEXELS_ACROSS = 8;
+
 export interface OcclusionOptions {
   /** Texels across. The height follows the aspect. */
   readonly width: number;
@@ -189,15 +192,47 @@ export class OcclusionBuffer {
     const radius = bounds.radius * Math.max(sx, sy, sz);
 
     /* The cube that contains the sphere, which contains the object. Conservative twice over. */
+    return this.boxBehind(x - radius, y - radius, z - radius, x + radius, y + radius, z + radius);
+  }
+
+  /**
+   * Whether a world-space box is entirely behind the declared occluders — the tighter question for
+   * something that is a box, where the cube around its sphere reaches far past it. **A flat region
+   * is the case it exists for**: a city block's sphere is half as deep underground as it is wide,
+   * nothing there occludes it, and the sphere test abstains for every block in the city. False
+   * whenever anything is uncertain, exactly as `occluded`.
+   */
+  occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean {
+    if (this.occluders === 0) return false;
+    if (!this.built) this.buildPyramid();
+    return this.boxBehind(
+      min[0] ?? 0,
+      min[1] ?? 0,
+      min[2] ?? 0,
+      max[0] ?? 0,
+      max[1] ?? 0,
+      max[2] ?? 0,
+    );
+  }
+
+  /** The shared test: a world box's corners projected, its rectangle tested against the pyramid. */
+  private boxBehind(
+    loX: number,
+    loY: number,
+    loZ: number,
+    hiX: number,
+    hiY: number,
+    hiZ: number,
+  ): boolean {
     let minX = Infinity;
     let minY = Infinity;
     let minZ = Infinity;
     let maxX = -Infinity;
     let maxY = -Infinity;
     for (let corner = 0; corner < 8; corner++) {
-      const px = corner & 1 ? x + radius : x - radius;
-      const py = corner & 2 ? y + radius : y - radius;
-      const pz = corner & 4 ? z + radius : z - radius;
+      const px = corner & 1 ? hiX : loX;
+      const py = corner & 2 ? hiY : loY;
+      const pz = corner & 4 ? hiZ : loZ;
       if (!this.project(px, py, pz, 0)) return false;
       minX = Math.min(minX, CORNERS[0] ?? 0);
       maxX = Math.max(maxX, CORNERS[0] ?? 0);
@@ -212,13 +247,22 @@ export class OcclusionBuffer {
     if (minX < 0 || minY < 0 || maxX > width || maxY > height) return false;
 
     /*
-     * The coarsest level whose texel is at least as wide as the rectangle, so the test reads at
-     * most two texels each way. `Math.log2` would say the same thing and is one of the calls this
-     * repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+     * The coarsest level at which the rectangle spans at most `TEXELS_ACROSS` texels, so the test
+     * reads at most that many plus one each way. `Math.log2` would say the same thing and is one of
+     * the calls this repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+     *
+     * **Eight, not one, since 2026-09-30.** At one the level's texel was as wide as the rectangle, and
+     * two such texels aligned to the grid span up to twice it — so anything whose rectangle came near
+     * an occluder's edge, or the buffer's own unwritten border row, read unwritten texels and
+     * abstained. That was every city region behind a row of buildings, whose rectangle sits just
+     * under the skyline; measured on a box seven metres wide behind a wall filling the view, which
+     * one abstained at and eight culls. Reading up to 81 texels instead of 4 costs a few dozen
+     * compares and keeps the answer exactly as conservative: the maximum over every texel the
+     * rectangle touches.
      */
     let level = 0;
     let span = Math.max(maxX - minX, maxY - minY);
-    while (span > 1 && level + 1 < this.levels.length) {
+    while (span > TEXELS_ACROSS && level + 1 < this.levels.length) {
       span *= 0.5;
       level++;
     }

package/src/render/pointLightSelection.ts

@@ -2,6 +2,8 @@
 
 import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.ts';
+import { gatherLights } from './lightGrid.ts';
+import type { LightGrid } from './lightGrid.ts';
 
 export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
 
@@ -43,8 +45,15 @@ const FADE_BAND_M = 40;
  */
 const CONTENTION_BAND_M = 3;
 
-/** Sort keys for the shadow list, which is ordered independently of the shaded one. */
-const shadowRank = new Float32Array(POINT_SHADOW_POOL);
+/**
+ * Sort keys for the shadow list, which is ordered independently of the shaded one.
+ *
+ * **Float64, and ties broken by source index**, the shaded list's rule. These were single precision
+ * compared against a double, so which of two lamps exactly as far away came first depended on
+ * which way the distance happened to round — and on the order the lamps were met, which is what a
+ * grid changes. Now the list is the same whatever order its candidates arrive in.
+ */
+const shadowRank = new Float64Array(POINT_SHADOW_POOL);
 
 /**
  * Every light in range this frame, by source index and squared distance, before the nearest are
@@ -344,6 +353,58 @@ export function selectPointLights(
   castX = x,
   castY = y,
   castZ = z,
+): void {
+  choose(sources, null, sources.length, x, y, z, out, timeSeconds, viewRange, castX, castY, castZ);
+}
+
+/**
+ * `selectPointLights` over a grid's sources, looking only at the lights near the eye: the same
+ * choice, tie for tie, for a world of thousands of fixed lights that the plain scan would visit
+ * every frame. See `lightGrid.ts` for why the result is the scan's exactly.
+ */
+export function selectGridLights(
+  grid: LightGrid,
+  x: number,
+  y: number,
+  z: number,
+  out: PointLightBuffer,
+  timeSeconds = 0,
+  viewRange = DEFAULT_POINT_LIGHT_VIEW_RANGE,
+  castX = x,
+  castY = y,
+  castZ = z,
+): void {
+  const count = gatherLights(grid, x, y, z, viewRange + grid.maxRadius);
+  choose(
+    grid.sources,
+    grid.gathered,
+    count,
+    x,
+    y,
+    z,
+    out,
+    timeSeconds,
+    viewRange,
+    castX,
+    castY,
+    castZ,
+  );
+}
+
+/** The choice itself, over every source or over the ones `visit` names, in source order. */
+function choose(
+  sources: readonly PointLightSource[],
+  visit: Int32Array | null,
+  visitCount: number,
+  x: number,
+  y: number,
+  z: number,
+  out: PointLightBuffer,
+  timeSeconds: number,
+  viewRange: number,
+  castX: number,
+  castY: number,
+  castZ: number,
 ): void {
   out.count = 0;
   out.shadowCount = 0;
@@ -362,7 +423,8 @@ export function selectPointLights(
   let cutSq = Infinity;
   let candidateCount = 0;
 
-  for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+  for (let visited = 0; visited < visitCount; visited++) {
+    const sourceIndex = visit === null ? visited : (visit[visited] as number);
     const light = sources[sourceIndex];
     if (light === undefined) continue;
     /*
@@ -431,7 +493,13 @@ export function selectPointLights(
     const castDistanceSq = cx * cx + cy * cy + cz * cz;
     if (castDistanceSq >= light.radius * light.radius) continue;
     let shadowSlot = out.shadowCount;
-    while (shadowSlot > 0 && (shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq) shadowSlot--;
+    while (
+      shadowSlot > 0 &&
+      ((shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq ||
+        ((shadowRank[shadowSlot - 1] ?? 0) === castDistanceSq &&
+          (out.shadowIndex[shadowSlot - 1] ?? -1) > sourceIndex))
+    )
+      shadowSlot--;
     if (shadowSlot >= POINT_SHADOW_POOL) continue;
     const lastShadow = Math.min(out.shadowCount, POINT_SHADOW_POOL - 1);
     for (let index = lastShadow; index > shadowSlot; index--) {