@waica/engine 0.23.0 → 0.25.0

package/dist/runtime-inspection.js

@@ -1,5 +1,6 @@
 import { anchoredPiecesOf } from './ui.js';
 import { componentClassOf } from './component-registry.js';
+import { capLights, lightingSnapshot, postSnapshot, } from './runtime-lighting-snapshot.js';
 export const RUNTIME_PROJECTION_LIMITS = {
     depth: 5,
     entries: 100,
@@ -293,6 +294,8 @@ export class RuntimeInspector {
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
             camera: this.game.cameraEffects.state,
+            lighting: lightingSnapshot(this.game, (entity) => this.idFor(entity)),
+            post: postSnapshot(this.game),
         });
     }
     audioSnapshot() {
@@ -341,7 +344,8 @@ export class RuntimeInspector {
             if (fitsSnapshot(capped))
                 return capped;
         }
-        return capAnchored(capped);
+        const anchoredCapped = capAnchored(capped);
+        return fitsSnapshot(anchoredCapped) ? anchoredCapped : capLights(anchoredCapped, fitsSnapshot);
     }
     idFor(entity) {
         const existing = this.ids.get(entity);

package/dist/runtime-lighting-snapshot.d.ts

@@ -0,0 +1,41 @@
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import type { ProjectionIssue } from './runtime-inspection.js';
+import type { AmbientLight, PostEffectsState } from './scene-render-options.js';
+/** One live Light as a Runtime Snapshot reports it: its entity's name, logical position and params. */
+export interface RuntimeSnapshotLight {
+    /** The entity's name, as `ui.anchored[].entity` reports it. */
+    entity: string;
+    /** The entity's snapshot id (`entity-N`), unique where names repeat. */
+    id: string;
+    x: number;
+    y: number;
+    radius: number;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+    bands: number;
+    softness: number;
+    castShadows: boolean;
+}
+/** `game.lighting` (issue #78 CA-12): the Ambient Light now and every live Light, in logical coordinates. */
+export interface RuntimeSnapshotLighting {
+    ambient: AmbientLight;
+    lights: RuntimeSnapshotLight[];
+}
+/** `game.post` (issue #78 CA-12): each Post Effect, null when off. */
+export type RuntimeSnapshotPost = PostEffectsState;
+export declare function lightingSnapshot(game: Game, idFor: (entity: Entity) => string): RuntimeSnapshotLighting;
+export declare function postSnapshot(game: Game): RuntimeSnapshotPost;
+/** What capping the lights needs from a snapshot: its lights and its projection issues. */
+interface LightsCappable {
+    lighting: RuntimeSnapshotLighting;
+    projectionIssues: ProjectionIssue[];
+}
+/**
+ * The global cap's last stage, once entities and Anchored Pieces are gone
+ * (review): drops lights from the end until the snapshot fits, recording how
+ * many went with a `truncated` marker at `lighting.lights[n]`.
+ */
+export declare function capLights<T extends LightsCappable>(snapshot: T, fits: (candidate: T) => boolean): T;
+export {};

package/dist/runtime-lighting-snapshot.js

@@ -0,0 +1,46 @@
+const hex = (channel) => Math.round(channel * 255).toString(16).padStart(2, '0');
+export function lightingSnapshot(game, idFor) {
+    return {
+        ambient: game.lighting.ambient,
+        lights: game.lighting.lights.map((light) => {
+            const field = light.field();
+            const [r, g, b] = field.color;
+            return {
+                entity: light.entity.name,
+                id: idFor(light.entity),
+                x: field.x,
+                y: field.y,
+                radius: field.radius,
+                color: `#${hex(r)}${hex(g)}${hex(b)}`,
+                intensity: field.intensity,
+                bands: field.bands,
+                softness: field.softness,
+                castShadows: field.castShadows,
+            };
+        }),
+    };
+}
+export function postSnapshot(game) {
+    return { vignette: game.post.vignette, colorGrade: game.post.colorGrade };
+}
+/**
+ * The global cap's last stage, once entities and Anchored Pieces are gone
+ * (review): drops lights from the end until the snapshot fits, recording how
+ * many went with a `truncated` marker at `lighting.lights[n]`.
+ */
+export function capLights(snapshot, fits) {
+    let capped = snapshot;
+    const retained = [...snapshot.lighting.lights];
+    while (retained.length > 0) {
+        retained.pop();
+        const omitted = snapshot.lighting.lights.length - retained.length;
+        capped = {
+            ...snapshot,
+            lighting: { ...snapshot.lighting, lights: [...retained] },
+            projectionIssues: [...snapshot.projectionIssues, { path: `lighting.lights[${retained.length}]`, marker: 'truncated', omitted }],
+        };
+        if (fits(capped))
+            return capped;
+    }
+    return capped;
+}

package/dist/scene-lighting.d.ts

@@ -0,0 +1,52 @@
+import type { Light } from './components/light.js';
+import type { Rgb } from './light-field.js';
+import { type AmbientLight } from './scene-render-options.js';
+import type { SceneRenderJson } from './scene.js';
+/** What `game.lighting.ambient` accepts: either field, a color as `#rrggbb` or a number. */
+export interface AmbientLightInput {
+    color?: string | number;
+    intensity?: number;
+}
+/** A `#rrggbb` color's three channels in 0..1. */
+export declare function hexChannels(hex: string): Rgb;
+/**
+ * `game.lighting` (issue #78, ADR 0026): the live scene's Ambient Light and
+ * its Lights. A scene is drawn lit while it declares `render.lighting`, a
+ * game sets the ambient at runtime, or a Light lives in it; otherwise it is
+ * drawn exactly as an unlit scene. Everything here dies with its scene.
+ */
+export declare class GameLighting {
+    constructor();
+    /** The Ambient Light now, a copy: color `#rrggbb`, intensity 0..1. */
+    get ambient(): AmbientLight;
+    /**
+     * Changes the Ambient Light, field by field — tween it with `game.time.tween`
+     * for a day/night cycle. Out-of-range values clamp; an unreadable color is
+     * ignored. Setting it lights a scene that declared no lighting.
+     */
+    set ambient(value: AmbientLightInput);
+    /** Whether the live scene is drawn lit. */
+    get active(): boolean;
+    /** Every live Light, in the order they were spawned. */
+    get lights(): readonly Light[];
+    /** Adopts a scene's `render.lighting`, replacing whatever the previous scene left. Called by Game. */
+    loadScene(render: SceneRenderJson | undefined): void;
+    /** Back to an unlit scene's state: full white, undeclared. Its Lights leave with their entities. */
+    unloadScene(): void;
+}
+/** The Ambient Light as light-map multipliers: its color's channels × its intensity. */
+export declare function ambientMultiplier(lighting: GameLighting): Rgb;
+/**
+ * Whether the Ambient Light leaves the art as drawn: lights only add and the
+ * light-map clamps at 1, so such a scene's light-map is 1 everywhere and the
+ * frame is drawn unlit, building nothing (review).
+ */
+export declare function ambientIsFull(lighting: GameLighting): boolean;
+/** Internal: a Light joins its scene's lighting when it is ready. */
+export declare function addLight(lighting: GameLighting, light: Light): void;
+/** Internal: a destroyed Light leaves at once, so the next drawn frame no longer has it. */
+export declare function removeLight(lighting: GameLighting, light: Light): void;
+/** Internal: a Tilemap's solid tiles changed (spawned, edited or destroyed); occlusion is rebuilt once. */
+export declare function markOccludersChanged(lighting: GameLighting | undefined): void;
+/** Internal: bumps whenever the solid tiles change, so the occluder grid is rebuilt only then (inference 9). */
+export declare function occluderRevision(lighting: GameLighting): number;

package/dist/scene-lighting.js

@@ -0,0 +1,107 @@
+import { hexColorOr, resolveAmbientLight } from './scene-render-options.js';
+const states = new WeakMap();
+function stateOf(lighting) {
+    const state = states.get(lighting);
+    if (!state)
+        throw new Error('a GameLighting was used before it was constructed');
+    return state;
+}
+/** `0xrrggbb` as `#rrggbb`; anything that is not a 24-bit integer as undefined. */
+function hexOfNumber(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffff)
+        return undefined;
+    return `#${value.toString(16).padStart(6, '0')}`;
+}
+/** A `#rrggbb` color's three channels in 0..1. */
+export function hexChannels(hex) {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return [((value >> 16) & 0xff) / 255, ((value >> 8) & 0xff) / 255, (value & 0xff) / 255];
+}
+/**
+ * `game.lighting` (issue #78, ADR 0026): the live scene's Ambient Light and
+ * its Lights. A scene is drawn lit while it declares `render.lighting`, a
+ * game sets the ambient at runtime, or a Light lives in it; otherwise it is
+ * drawn exactly as an unlit scene. Everything here dies with its scene.
+ */
+export class GameLighting {
+    constructor() {
+        states.set(this, { ambient: resolveAmbientLight(undefined), declared: false, lights: [], occluderRevision: 0 });
+    }
+    /** The Ambient Light now, a copy: color `#rrggbb`, intensity 0..1. */
+    get ambient() {
+        const { ambient } = stateOf(this);
+        return { color: ambient.color, intensity: ambient.intensity };
+    }
+    /**
+     * Changes the Ambient Light, field by field — tween it with `game.time.tween`
+     * for a day/night cycle. Out-of-range values clamp; an unreadable color is
+     * ignored. Setting it lights a scene that declared no lighting.
+     */
+    set ambient(value) {
+        const state = stateOf(this);
+        const color = typeof value.color === 'number' ? hexOfNumber(value.color) : value.color;
+        // An unreadable intensity (a NaN from a custom easing, say) is ignored, like an unreadable color.
+        const intensity = typeof value.intensity === 'number' && Number.isFinite(value.intensity) ? value.intensity : state.ambient.intensity;
+        state.ambient = resolveAmbientLight({
+            ambient: { color: hexColorOr(color, state.ambient.color), intensity },
+        });
+        state.declared = true;
+    }
+    /** Whether the live scene is drawn lit. */
+    get active() {
+        const state = stateOf(this);
+        return state.declared || state.lights.length > 0;
+    }
+    /** Every live Light, in the order they were spawned. */
+    get lights() {
+        return [...stateOf(this).lights];
+    }
+    /** Adopts a scene's `render.lighting`, replacing whatever the previous scene left. Called by Game. */
+    loadScene(render) {
+        const state = stateOf(this);
+        state.ambient = resolveAmbientLight(render?.lighting);
+        state.declared = render?.lighting !== undefined;
+    }
+    /** Back to an unlit scene's state: full white, undeclared. Its Lights leave with their entities. */
+    unloadScene() {
+        this.loadScene(undefined);
+    }
+}
+/** The Ambient Light as light-map multipliers: its color's channels × its intensity. */
+export function ambientMultiplier(lighting) {
+    const { color, intensity } = stateOf(lighting).ambient;
+    const [r, g, b] = hexChannels(color);
+    return [r * intensity, g * intensity, b * intensity];
+}
+/**
+ * Whether the Ambient Light leaves the art as drawn: lights only add and the
+ * light-map clamps at 1, so such a scene's light-map is 1 everywhere and the
+ * frame is drawn unlit, building nothing (review).
+ */
+export function ambientIsFull(lighting) {
+    return ambientMultiplier(lighting).every((channel) => channel >= 1);
+}
+/** Internal: a Light joins its scene's lighting when it is ready. */
+export function addLight(lighting, light) {
+    const { lights } = stateOf(lighting);
+    if (!lights.includes(light))
+        lights.push(light);
+}
+/** Internal: a destroyed Light leaves at once, so the next drawn frame no longer has it. */
+export function removeLight(lighting, light) {
+    const { lights } = stateOf(lighting);
+    const index = lights.indexOf(light);
+    if (index !== -1)
+        lights.splice(index, 1);
+}
+/** Internal: a Tilemap's solid tiles changed (spawned, edited or destroyed); occlusion is rebuilt once. */
+export function markOccludersChanged(lighting) {
+    // A Tilemap on a stand-in game (a test stub with no lighting) has nothing to notify.
+    const state = lighting ? states.get(lighting) : undefined;
+    if (state)
+        state.occluderRevision += 1;
+}
+/** Internal: bumps whenever the solid tiles change, so the occluder grid is rebuilt only then (inference 9). */
+export function occluderRevision(lighting) {
+    return stateOf(lighting).occluderRevision;
+}

package/dist/scene-render-options.d.ts

@@ -0,0 +1,51 @@
+import type { SceneLightingJson, ScenePostJson } from './scene.js';
+/** The Ambient Light: a `#rrggbb` color and an intensity in 0..1. */
+export interface AmbientLight {
+    color: string;
+    intensity: number;
+}
+export interface VignetteEffect {
+    /** How dark the corners get: 0 none, 1 black. */
+    intensity: number;
+    /** Where the darkening starts, from the centre (0) to the corners (1). */
+    radius: number;
+}
+export interface ColorGradeEffect {
+    /** A `#rrggbb` multiplier over the frame. */
+    tint: string;
+    /** 1 leaves contrast unchanged; 0 flattens to grey, 2 doubles it. */
+    contrast: number;
+    /** 1 leaves saturation unchanged; 0 is greyscale, 2 doubles it. */
+    saturation: number;
+}
+/** The scene's Post Effects; null is an effect that is off. */
+export interface PostEffectsState {
+    vignette: VignetteEffect | null;
+    colorGrade: ColorGradeEffect | null;
+}
+/** One field of a scene's `render` block that is outside its range, for validate_project. */
+export interface SceneRenderIssue {
+    field: string;
+    message: string;
+}
+/** A `#rrggbb` color in lower case, or `fallback` for anything else. */
+export declare function hexColorOr(value: unknown, fallback: string): string;
+/**
+ * The scene's starting Ambient Light: full white light unless `render.lighting.ambient`
+ * says otherwise. Runtime clamping (inference 11): an out-of-range value is
+ * clamped and an unreadable one falls back to its default, never thrown.
+ */
+export declare function resolveAmbientLight(json: SceneLightingJson | undefined): AmbientLight;
+/** A vignette as the runtime applies it, clamped; null when the scene has none. */
+export declare function resolveVignette(value: unknown): VignetteEffect | null;
+/** A color grade as the runtime applies it, absent fields neutral; null when the scene has none. */
+export declare function resolveColorGrade(value: unknown): ColorGradeEffect | null;
+/** The scene's starting Post Effects: every one off unless `render.post` turns it on. */
+export declare function resolvePostEffects(json: ScenePostJson | undefined): PostEffectsState;
+/**
+ * Every field of a scene's `render.lighting` and `render.post` that is
+ * outside its range, each with a message naming the field and its range —
+ * what the MCP scene validation reports (CA-2). Other render fields are not
+ * checked here.
+ */
+export declare function sceneRenderIssues(render: unknown): SceneRenderIssue[];

package/dist/scene-render-options.js

@@ -0,0 +1,126 @@
+const WHITE = '#ffffff';
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+/** Each numeric field's range (inference 12). */
+const RANGES = {
+    'render.lighting.ambient.intensity': [0, 1],
+    'render.post.vignette.intensity': [0, 1],
+    'render.post.vignette.radius': [0, 1],
+    'render.post.colorGrade.contrast': [0, 2],
+    'render.post.colorGrade.saturation': [0, 2],
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function recordOf(value) {
+    return isRecord(value) ? value : {};
+}
+/** A `#rrggbb` color in lower case, or `fallback` for anything else. */
+export function hexColorOr(value, fallback) {
+    return typeof value === 'string' && HEX_COLOR.test(value) ? value.toLowerCase() : fallback;
+}
+/** A finite number clamped to the field's range, or `fallback` for anything else. */
+function rangedOr(value, field, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const [min, max] = RANGES[field];
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * The scene's starting Ambient Light: full white light unless `render.lighting.ambient`
+ * says otherwise. Runtime clamping (inference 11): an out-of-range value is
+ * clamped and an unreadable one falls back to its default, never thrown.
+ */
+export function resolveAmbientLight(json) {
+    const ambient = recordOf(recordOf(json).ambient);
+    return {
+        color: hexColorOr(ambient.color, WHITE),
+        intensity: rangedOr(ambient.intensity, 'render.lighting.ambient.intensity', 1),
+    };
+}
+/** A vignette as the runtime applies it, clamped; null when the scene has none. */
+export function resolveVignette(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        intensity: rangedOr(value.intensity, 'render.post.vignette.intensity', 0.5),
+        radius: rangedOr(value.radius, 'render.post.vignette.radius', 0.5),
+    };
+}
+/** A color grade as the runtime applies it, absent fields neutral; null when the scene has none. */
+export function resolveColorGrade(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        tint: hexColorOr(value.tint, WHITE),
+        contrast: rangedOr(value.contrast, 'render.post.colorGrade.contrast', 1),
+        saturation: rangedOr(value.saturation, 'render.post.colorGrade.saturation', 1),
+    };
+}
+/** The scene's starting Post Effects: every one off unless `render.post` turns it on. */
+export function resolvePostEffects(json) {
+    const post = recordOf(json);
+    return { vignette: resolveVignette(post.vignette), colorGrade: resolveColorGrade(post.colorGrade) };
+}
+const shown = (value) => (typeof value === 'string' ? JSON.stringify(value) : String(value));
+function rangeIssue(field, value, issues) {
+    const [min, max] = RANGES[field];
+    if (typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max)
+        return;
+    issues.push({ field, message: `${field} must be a number from ${min} to ${max}; got ${shown(value)}.` });
+}
+function colorIssue(field, value, issues) {
+    if (value === undefined || (typeof value === 'string' && HEX_COLOR.test(value)))
+        return;
+    issues.push({ field, message: `${field} must be a #rrggbb color; got ${shown(value)}.` });
+}
+/** The block at `field` (its last segment, in `parent`), reported when present but not an object. */
+function block(parent, field, issues) {
+    const value = parent[field.slice(field.lastIndexOf('.') + 1)];
+    if (value === undefined)
+        return undefined;
+    if (isRecord(value))
+        return value;
+    issues.push({ field, message: `${field} must be an object; got ${shown(value)}.` });
+    return undefined;
+}
+function lightingIssues(render, issues) {
+    const lighting = block(render, 'render.lighting', issues);
+    const ambient = lighting && block(lighting, 'render.lighting.ambient', issues);
+    if (!ambient)
+        return;
+    colorIssue('render.lighting.ambient.color', ambient.color, issues);
+    if (ambient.intensity !== undefined)
+        rangeIssue('render.lighting.ambient.intensity', ambient.intensity, issues);
+}
+function postIssues(render, issues) {
+    const post = block(render, 'render.post', issues);
+    if (!post)
+        return;
+    const vignette = block(post, 'render.post.vignette', issues);
+    if (vignette) {
+        rangeIssue('render.post.vignette.intensity', vignette.intensity, issues);
+        rangeIssue('render.post.vignette.radius', vignette.radius, issues);
+    }
+    const grade = block(post, 'render.post.colorGrade', issues);
+    if (!grade)
+        return;
+    colorIssue('render.post.colorGrade.tint', grade.tint, issues);
+    if (grade.contrast !== undefined)
+        rangeIssue('render.post.colorGrade.contrast', grade.contrast, issues);
+    if (grade.saturation !== undefined)
+        rangeIssue('render.post.colorGrade.saturation', grade.saturation, issues);
+}
+/**
+ * Every field of a scene's `render.lighting` and `render.post` that is
+ * outside its range, each with a message naming the field and its range —
+ * what the MCP scene validation reports (CA-2). Other render fields are not
+ * checked here.
+ */
+export function sceneRenderIssues(render) {
+    if (!isRecord(render))
+        return [];
+    const issues = [];
+    lightingIssues(render, issues);
+    postIssues(render, issues);
+    return issues;
+}

package/dist/scene.d.ts

@@ -28,8 +28,37 @@ export interface PrefabJson {
     type: 'character' | 'object' | 'tile';
     components: SceneComponentJson[];
 }
+/**
+ * The scene's lighting (issue #78, ADR 0026). Declaring it — or spawning a
+ * Light — draws the scene lit; absent, the scene is drawn exactly as unlit.
+ */
+export interface SceneLightingJson {
+    /** Where no light reaches. Absent fields: `#ffffff` and 1, the art as drawn. */
+    ambient?: {
+        color?: string;
+        intensity?: number;
+    };
+}
+/** The scene's Post Effects, each off unless declared (issue #78). */
+export interface ScenePostJson {
+    /** Darkens the frame's edges: `intensity` 0..1 at the corners, starting at `radius` 0..1 from the centre. */
+    vignette?: {
+        intensity: number;
+        radius: number;
+    };
+    /** A `#rrggbb` tint multiplier, and contrast and saturation from 0 to 2 (1 leaves the frame unchanged). */
+    colorGrade?: {
+        tint?: string;
+        contrast?: number;
+        saturation?: number;
+    };
+}
 /** Scene-wide render options (v3). */
 export interface SceneRenderJson {
+    /** Ambient Light; with it (or any Light) the scene is lit (ADR 0026). */
+    lighting?: SceneLightingJson;
+    /** Vignette and color grade; with either on, the frame renders through a render target. */
+    post?: ScenePostJson;
     /**
      * 'y' orders same-layer sprites by their render-space Y — lower Y renders
      * in front (top-down depth). Absent: spawn order breaks same-layer ties.

package/dist/sprite-batch.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { TextureOutcome } from './assets/asset-loader.js';
 export type SpriteBatchShape = 'rectangle' | 'circle';
 /**
@@ -44,7 +44,7 @@ export declare class SpriteRunMesh {
     readonly mesh: THREE.InstancedMesh;
     private readonly colors;
     private readonly uvs;
-    constructor(base: THREE.BufferGeometry, material: THREE.MeshBasicMaterial, capacity: number);
+    constructor(base: THREE.BufferGeometry, material: THREE.MeshBasicNodeMaterial, capacity: number);
     get capacity(): number;
     /** Writes the sprite drawn `index`-th in this run. */
     write(index: number, instance: SpriteBatchInstance): void;
@@ -61,7 +61,7 @@ export declare class SpriteRunMesh {
  */
 export declare class SpriteBatch {
     private readonly geometry;
-    readonly material: THREE.MeshBasicMaterial;
+    readonly material: THREE.MeshBasicNodeMaterial;
     /** When the key's texture settled; null for untextured and bare entries. */
     readonly settled: Promise<TextureOutcome> | null;
     private readonly slots;

package/dist/sprite-batch.js

@@ -1,4 +1,6 @@
-import * as THREE from 'three';
+import { attribute, context, mat3, positionLocal, uv, vec3, vertexStage } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+import { TRANSPARENT_TEXEL_ALPHA } from './render-layers.js';
 /** The first capacity of a batch's instance buffers; it doubles when full. */
 export const INITIAL_SPRITE_BATCH_CAPACITY = 16;
 /** The key's canonical string: equal keys share one batch. */
@@ -12,41 +14,52 @@ export function spriteGeometry(shape) {
 }
 /** The per-instance UV transform a run carries: repeat (x, y) and offset (z, w). */
 const INSTANCE_UV = 'instanceUv';
+/** Whether three is building the material for one of the batch's instanced run meshes. */
+function drawsInstances(builder) {
+    return builder.object.isInstancedMesh === true;
+}
+/**
+ * The map UV of one instance: its repeat and offset as the same mat3 a
+ * texture's own matrix is, applied to the quad's UV per vertex — as every
+ * other map is (render-output.ts `mapUvPerVertex`) — so the corner UVs are
+ * the very floats the per-sprite draw interpolates.
+ */
+function instanceMapUv() {
+    const transform = attribute(INSTANCE_UV, 'vec4');
+    return vertexStage(mat3(transform.x, 0, 0, 0, transform.y, 0, transform.z, transform.w, 1).mul(vec3(uv(), 1)).xy);
+}
 /**
- * Shader hook shared by every batch material. The instance matrix already
- * holds view × world (three's own `modelViewMatrix` for that sprite, computed
- * the same way on the CPU), so the vertex shader skips `modelViewMatrix`; the
- * map's UV transform comes from the instance instead of `mapTransform`. Every
- * rewrite sits behind USE_INSTANCING: the hidden anchors share this material,
- * and if one were ever drawn as a plain mesh it compiles three's own chunks.
+ * Every batch's material, as a node material (ADR 0025). The instance
+ * matrix already holds view × world (three's own `modelViewMatrix` for that
+ * sprite, computed the same way on the CPU), so an instanced draw skips
+ * `modelViewMatrix`; the map's UV transform comes from the instance instead
+ * of the texture. Both apply to instanced draws only: the hidden anchors
+ * share this material, and if one were ever drawn as a plain mesh it gets
+ * three's own transforms.
  */
-function useInstanceTransforms(shader) {
-    shader.vertexShader = shader.vertexShader
-        .replace('#include <common>', ['#include <common>', '#ifdef USE_INSTANCING', `  attribute vec4 ${INSTANCE_UV};`, '#endif'].join('\n'))
-        .replace('#include <uv_vertex>', [
-        '#ifdef USE_INSTANCING',
-        '  #ifdef USE_MAP',
-        `    vMapUv = ( mat3( ${INSTANCE_UV}.x, 0.0, 0.0, 0.0, ${INSTANCE_UV}.y, 0.0, ${INSTANCE_UV}.z, ${INSTANCE_UV}.w, 1.0 ) * vec3( MAP_UV, 1 ) ).xy;`,
-        '  #endif',
-        '#else',
-        '  #include <uv_vertex>',
-        '#endif',
-    ].join('\n'))
-        .replace('#include <project_vertex>', [
-        '#ifdef USE_INSTANCING',
-        '  vec4 mvPosition = instanceMatrix * vec4( transformed, 1.0 );',
-        '  gl_Position = projectionMatrix * mvPosition;',
-        '#else',
-        '  #include <project_vertex>',
-        '#endif',
-    ].join('\n'));
+class SpriteBatchMaterial extends THREE.MeshBasicNodeMaterial {
+    constructor(parameters) {
+        super(parameters);
+        this.contextNode = context({
+            getUV: (texture, builder) => {
+                if (!drawsInstances(builder))
+                    return null;
+                // The instance transform replaces the map's own matrix.
+                texture.setUpdateMatrix(false);
+                return instanceMapUv();
+            },
+        });
+    }
+    setupPositionView(builder) {
+        // three's instancing already multiplied positionLocal by the instance matrix.
+        return drawsInstances(builder) ? positionLocal : super.setupPositionView(builder);
+    }
 }
 function createMaterial(key, textures) {
     // Double-sided: a flipped sprite mirrors through a negative x scale in its
     // matrix, exactly like its own mesh; per instance there is no winding flip.
-    const material = new THREE.MeshBasicMaterial({ transparent: true, side: THREE.DoubleSide });
+    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide, alphaTest: TRANSPARENT_TEXEL_ALPHA });
     material.forceSinglePass = true;
-    material.onBeforeCompile = useInstanceTransforms;
     if (key.texture === null)
         return { material, settled: null };
     const { texture, settled } = key.texture
@@ -88,6 +101,9 @@ export class SpriteRunMesh {
         this.mesh.instanceColor = this.colors;
         // Drawn in an explicit renderOrder; its instances are already in view space.
         this.mesh.frustumCulled = false;
+        // A run is collected through its sprites' anchors, which carry their own
+        // layers (Emissive or not, ADR 0026): the run itself is on every layer.
+        this.mesh.layers.enableAll();
         this.mesh.matrixAutoUpdate = false;
         this.mesh.boundingSphere = new THREE.Sphere();
     }

package/dist/sprite-batches.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { TextureOutcome } from './assets/asset-loader.js';
 import type { Game } from './game.js';
 import { SpriteBatch, type SpriteBatchInstance, type SpriteBatchKey, type SpriteBatchTextures } from './sprite-batch.js';
@@ -7,7 +7,7 @@ export interface SpriteUvSource {
     readonly offset: THREE.Vector2;
     readonly repeat: THREE.Vector2;
 }
-export type SpriteAnchor = THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicMaterial>;
+export type SpriteAnchor = THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicNodeMaterial>;
 /** Where an instance sits: its key, that key's batch and its slot there. */
 export interface SpriteBatchSeat {
     key: SpriteBatchKey;

package/dist/sprite-batches.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { SpriteBatch, spriteBatchKeyId, spriteGeometry, } from './sprite-batch.js';
 import { TransparentDrawCollector } from './sprite-draw-collector.js';
 import { compareTransparentDraws, forEachSpriteRun } from './sprite-runs.js';

package/dist/sprite-draw-collector.d.ts

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import type { Drawable } from './sprite-runs.js';
 /** A frame drawable: what three sorts it by, the object, and the sprite instance it stands for (null otherwise). */
 export interface FrameDrawable<K, I> extends Drawable<K> {
@@ -12,8 +12,8 @@ export interface CollectedSprites<K, I> {
     keyOf(instance: I): K;
 }
 /**
- * One frame's transparent drawables, collected the way WebGLRenderer's
- * projectObject walks the scene: visibility, camera layers, Group render
+ * One frame's transparent drawables, collected the way three's renderer
+ * (`_projectObject`) walks the scene: visibility, camera layers, Group render
  * order, frustum culling, and the clip-space z it sorts by. Sprite anchors
  * are hidden yet collected when in view; `skip` (the batches' own run
  * meshes) is never walked. The drawables are pooled across frames.