@driftengine/core 4.5.0 → 4.6.1

package/dist/render/instanceCull.js

@@ -0,0 +1,160 @@
+import { boxInFrustum } from '../math/frustum.js';
+/** How many planes a frustum holds, four floats each. */
+const PLANES = 6;
+/**
+ * Indices a culling batch must draw, all its instances together, before culling it instance by
+ * instance pays; below it the batch is drawn whole once its box is seen (`batchBoxVisible`).
+ *
+ * **What a per-instance cull costs is fixed a batch, and what it saves grows with the batch.** On
+ * WebGPU it is a dispatch and an indirect draw, and Chrome validates every indirect draw in its GPU
+ * process — measured at 8 µs apiece in a city frame whose six hundred small prop batches took one
+ * each, 52 fps against 70 with those draws gone. On WebGL2 it is a loop over the instances and an
+ * upload of the survivors. A few thousand indices cost a device less than either.
+ *
+ * What it gives up is the instances of a small batch that stand out of view once its box is in it,
+ * which the device transforms and clips for nothing. What would make it wrong is a device whose
+ * vertex stage limits the frame while the CPU idles — where this wants to come down.
+ */
+export const INSTANCE_CULL_MIN_INDICES = 1 << 14;
+/**
+ * Whether a culling batch of `count` instances of a mesh of `indexCount` indices is culled instance
+ * by instance, or drawn whole once its box is seen. See `INSTANCE_CULL_MIN_INDICES`.
+ */
+export function cullsInstances(count, indexCount) {
+    return count * indexCount >= INSTANCE_CULL_MIN_INDICES;
+}
+/**
+ * Keep the instances of `data` whose spheres meet `frustum`, compacted in order into `out`, and
+ * return how many. `out` must hold as many as `data` does; its count is set.
+ */
+export function cullInstances(data, local, frustum, out) {
+    const count = Math.min(data.count, data.capacity, out.capacity);
+    const models = data.models;
+    const tints = data.tints;
+    let kept = 0;
+    for (let i = 0; i < count; i++) {
+        sphereOf(models, i, local, scratch);
+        if (!sphereMeets(frustum, scratch))
+            continue;
+        /* Copied float by float: a subarray would be a view allocated per instance, per frame. */
+        const from = i * 16;
+        const to = kept * 16;
+        for (let k = 0; k < 16; k++)
+            out.models[to + k] = models[from + k];
+        out.tints[kept * 3] = tints[i * 3];
+        out.tints[kept * 3 + 1] = tints[i * 3 + 1];
+        out.tints[kept * 3 + 2] = tints[i * 3 + 2];
+        kept++;
+    }
+    out.count = kept;
+    return kept;
+}
+/** `sphereInFrustum` over a packed (x, y, z, radius): kept unless wholly beyond one plane. */
+function sphereMeets(frustum, sphere) {
+    const x = sphere[0];
+    const y = sphere[1];
+    const z = sphere[2];
+    const radius = sphere[3];
+    for (let plane = 0; plane < PLANES; plane++) {
+        const at = plane * 4;
+        const distance = frustum[at] * x +
+            frustum[at + 1] * y +
+            frustum[at + 2] * z +
+            frustum[at + 3];
+        if (distance < -radius)
+            return false;
+    }
+    return true;
+}
+/**
+ * The world box around every instance's sphere, for testing a whole batch at once: (minX, minY,
+ * minZ, maxX, maxY, maxZ) into `out`. A batch holding nothing writes a min above its max.
+ *
+ * **A box, not a sphere, and the difference is the whole point for a flat batch.** A region of props
+ * a hundred metres square has a sphere seventy metres deep underground, where nothing occludes it,
+ * so a sphere test never finds a region hidden. The box stays as flat as the props are.
+ */
+export function instancesBox(data, local, out) {
+    const count = Math.min(data.count, data.capacity);
+    if (count === 0) {
+        out[0] = 1;
+        out[1] = 1;
+        out[2] = 1;
+        out[3] = -1;
+        out[4] = -1;
+        out[5] = -1;
+        return;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i < count; i++) {
+        sphereOf(data.models, i, local, scratch);
+        const r = scratch[3];
+        minX = Math.min(minX, scratch[0] - r);
+        minY = Math.min(minY, scratch[1] - r);
+        minZ = Math.min(minZ, scratch[2] - r);
+        maxX = Math.max(maxX, scratch[0] + r);
+        maxY = Math.max(maxY, scratch[1] + r);
+        maxZ = Math.max(maxZ, scratch[2] + r);
+    }
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = minZ;
+    out[3] = maxX;
+    out[4] = maxY;
+    out[5] = maxZ;
+}
+const scratch = new Float32Array(4);
+/** Instance `i`'s world sphere into `out` as (x, y, z, radius). */
+function sphereOf(models, i, local, out) {
+    const m = i * 16;
+    const cx = local.centre[0] ?? 0;
+    const cy = local.centre[1] ?? 0;
+    const cz = local.centre[2] ?? 0;
+    const m0 = models[m];
+    const m1 = models[m + 1];
+    const m2 = models[m + 2];
+    const m4 = models[m + 4];
+    const m5 = models[m + 5];
+    const m6 = models[m + 6];
+    const m8 = models[m + 8];
+    const m9 = models[m + 9];
+    const m10 = models[m + 10];
+    out[0] = m0 * cx + m4 * cy + m8 * cz + models[m + 12];
+    out[1] = m1 * cx + m5 * cy + m9 * cz + models[m + 13];
+    out[2] = m2 * cx + m6 * cy + m10 * cz + models[m + 14];
+    out[3] =
+        local.radius *
+            Math.sqrt(Math.max(m0 * m0 + m1 * m1 + m2 * m2, m4 * m4 + m5 * m5 + m6 * m6, m8 * m8 + m9 * m9 + m10 * m10));
+}
+/**
+ * Whether a batch's box (`instancesBox`) can be seen at all: inside the frustum, and not behind the
+ * declared occluders. One test for a whole region's props, run before any instance is looked at.
+ */
+export function batchBoxVisible(box, frustum, occluder) {
+    const minX = box[0];
+    const minY = box[1];
+    const minZ = box[2];
+    const maxX = box[3];
+    const maxY = box[4];
+    const maxZ = box[5];
+    if (minX > maxX)
+        return false;
+    if (!boxInFrustum(frustum, minX, minY, minZ, maxX, maxY, maxZ))
+        return false;
+    if (occluder === null)
+        return true;
+    boxMin[0] = minX;
+    boxMin[1] = minY;
+    boxMin[2] = minZ;
+    boxMax[0] = maxX;
+    boxMax[1] = maxY;
+    boxMax[2] = maxZ;
+    return !occluder.occludedBox(boxMin, boxMax);
+}
+const boxMin = new Float32Array(3);
+const boxMax = new Float32Array(3);

package/dist/render/instances.d.ts

@@ -67,3 +67,18 @@ export declare const INSTANCE_STRIDE: number;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export declare function packInstances(instances: MeshInstances, out: Float32Array): void;
+/** How a batch made by `createInstanced` behaves. */
+export interface InstancedOptions {
+    /**
+     * Cull the camera draw: the whole batch skipped when its instances' sphere is out of view or behind
+     * the declared occluders, and otherwise each instance kept only where its sphere meets the view —
+     * on the CPU on WebGL2, as compute into an indirect draw on WebGPU — once the batch is large enough
+     * to repay that (`cullsInstances`); a smaller one is drawn whole. Shadow, mirror-free motion and
+     * blended draws still see every instance. Off by default, because a batch small enough to draw whole
+     * pays for nothing it would save.
+     *
+     * **For a batch spread over space** — a prop across a region, a crowd, traffic. A batch in one
+     * place gains only the whole-batch test, which it could as well do itself.
+     */
+    readonly cull?: boolean;
+}

package/dist/render/lightBudget.d.ts

@@ -131,22 +131,20 @@ export declare const ENVIRONMENT_TEXTURE_UNIT: number;
  */
 export declare const CLUSTER_TABLE_TEXTURE_UNIT: number;
 /**
- * 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 declare const IES_ATLAS_TEXTURE_UNIT: number;
+export declare const FIXTURE_ATLAS_TEXTURE_UNIT: number;
 /**
  * The joint palette, read by the **vertex** stage.
  *
@@ -173,21 +171,6 @@ export declare const SKIN_PALETTE_TEXTURE_UNIT: number;
  * of sixteen spoken for, three free.
  */
 export declare const MORPH_DELTA_TEXTURE_UNIT: number;
-/**
- * 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 declare const COOKIE_ATLAS_TEXTURE_UNIT: number;
 /**
  * The colour the frame had already drawn, for a refracting surface to sample.
  *
@@ -219,11 +202,17 @@ export declare const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT: number;
  */
 export declare const SUN_GLASS_TINT_TEXTURE_UNIT: number;
 /**
- * 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 declare const POINT_GLASS_TINT_TEXTURE_UNIT: number;
+/**
+ * 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 declare const SURFACE_EFFECTS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -129,22 +129,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.
  *
@@ -162,7 +160,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.
  *
@@ -171,21 +169,6 @@ export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
  * of sixteen spoken for, three free.
  */
 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.
  *
@@ -199,7 +182,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.
  *
@@ -217,11 +200,17 @@ 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/dist/render/lightGrid.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const LIGHT_GRID_MAX_CELLS: number;
+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 declare function createLightGrid(sources: readonly PointLightSource[], cell: number): LightGrid;
+/**
+ * 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 declare function gatherLights(grid: LightGrid, x: number, y: number, z: number, reach: number): number;

package/dist/render/lightGrid.js

@@ -0,0 +1,87 @@
+/** 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;
+/** Bucket `sources` into cells of `cell` metres. Built once; not a frame path. */
+export function createLightGrid(sources, cell) {
+    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 = [
+        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) => 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] + 1;
+    }
+    for (let c = 0; c < cells; c++)
+        start[c + 1] = start[c + 1] + start[c];
+    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]);
+        lights[cursor[c]] = index;
+        cursor[c] = cursor[c] + 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, x, y, z, reach) {
+    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]; at < start[c + 1]; at++) {
+                    gathered[count++] = lights[at];
+                }
+            }
+        }
+    }
+    return count;
+}

package/dist/render/mesh.d.ts

@@ -7,6 +7,9 @@ import type { MeshData } from '@driftengine/drft';
 export declare class Mesh {
     private readonly vao;
     private readonly buffers;
+    /** Every attribute bound from a buffer, so a batch can build a vertex array of its own. */
+    private readonly layout;
+    private indexBuffer;
     /**
      * The position and normal buffers, kept so `update` can rewrite them.
      *
@@ -16,7 +19,13 @@ export declare class Mesh {
     private readonly deformable;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
     private readonly positionFloats;
-    private readonly indexCount;
+    /**
+     * Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). **At zero the
+     * mesh has nothing to draw and no verb draws it**, as on WebGPU (`GpuMesh.indexCount`): a draw of
+     * nothing is silent here but is still a call and a counted draw, and the two backends count the
+     * same frame.
+     */
+    readonly indexCount: number;
     /**
      * The constant values this mesh's *absent* attributes are shaded with, re-applied on
      * every draw.
@@ -94,30 +103,18 @@ export declare class Mesh {
     /** Caller is responsible for having the flat program + uniforms bound. */
     draw(gl: WebGL2RenderingContext): void;
     /**
-     * Bind one buffer's per-instance attributes to this mesh's vertex array.
-     *
-     * **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.
-     */
-    attachInstances(gl: WebGL2RenderingContext, buffer: WebGLBuffer, stride: number): void;
-    /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
-    private bindInstanceColumns;
-    private instanceBuffer;
-    private instanceStride;
-    /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
-    private instanced;
-    /**
-     * 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.
+     * 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.
+     *
+     * **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.
      */
-    drawInstances(gl: WebGL2RenderingContext, count: number): void;
+    createInstanceArray(gl: WebGL2RenderingContext, instances: WebGLBuffer, stride: number): WebGLVertexArrayObject;
+    /** Draw `count` instances through a batch's own vertex array. See `createInstanceArray`. */
+    drawInstancesThrough(gl: WebGL2RenderingContext, vao: WebGLVertexArrayObject, count: number): void;
     dispose(gl: WebGL2RenderingContext): void;
     /**
      * Rewrite this mesh's positions, and its normals where the caller has them.
@@ -179,3 +176,5 @@ export interface IncrementalMesh {
  * them before a byte of it has landed.
  */
 export declare function createMeshIncremental(gl: WebGL2RenderingContext, data: MeshData, dynamic?: boolean): IncrementalMesh;
+/** Texture coordinates and layers interleaved as (u, v, layer), one row a vertex. */
+export declare function packUvLayers(uvs: Float32Array, layers: Float32Array): Float32Array;