@waica/engine 0.21.0 → 0.23.0

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

package/dist/sprite-draw-collector.d.ts

@@ -0,0 +1,42 @@
+import * as THREE from 'three';
+import type { Drawable } from './sprite-runs.js';
+/** A frame drawable: what three sorts it by, the object, and the sprite instance it stands for (null otherwise). */
+export interface FrameDrawable<K, I> extends Drawable<K> {
+    object: THREE.Object3D;
+    instance: I | null;
+}
+/** How the collector recognises a batched sprite's hidden anchor and its batch key. */
+export interface CollectedSprites<K, I> {
+    /** The live sprite instance this object anchors, or undefined for any other object. */
+    instanceOf(object: THREE.Object3D): I | undefined;
+    keyOf(instance: I): K;
+}
+/**
+ * One frame's transparent drawables, collected the way WebGLRenderer's
+ * projectObject walks the scene: visibility, camera layers, Group render
+ * order, frustum culling, and the clip-space z it sorts by. Sprite anchors
+ * are hidden yet collected when in view; `skip` (the batches' own run
+ * meshes) is never walked. The drawables are pooled across frames.
+ */
+export declare class TransparentDrawCollector<K, I> {
+    private readonly sprites;
+    private readonly skip;
+    /** This frame's drawables, in walk order; the same array every frame. */
+    readonly drawables: FrameDrawable<K, I>[];
+    private readonly pool;
+    private readonly projScreen;
+    private readonly frustum;
+    private readonly point;
+    private layers;
+    constructor(sprites: CollectedSprites<K, I>, skip: THREE.Object3D);
+    /** Walks `scene` for `camera`, whose matrices must be current. */
+    collect(scene: THREE.Object3D, camera: THREE.Camera): void;
+    private visit;
+    /** Files the object itself when three would draw it transparent; returns the group order for its children. */
+    private visitOwn;
+    /** three's per-object culling: `!frustumCulled || intersectsFrustum`. */
+    private inView;
+    private push;
+    /** The clip-space z three sorts the object by. */
+    private sortDepth;
+}

package/dist/sprite-draw-collector.js

@@ -0,0 +1,107 @@
+import * as THREE from 'three';
+function isRenderable(object) {
+    const flags = object;
+    return flags.isMesh === true || flags.isLine === true || flags.isPoints === true || flags.isSprite === true;
+}
+/** Whether three files any of the object's materials in its transparent list. */
+function drawsTransparent(object) {
+    const list = Array.isArray(object.material) ? object.material : [object.material];
+    return list.some((material) => {
+        const transmission = material.transmission ?? 0;
+        return material.visible && material.transparent && transmission <= 0;
+    });
+}
+/** The bounding-sphere center three sorts a mesh, line or points by: the object's own sphere if it has one. */
+function sortCenter(object) {
+    const own = object;
+    if (own.boundingSphere === undefined) {
+        const geometry = object.geometry;
+        if (geometry.boundingSphere === null)
+            geometry.computeBoundingSphere();
+        return geometry.boundingSphere?.center ?? new THREE.Vector3();
+    }
+    if (own.boundingSphere === null)
+        own.computeBoundingSphere?.();
+    return own.boundingSphere?.center ?? new THREE.Vector3();
+}
+/**
+ * One frame's transparent drawables, collected the way WebGLRenderer's
+ * projectObject walks the scene: visibility, camera layers, Group render
+ * order, frustum culling, and the clip-space z it sorts by. Sprite anchors
+ * are hidden yet collected when in view; `skip` (the batches' own run
+ * meshes) is never walked. The drawables are pooled across frames.
+ */
+export class TransparentDrawCollector {
+    sprites;
+    skip;
+    /** This frame's drawables, in walk order; the same array every frame. */
+    drawables = [];
+    pool = [];
+    projScreen = new THREE.Matrix4();
+    frustum = new THREE.Frustum();
+    point = new THREE.Vector4();
+    layers = new THREE.Layers();
+    constructor(sprites, skip) {
+        this.sprites = sprites;
+        this.skip = skip;
+    }
+    /** Walks `scene` for `camera`, whose matrices must be current. */
+    collect(scene, camera) {
+        this.layers = camera.layers;
+        this.projScreen.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+        this.frustum.setFromProjectionMatrix(this.projScreen, THREE.WebGLCoordinateSystem, camera.reversedDepth);
+        this.drawables.length = 0;
+        this.visit(scene, 0);
+    }
+    visit(object, groupOrder) {
+        if (object === this.skip)
+            return;
+        const instance = this.sprites.instanceOf(object);
+        if (instance !== undefined) {
+            if (object.layers.test(this.layers) && this.inView(object))
+                this.push(object, groupOrder, instance);
+            return;
+        }
+        if (!object.visible)
+            return;
+        const order = this.visitOwn(object, groupOrder);
+        for (const child of object.children)
+            this.visit(child, order);
+    }
+    /** Files the object itself when three would draw it transparent; returns the group order for its children. */
+    visitOwn(object, groupOrder) {
+        if (!object.layers.test(this.layers))
+            return groupOrder;
+        if (object.isGroup === true)
+            return object.renderOrder;
+        if (isRenderable(object) && drawsTransparent(object) && this.inView(object))
+            this.push(object, groupOrder, null);
+        return groupOrder;
+    }
+    /** three's per-object culling: `!frustumCulled || intersectsFrustum`. */
+    inView(object) {
+        return !object.frustumCulled || object.intersectsFrustum(this.frustum) === true;
+    }
+    push(object, groupOrder, instance) {
+        const index = this.drawables.length;
+        const drawable = this.pool[index] ?? { key: null, groupOrder: 0, renderOrder: 0, z: 0, id: 0, object, instance: null };
+        this.pool[index] = drawable;
+        drawable.key = instance === null ? null : this.sprites.keyOf(instance);
+        drawable.groupOrder = groupOrder;
+        drawable.renderOrder = object.renderOrder;
+        drawable.z = this.sortDepth(object);
+        drawable.id = object.id;
+        drawable.object = object;
+        drawable.instance = instance;
+        this.drawables.push(drawable);
+    }
+    /** The clip-space z three sorts the object by. */
+    sortDepth(object) {
+        if (object.isSprite === true) {
+            return this.point.setFromMatrixPosition(object.matrixWorld).applyMatrix4(this.projScreen).z;
+        }
+        const center = sortCenter(object);
+        // Vector4.copy of a Vector3, as three does it: w becomes 1.
+        return this.point.set(center.x, center.y, center.z, 1).applyMatrix4(object.matrixWorld).applyMatrix4(this.projScreen).z;
+    }
+}

package/dist/sprite-runs.d.ts

@@ -0,0 +1,40 @@
+/** One transparent renderable of a frame, with the fields three sorts it by. */
+export interface Drawable<K> {
+    /** The sprite's batch key; null for any other renderable (particles, tilemaps, meshes). */
+    key: K | null;
+    /** The renderOrder of the nearest ancestor Group (three's `groupOrder`). */
+    groupOrder: number;
+    renderOrder: number;
+    /** Clip-space z of the sort point, as three computes it: higher is farther. */
+    z: number;
+    /** Object3D id: three's last tie-break, so creation order. */
+    id: number;
+}
+/** A Sprite Batch run, or a renderable drawn on its own between runs. */
+export type DrawStep<K, T extends Drawable<K>> = {
+    kind: 'run';
+    key: K;
+    groupOrder: number;
+    items: T[];
+} | {
+    kind: 'other';
+    item: T;
+};
+/** three's `reversePainterSortStable`: the order it draws transparent objects in. */
+export declare function compareTransparentDraws<K>(a: Drawable<K>, b: Drawable<K>): number;
+/** What forEachSpriteRun reports, in draw order. */
+export interface SpriteRunVisitor<K, T extends Drawable<K>> {
+    /** A run: the drawables `start` (inclusive) to `end` (exclusive) share `key` and one group order. */
+    run(key: K, start: number, end: number): void;
+    other(item: T): void;
+}
+/**
+ * Walks drawables already in draw order and reports each maximal sequence of
+ * consecutive same-key sprites under one group order as a run. A sprite of
+ * another key, any other renderable, or a change of group order ends the
+ * run — so batching never changes what is drawn in front of what (ADR 0024).
+ * Allocates nothing: the frame pass calls it every rendered frame.
+ */
+export declare function forEachSpriteRun<K, T extends Drawable<K>>(ordered: readonly T[], visitor: SpriteRunVisitor<K, T>): void;
+/** Orders a frame's drawables exactly as three would draw them, then groups them into runs. */
+export declare function buildSpriteRuns<K, T extends Drawable<K>>(drawables: readonly T[]): DrawStep<K, T>[];

package/dist/sprite-runs.js

@@ -0,0 +1,49 @@
+/** three's `reversePainterSortStable`: the order it draws transparent objects in. */
+export function compareTransparentDraws(a, b) {
+    if (a.groupOrder !== b.groupOrder)
+        return a.groupOrder - b.groupOrder;
+    if (a.renderOrder !== b.renderOrder)
+        return a.renderOrder - b.renderOrder;
+    if (a.z !== b.z)
+        return b.z - a.z;
+    return a.id - b.id;
+}
+/**
+ * Walks drawables already in draw order and reports each maximal sequence of
+ * consecutive same-key sprites under one group order as a run. A sprite of
+ * another key, any other renderable, or a change of group order ends the
+ * run — so batching never changes what is drawn in front of what (ADR 0024).
+ * Allocates nothing: the frame pass calls it every rendered frame.
+ */
+export function forEachSpriteRun(ordered, visitor) {
+    let start = 0;
+    while (start < ordered.length) {
+        const first = ordered[start];
+        if (!first)
+            return;
+        const key = first.key;
+        if (key === null) {
+            visitor.other(first);
+            start += 1;
+            continue;
+        }
+        let end = start + 1;
+        while (end < ordered.length && ordered[end]?.key === key && ordered[end]?.groupOrder === first.groupOrder)
+            end += 1;
+        visitor.run(key, start, end);
+        start = end;
+    }
+}
+/** Orders a frame's drawables exactly as three would draw them, then groups them into runs. */
+export function buildSpriteRuns(drawables) {
+    const ordered = [...drawables].sort(compareTransparentDraws);
+    const steps = [];
+    forEachSpriteRun(ordered, {
+        run: (key, start, end) => {
+            const items = ordered.slice(start, end);
+            steps.push({ kind: 'run', key, groupOrder: items[0]?.groupOrder ?? 0, items });
+        },
+        other: (item) => steps.push({ kind: 'other', item }),
+    });
+    return steps;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",