@waica/engine 0.24.0 → 0.26.0

package/dist/scene-camera-3d.d.ts

@@ -0,0 +1,66 @@
+import type * as THREE from 'three/webgpu';
+/** A world-space point or direction as scene JSON stores it. */
+export type Vec3Json = [number, number, number];
+/**
+ * A scene's perspective camera (3D scenes, ADR 0027). Fixed by the scene; game
+ * code may move it. Y is up and the camera looks from `position` at `target`.
+ */
+export interface PerspectiveSceneCameraJson {
+    kind: 'perspective';
+    /** Where the camera sits. Default `[0, 5, 10]`. */
+    position?: Vec3Json;
+    /** The point it looks at. Default `[0, 0, 0]`. */
+    target?: Vec3Json;
+    /** Vertical field of view in degrees, in (0, 180). Default 60. */
+    fov?: number;
+    /** Near clipping plane, above 0. Default 0.1. */
+    near?: number;
+    /** Far clipping plane, above `near`. Default 1000. */
+    far?: number;
+    zoom?: never;
+    follow?: never;
+    deadzoneWidth?: never;
+    deadzoneHeight?: never;
+    lookahead?: never;
+    lookaheadY?: never;
+    smoothing?: never;
+    limits?: never;
+}
+export interface ResolvedPerspectiveCamera {
+    kind: 'perspective';
+    position: Vec3Json;
+    target: Vec3Json;
+    fov: number;
+    near: number;
+    far: number;
+}
+export declare const PERSPECTIVE_DEFAULTS: {
+    readonly position: Vec3Json;
+    readonly target: Vec3Json;
+    readonly fov: 60;
+    readonly near: 0.1;
+    readonly far: 1000;
+};
+/** True for a perspective camera block; everything else (or none) is the orthographic one. */
+export declare function isPerspectiveCameraJson(json: {
+    kind?: string;
+} | undefined): json is PerspectiveSceneCameraJson;
+/** Fills a perspective camera block with the engine defaults. */
+export declare function resolvePerspectiveCamera(json?: PerspectiveSceneCameraJson): ResolvedPerspectiveCamera;
+/** Points `camera` as the resolved block says, at the given aspect ratio. */
+export declare function placePerspectiveCamera(camera: THREE.PerspectiveCamera, resolved: ResolvedPerspectiveCamera, aspect: number): void;
+/** One field of a scene's render, camera or entity transform that is invalid, for validate_project. */
+export interface SceneFieldIssue {
+    field: string;
+    message: string;
+}
+/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
+export declare const shown: (value: unknown) => string;
+export declare function isFiniteNumber(value: unknown): value is number;
+/**
+ * Every field of a perspective camera block outside its range: `fov` in
+ * (0, 180), `near` above 0, `far` above `near`, and `position` and `target`
+ * three finite numbers, and none of the orthographic block's fields. Anything
+ * that is not a perspective block reports none.
+ */
+export declare function perspectiveCameraIssues(camera: unknown): SceneFieldIssue[];

package/dist/scene-camera-3d.js

@@ -0,0 +1,117 @@
+export const PERSPECTIVE_DEFAULTS = {
+    position: [0, 5, 10],
+    target: [0, 0, 0],
+    fov: 60,
+    near: 0.1,
+    far: 1000,
+};
+/** True for a perspective camera block; everything else (or none) is the orthographic one. */
+export function isPerspectiveCameraJson(json) {
+    return json?.kind === 'perspective';
+}
+/** Fills a perspective camera block with the engine defaults. */
+export function resolvePerspectiveCamera(json = { kind: 'perspective' }) {
+    return {
+        kind: 'perspective',
+        position: json.position ?? PERSPECTIVE_DEFAULTS.position,
+        target: json.target ?? PERSPECTIVE_DEFAULTS.target,
+        fov: json.fov ?? PERSPECTIVE_DEFAULTS.fov,
+        near: json.near ?? PERSPECTIVE_DEFAULTS.near,
+        far: json.far ?? PERSPECTIVE_DEFAULTS.far,
+    };
+}
+/** Points `camera` as the resolved block says, at the given aspect ratio. */
+export function placePerspectiveCamera(camera, resolved, aspect) {
+    camera.fov = resolved.fov;
+    camera.near = resolved.near;
+    camera.far = resolved.far;
+    camera.aspect = aspect;
+    camera.position.set(...resolved.position);
+    camera.lookAt(...resolved.target);
+    camera.updateProjectionMatrix();
+    camera.updateMatrixWorld();
+}
+/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
+export const shown = (value) => (typeof value === 'string' ? JSON.stringify(value) : String(value));
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function vectorIssue(field, value, issues) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber))
+        return;
+    issues.push({ field, message: `${field} must be three finite numbers [x, y, z]; got ${JSON.stringify(value)}.` });
+}
+function fovIssue(value, issues) {
+    if (value === undefined)
+        return;
+    if (isFiniteNumber(value) && value > 0 && value < 180)
+        return;
+    issues.push({ field: 'camera.fov', message: `camera.fov must be a number above 0 and below 180; got ${shown(value)}.` });
+}
+/** `position` and `target` as the camera would use them, when both are well-formed (declared or default). */
+function resolvedAim(block) {
+    const position = block.position ?? PERSPECTIVE_DEFAULTS.position;
+    const target = block.target ?? PERSPECTIVE_DEFAULTS.target;
+    const wellFormed = (value) => Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber);
+    return wellFormed(position) && wellFormed(target) ? { position, target } : null;
+}
+function aimIssue(block, issues) {
+    const aim = resolvedAim(block);
+    if (!aim || aim.position.some((value, axis) => value !== aim.target[axis]))
+        return;
+    issues.push({
+        field: 'camera.target',
+        message: `camera.target must differ from camera.position (${JSON.stringify(aim.position)}): a camera needs a direction to look in.`,
+    });
+}
+function planeIssues(near, far, issues) {
+    const nearIsValid = isFiniteNumber(near) && near > 0;
+    if (near !== undefined && !nearIsValid) {
+        issues.push({ field: 'camera.near', message: `camera.near must be a number above 0; got ${shown(near)}.` });
+    }
+    const nearValue = nearIsValid ? near : PERSPECTIVE_DEFAULTS.near;
+    if (far !== undefined && !(isFiniteNumber(far) && far > nearValue)) {
+        issues.push({ field: 'camera.far', message: `camera.far must be a number above near (${nearValue}); got ${shown(far)}.` });
+    }
+}
+/** The orthographic block's fields, which a perspective block does not accept. */
+const ORTHOGRAPHIC_ONLY_FIELDS = [
+    'follow',
+    'zoom',
+    'deadzoneWidth',
+    'deadzoneHeight',
+    'lookahead',
+    'lookaheadY',
+    'smoothing',
+    'limits',
+];
+function orthographicFieldIssues(block, issues) {
+    for (const field of ORTHOGRAPHIC_ONLY_FIELDS) {
+        if (block[field] === undefined)
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} belongs to an orthographic camera; a perspective camera does not accept it.` });
+    }
+}
+/**
+ * Every field of a perspective camera block outside its range: `fov` in
+ * (0, 180), `near` above 0, `far` above `near`, and `position` and `target`
+ * three finite numbers, and none of the orthographic block's fields. Anything
+ * that is not a perspective block reports none.
+ */
+export function perspectiveCameraIssues(camera) {
+    if (typeof camera !== 'object' || camera === null)
+        return [];
+    const block = { ...camera };
+    if (block.kind !== 'perspective')
+        return [];
+    const issues = [];
+    vectorIssue('camera.position', block.position, issues);
+    vectorIssue('camera.target', block.target, issues);
+    fovIssue(block.fov, issues);
+    aimIssue(block, issues);
+    planeIssues(block.near, block.far, issues);
+    orthographicFieldIssues(block, issues);
+    return issues;
+}

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-lights-3d.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+import type { SceneSpace } from './scene-space.js';
+import type { AmbientLight } from './scene-render-options.js';
+/**
+ * The Ambient Light of a 3D scene (ADR 0027): one `THREE.AmbientLight` the
+ * Game owns, fed by `game.lighting.ambient` (`render.lighting.ambient` and the
+ * runtime setter), color × intensity, full white when nothing says otherwise.
+ * It exists only while the live scene is 3D; a 2D scene lights through the
+ * light-map instead (ADR 0026).
+ */
+export declare class SceneAmbientLight3d {
+    private readonly scene;
+    private light;
+    constructor(scene: THREE.Scene);
+    /** Adds, updates or removes the light for the live scene's space; called once per frame before it is drawn. */
+    sync(space: SceneSpace, ambient: AmbientLight): void;
+}

package/dist/scene-lights-3d.js

@@ -0,0 +1,27 @@
+import * as THREE from 'three/webgpu';
+/**
+ * The Ambient Light of a 3D scene (ADR 0027): one `THREE.AmbientLight` the
+ * Game owns, fed by `game.lighting.ambient` (`render.lighting.ambient` and the
+ * runtime setter), color × intensity, full white when nothing says otherwise.
+ * It exists only while the live scene is 3D; a 2D scene lights through the
+ * light-map instead (ADR 0026).
+ */
+export class SceneAmbientLight3d {
+    scene;
+    light = null;
+    constructor(scene) {
+        this.scene = scene;
+    }
+    /** Adds, updates or removes the light for the live scene's space; called once per frame before it is drawn. */
+    sync(space, ambient) {
+        if (space !== '3d') {
+            this.light?.removeFromParent();
+            return;
+        }
+        this.light ??= new THREE.AmbientLight();
+        if (this.light.parent !== this.scene)
+            this.scene.add(this.light);
+        this.light.color.set(ambient.color);
+        this.light.intensity = ambient.intensity;
+    }
+}

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-simulation.d.ts

@@ -0,0 +1,22 @@
+import { type SceneFieldIssue, type Vec3Json } from './scene-camera-3d.js';
+import type { SceneSpace } from './scene-space.js';
+/**
+ * A 3D scene's `simulation` block (issue #159): the physics world's settings.
+ * Absent, or with `gravity` absent, the world pulls along -y at 9.81.
+ */
+export interface SceneSimulationJson {
+    /** The world's gravity vector in units per second squared. Default `[0, -9.81, 0]`. */
+    gravity?: Vec3Json;
+}
+export interface ResolvedSceneSimulation {
+    gravity: Vec3Json;
+}
+export declare const DEFAULT_GRAVITY: Readonly<Vec3Json>;
+/** The simulation a scene runs with: its `simulation` block, defaults filling the rest. A malformed gravity reads as the default (`validate_project` reports it). */
+export declare function resolveSceneSimulation(json: SceneSimulationJson | undefined): ResolvedSceneSimulation;
+/**
+ * Every invalid field of a scene's `simulation` block: a gravity that is not
+ * three finite numbers in a 3d scene, and any block at all in a 2d one, where
+ * nothing simulates.
+ */
+export declare function sceneSimulationIssues(simulation: unknown, space: SceneSpace): SceneFieldIssue[];

package/dist/scene-simulation.js

@@ -0,0 +1,29 @@
+import { isFiniteNumber } from './scene-camera-3d.js';
+export const DEFAULT_GRAVITY = [0, -9.81, 0];
+function isVec3(value) {
+    return Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber);
+}
+/** The simulation a scene runs with: its `simulation` block, defaults filling the rest. A malformed gravity reads as the default (`validate_project` reports it). */
+export function resolveSceneSimulation(json) {
+    const gravity = json?.gravity;
+    return { gravity: isVec3(gravity) ? [...gravity] : [...DEFAULT_GRAVITY] };
+}
+/**
+ * Every invalid field of a scene's `simulation` block: a gravity that is not
+ * three finite numbers in a 3d scene, and any block at all in a 2d one, where
+ * nothing simulates.
+ */
+export function sceneSimulationIssues(simulation, space) {
+    if (simulation === undefined)
+        return [];
+    if (space === '2d') {
+        return [{ field: 'simulation', message: `A simulation block needs render.space '3d'; this scene is 2d, where nothing simulates.` }];
+    }
+    if (typeof simulation !== 'object' || simulation === null || Array.isArray(simulation)) {
+        return [{ field: 'simulation', message: `simulation must be an object; got ${JSON.stringify(simulation)}.` }];
+    }
+    const gravity = Reflect.get(simulation, 'gravity');
+    if (gravity === undefined || isVec3(gravity))
+        return [];
+    return [{ field: 'simulation.gravity', message: `simulation.gravity must be three finite numbers [x, y, z]; got ${JSON.stringify(gravity)}.` }];
+}

package/dist/scene-space.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentClass, ComponentSpace } from './component.js';
+import { type SceneFieldIssue } from './scene-camera-3d.js';
+/**
+ * A scene's space (ADR 0027): `'2d'` is the engine's orthographic world,
+ * where `z` is draw order; `'3d'` makes `z` a world axis under a perspective
+ * camera and a real depth buffer. A scene declares it as `render.space`.
+ */
+export type SceneSpace = '2d' | '3d';
+export declare const SCENE_SPACES: readonly SceneSpace[];
+/** The scene's space: 3d only when `render.space` says exactly so. */
+export declare function resolveSceneSpace(render: unknown): SceneSpace;
+/**
+ * What a scene's render block makes of the draw-order options at runtime. A
+ * 3D scene has no y-sort and no isometric projection whatever the block
+ * says (`validate_project` reports them); a 2D scene reads them as always.
+ */
+export declare function resolveRenderPolicy(render: unknown): {
+    space: SceneSpace;
+    sort: 'y' | null;
+    projection: 'isometric' | null;
+};
+/**
+ * What a component class says about the space it belongs to: its `static
+ * space` marker, or nothing. Only that slice of `ComponentClass`, so the
+ * abstract `Component` and a class the caller builds by hand qualify too.
+ */
+export type SpaceMarked = Pick<ComponentClass, 'space'>;
+/** The space a component class belongs to; a class that declares none is `'both'`. */
+export declare function componentSpaceOf(Class: SpaceMarked): ComponentSpace;
+/**
+ * True when a component of this class does not belong in a scene of this
+ * space: a `'2d'` component in 3d, a `'3d'` one in 2d. Reads the class's
+ * `static space` marker, so engine, behavior and project-owned components
+ * answer the same way. A class the caller does not know (undefined) is
+ * space-neutral.
+ */
+export declare function componentSpaceMismatch(space: SceneSpace, Class: SpaceMarked | undefined): boolean;
+/**
+ * Every invalid field of a scene's `render.space`, its camera block and the
+ * render options a 3d scene cannot use: a space outside `'2d' | '3d'`, a
+ * camera that does not match the space, a perspective camera out of range
+ * and `render.sort`, `render.projection` or `render.batch` under 3d. Other
+ * render fields are `sceneRenderIssues`'s.
+ */
+export declare function sceneSpaceIssues(render: unknown, camera: unknown): SceneFieldIssue[];
+/**
+ * An entity's `position` (2 or 3 finite numbers), `rotation` (degrees) and
+ * `scale` (3 finite numbers each) that are anything else.
+ */
+export declare function entityTransformIssues(entity: unknown): SceneFieldIssue[];