@waica/engine 0.22.0 → 0.24.0

package/dist/spatial-broadphase.d.ts

@@ -15,7 +15,13 @@ export interface SpatialBroadphaseStats {
 export interface SpatialBroadphase<T> {
     readonly stats: SpatialBroadphaseStats;
     candidates(bounds: CollisionBounds): T[];
-    pairs(): Array<readonly [T, T]>;
+    /**
+     * Visits every distinct pair sharing a cell, or involving an overflow
+     * entry, once, in ascending query order. The grid is frozen at creation,
+     * so callbacks that move, spawn or destroy entities do not change which
+     * pairs are visited.
+     */
+    forEachPair(visit: (first: T, second: T) => void): void;
 }
 /**
  * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap

package/dist/spatial-broadphase.js

@@ -4,6 +4,7 @@ import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import { Tilemap } from './components/tilemap.js';
 import { sceneSolids } from './scene-solids.js';
+import { forEachCandidatePair } from './spatial-pairs.js';
 import { usableCollisionBody } from './spatial-query-geometry.js';
 const CELL_OCCUPANCY_CAP = 256;
 function rangeSize(range) {
@@ -54,13 +55,6 @@ function entryValue(entries, index) {
         throw new Error(`Spatial broadphase has no entry at index ${index}`);
     return entry.value;
 }
-/** The entry index stored at `position` of a bucket that is iterated within its bounds. */
-function indexAt(bucket, position) {
-    const index = bucket[position];
-    if (index === undefined)
-        throw new Error(`Spatial broadphase bucket has no index at position ${position}`);
-    return index;
-}
 /** The indexable sources in query order, each with the cell range it covers. */
 function spatialEntries(sources, cellSize, isIndexable) {
     return sources
@@ -79,47 +73,25 @@ function spatialEntries(sources, cellSize, isIndexable) {
 function spatialGrid(entries) {
     const buckets = new Map();
     const overflow = [];
+    const entryBuckets = [];
     for (const [index, entry] of entries.entries()) {
+        const own = [];
+        entryBuckets.push(own);
         if (!entry.range) {
             overflow.push(index);
             continue;
         }
         eachCell(entry.range, (key) => {
-            const bucket = buckets.get(key);
-            if (bucket)
-                bucket.push(index);
-            else
-                buckets.set(key, [index]);
-        });
-    }
-    return { buckets, overflow };
-}
-/** Distinct index pairs sharing a cell, or involving an overflow entry, in ascending order. */
-function candidatePairIndices(grid, entryCount) {
-    const pairKeys = new Set();
-    const width = entryCount;
-    const addPair = (left, right) => {
-        if (left === right)
-            return;
-        const first = Math.min(left, right);
-        const second = Math.max(left, right);
-        pairKeys.add(first * width + second);
-    };
-    for (const bucket of grid.buckets.values()) {
-        for (let left = 0; left < bucket.length; left += 1) {
-            for (let right = left + 1; right < bucket.length; right += 1) {
-                addPair(indexAt(bucket, left), indexAt(bucket, right));
+            let bucket = buckets.get(key);
+            if (!bucket) {
+                bucket = [];
+                buckets.set(key, bucket);
             }
-        }
-    }
-    for (const overflowIndex of grid.overflow) {
-        for (let index = 0; index < entryCount; index += 1) {
-            addPair(overflowIndex, index);
-        }
+            bucket.push(index);
+            own.push(bucket);
+        });
     }
-    return [...pairKeys]
-        .map((key) => [Math.floor(key / width), key % width])
-        .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2);
+    return { buckets, overflow, entryBuckets };
 }
 /**
  * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
@@ -144,11 +116,10 @@ export function createSpatialBroadphase(sources, cellSize, isIndexable = usableC
                 .sort((a, b) => a - b)
                 .map((index) => entryValue(entries, index));
         },
-        pairs() {
-            return candidatePairIndices(grid, entries.length).map(([first, second]) => [
-                entryValue(entries, first),
-                entryValue(entries, second),
-            ]);
+        forEachPair(visit) {
+            forEachCandidatePair(grid, (first, second) => {
+                visit(entryValue(entries, first), entryValue(entries, second));
+            });
         },
     };
 }

package/dist/spatial-pairs.d.ts

@@ -0,0 +1,17 @@
+/** The grid shape the pair walk needs: which buckets each entry is in, and the overflow. */
+export interface PairGrid {
+    /** Entries too large to bucket, ascending; they pair with every other entry. */
+    readonly overflow: readonly number[];
+    /** Per entry, the buckets it was added to, each ascending by entry index (empty for overflow entries). */
+    readonly entryBuckets: readonly (readonly (readonly number[])[])[];
+}
+type PairVisitor = (first: number, second: number) => void;
+/**
+ * Visits every distinct index pair sharing a cell, or involving an overflow
+ * entry, in ascending (first, second) order. Buckets fill in index order, so
+ * each one is already ascending: a body in one cell, with no overflow after
+ * it, needs no deduplication or sort. Equivalent to collecting all pairs,
+ * deduplicating and sorting them, without allocating per pair.
+ */
+export declare function forEachCandidatePair(grid: PairGrid, visit: PairVisitor): void;
+export {};

package/dist/spatial-pairs.js

@@ -0,0 +1,79 @@
+/** The entry index stored at `position` of a bucket that is iterated within its bounds. */
+function indexAt(bucket, position) {
+    const index = bucket[position];
+    if (index === undefined)
+        throw new Error(`Spatial broadphase bucket has no index at position ${position}`);
+    return index;
+}
+/** First position in an ascending bucket whose index is greater than `index`. */
+function firstAfter(bucket, index) {
+    let low = 0;
+    let high = bucket.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (indexAt(bucket, middle) <= index)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+/** Calls `each` with every index of an ascending bucket greater than `first`. */
+function eachLater(bucket, first, each) {
+    for (let position = firstAfter(bucket, first); position < bucket.length; position += 1) {
+        each(indexAt(bucket, position));
+    }
+}
+/** The later indices of `buckets`, deduplicated and ascending, in the walk's scratch list. */
+function laterNeighbours(walk, buckets, first) {
+    const { marked, neighbours } = walk;
+    neighbours.length = 0;
+    for (const bucket of buckets) {
+        eachLater(bucket, first, (second) => {
+            if (marked[second] === first)
+                return;
+            marked[second] = first;
+            neighbours.push(second);
+        });
+    }
+    return neighbours.sort((a, b) => a - b);
+}
+/** The pairs of bucketed entry `first` with every later entry sharing a cell or overflowing. */
+function visitBucketedPairs(walk, first) {
+    const { grid, visit } = walk;
+    const own = grid.entryBuckets[first];
+    if (!own)
+        throw new Error(`Spatial broadphase has no buckets for entry ${first}`);
+    // Overflow is ascending, like a bucket: laterNeighbours takes only its later part.
+    const hasLaterOverflow = (grid.overflow.at(-1) ?? -1) > first;
+    const [only] = own;
+    if (own.length === 1 && only && !hasLaterOverflow) {
+        eachLater(only, first, (second) => visit(first, second));
+        return;
+    }
+    const buckets = hasLaterOverflow ? [...own, grid.overflow] : own;
+    for (const second of laterNeighbours(walk, buckets, first))
+        visit(first, second);
+}
+/**
+ * Visits every distinct index pair sharing a cell, or involving an overflow
+ * entry, in ascending (first, second) order. Buckets fill in index order, so
+ * each one is already ascending: a body in one cell, with no overflow after
+ * it, needs no deduplication or sort. Equivalent to collecting all pairs,
+ * deduplicating and sorting them, without allocating per pair.
+ */
+export function forEachCandidatePair(grid, visit) {
+    const entryCount = grid.entryBuckets.length;
+    const isOverflow = new Uint8Array(entryCount);
+    for (const index of grid.overflow)
+        isOverflow[index] = 1;
+    const walk = { grid, visit, marked: new Int32Array(entryCount).fill(-1), neighbours: [] };
+    for (let first = 0; first < entryCount; first += 1) {
+        if (!isOverflow[first]) {
+            visitBucketedPairs(walk, first);
+            continue;
+        }
+        for (let second = first + 1; second < entryCount; second += 1)
+            visit(first, second);
+    }
+}

package/dist/sprite-batch.d.ts

@@ -0,0 +1,93 @@
+import * as THREE from 'three/webgpu';
+import type { TextureOutcome } from './assets/asset-loader.js';
+export type SpriteBatchShape = 'rectangle' | 'circle';
+/**
+ * What decides whether two sprites can share one draw: the art, its
+ * filtering and the quad's shape. `texture` null is the untextured entry of
+ * a shape; '' is an AnimatedSprite sheet with no url yet (a bare texture).
+ */
+export interface SpriteBatchKey {
+    texture: string | null;
+    pixelArt: boolean;
+    shape: SpriteBatchShape;
+}
+/** The first capacity of a batch's instance buffers; it doubles when full. */
+export declare const INITIAL_SPRITE_BATCH_CAPACITY = 16;
+/** Where a batch gets its key's texture: `game.assets` (ADR 0019). */
+export interface SpriteBatchTextures {
+    texture(url: string): {
+        texture: THREE.Texture;
+        settled: Promise<TextureOutcome>;
+    };
+}
+/** The key's canonical string: equal keys share one batch. */
+export declare function spriteBatchKeyId(key: SpriteBatchKey): string;
+/** The unit quad every sprite of a shape draws, exactly as the per-sprite path builds it. */
+export declare function spriteGeometry(shape: SpriteBatchShape): THREE.BufferGeometry;
+/** What a run writes per sprite. */
+export interface SpriteBatchInstance {
+    /** View × world of the sprite's quad. */
+    readonly modelView: THREE.Matrix4;
+    /** Linear RGB tint. */
+    readonly color: THREE.Color;
+    /** The map's repeat and offset (identity for an untransformed map). */
+    readonly uvRepeat: THREE.Vector2;
+    readonly uvOffset: THREE.Vector2;
+}
+/**
+ * One pooled draw of a run: an instanced quad and its three typed instance
+ * attributes (view × world, tint, map UV transform), sized by the longest
+ * run it has drawn — 16 instances at first, doubling when a longer run
+ * needs it, never shrinking during the scene.
+ */
+export declare class SpriteRunMesh {
+    readonly mesh: THREE.InstancedMesh;
+    private readonly colors;
+    private readonly uvs;
+    constructor(base: THREE.BufferGeometry, material: THREE.MeshBasicNodeMaterial, capacity: number);
+    get capacity(): number;
+    /** Writes the sprite drawn `index`-th in this run. */
+    write(index: number, instance: SpriteBatchInstance): void;
+    /** Draws the first `count` written instances and uploads only those. */
+    commit(count: number): void;
+    dispose(): void;
+}
+/**
+ * A Sprite Batch's resources for one key (CONTEXT.md, ADR 0024): the shared
+ * material, a slot per member, and the pooled run meshes its runs draw
+ * through — one per run of the key in a frame, each sized by its own run, so
+ * instance memory stays proportional to the sprites drawn. Released at
+ * unload (ADR 0011).
+ */
+export declare class SpriteBatch {
+    private readonly geometry;
+    readonly material: THREE.MeshBasicNodeMaterial;
+    /** When the key's texture settled; null for untextured and bare entries. */
+    readonly settled: Promise<TextureOutcome> | null;
+    private readonly slots;
+    private readonly freeSlots;
+    private _capacity;
+    private readonly runs;
+    private runsDrawn;
+    constructor(key: SpriteBatchKey, textures: SpriteBatchTextures, geometry: THREE.BufferGeometry);
+    /** The most members the key has held at once, rounded up to 16 × 2^n: no run is ever longer. */
+    get capacity(): number;
+    /** Live members. */
+    get size(): number;
+    /** Takes a freed slot first, growing the capacity geometrically only when none is left. */
+    join(): number;
+    /** Frees a member's slot for the next join, the same step. */
+    leave(slot: number): void;
+    /** Starts a frame: no run of the key drawn yet. */
+    beginFrame(): void;
+    /**
+     * The pooled mesh for the key's next run this frame, holding at least
+     * `length` instances. A pooled mesh is rebuilt only when this run is longer
+     * than any it drew before, doubling from its size (16 at first).
+     */
+    nextRun(length: number): SpriteRunMesh;
+    /** Takes the pooled meshes no run used this frame out of the scene. */
+    detachUndrawn(): void;
+    /** Releases every GPU-side object this batch created; its texture clone included. */
+    dispose(): void;
+}

package/dist/sprite-batch.js

@@ -0,0 +1,223 @@
+import { attribute, context, mat3, positionLocal, uv, vec3, vertexStage } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+/** The first capacity of a batch's instance buffers; it doubles when full. */
+export const INITIAL_SPRITE_BATCH_CAPACITY = 16;
+/** The key's canonical string: equal keys share one batch. */
+export function spriteBatchKeyId(key) {
+    const texture = key.texture === null ? 'none' : `url:${key.texture}`;
+    return `${texture}|${key.texture === null ? false : key.pixelArt}|${key.shape}`;
+}
+/** The unit quad every sprite of a shape draws, exactly as the per-sprite path builds it. */
+export function spriteGeometry(shape) {
+    return shape === 'circle' ? new THREE.CircleGeometry(0.5, 32) : new THREE.PlaneGeometry(1, 1);
+}
+/** The per-instance UV transform a run carries: repeat (x, y) and offset (z, w). */
+const INSTANCE_UV = 'instanceUv';
+/** Whether three is building the material for one of the batch's instanced run meshes. */
+function drawsInstances(builder) {
+    return builder.object.isInstancedMesh === true;
+}
+/**
+ * The map UV of one instance: its repeat and offset as the same mat3 a
+ * texture's own matrix is, applied to the quad's UV per vertex — as every
+ * other map is (render-output.ts `mapUvPerVertex`) — so the corner UVs are
+ * the very floats the per-sprite draw interpolates.
+ */
+function instanceMapUv() {
+    const transform = attribute(INSTANCE_UV, 'vec4');
+    return vertexStage(mat3(transform.x, 0, 0, 0, transform.y, 0, transform.z, transform.w, 1).mul(vec3(uv(), 1)).xy);
+}
+/**
+ * Every batch's material, as a node material (ADR 0025). The instance
+ * matrix already holds view × world (three's own `modelViewMatrix` for that
+ * sprite, computed the same way on the CPU), so an instanced draw skips
+ * `modelViewMatrix`; the map's UV transform comes from the instance instead
+ * of the texture. Both apply to instanced draws only: the hidden anchors
+ * share this material, and if one were ever drawn as a plain mesh it gets
+ * three's own transforms.
+ */
+class SpriteBatchMaterial extends THREE.MeshBasicNodeMaterial {
+    constructor(parameters) {
+        super(parameters);
+        this.contextNode = context({
+            getUV: (texture, builder) => {
+                if (!drawsInstances(builder))
+                    return null;
+                // The instance transform replaces the map's own matrix.
+                texture.setUpdateMatrix(false);
+                return instanceMapUv();
+            },
+        });
+    }
+    setupPositionView(builder) {
+        // three's instancing already multiplied positionLocal by the instance matrix.
+        return drawsInstances(builder) ? positionLocal : super.setupPositionView(builder);
+    }
+}
+function createMaterial(key, textures) {
+    // Double-sided: a flipped sprite mirrors through a negative x scale in its
+    // matrix, exactly like its own mesh; per instance there is no winding flip.
+    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide });
+    material.forceSinglePass = true;
+    if (key.texture === null)
+        return { material, settled: null };
+    const { texture, settled } = key.texture
+        ? textures.texture(key.texture)
+        : { texture: new THREE.Texture(), settled: null };
+    // One clone per key holds the filters, so pixelArt never leaks across keys.
+    if (key.pixelArt) {
+        texture.magFilter = THREE.NearestFilter;
+        texture.minFilter = THREE.NearestFilter;
+    }
+    material.map = texture;
+    return { material, settled };
+}
+/** Marks the first `count` items of an instance attribute for upload. */
+function upload(attribute, count) {
+    attribute.clearUpdateRanges();
+    attribute.addUpdateRange(0, count * attribute.itemSize);
+    attribute.needsUpdate = true;
+}
+/**
+ * One pooled draw of a run: an instanced quad and its three typed instance
+ * attributes (view × world, tint, map UV transform), sized by the longest
+ * run it has drawn — 16 instances at first, doubling when a longer run
+ * needs it, never shrinking during the scene.
+ */
+export class SpriteRunMesh {
+    mesh;
+    colors;
+    uvs;
+    constructor(base, material, capacity) {
+        // Its own copy of the quad's attributes, so disposing one run never frees
+        // buffers another geometry still binds.
+        const geometry = base.clone();
+        this.uvs = new THREE.InstancedBufferAttribute(new Float32Array(capacity * 4), 4).setUsage(THREE.DynamicDrawUsage);
+        geometry.setAttribute(INSTANCE_UV, this.uvs);
+        this.mesh = new THREE.InstancedMesh(geometry, material, capacity);
+        this.mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+        this.colors = new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3).setUsage(THREE.DynamicDrawUsage);
+        this.mesh.instanceColor = this.colors;
+        // Drawn in an explicit renderOrder; its instances are already in view space.
+        this.mesh.frustumCulled = false;
+        this.mesh.matrixAutoUpdate = false;
+        this.mesh.boundingSphere = new THREE.Sphere();
+    }
+    get capacity() {
+        return this.mesh.instanceMatrix.count;
+    }
+    /** Writes the sprite drawn `index`-th in this run. */
+    write(index, instance) {
+        instance.modelView.toArray(this.mesh.instanceMatrix.array, index * 16);
+        instance.color.toArray(this.colors.array, index * 3);
+        const uv = this.uvs.array;
+        uv[index * 4] = instance.uvRepeat.x;
+        uv[index * 4 + 1] = instance.uvRepeat.y;
+        uv[index * 4 + 2] = instance.uvOffset.x;
+        uv[index * 4 + 3] = instance.uvOffset.y;
+    }
+    /** Draws the first `count` written instances and uploads only those. */
+    commit(count) {
+        this.mesh.count = count;
+        for (const attribute of [this.mesh.instanceMatrix, this.colors, this.uvs])
+            upload(attribute, count);
+    }
+    dispose() {
+        this.mesh.removeFromParent();
+        this.mesh.geometry.dispose();
+        this.mesh.dispose();
+    }
+}
+/**
+ * A Sprite Batch's resources for one key (CONTEXT.md, ADR 0024): the shared
+ * material, a slot per member, and the pooled run meshes its runs draw
+ * through — one per run of the key in a frame, each sized by its own run, so
+ * instance memory stays proportional to the sprites drawn. Released at
+ * unload (ADR 0011).
+ */
+export class SpriteBatch {
+    geometry;
+    material;
+    /** When the key's texture settled; null for untextured and bare entries. */
+    settled;
+    // A slot reserves room in the key's capacity; it is not a position in any
+    // instance buffer, which a frame rewrites in draw order (CA-4 deviation).
+    slots = [];
+    freeSlots = [];
+    _capacity = INITIAL_SPRITE_BATCH_CAPACITY;
+    runs = [];
+    runsDrawn = 0;
+    constructor(key, textures, geometry) {
+        this.geometry = geometry;
+        const { material, settled } = createMaterial(key, textures);
+        this.material = material;
+        this.settled = settled;
+    }
+    /** The most members the key has held at once, rounded up to 16 × 2^n: no run is ever longer. */
+    get capacity() {
+        return this._capacity;
+    }
+    /** Live members. */
+    get size() {
+        return this.slots.length - this.freeSlots.length;
+    }
+    /** Takes a freed slot first, growing the capacity geometrically only when none is left. */
+    join() {
+        const reused = this.freeSlots.pop();
+        if (reused !== undefined) {
+            this.slots[reused] = true;
+            return reused;
+        }
+        this.slots.push(true);
+        while (this.slots.length > this._capacity)
+            this._capacity *= 2;
+        return this.slots.length - 1;
+    }
+    /** Frees a member's slot for the next join, the same step. */
+    leave(slot) {
+        if (this.slots[slot] !== true)
+            return;
+        this.slots[slot] = false;
+        this.freeSlots.push(slot);
+    }
+    /** Starts a frame: no run of the key drawn yet. */
+    beginFrame() {
+        this.runsDrawn = 0;
+    }
+    /**
+     * The pooled mesh for the key's next run this frame, holding at least
+     * `length` instances. A pooled mesh is rebuilt only when this run is longer
+     * than any it drew before, doubling from its size (16 at first).
+     */
+    nextRun(length) {
+        const index = this.runsDrawn;
+        this.runsDrawn += 1;
+        const pooled = this.runs[index];
+        if (pooled && pooled.capacity >= length)
+            return pooled;
+        let capacity = pooled?.capacity ?? INITIAL_SPRITE_BATCH_CAPACITY;
+        while (capacity < length)
+            capacity *= 2;
+        // Never past the key's reservation: a run cannot outnumber the members.
+        const run = new SpriteRunMesh(this.geometry, this.material, Math.min(capacity, Math.max(this._capacity, length)));
+        if (pooled) {
+            pooled.mesh.parent?.add(run.mesh);
+            pooled.dispose();
+        }
+        this.runs[index] = run;
+        return run;
+    }
+    /** Takes the pooled meshes no run used this frame out of the scene. */
+    detachUndrawn() {
+        for (let index = this.runsDrawn; index < this.runs.length; index += 1)
+            this.runs[index]?.mesh.removeFromParent();
+    }
+    /** Releases every GPU-side object this batch created; its texture clone included. */
+    dispose() {
+        for (const run of this.runs)
+            run.dispose();
+        this.runs.length = 0;
+        this.material.map?.dispose();
+        this.material.dispose();
+    }
+}

package/dist/sprite-batches.d.ts

@@ -0,0 +1,107 @@
+import * as THREE from 'three/webgpu';
+import type { TextureOutcome } from './assets/asset-loader.js';
+import type { Game } from './game.js';
+import { SpriteBatch, type SpriteBatchInstance, type SpriteBatchKey, type SpriteBatchTextures } from './sprite-batch.js';
+/** Where an instance reads its map's UV transform: an AnimatedSprite's sheet clone. */
+export interface SpriteUvSource {
+    readonly offset: THREE.Vector2;
+    readonly repeat: THREE.Vector2;
+}
+export type SpriteAnchor = THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicNodeMaterial>;
+/** Where an instance sits: its key, that key's batch and its slot there. */
+export interface SpriteBatchSeat {
+    key: SpriteBatchKey;
+    batch: SpriteBatch;
+    slot: number;
+}
+/**
+ * One sprite inside a Sprite Batch. Its `anchor` is a hidden mesh placed
+ * exactly where the sprite's own mesh would be — same parent, transform,
+ * shape geometry and creation order — so draw order, y-sort and the world
+ * matrix come out as before; the anchor itself is never drawn.
+ */
+export declare class SpriteInstance implements SpriteBatchInstance {
+    readonly anchor: SpriteAnchor;
+    private readonly owner;
+    seat: SpriteBatchSeat;
+    /** Linear RGB tint, what the per-sprite path writes into its material color. */
+    readonly color: THREE.Color;
+    /** Identity until an AnimatedSprite points it at its current sheet's clone. */
+    uvSource: SpriteUvSource;
+    readonly modelView: THREE.Matrix4;
+    /**
+     * For an AnimatedSprite: the sheet its key was last chosen for and whether
+     * that sheet had failed, so a frame on the same sheet skips the move.
+     */
+    shownSheet: number;
+    shownSheetFailed: boolean;
+    constructor(anchor: SpriteAnchor, owner: SpriteBatches, seat: SpriteBatchSeat);
+    get key(): SpriteBatchKey;
+    get uvRepeat(): THREE.Vector2;
+    get uvOffset(): THREE.Vector2;
+    /** Moves to the batch of `key` (a shape change, a failed texture, another sheet); a no-op for the same key. */
+    moveTo(key: SpriteBatchKey): void;
+    /** Frees the slot and removes the anchor: the sprite was destroyed. */
+    release(): void;
+}
+/** The batch instance whose hidden anchor this is; undefined for an ordinary mesh. */
+export declare function spriteInstanceOf(object: THREE.Object3D | undefined): SpriteInstance | undefined;
+/**
+ * A Game's Sprite Batches (ADR 0024): one SpriteBatch per key, the hidden
+ * anchors of every batched sprite, and the per-frame pass that orders the
+ * frame like three would, groups runs and draws each through one instanced
+ * mesh. Scene-scoped: unload() releases everything (ADR 0011).
+ */
+export declare class SpriteBatches {
+    private readonly textures;
+    /** Whether sprites readied from now on batch: the scene's `render.batch !== false`. */
+    enabled: boolean;
+    private readonly batches;
+    private readonly geometries;
+    private readonly live;
+    private readonly root;
+    /** Under root, one Group per non-zero group order, so a run keeps its sprites' Group renderOrder. */
+    private readonly groups;
+    private readonly collector;
+    private camera;
+    private nextOrder;
+    private readonly pinned;
+    private readonly pinnedOrders;
+    private pinnedScene;
+    private sceneAutoUpdate;
+    private readonly visitor;
+    constructor(textures: SpriteBatchTextures);
+    /** A new batched sprite in the key's batch; the caller parents its hidden anchor. */
+    attach(key: SpriteBatchKey): SpriteInstance;
+    /** When the key's texture settled; null for an untextured or bare entry. */
+    settled(key: SpriteBatchKey): Promise<TextureOutcome> | null;
+    move(instance: SpriteInstance, key: SpriteBatchKey): void;
+    detach(instance: SpriteInstance): void;
+    /**
+     * The frame pass, right before `renderer.render`: orders every transparent
+     * renderable as three would, draws each run of same-key sprites through one
+     * instanced mesh, and pins that order with renderOrder. Returns what undoes
+     * the temporary renderOrder of the non-sprite renderables after the render.
+     */
+    prepareFrame(scene: THREE.Scene, camera: THREE.Camera): () => void;
+    /** Runs `render` with this frame's runs drawn and the draw order pinned, then undoes the pin. */
+    drawFrame(scene: THREE.Scene, camera: THREE.Camera, render: () => void): void;
+    /** Releases every batch, geometry and run mesh; batching is on again for the next scene. */
+    unload(): void;
+    private batchFor;
+    private geometryFor;
+    /** Draws the frame's run `start`..`end` of `batch` through its next pooled run mesh, in its Group order. */
+    private drawRun;
+    /** Pins a non-sprite renderable's renderOrder to its place in the frame, until unpin. */
+    private pin;
+    /** After the render: every pinned renderOrder back, and the scene's own matrix updates. */
+    private readonly unpin;
+    /** The Group a run of `groupOrder` hangs from: three reads its renderOrder as the run's group order. */
+    private groupFor;
+    /** The instance with its view × world computed exactly as three computes `modelViewMatrix`. */
+    private placed;
+}
+/** Internal: the Game creates its batches here at construction, findable by its sprites. */
+export declare function createSpriteBatches(game: Game, textures: SpriteBatchTextures): SpriteBatches;
+/** A Game's Sprite Batches; undefined for anything that is not a constructed Game (a test stub). */
+export declare function spriteBatchesOf(game: Game): SpriteBatches | undefined;