@waica/engine 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -3,6 +3,9 @@ export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, Upd
 export { AssetLoader } from './assets/asset-loader.js';
 export type { AssetStatus } from './assets/asset-loader.js';
 export type { TextureBackend } from './assets/texture-backend.js';
+export { GltfModelBackend } from './assets/model-backend.js';
+export type { LoadedModel, ModelBackend } from './assets/model-backend.js';
+export type { ModelHandle, ModelOutcome } from './assets/model-cache.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
 export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
@@ -21,11 +24,20 @@ export { CameraEffects } from './camera-effects.js';
 export type { CameraEffectColor, CameraEffectHandle, CameraEffectsOptions, CameraEffectsState, FadeOptions, FlashOptions, ShakeOptions, } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game-time.js';
-export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
+export type { SceneCameraJson, OrthographicSceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
+export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
+export type { PerspectiveSceneCameraJson, ResolvedPerspectiveCamera, SceneFieldIssue, Vec3Json, } from './scene-camera-3d.js';
+export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
+export type { GameCamera, NormalizedPoint, ViewCamera, WorldPoint } from './camera-projection.js';
+export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
+export type { SceneSpace, SpaceMarked } from './scene-space.js';
+export type { RuntimeSnapshotView } from './runtime-view-snapshot.js';
+export { applyTransformJson } from './entity-transform.js';
+export type { PositionJson, TransformJson } from './entity-transform.js';
 export { Entity } from './entity.js';
-export { Component } from './component.js';
+export { COMPONENT_SPACES, Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';
-export type { ComponentClass, ContactNormal, ParamSpec, SolidContact, } from './component.js';
+export type { BodyContact, ComponentClass, ComponentSpace, ContactNormal, ParamSpec, SolidContact, } from './component.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export type { ComponentModule } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
@@ -40,6 +52,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, RuntimeSnapshotPointLight, RuntimeSnapshotSun, 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 +60,27 @@ 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 { Model } from './components/model.js';
+export type { ModelShape } from './components/model.js';
+export { Sun } from './components/sun.js';
+export { Collider, COLLIDER_SHAPES } from './components/collider.js';
+export type { ColliderShape } from './components/collider.js';
+export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';
+export type { BodyVector, RigidBodyType } from './components/rigid-body.js';
+export { DEFAULT_GRAVITY, resolveSceneSimulation, sceneSimulationIssues } from './scene-simulation.js';
+export type { ResolvedSceneSimulation, SceneSimulationJson } from './scene-simulation.js';
+export type { PhysicsBackend, RapierModule } from './physics-3d/rapier-module.js';
+export type { RuntimeSnapshotBody, RuntimeSnapshotPhysics } from './runtime-physics-snapshot.js';
+export { PointLight } from './components/point-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';
@@ -64,9 +98,10 @@ export type { TilemapCell, TilemapCellBounds, TilemapGridSpec, } from './tilemap
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
 export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit, SpatialQuery, SpatialQueryFilter, } from './spatial-query.js';
+export type { Point3d, QueryVolume3d, RayHit3d } from './spatial-query-3d.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

@@ -1,5 +1,6 @@
 export { Game } from './game.js';
 export { AssetLoader } from './assets/asset-loader.js';
+export { GltfModelBackend } from './assets/model-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
@@ -9,8 +10,12 @@ export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepScen
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
 export { CameraEffects } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
+export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
+export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
+export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
+export { applyTransformJson } from './entity-transform.js';
 export { Entity } from './entity.js';
-export { Component } from './component.js';
+export { COMPONENT_SPACES, Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
@@ -22,6 +27,18 @@ 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 { Model } from './components/model.js';
+export { Sun } from './components/sun.js';
+export { Collider, COLLIDER_SHAPES } from './components/collider.js';
+export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';
+export { DEFAULT_GRAVITY, resolveSceneSimulation, sceneSimulationIssues } from './scene-simulation.js';
+export { PointLight } from './components/point-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';

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;

package/dist/light-map-material.js

@@ -0,0 +1,203 @@
+import { abs, Break, ceil, clamp, float, floor, Fn, If, int, ivec2, length, Loop, max, min, mix, positionWorld, select, sign, texture, uniform, uv, vec2, vec4, } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+const draws = new WeakMap();
+/** Registers what a light-map mesh draws; the shared material reads it per object. */
+export function setLightDraw(mesh, draw) {
+    draws.set(mesh, draw);
+}
+function drawOf(object) {
+    return object ? draws.get(object) : undefined;
+}
+/** The light-map's shared uniforms, with an empty occluder grid. */
+export function createLightMapUniforms(empty) {
+    return {
+        isometric: uniform(0),
+        grid: uniform(new THREE.Vector4(0, 0, 1, 0)),
+        gridSize: uniform(new THREE.Vector2(1, 1)),
+        // An explicit UV: mapUvPerVertex (render-output.ts) leaves every other
+        // texture a per-vertex UV varying, one per load() here, past WebGPU's
+        // limit of 16 inter-stage variables. The grid is only ever load()ed.
+        occluders: texture(empty, vec2(0, 0)),
+    };
+}
+/** 1 when the grid cell holds a solid tile, 0 when it is open or outside the grid. */
+function solidAtNode(uniforms, cell) {
+    const size = uniforms.gridSize;
+    const inside = cell.x.greaterThanEqual(0).and(cell.y.greaterThanEqual(0))
+        .and(cell.x.lessThan(size.x)).and(cell.y.lessThan(size.y));
+    const clamped = clamp(cell, vec2(0, 0), size.sub(1));
+    // load() follows the uniform's texture, so a rebuilt grid reaches the shader.
+    const value = uniforms.occluders.load(ivec2(int(clamped.x), int(clamped.y))).r;
+    return select(inside, value, float(0));
+}
+/** light-field.ts `axisCrossing`: the first boundary's ray parameter and its growth per cell. */
+function axisCrossingNode(start, delta, cell) {
+    const flat = abs(delta).lessThan(1e-9);
+    const step = select(flat, float(1e30), float(1).div(max(abs(delta), 1e-9)));
+    const toBoundary = select(delta.greaterThan(0), cell.add(1).sub(start), start.sub(cell));
+    return { next: select(flat, float(1e30), toBoundary.mul(step)), step };
+}
+/**
+ * `segmentClear` of light-field.ts in TSL: walks the grid cells from the
+ * texel's to the light's (Amanatides–Woo) and returns 0 at the first solid
+ * one, never testing the texel's own cell — the lit face of a wall.
+ */
+function segmentClearNode(uniforms) {
+    const walk = Fn(([from, to]) => {
+        const grid = uniforms.grid;
+        const a = from.sub(grid.xy).div(grid.z).toVar();
+        const b = to.sub(grid.xy).div(grid.z).toVar();
+        const cell = floor(a).toVar();
+        const end = floor(b);
+        const delta = b.sub(a).toVar();
+        const x = axisCrossingNode(a.x, delta.x, cell.x);
+        const y = axisCrossingNode(a.y, delta.y, cell.y);
+        const nextX = x.next.toVar();
+        const nextY = y.next.toVar();
+        const cells = min(abs(end.x.sub(cell.x)).add(abs(end.y.sub(cell.y))), 4096);
+        const clear = float(1).toVar();
+        Loop({ start: int(0), end: int(cells), type: 'int', condition: '<' }, () => {
+            If(nextX.lessThan(nextY), () => {
+                cell.x.addAssign(sign(delta.x));
+                nextX.addAssign(x.step);
+            }).Else(() => {
+                cell.y.addAssign(sign(delta.y));
+                nextY.addAssign(y.step);
+            });
+            If(solidAtNode(uniforms, cell).greaterThan(0.5), () => {
+                clear.assign(0);
+                Break();
+            });
+        });
+        return clear;
+    });
+    return (from, to) => walk(from, to);
+}
+/**
+ * `segmentPenetration` of light-field.ts in TSL: the same walk, summing in
+ * logical units how far the ray runs through solid cells, the texel's own
+ * cell never counted.
+ */
+function segmentPenetrationNode(uniforms) {
+    const walk = Fn(([from, to]) => {
+        const grid = uniforms.grid;
+        const a = from.sub(grid.xy).div(grid.z).toVar();
+        const b = to.sub(grid.xy).div(grid.z).toVar();
+        const cell = floor(a).toVar();
+        const end = floor(b);
+        const delta = b.sub(a).toVar();
+        const x = axisCrossingNode(a.x, delta.x, cell.x);
+        const y = axisCrossingNode(a.y, delta.y, cell.y);
+        const nextX = x.next.toVar();
+        const nextY = y.next.toVar();
+        const entry = float(0).toVar();
+        const cells = min(abs(end.x.sub(cell.x)).add(abs(end.y.sub(cell.y))), 4096);
+        const length = to.sub(from).length();
+        const inside = float(0).toVar();
+        Loop({ start: int(0), end: int(cells), type: 'int', condition: '<' }, () => {
+            If(nextX.lessThan(nextY), () => {
+                entry.assign(nextX);
+                cell.x.addAssign(sign(delta.x));
+                nextX.addAssign(x.step);
+            }).Else(() => {
+                entry.assign(nextY);
+                cell.y.addAssign(sign(delta.y));
+                nextY.addAssign(y.step);
+            });
+            const exit = min(min(nextX, nextY), 1);
+            inside.addAssign(solidAtNode(uniforms, cell).mul(exit.sub(entry)).mul(length));
+        });
+        return inside;
+    });
+    return (from, to) => walk(from, to);
+}
+/** One light's per-object uniforms, read from the mesh being drawn. */
+function lightUniforms() {
+    return {
+        position: uniform(new THREE.Vector2()).onObjectUpdate(({ object }) => drawOf(object)?.position),
+        color: uniform(new THREE.Vector3()).onObjectUpdate(({ object }) => drawOf(object)?.color),
+        radius: uniform(1).onObjectUpdate(({ object }) => drawOf(object)?.radius),
+        bands: uniform(0).onObjectUpdate(({ object }) => drawOf(object)?.bands),
+        softness: uniform(0).onObjectUpdate(({ object }) => drawOf(object)?.softness),
+        castShadows: uniform(1).onObjectUpdate(({ object }) => drawOf(object)?.castShadows),
+    };
+}
+/** The texel's logical position: render space as is, or unprojected from the 2:1 lattice (ADR 0009). */
+function logicalPositionNode(isometric) {
+    const world = positionWorld.xy;
+    const unprojected = vec2(world.x.div(2).sub(world.y), world.x.div(2).negate().sub(world.y));
+    return mix(world, unprojected, isometric);
+}
+/** light-field.ts `lightFalloff` at `t` = d / radius: smooth, or the top of its band. */
+function falloffNode(t, bands) {
+    const c = clamp(t, 0, 1);
+    const smooth = float(1).sub(c.mul(c).mul(float(3).sub(c.mul(2))));
+    const banded = ceil(smooth.mul(bands)).div(max(bands, 1));
+    return select(t.lessThan(1), select(bands.greaterThan(0.5), banded, smooth), float(0));
+}
+/** light-field.ts `lightVisibility`: hard, the clear walk; soft, a smoothstep over how deep the ray runs through walls. */
+function visibilityNode(uniforms, light, logical) {
+    const visibility = float(1).toVar();
+    If(light.castShadows.greaterThan(0.5).and(uniforms.grid.w.greaterThan(0.5)), () => {
+        If(light.softness.greaterThan(0), () => {
+            const penetration = segmentPenetrationNode(uniforms)(logical, light.position);
+            const depth = clamp(penetration.div(light.softness.mul(uniforms.grid.z)), 0, 1);
+            visibility.assign(float(1).sub(depth.mul(depth).mul(float(3).sub(depth.mul(2)))));
+        }).Else(() => {
+            visibility.assign(segmentClearNode(uniforms)(logical, light.position));
+        });
+    });
+    return visibility;
+}
+/** Adds the light onto the cleared target: ONE + ONE, which the 8-bit target clamps at 1. */
+function addOnto(material) {
+    material.transparent = true;
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.blending = THREE.CustomBlending;
+    material.blendEquation = THREE.AddEquation;
+    material.blendSrc = THREE.OneFactor;
+    material.blendDst = THREE.OneFactor;
+    material.blendSrcAlpha = THREE.OneFactor;
+    material.blendDstAlpha = THREE.OneFactor;
+}
+/**
+ * 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 function createLightMaterial(uniforms) {
+    const light = lightUniforms();
+    const material = new THREE.MeshBasicNodeMaterial();
+    material.fragmentNode = Fn(() => {
+        const logical = logicalPositionNode(uniforms.isometric).toVar();
+        const reach = falloffNode(length(logical.sub(light.position)).div(max(light.radius, 1e-6)), light.bands).toVar();
+        const visibility = float(0).toVar();
+        If(reach.greaterThan(0), () => {
+            visibility.assign(visibilityNode(uniforms, light, logical));
+        });
+        return vec4(light.color.mul(reach).mul(visibility), 1);
+    })();
+    addOnto(material);
+    return material;
+}
+/**
+ * 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 function createMultiplyMaterial(light) {
+    const material = new THREE.MeshBasicNodeMaterial();
+    material.fragmentNode = vec4(texture(light, uv()).rgb, 1);
+    material.transparent = true;
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.blending = THREE.CustomBlending;
+    material.blendEquation = THREE.AddEquation;
+    material.blendSrc = THREE.ZeroFactor;
+    material.blendDst = THREE.SrcColorFactor;
+    material.blendSrcAlpha = THREE.ZeroFactor;
+    material.blendDstAlpha = THREE.OneFactor;
+    return material;
+}

package/dist/light-map.d.ts

@@ -0,0 +1,46 @@
+import * as THREE from 'three/webgpu';
+import type { Light } from './components/light.js';
+import { type OccluderGrid, type Rgb } from './light-field.js';
+/** What one frame's light-map is drawn from. */
+export interface LightMapFrame {
+    width: number;
+    height: number;
+    /** The Ambient Light the target is cleared to, as multipliers. */
+    ambient: Rgb;
+    lights: readonly Light[];
+    projection: 'isometric' | null;
+    /** Changes whenever the solid tiles or a Tilemap's origin change; the grid is rebuilt only then. */
+    occluderRevision: string;
+    occluders: () => OccluderGrid | null;
+}
+/**
+ * The scene's light-map (issue #78, ADR 0026): an 8-bit target (inference
+ * 16) the size of the internal resolution — or of the drawing buffer — with
+ * nearest upscale, cleared to the Ambient Light, onto which each live Light
+ * adds its term through one mesh over its footprint. Then multiplied over
+ * the frame by one quad.
+ */
+export declare class LightMap {
+    readonly target: THREE.RenderTarget<THREE.Texture<unknown, THREE.TextureEventMap>, THREE.RenderTargetEventMap>;
+    private readonly scene;
+    private readonly geometry;
+    private readonly empty;
+    private readonly uniforms;
+    private readonly material;
+    private readonly meshes;
+    private readonly multiply;
+    private occluderTexture;
+    private builtRevision;
+    private readonly clear;
+    private readonly savedClear;
+    /** Draws this frame's light-map into its target and leaves the renderer bound to `previous`. */
+    render(renderer: THREE.WebGPURenderer, camera: THREE.Camera, frame: LightMapFrame): void;
+    /** Multiplies the light-map over what is bound now: the canvas, or a Post Effect's canvas-like target. */
+    multiplyOver(renderer: THREE.WebGPURenderer): void;
+    dispose(): void;
+    private syncOccluders;
+    /** One mesh per live Light, placed over its footprint; a destroyed Light's mesh leaves now. */
+    private syncLights;
+    private place;
+    private createMesh;
+}