@waica/engine 0.23.0 → 0.25.0

package/dist/game.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { gameViewport } from './anchored-pieces.js';
 import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
@@ -12,12 +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 { 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 { GameLighting } from './scene-lighting.js';
 import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
@@ -62,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 = {};
@@ -70,11 +80,14 @@ 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;
+    /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
+    frame;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -105,6 +118,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,11 +157,25 @@ 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;
+        // 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,
@@ -157,6 +186,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);
@@ -200,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;
@@ -306,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;
@@ -338,6 +384,8 @@ export class Game {
         this.setViewHeight(this.sceneCamera.zoom);
     }
     start() {
+        if (this.disposed)
+            return;
         const activation = activeRuntimeBridgeHook();
         if (activation) {
             if (!this.runtimeBridge) {
@@ -357,19 +405,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 +448,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 +467,15 @@ 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.frame.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 +486,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 +614,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 +623,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,14 +634,10 @@ export class Game {
         this.camera.position.y = y + shake.y;
         try {
             anchoredPiecesOf(this.ui).place();
-            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));
+            // Before ready() the frame simulated, but three cannot draw yet.
+            if (!this.readiness.isReady)
+                return;
+            this.frame.draw();
         }
         finally {
             this.camera.position.x = x;

package/dist/index.d.ts

@@ -37,8 +37,10 @@ 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 { 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';
@@ -46,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';
@@ -65,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';
@@ -76,4 +87,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

@@ -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';
@@ -42,4 +48,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/light-field.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The CPU reference of a light-map texel (issue #78 CA-5..CA-7): what the
+ * light shader computes per texel, written once in plain TypeScript so it
+ * can be tested. The shader in `light-map-material.ts` follows it step by
+ * step; this file is the specification both are read against.
+ */
+/** A light-map value or a light color: three multipliers in 0..1 over the sRGB frame. */
+export type Rgb = [number, number, number];
+/** One Light as the light-map sees it: logical position and radius, its look, its shadow. */
+export interface LightField {
+    x: number;
+    y: number;
+    /** Logical units: the same distance in every grid direction, also on an isometric screen. */
+    radius: number;
+    color: Rgb;
+    intensity: number;
+    /** 0 = smooth falloff; N > 0 = N equal steps. */
+    bands: number;
+    /** 0 = hard shadow edge; up to 1 = the widest penumbra. */
+    softness: number;
+    castShadows: boolean;
+}
+/**
+ * Every Tilemap's solid tiles rasterized onto one logical grid: `solid` holds
+ * one byte per cell, row-major, row 0 at `originY` (rows grow with y).
+ */
+export interface OccluderGrid {
+    originX: number;
+    originY: number;
+    cellSize: number;
+    columns: number;
+    rows: number;
+    solid: Uint8Array;
+}
+/** A logical point. */
+export interface LogicalPoint {
+    x: number;
+    y: number;
+}
+/** What every light-map texel of a frame is computed from. */
+export interface LightScene {
+    ambient: Rgb;
+    lights: readonly LightField[];
+    grid: OccluderGrid | null;
+}
+/**
+ * Brightness at `t` = distance / radius: 1 at the centre, a smooth ease to 0
+ * at the radius and nothing beyond. With `bands` > 0 every lit point takes
+ * the top of its step, so the outermost band still reaches the radius.
+ */
+export declare function lightFalloff(t: number, bands: number): number;
+/** The render-space box a light covers: a circle's square, or the 2:1 ellipse's box on an isometric screen. */
+export declare function lightFootprint(radius: number, projection: 'isometric' | null): {
+    width: number;
+    height: number;
+};
+/**
+ * Whether the segment from a texel to a light crosses no solid cell other
+ * than the texel's own (the lit face of a wall, CA-7). A grid walk
+ * (Amanatides–Woo) over every cell the segment enters, the light's included.
+ */
+export declare function segmentClear(grid: OccluderGrid, from: LogicalPoint, to: LogicalPoint): boolean;
+/**
+ * How far the segment from a texel to a light travels inside solid cells,
+ * in logical units, never counting the texel's own cell (its lit face): the
+ * same grid walk as `segmentClear`, measuring instead of stopping.
+ */
+export declare function segmentPenetration(grid: OccluderGrid, from: LogicalPoint, to: LogicalPoint): number;
+/**
+ * How much of a light reaches a texel. Hard (softness 0): 1 or 0. Soft: one
+ * walk measures how deep the ray runs through solid cells, and the light
+ * fades over the first `softness` cells of it — a ray grazing a wall's
+ * corner keeps most of its light, one through the wall none — so the edge
+ * is a single transition that widens away from the occluder (PR #150 review).
+ */
+export declare function lightVisibility(grid: OccluderGrid | null, light: LightField, point: LogicalPoint): number;
+/** A light-map texel at a logical point: the Ambient Light plus every light's term, clamped per channel. */
+export declare function lightMapValue({ ambient, lights, grid }: LightScene, point: LogicalPoint): Rgb;

package/dist/light-field.js

@@ -0,0 +1,145 @@
+/**
+ * The CPU reference of a light-map texel (issue #78 CA-5..CA-7): what the
+ * light shader computes per texel, written once in plain TypeScript so it
+ * can be tested. The shader in `light-map-material.ts` follows it step by
+ * step; this file is the specification both are read against.
+ */
+/**
+ * Brightness at `t` = distance / radius: 1 at the centre, a smooth ease to 0
+ * at the radius and nothing beyond. With `bands` > 0 every lit point takes
+ * the top of its step, so the outermost band still reaches the radius.
+ */
+export function lightFalloff(t, bands) {
+    if (!(t < 1))
+        return 0;
+    const clamped = Math.max(0, t);
+    const smooth = 1 - clamped * clamped * (3 - 2 * clamped);
+    if (bands <= 0)
+        return smooth;
+    return Math.ceil(smooth * bands) / bands;
+}
+/** The render-space box a light covers: a circle's square, or the 2:1 ellipse's box on an isometric screen. */
+export function lightFootprint(radius, projection) {
+    if (projection === 'isometric')
+        return { width: 2 * Math.SQRT2 * radius, height: Math.SQRT2 * radius };
+    return { width: 2 * radius, height: 2 * radius };
+}
+function solidAt(grid, column, row) {
+    if (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows)
+        return false;
+    return grid.solid[row * grid.columns + column] === 1;
+}
+/** The ray parameter of the first cell boundary on one axis, and how much it grows per cell. */
+function axisCrossing(start, delta, cell) {
+    if (delta === 0)
+        return { next: Number.POSITIVE_INFINITY, step: Number.POSITIVE_INFINITY };
+    const step = Math.abs(1 / delta);
+    const toBoundary = delta > 0 ? cell + 1 - start : start - cell;
+    return { next: toBoundary * step, step };
+}
+/**
+ * Whether the segment from a texel to a light crosses no solid cell other
+ * than the texel's own (the lit face of a wall, CA-7). A grid walk
+ * (Amanatides–Woo) over every cell the segment enters, the light's included.
+ */
+export function segmentClear(grid, from, to) {
+    const ax = (from.x - grid.originX) / grid.cellSize;
+    const ay = (from.y - grid.originY) / grid.cellSize;
+    const bx = (to.x - grid.originX) / grid.cellSize;
+    const by = (to.y - grid.originY) / grid.cellSize;
+    const endColumn = Math.floor(bx);
+    const endRow = Math.floor(by);
+    const walk = { column: Math.floor(ax), row: Math.floor(ay), nextX: 0, nextY: 0 };
+    const x = axisCrossing(ax, bx - ax, walk.column);
+    const y = axisCrossing(ay, by - ay, walk.row);
+    walk.nextX = x.next;
+    walk.nextY = y.next;
+    const stepColumn = Math.sign(bx - ax);
+    const stepRow = Math.sign(by - ay);
+    const cells = Math.abs(endColumn - walk.column) + Math.abs(endRow - walk.row);
+    for (let index = 0; index < cells; index += 1) {
+        if (walk.nextX < walk.nextY) {
+            walk.column += stepColumn;
+            walk.nextX += x.step;
+        }
+        else {
+            walk.row += stepRow;
+            walk.nextY += y.step;
+        }
+        if (solidAt(grid, walk.column, walk.row))
+            return false;
+    }
+    return true;
+}
+/**
+ * How far the segment from a texel to a light travels inside solid cells,
+ * in logical units, never counting the texel's own cell (its lit face): the
+ * same grid walk as `segmentClear`, measuring instead of stopping.
+ */
+export function segmentPenetration(grid, from, to) {
+    const ax = (from.x - grid.originX) / grid.cellSize;
+    const ay = (from.y - grid.originY) / grid.cellSize;
+    const bx = (to.x - grid.originX) / grid.cellSize;
+    const by = (to.y - grid.originY) / grid.cellSize;
+    const walk = { column: Math.floor(ax), row: Math.floor(ay), nextX: 0, nextY: 0 };
+    const x = axisCrossing(ax, bx - ax, walk.column);
+    const y = axisCrossing(ay, by - ay, walk.row);
+    walk.nextX = x.next;
+    walk.nextY = y.next;
+    const cells = Math.abs(Math.floor(bx) - walk.column) + Math.abs(Math.floor(by) - walk.row);
+    const length = Math.hypot(to.x - from.x, to.y - from.y);
+    let inside = 0;
+    for (let index = 0; index < cells; index += 1) {
+        let entry;
+        if (walk.nextX < walk.nextY) {
+            entry = walk.nextX;
+            walk.column += Math.sign(bx - ax);
+            walk.nextX += x.step;
+        }
+        else {
+            entry = walk.nextY;
+            walk.row += Math.sign(by - ay);
+            walk.nextY += y.step;
+        }
+        if (solidAt(grid, walk.column, walk.row))
+            inside += (Math.min(walk.nextX, walk.nextY, 1) - entry) * length;
+    }
+    return inside;
+}
+/**
+ * How much of a light reaches a texel. Hard (softness 0): 1 or 0. Soft: one
+ * walk measures how deep the ray runs through solid cells, and the light
+ * fades over the first `softness` cells of it — a ray grazing a wall's
+ * corner keeps most of its light, one through the wall none — so the edge
+ * is a single transition that widens away from the occluder (PR #150 review).
+ */
+export function lightVisibility(grid, light, point) {
+    if (!grid || !light.castShadows)
+        return 1;
+    if (light.softness <= 0)
+        return segmentClear(grid, point, light) ? 1 : 0;
+    const depth = Math.min(1, segmentPenetration(grid, point, light) / (light.softness * grid.cellSize));
+    return 1 - depth * depth * (3 - 2 * depth);
+}
+/** One light's own term at a logical point: color × intensity × falloff × visibility, never negative. */
+function lightTerm(light, grid, point) {
+    const strength = Math.max(0, light.intensity);
+    const distance = Math.hypot(point.x - light.x, point.y - light.y);
+    const reach = light.radius > 0 ? lightFalloff(distance / light.radius, light.bands) : 0;
+    if (strength === 0 || reach === 0)
+        return [0, 0, 0];
+    const amount = strength * reach * lightVisibility(grid, light, point);
+    return [Math.max(0, light.color[0]) * amount, Math.max(0, light.color[1]) * amount, Math.max(0, light.color[2]) * amount];
+}
+const clampUnit = (value) => Math.min(1, Math.max(0, value));
+/** A light-map texel at a logical point: the Ambient Light plus every light's term, clamped per channel. */
+export function lightMapValue({ ambient, lights, grid }, point) {
+    const total = [ambient[0], ambient[1], ambient[2]];
+    for (const light of lights) {
+        const [r, g, b] = lightTerm(light, grid, point);
+        total[0] += r;
+        total[1] += g;
+        total[2] += b;
+    }
+    return [clampUnit(total[0]), clampUnit(total[1]), clampUnit(total[2])];
+}

package/dist/light-map-material.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from 'three/webgpu';
+/** What one light-map mesh draws: its light, in logical units, with its look. */
+export interface LightDraw {
+    readonly position: THREE.Vector2;
+    /** color × intensity, the term the light adds at its centre. */
+    readonly color: THREE.Vector3;
+    radius: number;
+    bands: number;
+    softness: number;
+    /** 1 casts shadows, 0 does not. */
+    castShadows: number;
+}
+/** Registers what a light-map mesh draws; the shared material reads it per object. */
+export declare function setLightDraw(mesh: THREE.Object3D, draw: LightDraw): void;
+/** The light-map's per-frame inputs every light reads: the projection and the occluder grid. */
+export interface LightMapUniforms {
+    /** 1 for an isometric scene: render space is unprojected to logical space per texel. */
+    readonly isometric: THREE.UniformNode<'float', number>;
+    /** originX, originY, cellSize and 1 when a grid exists (0 casts no shadow at all). */
+    readonly grid: THREE.UniformNode<'vec4', THREE.Vector4>;
+    /** The grid's columns and rows. */
+    readonly gridSize: THREE.UniformNode<'vec2', THREE.Vector2>;
+    /** One byte per cell, row 0 first: 255 solid, 0 open. */
+    readonly occluders: THREE.TextureNode;
+}
+/** The light-map's shared uniforms, with an empty occluder grid. */
+export declare function createLightMapUniforms(empty: THREE.Texture): LightMapUniforms;
+/**
+ * The material every light-map mesh shares (issue #78 CA-5..CA-7): per texel,
+ * `color × intensity × falloff(d / radius) × visibility` with `d` measured in
+ * logical space (ADR 0009), added onto the Ambient Light the target was
+ * cleared to. light-field.ts is its specification.
+ */
+export declare function createLightMaterial(uniforms: LightMapUniforms): THREE.MeshBasicNodeMaterial;
+/**
+ * The quad that multiplies the light-map over the frame already drawn
+ * (ADR 0026): `frame × light`, alpha kept, on the sRGB values as stored —
+ * on the canvas, or in a Post Effect's target, which stores them alike.
+ */
+export declare function createMultiplyMaterial(light: THREE.Texture): THREE.MeshBasicNodeMaterial;