@waica/engine 0.22.0 → 0.24.0

package/dist/game.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { gameViewport } from './anchored-pieces.js';
 import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
@@ -15,9 +15,12 @@ import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric, unprojectIsometric } from './projection.js';
-import { isYSortBatchParticipant, isYSortParticipant, ySortZ, } from './render-sort.js';
+import { canvasBackground, drawStraightToCanvas, mapUvPerVertex } from './render-output.js';
+import { RenderReadiness } from './render-readiness.js';
+import { applyYSort } 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';
@@ -69,9 +72,12 @@ export class Game {
      * or collisions — the editor's edit mode.
      */
     simulate = true;
-    // TODO(H1): migrate to WebGPURenderer (three/webgpu) with automatic WebGL2 fallback.
+    /** WebGPU when the browser offers it, else three's WebGL2 fallback (ADR 0025). */
     renderer;
+    readiness;
     resizeObserver;
+    /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
+    spriteBatches;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -102,6 +108,8 @@ export class Game {
     liveSceneName = null;
     /** True for the whole extent of a runFrame() call, incl. its tail. */
     insideFrame = false;
+    /** Set by dispose(): a disposed Game never starts again nor reports its renderer (review #3). */
+    disposed = false;
     /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
     pendingSceneLoad = null;
     constructor(options) {
@@ -133,14 +141,25 @@ 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).
             pixel: () => (this.resolution ? this.viewHeight / this.resolution.height : null),
         });
-        this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+        this.renderer = new THREE.WebGPURenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
-        this.scene.background = new THREE.Color(background);
+        // The model view on the CPU, as three's WebGL renderer computed it: a Sprite
+        // Batch instance carries that same matrix (ADR 0024), so batched and
+        // per-sprite draws stay pixel-identical.
+        this.renderer.highPrecision = true;
+        drawStraightToCanvas(this.renderer);
+        mapUvPerVertex(this.renderer);
+        this.readiness = new RenderReadiness(this.renderer, (error) => {
+            if (!this.disposed)
+                activeRuntimeBridgeHook()?.fail?.({ code: 'render-backend-failed', message: error.message });
+        });
+        this.scene.background = canvasBackground(background);
         this.camera = new THREE.OrthographicCamera();
         this.camera.position.z = 10;
         this.pointer = new Pointer(canvas, {
@@ -153,6 +172,19 @@ export class Game {
         this.resizeObserver = new ResizeObserver(() => this.resize());
         this.resizeObserver.observe(canvas);
     }
+    /**
+     * 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() {
+        return this.readiness.promise;
+    }
+    /** The Render Backend the renderer settled on; null until ready() resolved. */
+    get backend() {
+        return this.readiness.backend;
+    }
     /** Creates a live entity in the scene. */
     spawn(name) {
         const entity = new Entity(this, name);
@@ -205,6 +237,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 +333,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;
@@ -331,6 +366,8 @@ export class Game {
         this.setViewHeight(this.sceneCamera.zoom);
     }
     start() {
+        if (this.disposed)
+            return;
         const activation = activeRuntimeBridgeHook();
         if (activation) {
             if (!this.runtimeBridge) {
@@ -350,19 +387,27 @@ export class Game {
                     loadScene: (name) => this.loadSceneByName(name),
                     availableScenes: () => this.availableScenes,
                     assets: () => this.assets.status,
+                    backend: () => this.backend,
                 });
                 activation.register(this.runtimeBridge);
                 this.audio.setSilenced(true);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
             }
             this.renderSurface();
+            // Started before ready(): the paused frame draws once the renderer can, frame unchanged.
+            if (!this.readiness.isReady) {
+                this.readiness.whenReady(() => {
+                    if (this.runtimeBridge)
+                        this.renderSurface();
+                });
+            }
             return;
         }
         this.resetClock();
-        this.renderer.setAnimationLoop((time) => this.tick(time));
+        this.setAnimationLoop((time) => this.tick(time));
     }
     stop() {
-        this.renderer.setAnimationLoop(null);
+        this.setAnimationLoop(null);
     }
     /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity) {
@@ -385,6 +430,7 @@ export class Game {
     }
     /** Shuts the game down completely (loop, input, GPU). */
     dispose() {
+        this.disposed = true;
         this.stop();
         this.unregisterRuntimeBridge();
         this.input.dispose();
@@ -399,10 +445,18 @@ 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();
-        this.renderer.dispose();
+        this.readiness.disposeRenderer();
+    }
+    /**
+     * three installs the loop once its init settled; a failed init is
+     * reported by ready(), not by every loop change made before it.
+     */
+    setAnimationLoop(loop) {
+        this.renderer.setAnimationLoop(loop).catch(() => { });
     }
     /**
      * Real-time playback for the Runtime Bridge: the same clock-driven loop
@@ -413,7 +467,7 @@ export class Game {
      */
     resumeRuntime(onStep) {
         this.resetClock();
-        this.renderer.setAnimationLoop((time) => this.tick(time, onStep));
+        this.setAnimationLoop((time) => this.tick(time, onStep));
     }
     /** Forgets the clock and any partial step, so the next frame runs no burst. */
     resetClock() {
@@ -541,40 +595,6 @@ export class Game {
         this.runtimeBridge = null;
         this.audio.setSilenced(false);
     };
-    /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
-    applyYSort() {
-        const singles = [];
-        const batches = [];
-        const entries = [];
-        for (const entity of this.entities) {
-            for (const component of entity.components) {
-                if (isYSortBatchParticipant(component)) {
-                    const batchEntries = component.ySortEntries();
-                    batches.push({ participant: component, start: entries.length, count: batchEntries.length });
-                    entries.push(...batchEntries);
-                }
-                else if (isYSortParticipant(component)) {
-                    singles.push({ participant: component, index: entries.length });
-                    entries.push({ layer: component.layer, y: entity.node.position.y });
-                }
-            }
-        }
-        for (const participant of sceneDrainsOf(this).participants()) {
-            const batchEntries = participant.ySortEntries();
-            batches.push({ participant, start: entries.length, count: batchEntries.length });
-            entries.push(...batchEntries);
-        }
-        const z = ySortZ(entries);
-        for (const { participant, index } of singles) {
-            const sortZ = z[index];
-            if (sortZ === undefined)
-                throw new Error(`ySortZ returned no z for y-sort participant ${index}`);
-            participant.setSortZ(sortZ);
-        }
-        for (const { participant, start, count } of batches) {
-            participant.setSortZs(z.slice(start, start + count));
-        }
-    }
     renderSurface() {
         if (this.sceneProjection === 'isometric') {
             for (const entity of this.entities) {
@@ -584,7 +604,7 @@ export class Game {
             }
         }
         if (this.renderSort === 'y')
-            this.applyYSort();
+            applyYSort(this.entities, sceneDrainsOf(this).participants());
         this.ui.setActive(this.simulate);
         // The shake offset exists only while drawing (ADR 0020): Anchored Pieces
         // and the render see the drawn center, then the base comes back exactly,
@@ -595,6 +615,9 @@ export class Game {
         this.camera.position.y = y + shake.y;
         try {
             anchoredPiecesOf(this.ui).place();
+            // Before ready() the frame simulated, but three cannot draw yet.
+            if (!this.readiness.isReady)
+                return;
             if (this.resolution) {
                 // Letterbox bars: clear the whole canvas, then render inside the scissor.
                 this.renderer.setScissorTest(false);
@@ -602,7 +625,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/index.d.ts

@@ -37,7 +37,8 @@ export type { GamepadControl } from './gamepad.js';
 export { Pointer } from './pointer.js';
 export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
-export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
+export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeBridgeFailure, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
+export type { RenderBackend } from './render-readiness.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotCamera, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
@@ -76,4 +77,4 @@ export { StateMachine, evaluateTrigger, nextTransition } from './state/state-mac
 export type { StateJson, StateTransitionJson, TriggerEnv } from './state/state-machine.js';
 export { defineRole, defineStates, installArchetype, logicSet, registeredLogicSets, registeredRoles, resetRegistries, roleDefinition, } from './state/hooks.js';
 export type { ArchetypeBundle, RoleDefinition, RoleGraph, StateContext, StateHooks, StateLogic, } from './state/hooks.js';
-export * as THREE from 'three';
+export * as THREE from 'three/webgpu';

package/dist/index.js

@@ -42,4 +42,6 @@ export { StateMachine, evaluateTrigger, nextTransition } from './state/state-mac
 export { defineRole, defineStates, installArchetype, logicSet, registeredLogicSets, registeredRoles, resetRegistries, roleDefinition, } from './state/hooks.js';
 // Explicit escape hatch while our own API grows: a single source of three
 // for the whole workspace. The thesis is that three stays an implementation detail.
-export * as THREE from 'three';
+// It is the WebGPU build the engine draws with (ADR 0025): no classic WebGL renderer,
+// and node materials (TSL) instead of GLSL shaders.
+export * as THREE from 'three/webgpu';

package/dist/particle-batch.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { AssetLoader } from './assets/asset-loader.js';
 import type { ParticleBlend, ParticleOverflow } from './components/particle-emitter.js';
 import { type ParticleSpawn } from './particle-pool.js';

package/dist/particle-batch.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { reportRejection } from './report-rejection.js';
 import { ParticlePool, particleValueAt, } from './particle-pool.js';
 import { projectIsometric } from './projection.js';
@@ -116,6 +116,9 @@ export class ParticleBatch {
         colors.needsUpdate = true;
         this.sortIndices();
         this.mesh.geometry.setDrawRange(0, this.active * 6);
+        // WebGPURenderer issues a zero-count draw (WebGLRenderer skipped it):
+        // an empty batch is not drawn at all.
+        this.mesh.visible = this.active > 0;
     }
     ySortEntries() {
         this.sortEntrySlots();

package/dist/particle-sort-bounds.d.ts

@@ -1,3 +1,3 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
 export declare function refreshParticleSortBounds(geometry: THREE.BufferGeometry, active: number, emptyZ: number): void;

package/dist/particle-sort-bounds.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
 export function refreshParticleSortBounds(geometry, active, emptyZ) {
     const positions = geometry.getAttribute('position');

package/dist/pointer.js

@@ -140,7 +140,7 @@ export class Pointer {
                     renderX <= centerX + halfW &&
                     renderY >= centerY - halfH &&
                     renderY <= centerY + halfH) {
-                    // Matches Game.applyYSort's key exactly: the entity's node
+                    // Matches applyYSort (render-sort.ts)'s key exactly: the entity's node
                     // position, which for an isometric scene is the projected Y (the
                     // same `anchor.y` just used to place this box), not the logical one.
                     hits.push({ entity, layer: box.layer, y: anchor.y });

package/dist/render-output.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from 'three/webgpu';
+/**
+ * Makes WebGPURenderer draw the way WebGLRenderer did (ADR 0025): straight
+ * into the 8-bit canvas, each material encoding its color to sRGB in its own
+ * shader, so alpha blending happens on sRGB values. By default three renders
+ * into a linear half-float target and converts it in an extra full-screen
+ * pass: blending in linear space, which changes every translucent edge, and
+ * one more draw per frame. A render target keeps the linear working space.
+ */
+export declare function drawStraightToCanvas(renderer: THREE.WebGPURenderer): void;
+/**
+ * The scene background for a canvas drawn straight: three clears with a
+ * color's working-space (linear) components, and the canvas stores sRGB, so
+ * the clear carries the color's sRGB components — what WebGLRenderer wrote.
+ */
+export declare function canvasBackground(color: THREE.ColorRepresentation): THREE.Color;
+/**
+ * Applies a material map's UV transform (offset, repeat) per vertex, as
+ * WebGLRenderer's `vMapUv` did, instead of per fragment as three's node
+ * materials do by default. At a quad's corners the UV is 0 or 1, so the
+ * transformed corner UV is the same float however a shader compiler fuses
+ * the multiply and add — per fragment it is not, and a sprite whose sheet
+ * offset is not 0 could then sample a texel row apart in two shaders of the
+ * same picture (a Sprite Batch and its per-sprite fallback, ADR 0024).
+ * Textures with their own UV node, or sampled outside a mesh, stay three's.
+ */
+export declare function mapUvPerVertex(renderer: THREE.WebGPURenderer): void;

package/dist/render-output.js

@@ -0,0 +1,44 @@
+import { uv, vertexStage, workingToColorSpace } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+/**
+ * Makes WebGPURenderer draw the way WebGLRenderer did (ADR 0025): straight
+ * into the 8-bit canvas, each material encoding its color to sRGB in its own
+ * shader, so alpha blending happens on sRGB values. By default three renders
+ * into a linear half-float target and converts it in an extra full-screen
+ * pass: blending in linear space, which changes every translucent edge, and
+ * one more draw per frame. A render target keeps the linear working space.
+ */
+export function drawStraightToCanvas(renderer) {
+    // The working space as output: three then needs no intermediate target.
+    renderer.outputColorSpace = THREE.ColorManagement.workingColorSpace;
+    const context = renderer.contextNode.value;
+    context.getOutput = (output, builder) => builder.renderer.getRenderTarget() === null ? workingToColorSpace(output, THREE.SRGBColorSpace) : output;
+}
+/**
+ * The scene background for a canvas drawn straight: three clears with a
+ * color's working-space (linear) components, and the canvas stores sRGB, so
+ * the clear carries the color's sRGB components — what WebGLRenderer wrote.
+ */
+export function canvasBackground(color) {
+    const { r, g, b } = new THREE.Color(color).getRGB({ r: 0, g: 0, b: 0 }, THREE.SRGBColorSpace);
+    return new THREE.Color().setRGB(r, g, b, THREE.LinearSRGBColorSpace);
+}
+/**
+ * Applies a material map's UV transform (offset, repeat) per vertex, as
+ * WebGLRenderer's `vMapUv` did, instead of per fragment as three's node
+ * materials do by default. At a quad's corners the UV is 0 or 1, so the
+ * transformed corner UV is the same float however a shader compiler fuses
+ * the multiply and add — per fragment it is not, and a sprite whose sheet
+ * offset is not 0 could then sample a texel row apart in two shaders of the
+ * same picture (a Sprite Batch and its per-sprite fallback, ADR 0024).
+ * Textures with their own UV node, or sampled outside a mesh, stay three's.
+ */
+export function mapUvPerVertex(renderer) {
+    const context = renderer.contextNode.value;
+    context.getUV = (texture, builder) => {
+        if (texture.uvNode !== null || !builder.object.isMesh)
+            return null;
+        texture.setUpdateMatrix(false);
+        return vertexStage(texture.getTransformedUV(uv(texture.value.channel)));
+    };
+}

package/dist/render-readiness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The GPU API a Game draws through (CONTEXT.md): `webgpu` when the browser
+ * offers it, otherwise three's own WebGL2 fallback. The browser decides; no
+ * option forces either one (ADR 0025).
+ */
+export type RenderBackend = 'webgpu' | 'webgl2';
+/** The part of three's WebGPURenderer readiness depends on. */
+export interface InitializingRenderer {
+    init(): Promise<unknown>;
+    dispose(): Promise<void>;
+    /** After init(), the backend it settled on: the WebGPU one, or the WebGL2 fallback. */
+    readonly backend: object;
+}
+/**
+ * A renderer's asynchronous initialization, owned by its Game: started at
+ * construction, settled once, and the only gate between a frame and a draw.
+ * `promise` is what `game.ready()` hands out; a failure rejects it with an
+ * error naming both Render Backends and is also reported to `onFailure`.
+ */
+export declare class RenderReadiness {
+    private readonly renderer;
+    readonly promise: Promise<void>;
+    private state;
+    constructor(renderer: InitializingRenderer, onFailure: (error: Error) => void);
+    /** Runs `then` once the renderer is ready; never after a failed init. */
+    whenReady(then: () => void): void;
+    /** True once the renderer can draw. */
+    get isReady(): boolean;
+    /** The Render Backend after a successful init; null before it and after a failure. */
+    get backend(): RenderBackend | null;
+    /**
+     * Frees the renderer: right away once it is ready, after init settles
+     * while it is pending (three cannot dispose a renderer mid-init), never
+     * after a failed init (nothing was allocated).
+     */
+    disposeRenderer(): void;
+}

package/dist/render-readiness.js

@@ -0,0 +1,61 @@
+/** three flags its WebGPU backend with `isWebGPUBackend`; its WebGL2 fallback has no such flag. */
+function backendOf(backend) {
+    return 'isWebGPUBackend' in backend && backend.isWebGPUBackend === true ? 'webgpu' : 'webgl2';
+}
+function describeCause(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * A renderer's asynchronous initialization, owned by its Game: started at
+ * construction, settled once, and the only gate between a frame and a draw.
+ * `promise` is what `game.ready()` hands out; a failure rejects it with an
+ * error naming both Render Backends and is also reported to `onFailure`.
+ */
+export class RenderReadiness {
+    renderer;
+    promise;
+    state = { status: 'pending' };
+    constructor(renderer, onFailure) {
+        this.renderer = renderer;
+        this.promise = renderer.init().then(() => {
+            this.state = { status: 'ready', backend: backendOf(renderer.backend) };
+        }, (cause) => {
+            this.state = { status: 'failed' };
+            const error = new Error(`No Render Backend could initialize: neither webgpu nor webgl2 is available (${describeCause(cause)}).`, { cause });
+            onFailure(error);
+            throw error;
+        });
+        // The rejection belongs to whoever awaits game.ready(); a Game nobody
+        // asked must not surface it as an unhandled rejection on top of that.
+        this.promise.catch(() => { });
+    }
+    /** Runs `then` once the renderer is ready; never after a failed init. */
+    whenReady(then) {
+        this.promise.then(then, () => { });
+    }
+    /** True once the renderer can draw. */
+    get isReady() {
+        return this.state.status === 'ready';
+    }
+    /** The Render Backend after a successful init; null before it and after a failure. */
+    get backend() {
+        return this.state.status === 'ready' ? this.state.backend : null;
+    }
+    /**
+     * Frees the renderer: right away once it is ready, after init settles
+     * while it is pending (three cannot dispose a renderer mid-init), never
+     * after a failed init (nothing was allocated).
+     */
+    disposeRenderer() {
+        const dispose = () => {
+            this.renderer.dispose().catch((error) => {
+                console.error('[waica] could not dispose the renderer', error);
+            });
+        };
+        if (this.isReady) {
+            dispose();
+            return;
+        }
+        this.promise.then(dispose, () => { });
+    }
+}

package/dist/render-sort.d.ts

@@ -35,3 +35,17 @@ export declare function isYSortBatchParticipant(value: unknown): value is YSortB
  * apart, so their band is exactly the old fixed 0.01.
  */
 export declare function ySortZ(entries: readonly YSortEntry[]): number[];
+/** What applyYSort reads of an entity: its components and the Y its node draws at. */
+export interface YSortEntity {
+    readonly components: readonly unknown[];
+    readonly node: {
+        readonly position: {
+            readonly y: number;
+        };
+    };
+}
+/**
+ * Under y-sort, re-derives every participant's z from layer band + entity Y:
+ * the scene's entities, then the batch participants its drains hold.
+ */
+export declare function applyYSort(entities: readonly YSortEntity[], drains: readonly YSortBatchParticipant[]): void;

package/dist/render-sort.js

@@ -48,3 +48,40 @@ export function ySortZ(entries) {
     }
     return z;
 }
+/**
+ * Under y-sort, re-derives every participant's z from layer band + entity Y:
+ * the scene's entities, then the batch participants its drains hold.
+ */
+export function applyYSort(entities, drains) {
+    const singles = [];
+    const batches = [];
+    const entries = [];
+    for (const entity of entities) {
+        for (const component of entity.components) {
+            if (isYSortBatchParticipant(component)) {
+                const batchEntries = component.ySortEntries();
+                batches.push({ participant: component, start: entries.length, count: batchEntries.length });
+                entries.push(...batchEntries);
+            }
+            else if (isYSortParticipant(component)) {
+                singles.push({ participant: component, index: entries.length });
+                entries.push({ layer: component.layer, y: entity.node.position.y });
+            }
+        }
+    }
+    for (const participant of drains) {
+        const batchEntries = participant.ySortEntries();
+        batches.push({ participant, start: entries.length, count: batchEntries.length });
+        entries.push(...batchEntries);
+    }
+    const z = ySortZ(entries);
+    for (const { participant, index } of singles) {
+        const sortZ = z[index];
+        if (sortZ === undefined)
+            throw new Error(`ySortZ returned no z for y-sort participant ${index}`);
+        participant.setSortZ(sortZ);
+    }
+    for (const { participant, start, count } of batches) {
+        participant.setSortZs(z.slice(start, start + count));
+    }
+}

package/dist/runtime-bridge.d.ts

@@ -1,4 +1,5 @@
 import type { AssetStatus } from './assets/asset-loader.js';
+import type { RenderBackend } from './render-readiness.js';
 import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
@@ -20,9 +21,13 @@ export type RuntimeMode = 'paused' | 'real-time';
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
  * optional `value` in (0, 1] and that every control result carries
- * `actionValues` beside `heldActions`.
+ * `actionValues` beside `heldActions`. `render-backend` (issue #140, ADR
+ * 0025) announces that every metadata carries `backend`: the Render Backend
+ * once the renderer is ready, null before — a Run Session waits for it — and
+ * that a renderer that fails to initialize reports through the activation's
+ * `fail`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions', 'render-backend'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -32,6 +37,8 @@ export interface RuntimeMetadata {
     capabilities: readonly string[];
     /** `game.assets.status` at the moment of the read — reading it never advances `frame`. */
     assets: AssetStatus;
+    /** The Render Backend once `game.ready()` resolved; null until then (and for good after a failed init). */
+    backend: RenderBackend | null;
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'release';
@@ -76,11 +83,18 @@ export interface RuntimeBridge {
     inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     control(request: RuntimeControlRequest): RuntimeControlResult;
 }
+/** Why a Game can never become operational; reported through the activation. */
+export interface RuntimeBridgeFailure {
+    code: 'render-backend-failed';
+    message: string;
+}
 /** Ephemeral pre-page hook installed by the owner of a browser context. */
 export interface RuntimeBridgeActivation {
     readonly protocolVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     register(bridge: RuntimeBridge): void;
     unregister(bridge: RuntimeBridge): void;
+    /** Optional: told when the Game's renderer fails to initialize, so the owner stops waiting. */
+    fail?(failure: RuntimeBridgeFailure): void;
 }
 export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
 export interface RuntimeBridgeHost {
@@ -104,6 +118,8 @@ export interface RuntimeBridgeHost {
     availableScenes(): string[];
     /** A fresh `game.assets.status`. */
     assets(): AssetStatus;
+    /** The Render Backend, null until the renderer is ready. */
+    backend(): RenderBackend | null;
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -20,7 +20,11 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
  * optional `value` in (0, 1] and that every control result carries
- * `actionValues` beside `heldActions`.
+ * `actionValues` beside `heldActions`. `render-backend` (issue #140, ADR
+ * 0025) announces that every metadata carries `backend`: the Render Backend
+ * once the renderer is ready, null before — a Run Session waits for it — and
+ * that a renderer that fails to initialize reports through the activation's
+ * `fail`.
  */
 export const RUNTIME_BRIDGE_CAPABILITIES = [
     'click',
@@ -29,6 +33,7 @@ export const RUNTIME_BRIDGE_CAPABILITIES = [
     'assets',
     'camera-effects',
     'analog-actions',
+    'render-backend',
 ];
 export class RuntimeBridgeOperationError extends Error {
     code;
@@ -79,6 +84,7 @@ export class EngineRuntimeBridge {
             simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
             assets: this.host.assets(),
+            backend: this.host.backend(),
         };
     }
     inspect(filters = {}) {

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;