@waica/engine 0.25.0 → 0.27.0

package/dist/physics-3d/world-queries.js

@@ -0,0 +1,63 @@
+const IDENTITY = { x: 0, y: 0, z: 0, w: 1 };
+/**
+ * Rapier's predicate for a query: only colliders whose body record `accepts`.
+ * It runs inside Rapier's borrow of the world, so `accepts` must be a plain
+ * read of the record (the domain, liveness, the structural filter); game code
+ * such as a `where` predicate runs afterwards, on the collected records.
+ */
+function accepting(world, accepts) {
+    return (collider) => {
+        const record = world.recordOfCollider(collider.handle);
+        return record !== undefined && accepts(record);
+    };
+}
+/**
+ * Every collider along a ray whose record `accepts`, nearest first.
+ * `direction` is a unit vector, so the distance is in world units; an origin
+ * inside a collider hits it at distance 0.
+ */
+export function worldRayHits(world, ray, accepts) {
+    const { R, raw } = world;
+    const { origin, direction } = ray;
+    const hits = [];
+    raw.intersectionsWithRay(new R.Ray(origin, direction), ray.maxDistance, true, (hit) => {
+        const record = world.recordOfCollider(hit.collider.handle);
+        const distance = hit.timeOfImpact;
+        if (record) {
+            hits.push({
+                record,
+                distance,
+                point: { x: origin.x + direction.x * distance, y: origin.y + direction.y * distance, z: origin.z + direction.z * distance },
+                normal: { x: hit.normal.x, y: hit.normal.y, z: hit.normal.z },
+            });
+        }
+        return true;
+    }, undefined, undefined, undefined, undefined, accepting(world, accepts));
+    return hits.sort((a, b) => a.distance - b.distance);
+}
+/** Every record whose collider `accepts` and that intersects the volume. */
+export function recordsInVolume(world, volume, accepts) {
+    const { R, raw } = world;
+    const shape = volume.shape === 'box'
+        ? new R.Cuboid(volume.size.x / 2, volume.size.y / 2, volume.size.z / 2)
+        : new R.Ball(volume.radius);
+    const found = [];
+    raw.intersectionsWithShape(volume.center, IDENTITY, shape, (collider) => {
+        const record = world.recordOfCollider(collider.handle);
+        if (record)
+            found.push(record);
+        return true;
+    }, undefined, undefined, undefined, undefined, accepting(world, accepts));
+    return found;
+}
+/** Every record whose collider `accepts` and that contains the point. */
+export function recordsAtPoint(world, at, accepts) {
+    const found = [];
+    world.raw.intersectionsWithPoint(at, (collider) => {
+        const record = world.recordOfCollider(collider.handle);
+        if (record)
+            found.push(record);
+        return true;
+    }, undefined, undefined, undefined, undefined, accepting(world, accepts));
+    return found;
+}

package/dist/pointer-raycast.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+import type { Entity } from './entity.js';
+import type { PointerPick } from './pointer.js';
+/** A position inside the letterboxed game viewport, as fractions of its width and height. */
+export interface ViewportFraction {
+    nx: number;
+    ny: number;
+}
+/**
+ * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
+ * letterboxed point, intersected with the roots of every live Model
+ * (recursively, so a glTF's meshes count and a glTF still loading does not).
+ * The nearest hit wins, with its world-space point. With no hit the pick has
+ * no entity and the point where the ray meets the ground plane y = 0; a ray
+ * that never meets it (it looks at the sky) yields no pick.
+ */
+export declare function raycastPick(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[]): PointerPick | null;

package/dist/pointer-raycast.js

@@ -0,0 +1,48 @@
+import * as THREE from 'three/webgpu';
+import { Model } from './components/model.js';
+const raycaster = new THREE.Raycaster();
+/** The ground of a 3D scene: y = 0, normal up. */
+const GROUND = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+/** Every live Model's root, with the entity that owns it. */
+function modelRoots(entities) {
+    const roots = new Map();
+    for (const entity of entities) {
+        if (!entity.alive)
+            continue;
+        for (const component of entity.components) {
+            if (component instanceof Model && component.root)
+                roots.set(component.root, entity);
+        }
+    }
+    return roots;
+}
+/** The entity whose Model root `object` hangs under. */
+function ownerOf(object, roots) {
+    for (let node = object; node; node = node.parent) {
+        const entity = roots.get(node);
+        if (entity)
+            return entity;
+    }
+    return null;
+}
+/**
+ * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
+ * letterboxed point, intersected with the roots of every live Model
+ * (recursively, so a glTF's meshes count and a glTF still loading does not).
+ * The nearest hit wins, with its world-space point. With no hit the pick has
+ * no entity and the point where the ray meets the ground plane y = 0; a ray
+ * that never meets it (it looks at the sky) yields no pick.
+ */
+export function raycastPick(camera, at, entities) {
+    camera.updateMatrixWorld();
+    raycaster.setFromCamera(new THREE.Vector2(at.nx * 2 - 1, 1 - at.ny * 2), camera);
+    const roots = modelRoots(entities);
+    // A click can land before the first frame has placed anything.
+    for (const root of roots.keys())
+        root.updateWorldMatrix(true, true);
+    const [hit] = raycaster.intersectObjects([...roots.keys()], true);
+    if (hit)
+        return { entity: ownerOf(hit.object, roots), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
+    const ground = raycaster.ray.intersectPlane(GROUND, new THREE.Vector3());
+    return ground ? { entity: null, point: { x: ground.x, y: ground.y, z: ground.z } } : null;
+}

package/dist/pointer.d.ts

@@ -1,3 +1,4 @@
+import { type ViewCamera } from './camera-projection.js';
 import type { Entity } from './entity.js';
 import { type ProjectedPoint } from './projection.js';
 /** Fixed-resolution letterbox target; a duck-typed subset of GameResolution. */
@@ -17,7 +18,8 @@ export interface PointerCamera {
     bottom: number;
 }
 export interface PointerDeps {
-    camera: PointerCamera;
+    /** The live camera, or a function returning it when the scene can swap cameras. */
+    camera: ViewCamera | (() => ViewCamera);
     /** Fixed resolution (letterbox target), or null to fill the canvas. */
     resolution: PointerResolution | null;
     /** The scene's active render projection, read live. */
@@ -25,9 +27,14 @@ export interface PointerDeps {
     /** Live entity list — read at pick time, so later spawns are visible. */
     entities: readonly Entity[];
 }
-/** One resolved click: the logical-space point, plus the entity picked there (if any). */
+/**
+ * One resolved click: the logical-space point, plus the entity picked there
+ * (if any). In a 3D scene the point is in world space and carries `z`.
+ */
 export interface PointerPick {
-    readonly point: ProjectedPoint;
+    readonly point: ProjectedPoint & {
+        readonly z?: number;
+    };
     readonly entity: Entity | null;
 }
 /**
@@ -44,6 +51,7 @@ export declare class Pointer {
     private readonly canvas;
     private readonly deps;
     private pending;
+    private readonly liveCamera;
     constructor(canvas: HTMLCanvasElement, deps: PointerDeps);
     dispose(): void;
     /**
@@ -53,11 +61,24 @@ export declare class Pointer {
      */
     takePending(): PointerPick | null;
     /**
-     * Programmatic click injection (Runtime Bridge CA-10), in logical
-     * coordinates — resolved through the exact same picking a real click uses.
+     * Programmatic click injection (Runtime Bridge CA-10) — resolved through
+     * the exact same picking a real click uses. In a 2D scene `x` and `y` are
+     * logical coordinates and the pick always exists. In a 3D scene they are
+     * canvas CSS pixels from its top-left corner, as a pointer event reports
+     * them, and a ray that meets neither a model nor the ground gives null.
      */
-    injectClick(x: number, y: number): PointerPick;
+    injectClick(x: number, y: number): PointerPick | null;
+    /** Makes a pick the pending click; no pick leaves any earlier click alone. */
+    private queue;
     private handlePointerDown;
+    /** The pick under a viewport position: the 2D sprite boxes, or a 3D scene's raycast. */
+    private pickAt;
+    /**
+     * Where a canvas point (CSS px from its top-left corner) falls inside the
+     * letterboxed viewport, as fractions of its width and height; null on a
+     * letterbox bar (not a click on the world) or before the canvas has a size.
+     */
+    private viewportFraction;
     private letterboxRect;
     private toRenderPoint;
     private resolveRenderPoint;

package/dist/pointer.js

@@ -1,3 +1,5 @@
+import { isPerspectiveCamera } from './camera-projection.js';
+import { raycastPick } from './pointer-raycast.js';
 import { projectIsometric, unprojectIsometric } from './projection.js';
 import { ySortZ } from './render-sort.js';
 import { AnimatedSprite } from './components/animated-sprite.js';
@@ -30,9 +32,12 @@ export class Pointer {
     canvas;
     deps;
     pending = null;
+    liveCamera;
     constructor(canvas, deps) {
         this.canvas = canvas;
         this.deps = deps;
+        const { camera } = this.deps;
+        this.liveCamera = typeof camera === 'function' ? camera : () => camera;
         this.canvas.addEventListener('pointerdown', this.handlePointerDown);
     }
     dispose() {
@@ -50,39 +55,60 @@ export class Pointer {
         return pick;
     }
     /**
-     * Programmatic click injection (Runtime Bridge CA-10), in logical
-     * coordinates — resolved through the exact same picking a real click uses.
+     * Programmatic click injection (Runtime Bridge CA-10) — resolved through
+     * the exact same picking a real click uses. In a 2D scene `x` and `y` are
+     * logical coordinates and the pick always exists. In a 3D scene they are
+     * canvas CSS pixels from its top-left corner, as a pointer event reports
+     * them, and a ray that meets neither a model nor the ground gives null.
      */
     injectClick(x, y) {
+        const camera = this.liveCamera();
+        if (isPerspectiveCamera(camera))
+            return this.queue(this.pickAt(this.viewportFraction(x, y)));
         const renderPoint = this.toRenderPoint(x, y);
-        const pick = this.resolveRenderPoint(renderPoint.x, renderPoint.y);
-        this.pending = pick;
+        return this.queue(this.resolveRenderPoint(renderPoint.x, renderPoint.y));
+    }
+    /** Makes a pick the pending click; no pick leaves any earlier click alone. */
+    queue(pick) {
+        if (pick)
+            this.pending = pick;
         return pick;
     }
     handlePointerDown = (event) => {
         // Primary button only; a touch tap reports the same button (ADR-0010).
         if (event.button !== 0)
             return;
+        const rect = this.canvas.getBoundingClientRect();
+        this.queue(this.pickAt(this.viewportFraction(event.clientX - rect.left, event.clientY - rect.top)));
+    };
+    /** The pick under a viewport position: the 2D sprite boxes, or a 3D scene's raycast. */
+    pickAt(at) {
+        const camera = this.liveCamera();
+        if (!at)
+            return null;
+        if (isPerspectiveCamera(camera))
+            return raycastPick(camera, at, this.deps.entities);
+        const renderX = camera.position.x + camera.left + at.nx * (camera.right - camera.left);
+        const renderY = camera.position.y + camera.top - at.ny * (camera.top - camera.bottom);
+        return this.resolveRenderPoint(renderX, renderY);
+    }
+    /**
+     * Where a canvas point (CSS px from its top-left corner) falls inside the
+     * letterboxed viewport, as fractions of its width and height; null on a
+     * letterbox bar (not a click on the world) or before the canvas has a size.
+     */
+    viewportFraction(px, py) {
         const w = this.canvas.clientWidth;
         const h = this.canvas.clientHeight;
         if (w <= 0 || h <= 0)
-            return;
+            return null;
         const { vx, vy, vw, vh } = this.letterboxRect(w, h);
         if (vw <= 0 || vh <= 0)
-            return;
-        const rect = this.canvas.getBoundingClientRect();
-        const px = event.clientX - rect.left;
-        const py = event.clientY - rect.top;
+            return null;
         const nx = (px - vx) / vw;
         const ny = (py - vy) / vh;
-        // Outside the visible viewport (a letterbox bar): not a click on the world.
-        if (nx < 0 || nx > 1 || ny < 0 || ny > 1)
-            return;
-        const camera = this.deps.camera;
-        const renderX = camera.position.x + camera.left + nx * (camera.right - camera.left);
-        const renderY = camera.position.y + camera.top - ny * (camera.top - camera.bottom);
-        this.pending = this.resolveRenderPoint(renderX, renderY);
-    };
+        return nx < 0 || nx > 1 || ny < 0 || ny > 1 ? null : { nx, ny };
+    }
     letterboxRect(w, h) {
         const resolution = this.deps.resolution;
         if (!resolution)

package/dist/runtime-bridge.d.ts

@@ -85,7 +85,7 @@ export interface RuntimeBridge {
 }
 /** Why a Game can never become operational; reported through the activation. */
 export interface RuntimeBridgeFailure {
-    code: 'render-backend-failed';
+    code: 'render-backend-failed' | 'physics-backend-failed';
     message: string;
 }
 /** Ephemeral pre-page hook installed by the owner of a browser context. */

package/dist/runtime-inspection.d.ts

@@ -1,9 +1,12 @@
 import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
 import type { CameraEffectsState } from './camera-effects.js';
+import type { SceneSpace } from './scene-space.js';
+import { type RuntimeSnapshotView } from './runtime-view-snapshot.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
 import { type RuntimeSnapshotLighting, type RuntimeSnapshotPost } from './runtime-lighting-snapshot.js';
+import { type RuntimeSnapshotPhysics } from './runtime-physics-snapshot.js';
 export type ProjectionMarkerKind = 'cycle' | 'unsupported' | 'error' | 'truncated';
 export interface ProjectionMarker {
     $waica: ProjectionMarkerKind | 'date' | 'bigint' | 'map' | 'set';
@@ -125,10 +128,16 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     time: RuntimeSnapshotTime;
     ui: RuntimeSnapshotUi;
     camera: RuntimeSnapshotCamera;
+    /** The live scene's space (`render.space`, ADR 0027); `'2d'` with no scene. Never filtered. */
+    space: SceneSpace;
+    /** The view the scene is drawn from: the orthographic centre and zoom, or the perspective pose (issue #154 CA-16). Never filtered. */
+    view: RuntimeSnapshotView;
     /** Ambient Light and live Lights (issue #78 CA-12), logical coordinates; never filtered. */
     lighting: RuntimeSnapshotLighting;
     /** Post Effects (issue #78 CA-12), each null when off; never filtered. */
     post: RuntimeSnapshotPost;
+    /** The live 3D scene's physics world: state, gravity and bodies (issue #159 CA-17); absent in a 2D scene, never filtered. */
+    physics?: RuntimeSnapshotPhysics;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;

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