@waica/engine 0.24.0 → 0.25.0

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.js

@@ -1,5 +1,6 @@
 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. */
@@ -57,7 +58,7 @@ class SpriteBatchMaterial extends THREE.MeshBasicNodeMaterial {
 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 SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide });
+    const material = new SpriteBatchMaterial({ transparent: true, side: THREE.DoubleSide, alphaTest: TRANSPARENT_TEXEL_ALPHA });
     material.forceSinglePass = true;
     if (key.texture === null)
         return { material, settled: null };
@@ -100,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",