@waica/engine 0.24.0 → 0.25.0

package/README.md

@@ -183,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/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

@@ -5,6 +5,7 @@ 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

@@ -3,6 +3,7 @@ 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

@@ -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() {
@@ -349,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/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

@@ -11,8 +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';
@@ -94,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;
@@ -108,6 +114,8 @@ export declare class Game {
     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;
     /**

package/dist/game.js

@@ -12,14 +12,18 @@ import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedT
 import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
 import { Pointer } from './pointer.js';
+import { GamePost } from './post-effects.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
+import { FrameComposer } from './lit-frame.js';
+import { EMISSIVE_LAYER } from './render-layers.js';
 import { projectIsometric, unprojectIsometric } from './projection.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 { GameLighting } from './scene-lighting.js';
 import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
@@ -64,6 +68,10 @@ export class Game {
     cameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
+    /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
+    lighting = new GameLighting();
+    /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
+    post = new GamePost();
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -78,6 +86,8 @@ export class Game {
     resizeObserver;
     /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
     spriteBatches;
+    /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
+    frame;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -162,6 +172,10 @@ export class Game {
         this.scene.background = canvasBackground(background);
         this.camera = new THREE.OrthographicCamera();
         this.camera.position.z = 10;
+        // Emissive drawables sit on their own layer; an unlit frame draws it in place.
+        this.camera.layers.enable(EMISSIVE_LAYER);
+        const { renderer, spriteBatches, resolution } = this;
+        this.frame = new FrameComposer({ game: this, renderer, spriteBatches, resolution });
         this.pointer = new Pointer(canvas, {
             camera: this.camera,
             resolution: this.resolution,
@@ -228,6 +242,8 @@ export class Game {
         // destroyed below, so an owner's own destroy() cancellation is a no-op.
         this.time.cancelSceneScoped();
         this.cameraEffects.unloadScene();
+        this.lighting.unloadScene();
+        this.post.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -334,6 +350,8 @@ export class Game {
     setSceneRender(json) {
         this.renderSort = json?.sort === 'y' ? 'y' : null;
         this.spriteBatches.enabled = json?.batch !== false;
+        this.lighting.loadScene(json);
+        this.post.loadScene(json);
         const projection = json?.projection === 'isometric' ? 'isometric' : null;
         if (projection === this.sceneProjection)
             return;
@@ -449,6 +467,7 @@ 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.frame.dispose();
         this.readiness.disposeRenderer();
     }
     /**
@@ -618,14 +637,7 @@ export class Game {
             // 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);
-                this.renderer.setClearColor(0x000000, 1);
-                this.renderer.clear(true, false, false);
-                this.renderer.setScissorTest(true);
-            }
-            this.spriteBatches.drawFrame(this.scene, this.camera, () => this.renderer.render(this.scene, this.camera));
+            this.frame.draw();
         }
         finally {
             this.camera.position.x = x;

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_B
 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 { RuntimeSnapshotLight, RuntimeSnapshotLighting, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.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';
 export { Stats } from './stats.js';
@@ -47,6 +48,15 @@ export type { StatValue } from './stats.js';
 export { GameUi } from './ui.js';
 export type { AnchoredPieceHandle, AttachOptions } from './anchored-pieces.js';
 export { Sprite } from './components/sprite.js';
+export { Light } from './components/light.js';
+export { GameLighting } from './scene-lighting.js';
+export type { AmbientLightInput } from './scene-lighting.js';
+export { GamePost } from './post-effects.js';
+export { EMISSIVE_LAYER, setEmissive } from './render-layers.js';
+export { lightFalloff, lightMapValue, lightVisibility } from './light-field.js';
+export type { LightField, OccluderGrid, Rgb } from './light-field.js';
+export { sceneRenderIssues } from './scene-render-options.js';
+export type { AmbientLight, ColorGradeEffect, PostEffectsState, SceneRenderIssue, VignetteEffect, } from './scene-render-options.js';
 export { ParticleEmitter } from './components/particle-emitter.js';
 export type { ParticleBlend, ParticleDestroyMode, ParticleOverflow, ParticleSpace, ParticleVector, } from './components/particle-emitter.js';
 export { Solid } from './components/solid.js';
@@ -66,7 +76,7 @@ export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, }
 export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit, SpatialQuery, SpatialQueryFilter, } from './spatial-query.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
-export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, PrefabJson, } from './scene.js';
+export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, SceneLightingJson, ScenePostJson, PrefabJson, } from './scene.js';
 export { ClipPlayer } from './animation/clip-player.js';
 export type { ClipDef } from './animation/clip-player.js';
 export { sheetCell, sheetFrameCount, locateFrame } from './animation/sheet.js';

package/dist/index.js

@@ -22,6 +22,12 @@ export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';
+export { Light } from './components/light.js';
+export { GameLighting } from './scene-lighting.js';
+export { GamePost } from './post-effects.js';
+export { EMISSIVE_LAYER, setEmissive } from './render-layers.js';
+export { lightFalloff, lightMapValue, lightVisibility } from './light-field.js';
+export { sceneRenderIssues } from './scene-render-options.js';
 export { ParticleEmitter } from './components/particle-emitter.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';