@waica/engine 0.25.0 → 0.26.0

package/dist/runtime-inspection.js

@@ -1,6 +1,8 @@
+import { cameraEffectsSnapshot, viewSnapshot } from './runtime-view-snapshot.js';
 import { anchoredPiecesOf } from './ui.js';
 import { componentClassOf } from './component-registry.js';
 import { capLights, lightingSnapshot, postSnapshot, } from './runtime-lighting-snapshot.js';
+import { capBodies, physicsSection } from './runtime-physics-snapshot.js';
 export const RUNTIME_PROJECTION_LIMITS = {
     depth: 5,
     entries: 100,
@@ -293,9 +295,12 @@ export class RuntimeInspector {
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
-            camera: this.game.cameraEffects.state,
+            camera: cameraEffectsSnapshot(this.game),
+            space: this.game.space,
+            view: viewSnapshot(this.game),
             lighting: lightingSnapshot(this.game, (entity) => this.idFor(entity)),
             post: postSnapshot(this.game),
+            ...physicsSection(this.game, (entity) => this.idFor(entity)),
         });
     }
     audioSnapshot() {
@@ -345,7 +350,8 @@ export class RuntimeInspector {
                 return capped;
         }
         const anchoredCapped = capAnchored(capped);
-        return fitsSnapshot(anchoredCapped) ? anchoredCapped : capLights(anchoredCapped, fitsSnapshot);
+        const bodiesCapped = capBodies(anchoredCapped, fitsSnapshot);
+        return fitsSnapshot(bodiesCapped) ? bodiesCapped : capLights(bodiesCapped, fitsSnapshot);
     }
     idFor(entity) {
         const existing = this.ids.get(entity);

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

@@ -1,6 +1,7 @@
 import type { Entity } from './entity.js';
 import type { Game } from './game.js';
 import type { ProjectionIssue } from './runtime-inspection.js';
+import type { Vec3Json } from './scene-camera-3d.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 {
@@ -18,10 +19,35 @@ export interface RuntimeSnapshotLight {
     softness: number;
     castShadows: boolean;
 }
-/** `game.lighting` (issue #78 CA-12): the Ambient Light now and every live Light, in logical coordinates. */
+/** One live Sun in a 3D scene (issue #154 CA-16): its entity's name and id, the unit direction it shines along, color and intensity. */
+export interface RuntimeSnapshotSun {
+    entity: string;
+    id: string;
+    direction: Vec3Json;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+}
+/** One live Point Light in a 3D scene (issue #154 CA-16): its world position and look; `distance` 0 is unlimited. */
+export interface RuntimeSnapshotPointLight {
+    entity: string;
+    id: string;
+    position: Vec3Json;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+    distance: number;
+}
+/**
+ * `game.lighting` (issue #78 CA-12): the Ambient Light now and every live
+ * Light, in logical coordinates. A 3D scene (issue #154 CA-16) adds its
+ * Suns and Point Lights; a 2D scene's snapshot has neither key.
+ */
 export interface RuntimeSnapshotLighting {
     ambient: AmbientLight;
     lights: RuntimeSnapshotLight[];
+    sun?: RuntimeSnapshotSun[];
+    pointLights?: RuntimeSnapshotPointLight[];
 }
 /** `game.post` (issue #78 CA-12): each Post Effect, null when off. */
 export type RuntimeSnapshotPost = PostEffectsState;

package/dist/runtime-lighting-snapshot.js

@@ -1,6 +1,37 @@
+import * as THREE from 'three/webgpu';
+import { PointLight } from './components/point-light.js';
+import { Sun } from './components/sun.js';
 const hex = (channel) => Math.round(channel * 255).toString(16).padStart(2, '0');
+const rounded = (value) => Math.round(value * 1e6) / 1e6 || 0;
+const hexOf = (color) => `#${(color & 0xffffff).toString(16).padStart(6, '0')}`;
+function unit(direction) {
+    const [x, y, z] = new THREE.Vector3(...direction).normalize().toArray();
+    return [rounded(x), rounded(y), rounded(z)];
+}
+/** The Suns and Point Lights of a 3D scene's entities, in spawn order. */
+function lights3dSnapshot(game, idFor) {
+    const sun = [];
+    const pointLights = [];
+    for (const entity of game.entities) {
+        for (const component of entity.components) {
+            if (component instanceof Sun) {
+                const { direction, color, intensity } = component;
+                sun.push({ entity: entity.name, id: idFor(entity), direction: unit(direction), color: hexOf(color), intensity });
+            }
+            else if (component instanceof PointLight && component.light) {
+                const { color, intensity, distance, light } = component;
+                light.updateWorldMatrix(true, false);
+                const at = light.getWorldPosition(new THREE.Vector3());
+                const position = [rounded(at.x), rounded(at.y), rounded(at.z)];
+                pointLights.push({ entity: entity.name, id: idFor(entity), position, color: hexOf(color), intensity, distance });
+            }
+        }
+    }
+    return { sun, pointLights };
+}
 export function lightingSnapshot(game, idFor) {
     return {
+        ...(game.space === '3d' ? lights3dSnapshot(game, idFor) : {}),
         ambient: game.lighting.ambient,
         lights: game.lighting.lights.map((light) => {
             const field = light.field();

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

@@ -0,0 +1,41 @@
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import { type BodyKind } from './physics-3d/body-sync.js';
+import type { PhysicsState } from './physics-3d/physics-host.js';
+import type { ProjectionIssue } from './runtime-inspection.js';
+import type { Vec3Json } from './scene-camera-3d.js';
+/** One live body of a 3D scene (issue #159 CA-17): its entity's name and snapshot id, its Rapier type, velocity and whether it stands on something. */
+export interface RuntimeSnapshotBody {
+    entity: string;
+    id: string;
+    type: BodyKind;
+    velocity: Vec3Json;
+    grounded: boolean;
+}
+/**
+ * `game.physics` of a 3D scene (issue #159 CA-17), beside `lighting`: the
+ * world's state (`loading` until the Rapier module arrives), its gravity and
+ * every body in spawn order, rounded to 1e-6. Never filtered by entity or
+ * component filters; a 2D scene's snapshot has no `physics` key.
+ */
+export interface RuntimeSnapshotPhysics {
+    state: PhysicsState;
+    gravity: Vec3Json;
+    bodies: RuntimeSnapshotBody[];
+}
+/** The `physics` section of a 3D scene's snapshot, as the spread that adds it; nothing in a 2D scene. */
+export declare function physicsSection(game: Game, idFor: (entity: Entity) => string): {
+    physics?: RuntimeSnapshotPhysics;
+};
+/** What capping the bodies needs from a snapshot: its physics section and its projection issues. */
+interface BodiesCappable {
+    physics?: RuntimeSnapshotPhysics;
+    projectionIssues: ProjectionIssue[];
+}
+/**
+ * The global cap's stage for bodies, beside the lights' (`capLights`): drops
+ * bodies from the end until the snapshot fits, recording how many went with a
+ * `truncated` marker at `physics.bodies[n]`.
+ */
+export declare function capBodies<T extends BodiesCappable>(snapshot: T, fits: (candidate: T) => boolean): T;
+export {};

package/dist/runtime-physics-snapshot.js

@@ -0,0 +1,45 @@
+import { bodyVelocity } from './physics-3d/body-sync.js';
+const rounded = (value) => Math.round(value * 1e6) / 1e6 || 0;
+const roundedVector = (x, y, z) => [rounded(x), rounded(y), rounded(z)];
+/** The `physics` section of a 3D scene's snapshot, as the spread that adds it; nothing in a 2D scene. */
+export function physicsSection(game, idFor) {
+    if (game.space !== '3d')
+        return {};
+    const world = game.physics.world;
+    const [gx, gy, gz] = game.physics.sceneGravity;
+    const bodies = (world?.bodiesOf(game.entities) ?? []).map((record) => {
+        const { x, y, z } = bodyVelocity(record);
+        return {
+            entity: record.entity.name,
+            id: idFor(record.entity),
+            type: record.kind,
+            velocity: roundedVector(x, y, z),
+            grounded: record.grounded,
+        };
+    });
+    return { physics: { state: game.physics.state, gravity: roundedVector(gx, gy, gz), bodies } };
+}
+/**
+ * The global cap's stage for bodies, beside the lights' (`capLights`): drops
+ * bodies from the end until the snapshot fits, recording how many went with a
+ * `truncated` marker at `physics.bodies[n]`.
+ */
+export function capBodies(snapshot, fits) {
+    const physics = snapshot.physics;
+    if (!physics || fits(snapshot))
+        return snapshot;
+    let capped = snapshot;
+    const retained = [...physics.bodies];
+    while (retained.length > 0) {
+        retained.pop();
+        const omitted = physics.bodies.length - retained.length;
+        capped = {
+            ...snapshot,
+            physics: { ...physics, bodies: [...retained] },
+            projectionIssues: [...snapshot.projectionIssues, { path: `physics.bodies[${retained.length}]`, marker: 'truncated', omitted }],
+        };
+        if (fits(capped))
+            return capped;
+    }
+    return capped;
+}

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

@@ -0,0 +1,25 @@
+import type { CameraEffectsState } from './camera-effects.js';
+import type { Game } from './game.js';
+import type { Vec3Json } from './scene-camera-3d.js';
+/**
+ * The view the scene is drawn from (issue #154 CA-16), beside the Camera
+ * Effects `camera`: the orthographic camera's centre and visible height, or
+ * the perspective camera's pose. Always reflects the live camera.
+ */
+export type RuntimeSnapshotView = {
+    kind: 'orthographic';
+    position: [number, number];
+    zoom: number;
+} | {
+    kind: 'perspective';
+    position: Vec3Json;
+    target: Vec3Json;
+    fov: number;
+};
+export declare function viewSnapshot(game: Game): RuntimeSnapshotView;
+/**
+ * `game.cameraEffects.state` as the snapshot reports it. A perspective camera
+ * does not shake (spec decision 24: shake is a no-op in a 3D scene), so a 3D
+ * scene reports no offset even though the effect's own state keeps decaying.
+ */
+export declare function cameraEffectsSnapshot(game: Game): CameraEffectsState;

package/dist/runtime-view-snapshot.js

@@ -0,0 +1,30 @@
+import * as THREE from 'three/webgpu';
+import { isPerspectiveCamera } from './camera-projection.js';
+/** Float noise off a pose, so a camera that did not move reports the numbers it was declared with. */
+const clean = (value) => Math.round(value * 1e6) / 1e6 || 0;
+function vector(value) {
+    return [clean(value.x), clean(value.y), clean(value.z)];
+}
+export function viewSnapshot(game) {
+    const camera = game.camera;
+    if (!isPerspectiveCamera(camera)) {
+        return { kind: 'orthographic', position: [clean(camera.position.x), clean(camera.position.y)], zoom: game.view };
+    }
+    camera.updateMatrixWorld();
+    const ahead = camera.getWorldDirection(new THREE.Vector3()).multiplyScalar(game.cameraRig.lookDistance);
+    return {
+        kind: 'perspective',
+        position: vector(camera.position),
+        target: vector(camera.position.clone().add(ahead)),
+        fov: camera.fov,
+    };
+}
+/**
+ * `game.cameraEffects.state` as the snapshot reports it. A perspective camera
+ * does not shake (spec decision 24: shake is a no-op in a 3D scene), so a 3D
+ * scene reports no offset even though the effect's own state keeps decaying.
+ */
+export function cameraEffectsSnapshot(game) {
+    const state = game.cameraEffects.state;
+    return game.space === '3d' ? { ...state, shake: { x: 0, y: 0 } } : state;
+}

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-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-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[];