@waica/engine 0.22.0 → 0.23.0

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.22.0",
+  "version": "0.23.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",