@waica/engine 0.22.0 → 0.23.0

package/README.md

@@ -150,6 +150,20 @@ The cues that hook a `StateMachine` must come after it and after the `ParticleEm
 
 `active`, `capacity`, and `emitting` are the only fields exposed by Runtime Snapshot. Particle arrays remain private. This first CPU implementation is intended for bounded 2D effects, not collision, per-particle scripting, GPU simulation, trails, rotation, or sub-emitters.
 
+## Sprite Batches
+
+`Sprite` and `AnimatedSprite` are drawn through **Sprite Batches** by default (ADR 0024). Every frame, after y-sort, the engine orders everything it draws exactly as three would without batching — layer bands, then y-sort, then spawn order, with particle batches, tilemaps and any other mesh in between — and each run of consecutive sprites that share a batch key becomes one instanced draw call. The key is the art and how it is sampled: the texture (an `AnimatedSprite`'s current sheet), `pixelArt` and `shape`. Each sprite is one instance carrying its own placement, color, frame and flip, so tinting, resizing, re-anchoring or animating a sprite never creates a material, and what is drawn in front of what never changes.
+
+- **On by default.** A scene without a `render` block, or with `render.batch: true`, batches. Nothing to configure: sprites of one texture in a row draw in one call, a sprite of other art (or a particle batch, a tilemap) in between starts a new run.
+- **Culling and Group order kept.** A sprite outside the camera is skipped for the frame, as three culls a sprite's own mesh, and an off-camera renderable never splits a run. A run hangs under a Group with its sprites' Group `renderOrder`, so `entity.node.renderOrder` orders batched sprites exactly as it orders their meshes without batching.
+- **Shared art.** All live sprites of one key share one material and one texture clone, scene-scoped: released with the scene at `unloadScene()` and `game.dispose()`. A sprite whose texture fails moves alone to the untextured entry of its shape and keeps showing its `color`.
+- **Reusable slots and buffers.** A destroyed sprite's slot goes to the next spawn of its key. Each run draws through a pooled instance buffer sized by that run: 16 instances at first, doubling when a longer run needs it, never shrinking during the scene. A key drawn as several runs keeps one buffer per run, so instance memory stays proportional to the sprites drawn. Once the buffers have grown to a scene's longest runs (and as many runs as it ever splits into), spawning, destroying and reordering sprites allocates no GPU objects.
+- **Turning it off.** Scene JSON `"render": { "batch": false }` (the editor's **Sprite batching** toggle in the scene inspector) restores the per-sprite path: one mesh, one material and one draw call per sprite. Use it to rule batching out when a scene looks different than you expect, or while debugging draw order; the cost is one draw call per sprite, which is what dominates frame time with thousands of sprites.
+
+Under batching, the object a sprite adds to its entity is a hidden placement anchor that is never drawn. Hide or show a batched sprite through its entity (`entity.node.visible`, as `Health` blinking does); the anchor's own `visible` is not read for the batched draw, and setting it to true makes three also draw the anchor as a plain quad (without the sprite's tint or frame) — leave it alone, or use `render.batch: false` when code needs one real mesh per sprite.
+
+How much batching saves depends on how interleaved a scene is: one texture over the whole scene draws in one call, while a top-down scene that alternates many textures by y gains little. Runtime Snapshots are unchanged — batches are not entities, and sprites report the same state either way.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

package/dist/collision-category.js

@@ -5,7 +5,10 @@ export function validCollisionLayer(value) {
 }
 /** Package-internal exact directional interest check. */
 export function collisionMaskTargets(mask, targetLayer) {
-    if (!validCollisionLayer(targetLayer) || !Array.isArray(mask))
+    if (!Array.isArray(mask))
         return false;
-    return mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+    // Membership first: with explicit masks it rejects most pairs of a dense
+    // scene before the layer's syntax check runs. A '*' mask still checks it.
+    const named = mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+    return named && validCollisionLayer(targetLayer);
 }

package/dist/collision-dispatch.d.ts

@@ -4,5 +4,11 @@ export interface CollisionDispatchStats {
     readonly candidatePairs: number;
     readonly narrowphaseCalls: number;
 }
-/** Game's package-internal trigger dispatch implementation. */
+/**
+ * Game's package-internal trigger dispatch implementation. Pairs come from a
+ * frozen grid; each pair is then checked live, most selective checks first
+ * (liveness, masks, then the snapshotted Hitbox still mounted). The checks
+ * have no side effects, so their order only changes how fast a pair is
+ * rejected.
+ */
 export declare function dispatchCollisions(game: Game): CollisionDispatchStats;

package/dist/collision-dispatch.js

@@ -3,34 +3,41 @@ import { collisionMaskTargets } from './collision-category.js';
 import { collisionOverlap } from './collision-shape.js';
 import { Hitbox } from './components/hitbox.js';
 import { createHitboxBroadphase } from './spatial-broadphase.js';
-/** Game's package-internal trigger dispatch implementation. */
+/**
+ * Game's package-internal trigger dispatch implementation. Pairs come from a
+ * frozen grid; each pair is then checked live, most selective checks first
+ * (liveness, masks, then the snapshotted Hitbox still mounted). The checks
+ * have no side effects, so their order only changes how fast a pair is
+ * rejected.
+ */
 export function dispatchCollisions(game) {
-    const pairs = createHitboxBroadphase(game).pairs();
+    let candidatePairs = 0;
     let narrowphaseCalls = 0;
-    for (const [first, second] of pairs) {
+    createHitboxBroadphase(game).forEachPair((first, second) => {
+        candidatePairs += 1;
         const a = first.entity;
         const b = second.entity;
         if (!a.alive || !b.alive)
-            continue;
-        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
-            continue;
+            return;
         const notifyA = collisionMaskTargets(first.hitbox.collidesWith, second.hitbox.layer);
         const notifyB = collisionMaskTargets(second.hitbox.collidesWith, first.hitbox.layer);
         if (!notifyA && !notifyB)
-            continue;
+            return;
+        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
+            return;
         narrowphaseCalls += 1;
         if (!collisionOverlap(collisionBody(first.hitbox), collisionBody(second.hitbox)))
-            continue;
+            return;
         if (notifyA) {
             for (const component of [...a.components])
                 component.onCollide?.(b);
         }
         if (!a.alive || !b.alive)
-            continue;
+            return;
         if (notifyB) {
             for (const component of [...b.components])
                 component.onCollide?.(a);
         }
-    }
-    return { candidatePairs: pairs.length, narrowphaseCalls };
+    });
+    return { candidatePairs, narrowphaseCalls };
 }

package/dist/components/animated-sprite.d.ts

@@ -113,6 +113,8 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
      * touches game.assets, so it counts nowhere and warns about nothing.
      */
     private sheetTexture;
+    /** The batch key of a sheet: its art, this sprite's filtering, a rectangle. */
+    private sheetKey;
     private showFrame;
     /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     private syncQuad;

package/dist/components/animated-sprite.js

@@ -4,6 +4,9 @@ import { ClipPlayer } from '../animation/clip-player.js';
 import { locateFrame, sheetCell } from '../animation/sheet.js';
 import { spritePlacement } from '../sprite-placement.js';
 import { reportRejection } from '../report-rejection.js';
+import { spriteBatchesOf, spriteInstanceOf } from '../sprite-batches.js';
+/** Where a frame on a failed sheet draws: the flat (white) untextured quad. */
+const UNTEXTURED = { texture: null, pixelArt: false, shape: 'rectangle' };
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
@@ -139,6 +142,8 @@ export class AnimatedSprite extends Component {
     texs = [];
     // Clones whose sheet failed to load: applyFrame never installs them (CA-4).
     failedSheets = new Set();
+    // The drawn quad, or under Sprite Batches (ADR 0024) the hidden anchor of
+    // this sprite's instance, whose frame UV is read from the sheet clone.
     mesh;
     frame = 0;
     // Current frame's quad scale relative to the sheet's largest cell: always
@@ -169,8 +174,17 @@ export class AnimatedSprite extends Component {
             tex.repeat.set(1 / Math.max(1, sheet.cols), 1 / Math.max(1, sheet.rows));
             return tex;
         });
-        const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
-        this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+        const batches = spriteBatchesOf(this.game);
+        if (batches?.enabled) {
+            const instance = batches.attach(this.sheetKey(0));
+            instance.shownSheet = 0;
+            instance.uvSource = this.texs[0] ?? instance.uvSource;
+            this.mesh = instance.anchor;
+        }
+        else {
+            const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
+            this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+        }
         this.mesh.position.z = this.layer * 0.01;
         this.syncQuad();
         this.entity.node.add(this.mesh);
@@ -193,9 +207,16 @@ export class AnimatedSprite extends Component {
         this.showFrame(this.player.advance(dt));
     }
     onDestroy() {
-        this.mesh?.removeFromParent();
-        this.mesh?.geometry.dispose();
-        this.mesh?.material.dispose();
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.release();
+        }
+        else {
+            this.mesh?.removeFromParent();
+            this.mesh?.geometry.dispose();
+            this.mesh?.material.dispose();
+        }
+        this.mesh = undefined;
         // Only this sprite's clones: the cached bases live with the Game.
         for (const tex of this.texs)
             tex.dispose();
@@ -225,6 +246,10 @@ export class AnimatedSprite extends Component {
         }), 'sheet texture settle');
         return texture;
     }
+    /** The batch key of a sheet: its art, this sprite's filtering, a rectangle. */
+    sheetKey(index) {
+        return { texture: this.sheets[index]?.texture ?? '', pixelArt: this.pixelArt, shape: 'rectangle' };
+    }
     showFrame(index) {
         this.frame = index;
         this.applyFrame();
@@ -254,7 +279,17 @@ export class AnimatedSprite extends Component {
         const tex = this.texs[located.sheet];
         if (!sheet || !tex)
             return;
-        if (this.mesh) {
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            const failed = this.failedSheets.has(tex);
+            if (instance.shownSheet !== located.sheet || instance.shownSheetFailed !== failed) {
+                instance.moveTo(failed ? UNTEXTURED : this.sheetKey(located.sheet));
+                instance.shownSheet = located.sheet;
+                instance.shownSheetFailed = failed;
+            }
+            instance.uvSource = tex;
+        }
+        else if (this.mesh) {
             const map = this.failedSheets.has(tex) ? null : tex;
             if (this.mesh.material.map !== map) {
                 this.mesh.material.map = map;

package/dist/components/sprite.d.ts

@@ -68,6 +68,12 @@ export declare class Sprite extends Component implements YSortParticipant {
     set shape(value: SpriteShape);
     private mesh?;
     onReady(): void;
+    private buildMesh;
+    /**
+     * One instance in the batch of this sprite's key, tinted like the material
+     * the per-sprite path would build: white over a texture, `color` without.
+     */
+    private joinBatch;
     onDestroy(): void;
     /**
      * CA-4's failure rule: an image that never arrives leaves the flat

package/dist/components/sprite.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { Component } from '../component.js';
 import { spritePlacement } from '../sprite-placement.js';
 import { reportRejection } from '../report-rejection.js';
+import { spriteBatchesOf, spriteInstanceOf } from '../sprite-batches.js';
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
@@ -41,7 +42,11 @@ export class Sprite extends Component {
     }
     set color(value) {
         this._color = value;
-        this.mesh?.material.color.setHex(value);
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance)
+            instance.color.setHex(value);
+        else
+            this.mesh?.material.color.setHex(value);
     }
     _offsetX = 0;
     _offsetY = 0;
@@ -102,11 +107,30 @@ export class Sprite extends Component {
         this._shape = value === 'circle' ? 'circle' : 'rectangle';
         if (!this.mesh)
             return;
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.moveTo({ ...instance.key, shape: this._shape });
+            return;
+        }
         this.mesh.geometry.dispose();
         this.mesh.geometry = this.createGeometry();
     }
+    // The drawn quad, or under Sprite Batches (ADR 0024) the hidden anchor of
+    // this sprite's instance: the same placement either way.
     mesh;
     onReady() {
+        const batches = spriteBatchesOf(this.game);
+        if (batches?.enabled)
+            this.joinBatch(batches);
+        else
+            this.buildMesh();
+        if (!this.mesh)
+            return;
+        this.mesh.position.z = this.layer * 0.01;
+        this.syncQuad();
+        this.entity.node.add(this.mesh);
+    }
+    buildMesh() {
         const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
         if (this.texture) {
             // Its own clone of the cached base (game.assets, ADR 0019): filters
@@ -125,11 +149,35 @@ export class Sprite extends Component {
             }), 'sprite texture settle');
         }
         this.mesh = new THREE.Mesh(this.createGeometry(), material);
-        this.mesh.position.z = this.layer * 0.01;
-        this.syncQuad();
-        this.entity.node.add(this.mesh);
+    }
+    /**
+     * One instance in the batch of this sprite's key, tinted like the material
+     * the per-sprite path would build: white over a texture, `color` without.
+     */
+    joinBatch(batches) {
+        const key = { texture: this.texture || null, pixelArt: this.pixelArt, shape: this._shape };
+        const instance = batches.attach(key);
+        instance.color.setHex(this.texture ? 0xffffff : this.color);
+        this.mesh = instance.anchor;
+        const settled = batches.settled(key);
+        if (!settled)
+            return;
+        reportRejection(settled.then((outcome) => {
+            // CA-4's failure rule, copy-on-write: only this sprite leaves the
+            // shared entry, for the untextured one of its shape, with its color.
+            if (outcome !== 'failed' || spriteInstanceOf(this.mesh) !== instance)
+                return;
+            instance.moveTo({ ...instance.key, texture: null });
+            instance.color.setHex(this.color);
+        }), 'sprite texture settle');
     }
     onDestroy() {
+        const instance = spriteInstanceOf(this.mesh);
+        if (instance) {
+            instance.release();
+            this.mesh = undefined;
+            return;
+        }
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
         // Only this sprite's clone: the cached base lives with the Game.

package/dist/game.d.ts

@@ -103,6 +103,8 @@ export declare class Game {
     simulate: boolean;
     private readonly renderer;
     private readonly resizeObserver;
+    /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
+    private readonly spriteBatches;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     /**

package/dist/game.js

@@ -18,6 +18,7 @@ import { projectIsometric, unprojectIsometric } from './projection.js';
 import { isYSortBatchParticipant, isYSortParticipant, ySortZ, } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { sceneDrainsOf } from './scene-drains.js';
+import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { anchoredPiecesOf, GameUi } from './ui.js';
@@ -72,6 +73,8 @@ export class Game {
     // TODO(H1): migrate to WebGPURenderer (three/webgpu) with automatic WebGL2 fallback.
     renderer;
     resizeObserver;
+    /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
+    spriteBatches;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -133,6 +136,7 @@ export class Game {
             // catalog is registered at call time, which outlives every scene.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.spriteBatches = createSpriteBatches(this, this.assets);
         this.cameraEffects = new CameraEffects({
             host: () => canvas.parentElement ?? document.body,
             // One screen pixel in world units: the shake snaps to it (never the base).
@@ -205,6 +209,8 @@ export class Game {
             entity.destroy();
         // Drains transferred by the destruction cascade above are scene-scoped too.
         sceneDrainsOf(this).clear();
+        // After the cascade freed every slot: the batches go with their scene.
+        this.spriteBatches.unload();
         this.registry = null;
         this.renderSort = null;
         this.sceneProjection = null;
@@ -299,6 +305,7 @@ export class Game {
      */
     setSceneRender(json) {
         this.renderSort = json?.sort === 'y' ? 'y' : null;
+        this.spriteBatches.enabled = json?.batch !== false;
         const projection = json?.projection === 'isometric' ? 'isometric' : null;
         if (projection === this.sceneProjection)
             return;
@@ -399,6 +406,7 @@ export class Game {
         for (const entity of [...this.entities])
             entity.destroy();
         sceneDrainsOf(this).clear();
+        this.spriteBatches.unload();
         // After the entities: their clones go with the cascade above, the
         // cached bases go here, exactly once (ADR 0019).
         this.assets.dispose();
@@ -602,7 +610,7 @@ export class Game {
                 this.renderer.clear(true, false, false);
                 this.renderer.setScissorTest(true);
             }
-            this.renderer.render(this.scene, this.camera);
+            this.spriteBatches.drawFrame(this.scene, this.camera, () => this.renderer.render(this.scene, this.camera));
         }
         finally {
             this.camera.position.x = x;

package/dist/scene.d.ts

@@ -37,6 +37,16 @@ export interface SceneRenderJson {
     sort?: 'y';
     /** Logical positions are projected to the fixed 2:1 render lattice. */
     projection?: 'isometric';
+    /**
+     * Sprite Batches (ADR 0024). Absent or true: sprites that share art —
+     * same texture (an AnimatedSprite's current sheet), pixel-art filtering and
+     * shape — and sit next to each other in draw order are drawn together in
+     * one call, each one an instance with its own placement, color and frame;
+     * what is drawn in front of what never changes. false: one mesh, one
+     * material and one draw call per sprite, the pre-batching path — set it to
+     * rule batching out of a visual difference or while debugging draw order.
+     */
+    batch?: boolean;
 }
 export interface SceneJson {
     waicaScene: 1 | 2 | 3;

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);
+    }
+}