@waica/engine 0.23.0 → 0.25.0

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;
+}

package/dist/light-map.js

@@ -0,0 +1,132 @@
+import * as THREE from 'three/webgpu';
+import { FrameQuad } from './frame-quad.js';
+import { lightFootprint } from './light-field.js';
+import { createLightMapUniforms, createLightMaterial, createMultiplyMaterial, setLightDraw, } from './light-map-material.js';
+import { projectIsometric } from './projection.js';
+function emptyOccluders() {
+    const texture = new THREE.DataTexture(new Uint8Array([0]), 1, 1, THREE.RedFormat, THREE.UnsignedByteType);
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * 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 class LightMap {
+    target = new THREE.RenderTarget(1, 1, {
+        type: THREE.UnsignedByteType,
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+        depthBuffer: false,
+    });
+    scene = new THREE.Scene();
+    geometry = new THREE.PlaneGeometry(1, 1);
+    empty = emptyOccluders();
+    uniforms = createLightMapUniforms(this.empty);
+    material = createLightMaterial(this.uniforms);
+    meshes = new Map();
+    multiply = new FrameQuad(createMultiplyMaterial(this.target.texture));
+    occluderTexture = null;
+    builtRevision = '';
+    clear = new THREE.Color();
+    savedClear = new THREE.Color();
+    /** Draws this frame's light-map into its target and leaves the renderer bound to `previous`. */
+    render(renderer, camera, frame) {
+        if (this.target.width !== frame.width || this.target.height !== frame.height) {
+            this.target.setSize(frame.width, frame.height);
+        }
+        this.syncOccluders(frame);
+        this.syncLights(frame);
+        const previous = renderer.getRenderTarget();
+        const alpha = renderer.getClearAlpha();
+        renderer.getClearColor(this.savedClear);
+        this.clear.setRGB(frame.ambient[0], frame.ambient[1], frame.ambient[2], THREE.LinearSRGBColorSpace);
+        renderer.setClearColor(this.clear, 1);
+        renderer.setRenderTarget(this.target);
+        renderer.render(this.scene, camera);
+        renderer.setRenderTarget(previous);
+        renderer.setClearColor(this.savedClear, alpha);
+    }
+    /** Multiplies the light-map over what is bound now: the canvas, or a Post Effect's canvas-like target. */
+    multiplyOver(renderer) {
+        this.multiply.render(renderer);
+    }
+    dispose() {
+        this.target.dispose();
+        this.geometry.dispose();
+        this.material.dispose();
+        this.multiply.dispose();
+        this.empty.dispose();
+        this.occluderTexture?.dispose();
+        this.meshes.clear();
+    }
+    syncOccluders(frame) {
+        if (frame.occluderRevision === this.builtRevision)
+            return;
+        this.builtRevision = frame.occluderRevision;
+        this.occluderTexture?.dispose();
+        this.occluderTexture = null;
+        const grid = frame.occluders();
+        if (!grid) {
+            this.uniforms.occluders.value = this.empty;
+            this.uniforms.grid.value.set(0, 0, 1, 0);
+            this.uniforms.gridSize.value.set(1, 1);
+            return;
+        }
+        const bytes = grid.solid.map((value) => (value === 1 ? 255 : 0));
+        const texture = new THREE.DataTexture(bytes, grid.columns, grid.rows, THREE.RedFormat, THREE.UnsignedByteType);
+        texture.needsUpdate = true;
+        this.occluderTexture = texture;
+        this.uniforms.occluders.value = texture;
+        this.uniforms.grid.value.set(grid.originX, grid.originY, grid.cellSize, 1);
+        this.uniforms.gridSize.value.set(grid.columns, grid.rows);
+    }
+    /** One mesh per live Light, placed over its footprint; a destroyed Light's mesh leaves now. */
+    syncLights(frame) {
+        this.uniforms.isometric.value = frame.projection === 'isometric' ? 1 : 0;
+        const live = new Set(frame.lights);
+        for (const [light, entry] of this.meshes) {
+            if (live.has(light))
+                continue;
+            entry.mesh.removeFromParent();
+            this.meshes.delete(light);
+        }
+        for (const light of frame.lights)
+            this.place(light, frame.projection);
+    }
+    place(light, projection) {
+        const entry = this.meshes.get(light) ?? this.createMesh(light);
+        const field = light.field();
+        entry.draw.position.set(field.x, field.y);
+        entry.draw.color.set(field.color[0], field.color[1], field.color[2]).multiplyScalar(field.intensity);
+        entry.draw.radius = field.radius;
+        entry.draw.bands = field.bands;
+        entry.draw.softness = field.softness;
+        entry.draw.castShadows = field.castShadows ? 1 : 0;
+        const center = projection === 'isometric' ? projectIsometric(field.x, field.y) : { x: field.x, y: field.y };
+        const footprint = lightFootprint(field.radius, projection);
+        entry.mesh.position.set(center.x, center.y, 0);
+        entry.mesh.scale.set(Math.max(footprint.width, 1e-6), Math.max(footprint.height, 1e-6), 1);
+        entry.mesh.visible = field.radius > 0 && field.intensity > 0;
+    }
+    createMesh(light) {
+        const mesh = new THREE.Mesh(this.geometry, this.material);
+        mesh.frustumCulled = false;
+        const draw = {
+            position: new THREE.Vector2(),
+            color: new THREE.Vector3(),
+            radius: 0,
+            bands: 0,
+            softness: 0,
+            castShadows: 1,
+        };
+        setLightDraw(mesh, draw);
+        this.scene.add(mesh);
+        const entry = { mesh, draw };
+        this.meshes.set(light, entry);
+        return entry;
+    }
+}

package/dist/lit-frame.d.ts

@@ -0,0 +1,48 @@
+import * as THREE from 'three/webgpu';
+import type { Game, GameResolution } from './game.js';
+import type { SpriteBatches } from './sprite-batches.js';
+/** What a frame is drawn with besides the Game's public state: its renderer and Sprite Batches. */
+export interface FrameSurface {
+    readonly game: Game;
+    readonly renderer: THREE.WebGPURenderer;
+    readonly spriteBatches: SpriteBatches;
+    /** The fixed internal resolution, null to fill the canvas. */
+    readonly resolution: GameResolution | null;
+}
+/**
+ * What the occluder grid is built from: the solid tiles' revision and every
+ * Tilemap's origin, so moving a Tilemap rebuilds it too (review) — still
+ * never per frame while nothing changes.
+ */
+export declare function occluderSignature(game: Game): string;
+/**
+ * Draws one frame (issue #78, ADR 0026). Off path (B4): an unlit scene with
+ * no Post Effect is one render straight into the canvas, exactly as before,
+ * and nothing here is ever built. Lit: the scene without its Emissive
+ * drawables, then the light-map multiplied over it, then the Emissive
+ * drawables. With a Post Effect, all of that goes into a target drawn like the
+ * canvas and
+ * one pass writes it to the canvas.
+ */
+export declare class FrameComposer {
+    private readonly surface;
+    private lightMap;
+    private postPass;
+    private readonly size;
+    constructor(surface: FrameSurface);
+    draw(): void;
+    dispose(): void;
+    /** The light-map's (and the Post Effects') size: the internal resolution, else the drawing buffer (B2). */
+    private frameSize;
+    /** Letterbox bars: clear the whole canvas, then render inside the scissor. */
+    private clearLetterbox;
+    /** The scene through its Sprite Batches (ADR 0024), for the camera's current layers. */
+    private drawScene;
+    /** The scene for one layer mask, restoring the camera's own mask after. */
+    private drawLayers;
+    /** Scene, light-map, Emissive drawables, into whatever target is bound now. */
+    private drawLit;
+    private composeLight;
+    /** The frame into the Post Effects' canvas-like target, then one pass to the canvas (CA-11). */
+    private drawThroughPost;
+}

package/dist/lit-frame.js

@@ -0,0 +1,167 @@
+import * as THREE from 'three/webgpu';
+import { Tilemap } from './components/tilemap.js';
+import { LightMap } from './light-map.js';
+import { buildOccluderGrid } from './occluder-grid.js';
+import { PostPass } from './post-pass.js';
+import { EMISSIVE_LAYER } from './render-layers.js';
+import { ambientIsFull, ambientMultiplier, occluderRevision } from './scene-lighting.js';
+/** Layer 0 alone: every drawable that is not Emissive. */
+const LIT_MASK = 1;
+const EMISSIVE_MASK = 1 << EMISSIVE_LAYER;
+/**
+ * What the occluder grid is built from: the solid tiles' revision and every
+ * Tilemap's origin, so moving a Tilemap rebuilds it too (review) — still
+ * never per frame while nothing changes.
+ */
+export function occluderSignature(game) {
+    const origins = occluderSources(game.entities).map(({ originX, originY }) => `${originX},${originY}`);
+    return `${occluderRevision(game.lighting)}|${origins.join(';')}`;
+}
+/** Every Tilemap of the scene as an occluder source (inference 8). */
+function occluderSources(entities) {
+    const sources = [];
+    for (const entity of entities) {
+        for (const component of entity.components) {
+            if (!(component instanceof Tilemap))
+                continue;
+            sources.push({
+                originX: entity.position.x,
+                originY: entity.position.y,
+                cellSize: component.cellSize,
+                mapWidth: component.mapWidth,
+                mapHeight: component.mapHeight,
+                cells: component.cells,
+                solidTiles: component.solidTiles,
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Draws one frame (issue #78, ADR 0026). Off path (B4): an unlit scene with
+ * no Post Effect is one render straight into the canvas, exactly as before,
+ * and nothing here is ever built. Lit: the scene without its Emissive
+ * drawables, then the light-map multiplied over it, then the Emissive
+ * drawables. With a Post Effect, all of that goes into a target drawn like the
+ * canvas and
+ * one pass writes it to the canvas.
+ */
+export class FrameComposer {
+    surface;
+    lightMap = null;
+    postPass = null;
+    size = new THREE.Vector2();
+    constructor(surface) {
+        this.surface = surface;
+    }
+    draw() {
+        // Full Ambient Light: the light-map would be 1 everywhere, so nothing to multiply.
+        const lit = this.surface.game.lighting.active && !ambientIsFull(this.surface.game.lighting);
+        const post = this.surface.game.post.active;
+        if (!lit && !post) {
+            this.clearLetterbox();
+            this.drawScene();
+            return;
+        }
+        const { width, height } = this.frameSize();
+        if (!post) {
+            this.clearLetterbox();
+            this.drawLit(width, height);
+            return;
+        }
+        this.drawThroughPost(width, height, lit);
+    }
+    dispose() {
+        this.lightMap?.dispose();
+        this.lightMap = null;
+        this.postPass?.dispose();
+        this.postPass = null;
+    }
+    /** The light-map's (and the Post Effects') size: the internal resolution, else the drawing buffer (B2). */
+    frameSize() {
+        const { renderer, resolution } = this.surface;
+        if (resolution)
+            return { width: Math.max(1, Math.round(resolution.width)), height: Math.max(1, Math.round(resolution.height)) };
+        renderer.getDrawingBufferSize(this.size);
+        return { width: Math.max(1, this.size.x), height: Math.max(1, this.size.y) };
+    }
+    /** Letterbox bars: clear the whole canvas, then render inside the scissor. */
+    clearLetterbox() {
+        const { renderer, resolution } = this.surface;
+        if (!resolution)
+            return;
+        renderer.setScissorTest(false);
+        renderer.setClearColor(0x000000, 1);
+        renderer.clear(true, false, false);
+        renderer.setScissorTest(true);
+    }
+    /** The scene through its Sprite Batches (ADR 0024), for the camera's current layers. */
+    drawScene() {
+        const { spriteBatches, renderer } = this.surface;
+        const { scene, camera } = this.surface.game;
+        spriteBatches.drawFrame(scene, camera, () => renderer.render(scene, camera));
+    }
+    /** The scene for one layer mask, restoring the camera's own mask after. */
+    drawLayers(mask) {
+        const layers = this.surface.game.camera.layers;
+        const own = layers.mask;
+        layers.mask = mask;
+        try {
+            this.drawScene();
+        }
+        finally {
+            layers.mask = own;
+        }
+    }
+    /** Scene, light-map, Emissive drawables, into whatever target is bound now. */
+    drawLit(width, height) {
+        this.drawLayers(LIT_MASK);
+        this.composeLight(width, height);
+    }
+    composeLight(width, height) {
+        const { renderer } = this.surface;
+        const { scene, camera, lighting } = this.surface.game;
+        this.lightMap ??= new LightMap();
+        this.lightMap.render(renderer, camera, {
+            width,
+            height,
+            ambient: ambientMultiplier(lighting),
+            lights: lighting.lights,
+            projection: this.surface.game.projection,
+            occluderRevision: occluderSignature(this.surface.game),
+            occluders: () => buildOccluderGrid(occluderSources(this.surface.game.entities)),
+        });
+        const autoClear = renderer.autoClear;
+        const background = scene.background;
+        renderer.autoClear = false;
+        scene.background = null;
+        try {
+            this.lightMap.multiplyOver(renderer);
+            this.drawLayers(EMISSIVE_MASK);
+        }
+        finally {
+            renderer.autoClear = autoClear;
+            scene.background = background;
+        }
+    }
+    /** The frame into the Post Effects' canvas-like target, then one pass to the canvas (CA-11). */
+    drawThroughPost(width, height, lit) {
+        const { renderer } = this.surface;
+        const { post } = this.surface.game;
+        this.postPass ??= new PostPass();
+        this.postPass.resize(width, height);
+        // The target stores what the canvas would, so the scene's own (canvas) background clears it.
+        renderer.setRenderTarget(this.postPass.target);
+        try {
+            if (lit)
+                this.drawLit(width, height);
+            else
+                this.drawScene();
+        }
+        finally {
+            renderer.setRenderTarget(null);
+        }
+        this.clearLetterbox();
+        this.postPass.draw(renderer, { vignette: post.vignette, colorGrade: post.colorGrade });
+    }
+}

package/dist/occluder-grid.d.ts

@@ -0,0 +1,19 @@
+import type { OccluderGrid } from './light-field.js';
+/** What a Tilemap contributes to occlusion: its logical grid and which of its tiles are solid. */
+export interface OccluderSource {
+    originX: number;
+    originY: number;
+    cellSize: number;
+    mapWidth: number;
+    mapHeight: number;
+    cells: readonly number[];
+    solidTiles: readonly number[];
+}
+/**
+ * Every Tilemap's solid tiles rasterized onto one logical grid (inference 8):
+ * the finest cell size among them, spanning all their maps. With a single
+ * Tilemap — or several sharing a cell size and an aligned origin — each grid
+ * cell is exactly one tile. Null when no solid tile is placed anywhere: the
+ * lights then cast no shadow at all.
+ */
+export declare function buildOccluderGrid(sources: readonly OccluderSource[]): OccluderGrid | null;

package/dist/occluder-grid.js

@@ -0,0 +1,50 @@
+/** Floating-point slack so a tile edge lying on a grid line covers no neighbouring cell. */
+const EDGE = 1e-6;
+function solidBoxes(source) {
+    const solid = new Set(source.solidTiles);
+    const width = Math.max(0, Math.floor(source.mapWidth));
+    const height = Math.max(0, Math.floor(source.mapHeight));
+    const size = source.cellSize;
+    const boxes = [];
+    if (!(size > 0) || solid.size === 0)
+        return boxes;
+    for (let index = 0; index < width * height; index += 1) {
+        if (!solid.has(source.cells[index] ?? -1))
+            continue;
+        const minX = source.originX + (index % width) * size;
+        const minY = source.originY + Math.floor(index / width) * size;
+        boxes.push({ minX, minY, maxX: minX + size, maxY: minY + size });
+    }
+    return boxes;
+}
+/**
+ * Every Tilemap's solid tiles rasterized onto one logical grid (inference 8):
+ * the finest cell size among them, spanning all their maps. With a single
+ * Tilemap — or several sharing a cell size and an aligned origin — each grid
+ * cell is exactly one tile. Null when no solid tile is placed anywhere: the
+ * lights then cast no shadow at all.
+ */
+export function buildOccluderGrid(sources) {
+    const contributing = sources.map((source) => ({ source, boxes: solidBoxes(source) })).filter(({ boxes }) => boxes.length > 0);
+    if (contributing.length === 0)
+        return null;
+    const cellSize = Math.min(...contributing.map(({ source }) => source.cellSize));
+    const originX = Math.min(...contributing.map(({ source }) => source.originX));
+    const originY = Math.min(...contributing.map(({ source }) => source.originY));
+    const right = Math.max(...contributing.map(({ source }) => source.originX + Math.floor(source.mapWidth) * source.cellSize));
+    const top = Math.max(...contributing.map(({ source }) => source.originY + Math.floor(source.mapHeight) * source.cellSize));
+    const columns = Math.max(1, Math.ceil((right - originX) / cellSize - EDGE));
+    const rows = Math.max(1, Math.ceil((top - originY) / cellSize - EDGE));
+    const solid = new Uint8Array(columns * rows);
+    for (const { boxes } of contributing) {
+        for (const box of boxes) {
+            const fromColumn = Math.max(0, Math.floor((box.minX - originX) / cellSize + EDGE));
+            const toColumn = Math.min(columns, Math.ceil((box.maxX - originX) / cellSize - EDGE));
+            const fromRow = Math.max(0, Math.floor((box.minY - originY) / cellSize + EDGE));
+            const toRow = Math.min(rows, Math.ceil((box.maxY - originY) / cellSize - EDGE));
+            for (let row = fromRow; row < toRow; row += 1)
+                solid.fill(1, row * columns + fromColumn, row * columns + toColumn);
+        }
+    }
+    return { originX, originY, cellSize, columns, rows, solid };
+}

package/dist/particle-batch.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { AssetLoader } from './assets/asset-loader.js';
 import type { ParticleBlend, ParticleOverflow } from './components/particle-emitter.js';
 import { type ParticleSpawn } from './particle-pool.js';