@waica/engine 0.22.0 → 0.24.0

package/README.md

@@ -6,6 +6,25 @@ Waica's public engine core: entities and components, the game loop, scene and pr
 import { Component, Game, loadScene } from '@waica/engine'
 ```
 
+## Migrating to 0.24.0: WebGPURenderer and `game.ready()`
+
+A `Game` draws through three's `WebGPURenderer` (ADR 0025): WebGPU when the browser offers it, otherwise the renderer's own WebGL2 fallback. The browser decides — there is no option to force either one — and `game.backend` reports which one it got (`'webgpu'` or `'webgl2'`; `null` until the renderer is ready).
+
+- **Await `game.ready()` before the first frame.** `new Game(...)` stays synchronous, but the renderer initializes asynchronously. Frames before it finishes still simulate (steps, `onUpdate`) but draw nothing, so a host waits for it before `game.start()`:
+
+  ```ts
+  const game = new Game({ canvas })
+  loadScene(game, scene, registry)
+  await game.assets.ready()
+  await game.ready()
+  game.start()
+  ```
+
+  Every call returns the same promise. It rejects with an error naming both `webgpu` and `webgl2` when neither initializes; nothing is ever drawn then. A `Game` disposed while `ready()` is pending never starts, and its renderer is released once initialization settles.
+- **`THREE` is the `three/webgpu` build.** `import { THREE } from '@waica/engine'` now re-exports `three/webgpu`, the same copy of three the engine draws with: `THREE.WebGPURenderer` exists and `THREE.WebGLRenderer` does not. Custom GLSL does not render under `WebGPURenderer` — `ShaderMaterial`, `RawShaderMaterial` and `material.onBeforeCompile` are not supported there — so write custom shading as node materials with TSL (`three/tsl`). Built-in materials such as `MeshBasicMaterial` keep working unchanged.
+- **Tests under happy-dom.** happy-dom has no GPU: a project test that builds a `Game` replaces `WebGPURenderer` from `three/webgpu` with a fake (it previously replaced `WebGLRenderer` from `three`), whose `init()` resolves.
+- **Run Sessions.** A Run Session waits for the Render Backend before it reports ready, steps or screenshots, and its snapshots carry `backend`. A renderer that cannot initialize ends `start_project` with a runtime error that names the failure.
+
 ## Hitbox Collision Layers and Masks
 
 Every `Hitbox` belongs to one named Collision Layer and declares the other layers in which it is interested through a Collision Mask:
@@ -150,6 +169,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/assets/asset-loader.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { type TextureBackend } from './texture-backend.js';
 /** `game.assets.status`: a fresh snapshot of the cache's counters, cumulative for the Game. */
 export interface AssetStatus {

package/dist/assets/asset-loader.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { ThreeTextureBackend } from './texture-backend.js';
 import { reportRejection } from '../report-rejection.js';
 /**

package/dist/assets/texture-backend.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /**
  * The seam between `game.assets` and the browser (ADR 0013's move, applied
  * to textures — ADR 0019). `load` resolves once the image behind `url` is

package/dist/assets/texture-backend.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /** The real implementation: one `THREE.TextureLoader` per Game, wrapped in a promise. */
 export class ThreeTextureBackend {
     loader = new THREE.TextureLoader();

package/dist/camera.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 export const CAMERA_DEFAULTS = {
     position: [0, 0],
     zoom: 12,

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

@@ -1,9 +1,12 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { Component } from '../component.js';
 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

@@ -1,7 +1,8 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 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/components/tilemap.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { sheetCell } from '../animation/sheet.js';
 import { Component } from '../component.js';
 import { projectIsometric } from '../projection.js';
@@ -283,6 +283,8 @@ export class Tilemap extends Component {
         geometry.setIndex(new THREE.BufferAttribute(new Uint32Array(buffers.indices), 1));
         mesh.geometry.dispose();
         mesh.geometry = geometry;
+        // WebGPURenderer issues a zero-count draw (WebGLRenderer skipped it): no tile, no draw.
+        mesh.visible = buffers.indices.length > 0;
     }
     /** The loaded sheet image's size, or one pixel per sheet cell until it arrives. */
     sheetSize() {

package/dist/entity.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { Component, ComponentClass } from './component.js';
 import type { Game } from './game.js';
 /**

package/dist/entity.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /**
  * A live scene node: a transform (three Group) + components.
  * Created with `game.spawn(name)`.

package/dist/game.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { AssetLoader } from './assets/asset-loader.js';
 import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
@@ -11,6 +11,7 @@ import { Emitter } from './events.js';
 import { GameTime } from './game-time.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
+import { type RenderBackend } from './render-readiness.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { type SpatialQuery } from './spatial-query.js';
 import { Stats, type StatValue } from './stats.js';
@@ -101,8 +102,12 @@ export declare class Game {
      * or collisions — the editor's edit mode.
      */
     simulate: boolean;
+    /** WebGPU when the browser offers it, else three's WebGL2 fallback (ADR 0025). */
     private readonly renderer;
+    private readonly readiness;
     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;
     /**
@@ -133,9 +138,20 @@ export declare class Game {
     private liveSceneName;
     /** True for the whole extent of a runFrame() call, incl. its tail. */
     private insideFrame;
+    /** Set by dispose(): a disposed Game never starts again nor reports its renderer (review #3). */
+    private disposed;
     /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
     private pendingSceneLoad;
     constructor(options: GameOptions);
+    /**
+     * Resolves once the renderer can draw; rejects, naming both Render
+     * Backends, when neither initializes. Every call returns the same promise.
+     * Frames before it simulate but draw nothing, so a host awaits it before
+     * its first frame (ADR 0025).
+     */
+    ready(): Promise<void>;
+    /** The Render Backend the renderer settled on; null until ready() resolved. */
+    get backend(): RenderBackend | null;
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
     /** Instantiates a registered prefab after a scene has supplied the registry. */
@@ -203,6 +219,11 @@ export declare class Game {
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
     dispose(): void;
+    /**
+     * three installs the loop once its init settled; a failed init is
+     * reported by ready(), not by every loop change made before it.
+     */
+    private setAnimationLoop;
     /**
      * Real-time playback for the Runtime Bridge: the same clock-driven loop
      * as start(), sharing the accumulator, with `onStep` told after every
@@ -246,8 +267,6 @@ export declare class Game {
     private runHostUpdates;
     private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
-    /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
-    private applyYSort;
     private renderSurface;
     private componentUpdateSchedule;
     private updateSceneCamera;