@waica/engine 0.25.0 → 0.26.0

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

@@ -0,0 +1,158 @@
+import { Collider } from '../components/collider.js';
+import { RigidBody } from '../components/rigid-body.js';
+import { SIMULATION_STEP } from '../fixed-step.js';
+import { colliderProblem, createBody, rigidBodyProblem, syncBodyPose } from './body-sync.js';
+import { CharacterMotion } from './character-controller.js';
+/**
+ * One Rapier world and the bodies of the live 3D scene (ADR 0028): created
+ * with the scene, stepped once per Simulation Step, freed with the scene. It
+ * owns every Rapier handle; components only hold plain params and ask the
+ * Game's `physics` for velocity, impulses and the like by entity.
+ */
+export class PhysicsWorld {
+    R;
+    /** The Rapier world itself, for the modules that query it; nothing outside `physics-3d/` and its tests should touch it. */
+    raw;
+    records = new Map();
+    byCollider = new Map();
+    /** Entities with a RigidBody and, so far, no Collider: warned about at the first step if it stays so. */
+    orphans = new Set();
+    /** The last warning each entity got, so the same problem seen from both of its components is said once. */
+    warned = new WeakMap();
+    sensors = 0;
+    /** Bodies came or went since Rapier last updated the structure its queries read. */
+    queriesStale = false;
+    characters;
+    constructor(
+    /** The Rapier module the world was made with, for the shapes and rays its queries build. */
+    R, gravity) {
+        this.R = R;
+        this.raw = new R.World({ x: gravity[0], y: gravity[1], z: gravity[2] });
+        this.raw.timestep = SIMULATION_STEP;
+        this.characters = new CharacterMotion(R, this.raw);
+    }
+    /** Whether any body has a sensor Collider, so the sensor dispatch can be skipped when none does. */
+    get hasSensors() {
+        return this.sensors > 0;
+    }
+    get gravity() {
+        const { x, y, z } = this.raw.gravity;
+        return [x, y, z];
+    }
+    set gravity(value) {
+        this.raw.gravity = { x: value[0], y: value[1], z: value[2] };
+    }
+    /** The record of an entity's body, if it has one. */
+    recordOf(entity) {
+        return this.records.get(entity);
+    }
+    /** The record that owns a Rapier collider handle. */
+    recordOfCollider(handle) {
+        return this.byCollider.get(handle);
+    }
+    /** The bodies of the given entities, in their order. */
+    bodiesOf(entities) {
+        return entities.flatMap((entity) => {
+            const record = this.records.get(entity);
+            return record ? [record] : [];
+        });
+    }
+    /**
+     * Builds (or rebuilds) the entity's body from the Collider and RigidBody it
+     * has now. Called from each component's `onReady`, so either order of the
+     * two works: the later one replaces the earlier one's body.
+     */
+    attach(entity) {
+        const collider = entity.get(Collider);
+        const rigid = entity.get(RigidBody) ?? null;
+        if (!collider) {
+            if (rigid)
+                this.orphans.add(entity);
+            return;
+        }
+        this.detach(entity);
+        const problem = colliderProblem(collider);
+        const bodyProblem = problem === null && rigid ? rigidBodyProblem(rigid) : null;
+        if (problem !== null)
+            return this.warnOnce(entity, `Collider on "${entity.name}" creates no body: ${problem}.`);
+        if (bodyProblem !== null)
+            return this.warnOnce(entity, `RigidBody on "${entity.name}" creates no body: ${bodyProblem}.`);
+        const record = createBody(this.R, this.raw, { entity, collider, rigid });
+        this.records.set(entity, record);
+        this.queriesStale = true;
+        this.byCollider.set(record.shape.handle, record);
+        if (record.sensor)
+            this.sensors += 1;
+    }
+    /** Removes the entity's body and collider; a no-op for an entity without one. */
+    detach(entity) {
+        this.orphans.delete(entity);
+        const record = this.records.get(entity);
+        if (!record)
+            return;
+        this.records.delete(entity);
+        this.byCollider.delete(record.shape.handle);
+        if (record.sensor)
+            this.sensors -= 1;
+        this.raw.removeRigidBody(record.body);
+        this.queriesStale = true;
+    }
+    /**
+     * One Simulation Step of physics: every kinematic body is moved through the
+     * character controller, Rapier steps, then moving bodies write their pose to
+     * their entities.
+     */
+    step() {
+        this.warnOrphans();
+        this.characters.follow(this.records.values());
+        for (const record of this.records.values()) {
+            if (record.kind !== 'kinematic')
+                continue;
+            this.refreshQueries();
+            this.characters.move(record);
+        }
+        this.raw.step();
+        this.queriesStale = false;
+        for (const record of this.records.values())
+            syncBodyPose(record);
+    }
+    /**
+     * Makes ray casts, shape queries and the character controller see the bodies
+     * created or removed since the last step: Rapier only updates the structure
+     * they read inside `step()`, so a body spawned this frame would be invisible
+     * (a character would fall through a floor spawned with it). A step of zero
+     * seconds updates it and moves nothing.
+     */
+    refreshQueries() {
+        if (!this.queriesStale)
+            return;
+        this.queriesStale = false;
+        const timestep = this.raw.timestep;
+        this.raw.timestep = 0;
+        this.raw.step();
+        this.raw.timestep = timestep;
+    }
+    /** Frees the Rapier world and forgets every body. The entities are destroyed (and detached) before this. */
+    free() {
+        this.records.clear();
+        this.byCollider.clear();
+        this.orphans.clear();
+        this.sensors = 0;
+        this.characters.free();
+        this.raw.free();
+    }
+    warnOrphans() {
+        for (const entity of this.orphans) {
+            this.orphans.delete(entity);
+            if (!entity.alive || entity.has(Collider))
+                continue;
+            this.warnOnce(entity, `RigidBody on "${entity.name}" needs a Collider on the same entity; no body was created.`);
+        }
+    }
+    warnOnce(entity, message) {
+        if (this.warned.get(entity) === message)
+            return;
+        this.warned.set(entity, message);
+        console.warn(`[waica] ${message}`);
+    }
+}

package/dist/physics-3d/rapier-module.d.ts

@@ -0,0 +1,17 @@
+import type * as Rapier from '@dimforge/rapier3d-deterministic-compat';
+/** The initialized Rapier module: the `RAPIER` namespace the package documents. */
+export type RapierModule = typeof Rapier;
+export type { Collider as RapierCollider, ColliderDesc as RapierColliderDesc, KinematicCharacterController as RapierCharacterController, RigidBody as RapierBody, TempContactManifold as RapierManifold, World as RapierWorld, } from '@dimforge/rapier3d-deterministic-compat';
+/** The package name, for the messages that name it. */
+export declare const RAPIER_PACKAGE = "@dimforge/rapier3d-deterministic-compat";
+/**
+ * Where a Game gets Rapier (ADR 0013's seam, applied to physics): resolves to
+ * the initialized module. Defaults to `loadRapier`; a project's own tests pass
+ * the real module they initialized once, or a rejecting stub for the failure path.
+ */
+export type PhysicsBackend = () => Promise<RapierModule>;
+/**
+ * Imports and initializes Rapier, once per page: every Game that asks shares
+ * the same module. A failed load is forgotten, so a later Game may retry.
+ */
+export declare function loadRapier(): Promise<RapierModule>;

package/dist/physics-3d/rapier-module.js

@@ -0,0 +1,19 @@
+/** The package name, for the messages that name it. */
+export const RAPIER_PACKAGE = '@dimforge/rapier3d-deterministic-compat';
+let shared = null;
+/**
+ * Imports and initializes Rapier, once per page: every Game that asks shares
+ * the same module. A failed load is forgotten, so a later Game may retry.
+ */
+export function loadRapier() {
+    shared ??= import('@dimforge/rapier3d-deterministic-compat')
+        .then(async (module) => {
+        await module.init();
+        return module;
+    })
+        .catch((error) => {
+        shared = null;
+        throw error;
+    });
+    return shared;
+}

package/dist/physics-3d/sensor-dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { Game } from '../game.js';
+import type { PhysicsWorld } from './physics-world.js';
+/**
+ * The 3D counterpart of the Hitbox trigger dispatch (CA-16): after the physics
+ * step, every overlap involving a sensor Collider fires `onCollide(other)` on
+ * the components of each side whose interest names the other's layer, every
+ * step while they overlap. Pairs are frozen first and each is re-checked live,
+ * like the 2D dispatch.
+ */
+export declare function dispatchSensorCollisions(game: Game, world: PhysicsWorld): void;

package/dist/physics-3d/sensor-dispatch.js

@@ -0,0 +1,77 @@
+import { collisionMaskTargets } from '../collision-category.js';
+import { Collider } from '../components/collider.js';
+/** The mask a Collider has when nothing was declared: every layer. */
+function isDefaultMask(mask) {
+    return mask.length === 1 && mask[0] === '*';
+}
+/**
+ * Whether `self` is notified about `target` (ADR 0016's directional
+ * interest). A sensor always has an interest, its `collidesWith` (default
+ * every layer), except that the default mask leaves out the level's fixed
+ * solids: a 2D Hitbox never sees a Solid, so a pickup resting on the floor is
+ * not told about the floor every step; naming their layer still works. A
+ * solid collider has no interest until it declares a mask of its own
+ * (inference 14, issue #159): the default `['*']` on a solid means "no
+ * interest", so a wall or a character is not woken by every trigger it touches.
+ */
+function interestedIn(self, target) {
+    const { collider } = self;
+    const defaultMask = isDefaultMask(collider.collidesWith);
+    if (!self.sensor && defaultMask)
+        return false;
+    if (defaultMask && !target.sensor && target.kind === 'fixed')
+        return false;
+    return collisionMaskTargets(collider.collidesWith, target.collider.layer);
+}
+/** Every sensor overlap of the world as a frozen snapshot: each pair once, the earlier-spawned sensor first. */
+function sensorPairs(game, world) {
+    const records = world.bodiesOf(game.entities);
+    const spawnIndex = new Map(records.map((record, index) => [record, index]));
+    const spawnedBefore = (a, b) => (spawnIndex.get(a) ?? 0) < (spawnIndex.get(b) ?? 0);
+    const pairs = [];
+    for (const sensor of records.filter((record) => record.sensor)) {
+        world.raw.intersectionPairsWith(sensor.shape, (shape) => {
+            const other = world.recordOfCollider(shape.handle);
+            if (!other || other === sensor)
+                return;
+            // Two sensors see each other: the earlier one reports the pair.
+            if (other.sensor && spawnedBefore(other, sensor))
+                return;
+            pairs.push([sensor, other]);
+        });
+    }
+    return pairs;
+}
+/** Both entities of a snapshotted pair are alive and still carry the Collider it was taken from. */
+function stillOverlapping([first, second]) {
+    return (first.entity.alive &&
+        second.entity.alive &&
+        first.entity.get(Collider) === first.collider &&
+        second.entity.get(Collider) === second.collider);
+}
+/** `onCollide(other)` on every component of `self`'s entity, when its interest names `other`'s layer. */
+function notify(self, other) {
+    if (!interestedIn(self, other))
+        return;
+    for (const component of [...self.entity.components])
+        component.onCollide?.(other.entity);
+}
+/**
+ * The 3D counterpart of the Hitbox trigger dispatch (CA-16): after the physics
+ * step, every overlap involving a sensor Collider fires `onCollide(other)` on
+ * the components of each side whose interest names the other's layer, every
+ * step while they overlap. Pairs are frozen first and each is re-checked live,
+ * like the 2D dispatch.
+ */
+export function dispatchSensorCollisions(game, world) {
+    if (!world.hasSensors)
+        return;
+    for (const pair of sensorPairs(game, world)) {
+        if (!stillOverlapping(pair))
+            continue;
+        const [first, second] = pair;
+        notify(first, second);
+        if (stillOverlapping(pair))
+            notify(second, first);
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { BodyRecord } from './body-sync.js';
+import type { PhysicsWorld } from './physics-world.js';
+/** A point or a direction in world space, as `game.query` takes and returns it. */
+export interface Point3d {
+    x: number;
+    y: number;
+    z: number;
+}
+/** A volume `game.query.area` tests sensor colliders against. */
+export type QueryVolume3d = {
+    shape: 'box';
+    center: Point3d;
+    size: Point3d;
+} | {
+    shape: 'sphere';
+    center: Point3d;
+    radius: number;
+};
+/** One collider a ray reaches: whose it is, how far, where and which way its surface faces. */
+export interface WorldRayHit {
+    record: BodyRecord;
+    distance: number;
+    point: Point3d;
+    normal: Point3d;
+}
+/**
+ * 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 declare function worldRayHits(world: PhysicsWorld, ray: {
+    origin: Point3d;
+    direction: Point3d;
+    maxDistance: number;
+}, accepts: (record: BodyRecord) => boolean): WorldRayHit[];
+/** Every record whose collider `accepts` and that intersects the volume. */
+export declare function recordsInVolume(world: PhysicsWorld, volume: QueryVolume3d, accepts: (record: BodyRecord) => boolean): BodyRecord[];
+/** Every record whose collider `accepts` and that contains the point. */
+export declare function recordsAtPoint(world: PhysicsWorld, at: Point3d, accepts: (record: BodyRecord) => boolean): BodyRecord[];

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;