@waica/engine 0.23.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:

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/components/animated-sprite.js

@@ -1,4 +1,4 @@
-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';

package/dist/components/sprite.js

@@ -1,4 +1,4 @@
-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';

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,7 +102,9 @@ 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;
@@ -135,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. */
@@ -205,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
@@ -248,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;

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,7 +15,9 @@ 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';
@@ -70,8 +72,9 @@ 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;
@@ -105,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) {
@@ -142,9 +147,19 @@ export class Game {
             // 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, {
@@ -157,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);
@@ -338,6 +366,8 @@ export class Game {
         this.setViewHeight(this.sceneCamera.zoom);
     }
     start() {
+        if (this.disposed)
+            return;
         const activation = activeRuntimeBridgeHook();
         if (activation) {
             if (!this.runtimeBridge) {
@@ -357,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) {
@@ -392,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();
@@ -410,7 +449,14 @@ export class Game {
         // 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
@@ -421,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() {
@@ -549,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) {
@@ -592,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,
@@ -603,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);

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/sprite-batch.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { TextureOutcome } from './assets/asset-loader.js';
 export type SpriteBatchShape = 'rectangle' | 'circle';
 /**
@@ -44,7 +44,7 @@ export declare class SpriteRunMesh {
     readonly mesh: THREE.InstancedMesh;
     private readonly colors;
     private readonly uvs;
-    constructor(base: THREE.BufferGeometry, material: THREE.MeshBasicMaterial, capacity: number);
+    constructor(base: THREE.BufferGeometry, material: THREE.MeshBasicNodeMaterial, capacity: number);
     get capacity(): number;
     /** Writes the sprite drawn `index`-th in this run. */
     write(index: number, instance: SpriteBatchInstance): void;
@@ -61,7 +61,7 @@ export declare class SpriteRunMesh {
  */
 export declare class SpriteBatch {
     private readonly geometry;
-    readonly material: THREE.MeshBasicMaterial;
+    readonly material: THREE.MeshBasicNodeMaterial;
     /** When the key's texture settled; null for untextured and bare entries. */
     readonly settled: Promise<TextureOutcome> | null;
     private readonly slots;

package/dist/sprite-batch.js

@@ -1,4 +1,5 @@
-import * as THREE from 'three';
+import { attribute, context, mat3, positionLocal, uv, vec3, vertexStage } from 'three/tsl';
+import * as THREE from 'three/webgpu';
 /** 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. */
@@ -12,41 +13,52 @@ export function spriteGeometry(shape) {
 }
 /** The per-instance UV transform a run carries: repeat (x, y) and offset (z, w). */
 const INSTANCE_UV = 'instanceUv';
+/** Whether three is building the material for one of the batch's instanced run meshes. */
+function drawsInstances(builder) {
+    return builder.object.isInstancedMesh === true;
+}
+/**
+ * The map UV of one instance: its repeat and offset as the same mat3 a
+ * texture's own matrix is, applied to the quad's UV per vertex — as every
+ * other map is (render-output.ts `mapUvPerVertex`) — so the corner UVs are
+ * the very floats the per-sprite draw interpolates.
+ */
+function instanceMapUv() {
+    const transform = attribute(INSTANCE_UV, 'vec4');
+    return vertexStage(mat3(transform.x, 0, 0, 0, transform.y, 0, transform.z, transform.w, 1).mul(vec3(uv(), 1)).xy);
+}
 /**
- * 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.
+ * Every batch's material, as a node material (ADR 0025). The instance
+ * matrix already holds view × world (three's own `modelViewMatrix` for that
+ * sprite, computed the same way on the CPU), so an instanced draw skips
+ * `modelViewMatrix`; the map's UV transform comes from the instance instead
+ * of the texture. Both apply to instanced draws only: the hidden anchors
+ * share this material, and if one were ever drawn as a plain mesh it gets
+ * three's own transforms.
  */
-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'));
+class SpriteBatchMaterial extends THREE.MeshBasicNodeMaterial {
+    constructor(parameters) {
+        super(parameters);
+        this.contextNode = context({
+            getUV: (texture, builder) => {
+                if (!drawsInstances(builder))
+                    return null;
+                // The instance transform replaces the map's own matrix.
+                texture.setUpdateMatrix(false);
+                return instanceMapUv();
+            },
+        });
+    }
+    setupPositionView(builder) {
+        // three's instancing already multiplied positionLocal by the instance matrix.
+        return drawsInstances(builder) ? positionLocal : super.setupPositionView(builder);
+    }
 }
 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 });
+    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide });
     material.forceSinglePass = true;
-    material.onBeforeCompile = useInstanceTransforms;
     if (key.texture === null)
         return { material, settled: null };
     const { texture, settled } = key.texture

package/dist/sprite-batches.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 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';
@@ -7,7 +7,7 @@ export interface SpriteUvSource {
     readonly offset: THREE.Vector2;
     readonly repeat: THREE.Vector2;
 }
-export type SpriteAnchor = THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicMaterial>;
+export type SpriteAnchor = THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicNodeMaterial>;
 /** Where an instance sits: its key, that key's batch and its slot there. */
 export interface SpriteBatchSeat {
     key: SpriteBatchKey;

package/dist/sprite-batches.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { SpriteBatch, spriteBatchKeyId, spriteGeometry, } from './sprite-batch.js';
 import { TransparentDrawCollector } from './sprite-draw-collector.js';
 import { compareTransparentDraws, forEachSpriteRun } from './sprite-runs.js';

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

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 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> {
@@ -12,8 +12,8 @@ export interface CollectedSprites<K, I> {
     keyOf(instance: I): K;
 }
 /**
- * One frame's transparent drawables, collected the way WebGLRenderer's
- * projectObject walks the scene: visibility, camera layers, Group render
+ * One frame's transparent drawables, collected the way three's renderer
+ * (`_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.

package/dist/sprite-draw-collector.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 function isRenderable(object) {
     const flags = object;
     return flags.isMesh === true || flags.isLine === true || flags.isPoints === true || flags.isSprite === true;
@@ -25,8 +25,8 @@ function sortCenter(object) {
     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
+ * One frame's transparent drawables, collected the way three's renderer
+ * (`_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.

package/package.json

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