@waica/engine 0.22.0 → 0.23.0

package/dist/sprite-batch.d.ts

@@ -0,0 +1,93 @@
+import * as THREE from 'three';
+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.MeshBasicMaterial, 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.MeshBasicMaterial;
+    /** 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,211 @@
+import * as THREE from 'three';
+/** 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';
+/**
+ * Shader hook shared by every batch material. The instance matrix already
+ * holds view × world (three's own `modelViewMatrix` for that sprite, computed
+ * the same way on the CPU), so the vertex shader skips `modelViewMatrix`; the
+ * map's UV transform comes from the instance instead of `mapTransform`. Every
+ * rewrite sits behind USE_INSTANCING: the hidden anchors share this material,
+ * and if one were ever drawn as a plain mesh it compiles three's own chunks.
+ */
+function useInstanceTransforms(shader) {
+    shader.vertexShader = shader.vertexShader
+        .replace('#include <common>', ['#include <common>', '#ifdef USE_INSTANCING', `  attribute vec4 ${INSTANCE_UV};`, '#endif'].join('\n'))
+        .replace('#include <uv_vertex>', [
+        '#ifdef USE_INSTANCING',
+        '  #ifdef USE_MAP',
+        `    vMapUv = ( mat3( ${INSTANCE_UV}.x, 0.0, 0.0, 0.0, ${INSTANCE_UV}.y, 0.0, ${INSTANCE_UV}.z, ${INSTANCE_UV}.w, 1.0 ) * vec3( MAP_UV, 1 ) ).xy;`,
+        '  #endif',
+        '#else',
+        '  #include <uv_vertex>',
+        '#endif',
+    ].join('\n'))
+        .replace('#include <project_vertex>', [
+        '#ifdef USE_INSTANCING',
+        '  vec4 mvPosition = instanceMatrix * vec4( transformed, 1.0 );',
+        '  gl_Position = projectionMatrix * mvPosition;',
+        '#else',
+        '  #include <project_vertex>',
+        '#endif',
+    ].join('\n'));
+}
+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 THREE.MeshBasicMaterial({ transparent: true, side: THREE.DoubleSide });
+    material.forceSinglePass = true;
+    material.onBeforeCompile = useInstanceTransforms;
+    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';
+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.MeshBasicMaterial>;
+/** 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;

package/dist/sprite-batches.js

@@ -0,0 +1,260 @@
+import * as THREE from 'three';
+import { SpriteBatch, spriteBatchKeyId, spriteGeometry, } from './sprite-batch.js';
+import { TransparentDrawCollector } from './sprite-draw-collector.js';
+import { compareTransparentDraws, forEachSpriteRun } from './sprite-runs.js';
+/**
+ * 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 class SpriteInstance {
+    anchor;
+    owner;
+    seat;
+    /** Linear RGB tint, what the per-sprite path writes into its material color. */
+    color = new THREE.Color(1, 1, 1);
+    /** Identity until an AnimatedSprite points it at its current sheet's clone. */
+    uvSource = { offset: new THREE.Vector2(0, 0), repeat: new THREE.Vector2(1, 1) };
+    modelView = new 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 = -1;
+    shownSheetFailed = false;
+    constructor(anchor, owner, seat) {
+        this.anchor = anchor;
+        this.owner = owner;
+        this.seat = seat;
+    }
+    get key() {
+        return this.seat.key;
+    }
+    get uvRepeat() {
+        return this.uvSource.repeat;
+    }
+    get uvOffset() {
+        return this.uvSource.offset;
+    }
+    /** Moves to the batch of `key` (a shape change, a failed texture, another sheet); a no-op for the same key. */
+    moveTo(key) {
+        this.owner.move(this, key);
+    }
+    /** Frees the slot and removes the anchor: the sprite was destroyed. */
+    release() {
+        this.owner.detach(this);
+    }
+}
+const anchors = new WeakMap();
+/** The batch instance whose hidden anchor this is; undefined for an ordinary mesh. */
+export function spriteInstanceOf(object) {
+    return object ? anchors.get(object) : 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 class SpriteBatches {
+    textures;
+    /** Whether sprites readied from now on batch: the scene's `render.batch !== false`. */
+    enabled = true;
+    batches = new Map();
+    geometries = new Map();
+    live = new Set();
+    root = new THREE.Group();
+    /** Under root, one Group per non-zero group order, so a run keeps its sprites' Group renderOrder. */
+    groups = new Map();
+    collector;
+    // Per-frame state, reused every frame: the camera, the next renderOrder to
+    // pin, and the non-sprite renderables whose renderOrder is pinned.
+    camera = new THREE.Camera();
+    nextOrder = 0;
+    pinned = [];
+    pinnedOrders = [];
+    pinnedScene = null;
+    sceneAutoUpdate = true;
+    visitor = {
+        run: (batch, start, end) => this.drawRun(batch, start, end),
+        other: (item) => this.pin(item.object),
+    };
+    constructor(textures) {
+        this.textures = textures;
+        this.root.name = 'waica:sprite-batches';
+        this.collector = new TransparentDrawCollector({
+            instanceOf: (object) => {
+                const instance = anchors.get(object);
+                return instance && this.live.has(instance) ? instance : undefined;
+            },
+            keyOf: (instance) => instance.seat.batch,
+        }, this.root);
+    }
+    /** A new batched sprite in the key's batch; the caller parents its hidden anchor. */
+    attach(key) {
+        const batch = this.batchFor(key);
+        const anchor = new THREE.Mesh(this.geometryFor(key.shape), batch.material);
+        // Never drawn and never read for visibility: a batched sprite shows or
+        // hides through its entity's node (README "Sprite Batches").
+        anchor.visible = false;
+        const instance = new SpriteInstance(anchor, this, { key, batch, slot: batch.join() });
+        anchors.set(anchor, instance);
+        this.live.add(instance);
+        return instance;
+    }
+    /** When the key's texture settled; null for an untextured or bare entry. */
+    settled(key) {
+        return this.batchFor(key).settled;
+    }
+    move(instance, key) {
+        if (spriteBatchKeyId(key) === spriteBatchKeyId(instance.key))
+            return;
+        instance.seat.batch.leave(instance.seat.slot);
+        const batch = this.batchFor(key);
+        instance.seat = { key, batch, slot: batch.join() };
+        instance.anchor.material = batch.material;
+        instance.anchor.geometry = this.geometryFor(key.shape);
+    }
+    detach(instance) {
+        if (!this.live.delete(instance))
+            return;
+        instance.seat.batch.leave(instance.seat.slot);
+        instance.anchor.removeFromParent();
+        anchors.delete(instance.anchor);
+    }
+    /**
+     * 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, camera) {
+        if (this.live.size === 0) {
+            this.root.removeFromParent();
+            return this.unpin;
+        }
+        scene.updateMatrixWorld();
+        camera.updateMatrixWorld();
+        this.collector.collect(scene, camera);
+        const drawables = this.collector.drawables.sort(compareTransparentDraws);
+        this.camera = camera;
+        this.nextOrder = 0;
+        for (const batch of this.batches.values())
+            batch.beginFrame();
+        forEachSpriteRun(drawables, this.visitor);
+        for (const batch of this.batches.values())
+            batch.detachUndrawn();
+        if (this.root.parent !== scene)
+            scene.add(this.root);
+        // Matrices are current: three's own update would recompute the same.
+        this.pinnedScene = scene;
+        this.sceneAutoUpdate = scene.matrixWorldAutoUpdate;
+        scene.matrixWorldAutoUpdate = false;
+        return this.unpin;
+    }
+    /** Runs `render` with this frame's runs drawn and the draw order pinned, then undoes the pin. */
+    drawFrame(scene, camera, render) {
+        const restore = this.prepareFrame(scene, camera);
+        try {
+            render();
+        }
+        finally {
+            restore();
+        }
+    }
+    /** Releases every batch, geometry and run mesh; batching is on again for the next scene. */
+    unload() {
+        for (const instance of [...this.live])
+            instance.release();
+        for (const batch of this.batches.values())
+            batch.dispose();
+        this.batches.clear();
+        for (const geometry of this.geometries.values())
+            geometry.dispose();
+        this.geometries.clear();
+        for (const group of this.groups.values())
+            group.removeFromParent();
+        this.groups.clear();
+        this.root.removeFromParent();
+        this.enabled = true;
+    }
+    batchFor(key) {
+        const id = spriteBatchKeyId(key);
+        const existing = this.batches.get(id);
+        if (existing)
+            return existing;
+        const created = new SpriteBatch(key, this.textures, this.geometryFor(key.shape));
+        this.batches.set(id, created);
+        return created;
+    }
+    geometryFor(shape) {
+        const existing = this.geometries.get(shape);
+        if (existing)
+            return existing;
+        const created = spriteGeometry(shape);
+        this.geometries.set(shape, created);
+        return created;
+    }
+    /** Draws the frame's run `start`..`end` of `batch` through its next pooled run mesh, in its Group order. */
+    drawRun(batch, start, end) {
+        const drawables = this.collector.drawables;
+        const run = batch.nextRun(end - start);
+        for (let index = start; index < end; index += 1)
+            run.write(index - start, this.placed(drawables[index]?.instance));
+        run.commit(end - start);
+        run.mesh.renderOrder = this.nextOrder;
+        this.nextOrder += 1;
+        const group = this.groupFor(drawables[start]?.groupOrder ?? 0);
+        if (run.mesh.parent !== group)
+            group.add(run.mesh);
+    }
+    /** Pins a non-sprite renderable's renderOrder to its place in the frame, until unpin. */
+    pin(object) {
+        this.pinned.push(object);
+        this.pinnedOrders.push(object.renderOrder);
+        object.renderOrder = this.nextOrder;
+        this.nextOrder += 1;
+    }
+    /** After the render: every pinned renderOrder back, and the scene's own matrix updates. */
+    unpin = () => {
+        for (const [index, object] of this.pinned.entries())
+            object.renderOrder = this.pinnedOrders[index] ?? object.renderOrder;
+        this.pinned.length = 0;
+        this.pinnedOrders.length = 0;
+        if (this.pinnedScene)
+            this.pinnedScene.matrixWorldAutoUpdate = this.sceneAutoUpdate;
+        this.pinnedScene = null;
+    };
+    /** The Group a run of `groupOrder` hangs from: three reads its renderOrder as the run's group order. */
+    groupFor(groupOrder) {
+        if (groupOrder === 0)
+            return this.root;
+        const existing = this.groups.get(groupOrder);
+        if (existing)
+            return existing;
+        const group = new THREE.Group();
+        group.renderOrder = groupOrder;
+        this.root.add(group);
+        this.groups.set(groupOrder, group);
+        return group;
+    }
+    /** The instance with its view × world computed exactly as three computes `modelViewMatrix`. */
+    placed(instance) {
+        if (!instance)
+            throw new Error('a Sprite Batch run holds only sprites');
+        instance.modelView.multiplyMatrices(this.camera.matrixWorldInverse, instance.anchor.matrixWorld);
+        return instance;
+    }
+}
+const registry = new WeakMap();
+/** Internal: the Game creates its batches here at construction, findable by its sprites. */
+export function createSpriteBatches(game, textures) {
+    const batches = new SpriteBatches(textures);
+    registry.set(game, batches);
+    return batches;
+}
+/** A Game's Sprite Batches; undefined for anything that is not a constructed Game (a test stub). */
+export function spriteBatchesOf(game) {
+    return registry.get(game);
+}