@waica/engine 0.23.0 → 0.25.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:
@@ -164,6 +183,30 @@ Under batching, the object a sprite adds to its entity is a hidden placement anc
 
 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.
 
+## Lighting and Post Effects
+
+A scene can be lit (issue #78, ADR 0026). Without lighting and without a Post Effect a scene is drawn exactly as before: one render straight into the canvas, no render target.
+
+```json
+"render": {
+  "lighting": { "ambient": { "color": "#5a6a9a", "intensity": 0.3 } },
+  "post": {
+    "vignette": { "intensity": 0.45, "radius": 0.35 },
+    "colorGrade": { "tint": "#ffeedd", "contrast": 1.1, "saturation": 0.9 }
+  }
+}
+```
+
+- **Ambient Light.** `render.lighting.ambient` is where no light reaches: `color` (`#rrggbb`, default `#ffffff`) times `intensity` (0..1, default 1). `game.lighting.ambient` reads it and sets it at runtime, field by field (`game.lighting.ambient = { intensity: 0.2 }`), so a day/night cycle is a `game.time.tween` whose `onUpdate` sets it. Setting it lights a scene that declared none. It dies with its scene: a scene load or swap takes the next scene's value.
+- **Light.** A component: `radius` (logical units), `color`, `intensity` (≥ 0), `bands` (0 smooth, up to 16 equal steps), `softness` (0 hard shadow edge, up to 1), `castShadows` (default true) and `offsetX`/`offsetY` from its entity. Its falloff is `1 − smoothstep(d / radius)`, measured in logical space, so on an isometric screen it is a 2:1 ellipse. Lights add to the Ambient Light and never darken; the sum clamps at 1. A scene with a live Light is lit even without `render.lighting`, but under full Ambient Light (`#ffffff`, 1) a light changes no pixel, so such a frame skips the light-map altogether. `game.lighting.lights` lists them.
+- **Occlusion.** Only Tilemap `solidTiles` stop light: a point whose line to the light crosses a solid tile other than its own is in shadow, while the solid tile itself keeps the light that reaches it (its lit face). Every Tilemap of the scene contributes; the grid is rebuilt only when a Tilemap spawns, is destroyed or changes its tiles. Props with a `Solid` and moving entities cast no shadow.
+- **Emissive.** `Sprite`, `AnimatedSprite` and `ParticleEmitter` take `emissive: true`: drawn after the light-map at full brightness (a flame, sparks), still in their own order and Sprite Batch runs. Every drawable discards its fully transparent texels, so an Emissive drawable behind a lit sprite shows through that sprite's transparent texels and stays hidden behind its opaque ones. Engine-wise they sit on `EMISSIVE_LAYER`; `setEmissive(object, true)` puts any three.js object there.
+- **How a lit frame is drawn.** The scene without its Emissive drawables goes straight to the canvas as always; then a light-map — an 8-bit target the size of the fixed `resolution` (nearest upscale), or of the drawing buffer without one — cleared to the Ambient Light and lit by one quad per Light is multiplied over it; then the Emissive drawables. The multiply works on the canvas's sRGB values, so Ambient Light 1 with no light leaves the frame identical.
+- **Post Effects.** `render.post.vignette` (`intensity` and `radius`, 0..1) darkens towards the corners; `render.post.colorGrade` (`tint`, `contrast` and `saturation` 0..2, 1 = unchanged) grades the frame. With either on, the frame (lighting and Emissive drawables included) renders into an 8-bit target at the light-map's size, drawn exactly as onto the canvas (sRGB-encoded, blending on sRGB values, so no sprite edge changes), and one full-screen pass grades it and writes it to the canvas. `game.post.vignette` and `game.post.colorGrade` read and set them field by field over the current values, like the ambient (null turns one off); they die with their scene. Camera Effects stay above and are never altered.
+- **Validation and snapshots.** `validate_project` reports an out-of-range render field as `invalid-scene-render` and a Light param outside its range as `invalid-light-param`, naming it; at runtime out-of-range values are clamped. Every Runtime Snapshot carries `lighting: { ambient, lights: [{ entity, id, x, y, radius, color, intensity, bands, softness, castShadows }] }` in logical coordinates and `post: { vignette, colorGrade }` (null when off).
+
+The CPU reference of a light-map texel — `lightFalloff`, `lightVisibility`, `lightMapValue` — is exported for tools and tests; the shader follows it.
+
 ## 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/components/animated-sprite.d.ts

@@ -40,6 +40,9 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
             max: number;
             step: number;
         };
+        emissive: {
+            label: string;
+        };
     };
     static transient: string[];
     /** Spritesheet URL. */
@@ -85,6 +88,9 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     flipX: boolean;
     /** Mirrors the quad horizontally — directional clips reuse east art for west. */
     setFlipX(value: boolean): void;
+    private _emissive;
+    get emissive(): boolean;
+    set emissive(value: boolean);
     clips: Record<string, ClipDef>;
     initialClip?: string;
     /** Clip currently playing. */

package/dist/components/animated-sprite.js

@@ -1,10 +1,11 @@
-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';
+import { setEmissive, TRANSPARENT_TEXEL_ALPHA } from '../render-layers.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));
@@ -27,6 +28,7 @@ export class AnimatedSprite extends Component {
         anchorX: { label: 'x anchor', min: 0, max: 1, step: 0.25 },
         anchorY: { label: 'y anchor', min: 0, max: 1, step: 0.25 },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
+        emissive: { label: 'emissive' },
     };
     static transient = [
         'current',
@@ -133,6 +135,17 @@ export class AnimatedSprite extends Component {
         this.flipX = value;
         this.syncQuad();
     }
+    // Emissive (issue #78 CA-10): never darkened by the light-map, drawn after
+    // it at full brightness. On its own render layer.
+    _emissive = false;
+    get emissive() {
+        return this._emissive;
+    }
+    set emissive(value) {
+        this._emissive = value === true;
+        if (this.mesh)
+            setEmissive(this.mesh, this._emissive);
+    }
     clips = {};
     initialClip;
     /** Clip currently playing. */
@@ -182,10 +195,11 @@ export class AnimatedSprite extends Component {
             this.mesh = instance.anchor;
         }
         else {
-            const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
+            const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true, alphaTest: TRANSPARENT_TEXEL_ALPHA });
             this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
         }
         this.mesh.position.z = this.layer * 0.01;
+        setEmissive(this.mesh, this._emissive);
         this.syncQuad();
         this.entity.node.add(this.mesh);
         if (this.initialClip)

package/dist/components/light.d.ts

@@ -0,0 +1,68 @@
+import { Component } from '../component.js';
+import type { LightField } from '../light-field.js';
+/**
+ * A source of 2D light owned by its entity (issue #78, `CONTEXT.md` Light):
+ * a radius in logical world units — an ellipse on an isometric screen — a
+ * color, an intensity, a falloff that is smooth or split into `bands`, and a
+ * shadow edge that is hard or `soft`. Solid tiles stop it unless
+ * `castShadows` is off. Lights brighten what the Ambient Light leaves dark;
+ * they never darken. A live Light makes its scene draw lit.
+ */
+export declare class Light extends Component {
+    static componentName: string;
+    static params: {
+        radius: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        bands: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        softness: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        castShadows: {
+            label: string;
+        };
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+    };
+    /** Logical world units from its centre to where it fades out. */
+    radius: number;
+    /** `0xrrggbb`, multiplied over the art it reaches. */
+    color: number;
+    intensity: number;
+    /** 0 = smooth falloff; N = N equal steps (at most 16). */
+    bands: number;
+    /** 0 = hard shadow edge; up to 1 = the widest penumbra. */
+    softness: number;
+    /** Off: solid tiles do not stop this light. */
+    castShadows: boolean;
+    /** Logical offset from the entity's position, like a Solid's. */
+    offsetX: number;
+    offsetY: number;
+    onReady(): void;
+    onDestroy(): void;
+    /** This light as the light-map reads it: logical position, clamped params, color channels in 0..1. */
+    field(): LightField;
+}

package/dist/components/light.js

@@ -0,0 +1,59 @@
+import { Component } from '../component.js';
+import { addLight, removeLight } from '../scene-lighting.js';
+const MAX_BANDS = 16;
+const finiteOr = (value, fallback) => (Number.isFinite(value) ? value : fallback);
+/**
+ * A source of 2D light owned by its entity (issue #78, `CONTEXT.md` Light):
+ * a radius in logical world units — an ellipse on an isometric screen — a
+ * color, an intensity, a falloff that is smooth or split into `bands`, and a
+ * shadow edge that is hard or `soft`. Solid tiles stop it unless
+ * `castShadows` is off. Lights brighten what the Ambient Light leaves dark;
+ * they never darken. A live Light makes its scene draw lit.
+ */
+export class Light extends Component {
+    static componentName = 'Light';
+    static params = {
+        radius: { label: 'Radius', min: 0, step: 0.25 },
+        color: { label: 'Color', kind: 'color' },
+        intensity: { label: 'Intensity', min: 0, step: 0.1 },
+        bands: { label: 'Bands (0 = smooth)', min: 0, max: MAX_BANDS, step: 1 },
+        softness: { label: 'Shadow softness', min: 0, max: 1, step: 0.05 },
+        castShadows: { label: 'Cast shadows' },
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+    };
+    /** Logical world units from its centre to where it fades out. */
+    radius = 4;
+    /** `0xrrggbb`, multiplied over the art it reaches. */
+    color = 0xffffff;
+    intensity = 1;
+    /** 0 = smooth falloff; N = N equal steps (at most 16). */
+    bands = 0;
+    /** 0 = hard shadow edge; up to 1 = the widest penumbra. */
+    softness = 0;
+    /** Off: solid tiles do not stop this light. */
+    castShadows = true;
+    /** Logical offset from the entity's position, like a Solid's. */
+    offsetX = 0;
+    offsetY = 0;
+    onReady() {
+        addLight(this.game.lighting, this);
+    }
+    onDestroy() {
+        removeLight(this.game.lighting, this);
+    }
+    /** This light as the light-map reads it: logical position, clamped params, color channels in 0..1. */
+    field() {
+        const color = Number.isFinite(this.color) ? Math.trunc(this.color) & 0xffffff : 0xffffff;
+        return {
+            x: this.entity.position.x + finiteOr(this.offsetX, 0),
+            y: this.entity.position.y + finiteOr(this.offsetY, 0),
+            radius: Math.max(0, finiteOr(this.radius, 0)),
+            color: [((color >> 16) & 0xff) / 255, ((color >> 8) & 0xff) / 255, (color & 0xff) / 255],
+            intensity: Math.max(0, finiteOr(this.intensity, 0)),
+            bands: Math.min(MAX_BANDS, Math.max(0, Math.round(finiteOr(this.bands, 0)))),
+            softness: Math.min(1, Math.max(0, finiteOr(this.softness, 0))),
+            castShadows: this.castShadows !== false,
+        };
+    }
+}

package/dist/components/particle-emitter.d.ts

@@ -107,6 +107,9 @@ export declare class ParticleEmitter extends Component implements YSortBatchPart
             label: string;
             step: number;
         };
+        emissive: {
+            label: string;
+        };
     };
     rate: number;
     emitting: boolean;
@@ -144,6 +147,9 @@ export declare class ParticleEmitter extends Component implements YSortBatchPart
     private _layer;
     get layer(): number;
     set layer(value: number);
+    private _emissive;
+    get emissive(): boolean;
+    set emissive(value: boolean);
     private _batch?;
     private _unsubscribeRenderSync?;
     private _emissionRemainder;

package/dist/components/particle-emitter.js

@@ -1,6 +1,7 @@
 import { Component } from '../component.js';
 import { ParticleBatch, } from '../particle-batch.js';
 import { sceneDrainsOf } from '../scene-drains.js';
+import { setEmissive } from '../render-layers.js';
 /** A fixed-capacity source of short-lived, batched 2D particles. */
 export class ParticleEmitter extends Component {
     static componentName = 'ParticleEmitter';
@@ -30,6 +31,7 @@ export class ParticleEmitter extends Component {
         pixelArt: { label: 'Pixel art' },
         blend: { label: 'Blend', options: ['normal', 'additive'] },
         layer: { label: 'Layer', step: 1 },
+        emissive: { label: 'Emissive' },
     };
     rate = 0;
     emitting = true;
@@ -116,6 +118,16 @@ export class ParticleEmitter extends Component {
         this._batch?.setLayer(next);
         this._batch?.sync(this.renderContext());
     }
+    // Emissive (issue #78 CA-10): never darkened by the light-map.
+    _emissive = false;
+    get emissive() {
+        return this._emissive;
+    }
+    set emissive(value) {
+        this._emissive = value === true;
+        if (this._batch)
+            setEmissive(this._batch.mesh, this._emissive);
+    }
     _batch;
     _unsubscribeRenderSync;
     _emissionRemainder = 0;
@@ -133,6 +145,7 @@ export class ParticleEmitter extends Component {
             assets: this.game.assets,
         });
         this._batch.setTexture(this.texture, this.pixelArt);
+        setEmissive(this._batch.mesh, this._emissive);
         this.game.scene.add(this._batch.mesh);
         this._batch.sync(this.renderContext());
         this._unsubscribeRenderSync = this.game.onUpdate(() => this._batch?.sync(this.renderContext()));

package/dist/components/sprite.d.ts

@@ -32,6 +32,9 @@ export declare class Sprite extends Component implements YSortParticipant {
             max: number;
             step: number;
         };
+        emissive: {
+            label: string;
+        };
     };
     static transient: string[];
     private _width;
@@ -55,6 +58,9 @@ export declare class Sprite extends Component implements YSortParticipant {
     set anchorX(value: number);
     get anchorY(): number;
     set anchorY(value: number);
+    private _emissive;
+    get emissive(): boolean;
+    set emissive(value: boolean);
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture?: string;
     pixelArt: boolean;

package/dist/components/sprite.js

@@ -1,8 +1,9 @@
-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';
+import { setEmissive, TRANSPARENT_TEXEL_ALPHA } from '../render-layers.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
@@ -16,6 +17,7 @@ export class Sprite extends Component {
         anchorX: { label: 'x anchor', min: 0, max: 1, step: 0.25 },
         anchorY: { label: 'y anchor', min: 0, max: 1, step: 0.25 },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
+        emissive: { label: 'emissive' },
     };
     static transient = ['mesh'];
     // Size, color and offset are reactive so inspector edits update the live quad.
@@ -80,6 +82,17 @@ export class Sprite extends Component {
         this._anchorY = clampAnchor(value);
         this.syncQuad();
     }
+    // Emissive (issue #78 CA-10): never darkened by the light-map, drawn after
+    // it at full brightness. On its own render layer.
+    _emissive = false;
+    get emissive() {
+        return this._emissive;
+    }
+    set emissive(value) {
+        this._emissive = value === true;
+        if (this.mesh)
+            setEmissive(this.mesh, this._emissive);
+    }
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture;
     pixelArt = false;
@@ -127,11 +140,12 @@ export class Sprite extends Component {
         if (!this.mesh)
             return;
         this.mesh.position.z = this.layer * 0.01;
+        setEmissive(this.mesh, this._emissive);
         this.syncQuad();
         this.entity.node.add(this.mesh);
     }
     buildMesh() {
-        const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
+        const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true, alphaTest: TRANSPARENT_TEXEL_ALPHA });
         if (this.texture) {
             // Its own clone of the cached base (game.assets, ADR 0019): filters
             // are per clone, colour space comes with the base, and the image lands

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';
@@ -6,6 +6,8 @@ import { SOLID_SOURCE_SYMBOL } from '../scene-solids.js';
 import { cellAt as gridCellAt, cellBounds as gridCellBounds, cellIndex as gridCellIndex, } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
 import { reportRejection } from '../report-rejection.js';
+import { markOccludersChanged } from '../scene-lighting.js';
+import { TRANSPARENT_TEXEL_ALPHA } from '../render-layers.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
@@ -175,6 +177,7 @@ export class Tilemap extends Component {
         this.loadedTexture?.dispose();
         this.loadedTexture = undefined;
         this.derivedSolids = [];
+        markOccludersChanged(this.game.lighting);
     }
     solids() {
         return this.derivedSolids;
@@ -255,6 +258,7 @@ export class Tilemap extends Component {
         return new THREE.MeshBasicMaterial({
             color: this.color,
             transparent: true,
+            alphaTest: TRANSPARENT_TEXEL_ALPHA,
         });
     }
     rebuildGeometry() {
@@ -283,6 +287,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() {
@@ -347,5 +353,7 @@ export class Tilemap extends Component {
             next.push(solid);
         }
         this.derivedSolids = next;
+        // Occlusion is rebuilt from the solid tiles only when they change (inference 9).
+        markOccludersChanged(this.game.lighting);
     }
 }

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/frame-quad.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from 'three/webgpu';
+/** Whether `value` is the scene of a FrameQuad. */
+export declare function isFrameQuad(value: unknown): boolean;
+/**
+ * A full-viewport pass drawn as an ordinary scene with its own camera — not
+ * a THREE.QuadMesh: on the WebGPU backend a QuadMesh drawn to the canvas
+ * marks that render a full-screen pass, and the next render to the canvas in
+ * the same frame then loses everything drawn before it (seen in the issue
+ * #78 e2e). The lit frame draws its Emissive drawables after its multiply
+ * quad, so its quad must be ordinary.
+ */
+export declare class FrameQuad {
+    readonly material: THREE.Material;
+    private readonly scene;
+    private readonly camera;
+    private readonly mesh;
+    constructor(material: THREE.Material);
+    /** Draws the quad into whatever is bound now, inside the current viewport. */
+    render(renderer: THREE.WebGPURenderer): void;
+    dispose(): void;
+}

package/dist/frame-quad.js

@@ -0,0 +1,50 @@
+import * as THREE from 'three/webgpu';
+/** The scenes FrameQuad draws, so a test can tell them from any other render. */
+const quadScenes = new WeakSet();
+/** Whether `value` is the scene of a FrameQuad. */
+export function isFrameQuad(value) {
+    return typeof value === 'object' && value !== null && quadScenes.has(value);
+}
+/**
+ * Two triangles covering the viewport, with three's QuadMesh UV convention
+ * (v = 1 at the bottom), so a render target samples upright on both Render
+ * Backends — three flips a render target's v itself on WebGL2.
+ */
+function quadGeometry() {
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', new THREE.Float32BufferAttribute([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0], 3));
+    geometry.setAttribute('uv', new THREE.Float32BufferAttribute([0, 1, 1, 1, 1, 0, 0, 0], 2));
+    geometry.setIndex([0, 1, 2, 0, 2, 3]);
+    return geometry;
+}
+/**
+ * A full-viewport pass drawn as an ordinary scene with its own camera — not
+ * a THREE.QuadMesh: on the WebGPU backend a QuadMesh drawn to the canvas
+ * marks that render a full-screen pass, and the next render to the canvas in
+ * the same frame then loses everything drawn before it (seen in the issue
+ * #78 e2e). The lit frame draws its Emissive drawables after its multiply
+ * quad, so its quad must be ordinary.
+ */
+export class FrameQuad {
+    material;
+    scene = new THREE.Scene();
+    camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    mesh;
+    constructor(material) {
+        this.material = material;
+        this.mesh = new THREE.Mesh(quadGeometry(), material);
+        this.mesh.position.z = -0.5;
+        this.mesh.frustumCulled = false;
+        this.scene.add(this.mesh);
+        this.scene.matrixWorldAutoUpdate = true;
+        quadScenes.add(this.scene);
+    }
+    /** Draws the quad into whatever is bound now, inside the current viewport. */
+    render(renderer) {
+        renderer.render(this.scene, this.camera);
+    }
+    dispose() {
+        this.mesh.geometry.dispose();
+        this.material.dispose();
+    }
+}

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,7 +11,10 @@ import { Emitter } from './events.js';
 import { GameTime } from './game-time.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
+import { GamePost } from './post-effects.js';
+import { type RenderBackend } from './render-readiness.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { GameLighting } from './scene-lighting.js';
 import { type SpatialQuery } from './spatial-query.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
@@ -93,6 +96,10 @@ export declare class Game {
     readonly cameraEffects: CameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
+    /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
+    readonly lighting: GameLighting;
+    /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
+    readonly post: GamePost;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -101,10 +108,14 @@ 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;
+    /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
+    private readonly frame;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     /**
@@ -135,9 +146,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 +227,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 +275,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;