@waica/engine 0.28.0 → 0.29.1

package/dist/input.d.ts

@@ -1,6 +1,7 @@
+import { type MouseInputOptions, type MouseMovement } from './input-mouse.js';
 export type ActionName = string;
 export type InjectedActionOperation = 'press' | 'hold' | 'release';
-/** Action → source codes: `KeyboardEvent.code` values and `Gamepad:<control>` codes (ADR 0023). */
+/** Action → source codes: `KeyboardEvent.code` values, `Gamepad:<control>` codes (ADR 0023) and `Mouse:Left`/`Mouse:Right`. */
 export type InputBindings = Record<string, string[]>;
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export declare const DEFAULT_BINDINGS: Readonly<InputBindings>;
@@ -15,14 +16,16 @@ export type InjectedValueCheck = {
  * takes a value, a finite number in (0, 1]; an absent value always passes.
  */
 export declare function checkInjectedValue(operation: InjectedActionOperation, value: unknown): InjectedValueCheck;
-export interface InputOptions {
+export interface InputOptions extends MouseInputOptions {
     /** Radial stick dead zone in [0, 1); absent or invalid means 0.2. */
     gamepadDeadZone?: number;
 }
 /**
- * Action-based input with archetype default bindings. Sources are keys and
- * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
- * max across its sources, and is held at 0.5 or above. Touch is still TODO.
+ * Action-based input with archetype default bindings. Sources are keys,
+ * player 1's standard gamepad (ADR 0023) and the mouse buttons on the game
+ * canvas; every Action has a 0..1 value, the max across its sources, and is
+ * held at 0.5 or above. The mouse also reports its locked movement and the
+ * wheel per Simulation Step (issue #181). Touch is still TODO.
  */
 export declare class Input {
     private readonly bindings;
@@ -40,6 +43,8 @@ export declare class Input {
     private readonly disarmed;
     /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
     private heldAtStepEnd;
+    /** Mouse buttons press `Mouse:` codes into the same sets keys use, so they behave exactly as keys. */
+    private readonly mouse;
     /** Installs exactly the action map supplied by the active archetype/project. */
     constructor(bindings?: Readonly<InputBindings>, options?: InputOptions);
     /** Is the action held this frame (some source at 0.5 or above)? */
@@ -84,6 +89,20 @@ export declare class Input {
      * before component updates.
      */
     pollGamepad(): void;
+    /** Freezes the mouse movement and wheel since the last step; the Game calls this beside pollGamepad(). */
+    pollMouse(): void;
+    /** The mouse movement of this Simulation Step while the pointer is locked to the canvas, in CSS px; zero between steps. */
+    mouseMovement(): MouseMovement;
+    /** The wheel delta of this Simulation Step over the canvas, in CSS px (positive scrolls down); zero between steps. */
+    wheelDelta(): number;
+    /** Adds a mouse movement to the next step as if the pointer were locked (the Runtime Bridge's `look`). */
+    injectLook(dx: number, dy: number): void;
+    /** Gives the pointer back if it is locked to the game canvas; a lock elsewhere is not the game's. */
+    releasePointerLock(): void;
+    /** Asks the browser to lock the pointer to the game canvas. */
+    requestPointerLock(): void;
+    /** Is the pointer locked to the game canvas? */
+    get pointerLocked(): boolean;
     /**
      * Marks this frame's press of the action as spent, so consumers that
      * honor consumption (state-machine 'input:' triggers) ignore it. One
@@ -102,5 +121,7 @@ export declare class Input {
     private releaseAll;
     private onVisibilityChange;
     private onKeyDown;
+    /** A key or mouse button went down. */
+    private press;
     private onKeyUp;
 }

package/dist/input.js

@@ -1,4 +1,5 @@
 import { ACTION_HELD_THRESHOLD, connectedGamepads, GAMEPAD_CODE_PREFIX, gamepadControl, gamepadValues, GamepadSlot, resolveGamepadDeadZone, } from './gamepad.js';
+import { isUnknownMouseCode, MouseInput } from './input-mouse.js';
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export const DEFAULT_BINDINGS = {};
 /**
@@ -16,9 +17,11 @@ export function checkInjectedValue(operation, value) {
     return { value };
 }
 /**
- * Action-based input with archetype default bindings. Sources are keys and
- * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
- * max across its sources, and is held at 0.5 or above. Touch is still TODO.
+ * Action-based input with archetype default bindings. Sources are keys,
+ * player 1's standard gamepad (ADR 0023) and the mouse buttons on the game
+ * canvas; every Action has a 0..1 value, the max across its sources, and is
+ * held at 0.5 or above. The mouse also reports its locked movement and the
+ * wheel per Simulation Step (issue #181). Touch is still TODO.
  */
 export class Input {
     bindings = new Map();
@@ -36,17 +39,25 @@ export class Input {
     disarmed = new Set();
     /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
     heldAtStepEnd = new Set();
+    /** Mouse buttons press `Mouse:` codes into the same sets keys use, so they behave exactly as keys. */
+    mouse;
     /** Installs exactly the action map supplied by the active archetype/project. */
     constructor(bindings = DEFAULT_BINDINGS, options = {}) {
         const warned = new Set();
         for (const [action, codes] of Object.entries(bindings)) {
             this.bindings.set(action, new Set(codes));
             for (const code of codes)
-                warnUnknownPadCode(code, warned);
+                warnUnknownCode(code, warned);
         }
         this.deadZone = resolveGamepadDeadZone(options.gamepadDeadZone, (message) => {
             console.warn(message);
         });
+        const keyLike = {
+            press: (code) => this.press(code),
+            release: (code) => this.down.delete(code),
+            binds: (code) => [...this.bindings.values()].some((codes) => codes.has(code)),
+        };
+        this.mouse = new MouseInput(keyLike, options);
         window.addEventListener('keydown', this.onKeyDown);
         window.addEventListener('keyup', this.onKeyUp);
         window.addEventListener('blur', this.releaseAll);
@@ -161,6 +172,34 @@ export class Input {
         }
         this.padValues = raw;
     }
+    /** Freezes the mouse movement and wheel since the last step; the Game calls this beside pollGamepad(). */
+    pollMouse() {
+        this.mouse.poll();
+    }
+    /** The mouse movement of this Simulation Step while the pointer is locked to the canvas, in CSS px; zero between steps. */
+    mouseMovement() {
+        return this.mouse.movement();
+    }
+    /** The wheel delta of this Simulation Step over the canvas, in CSS px (positive scrolls down); zero between steps. */
+    wheelDelta() {
+        return this.mouse.wheelDelta();
+    }
+    /** Adds a mouse movement to the next step as if the pointer were locked (the Runtime Bridge's `look`). */
+    injectLook(dx, dy) {
+        this.mouse.inject(dx, dy);
+    }
+    /** Gives the pointer back if it is locked to the game canvas; a lock elsewhere is not the game's. */
+    releasePointerLock() {
+        this.mouse.releaseLock();
+    }
+    /** Asks the browser to lock the pointer to the game canvas. */
+    requestPointerLock() {
+        this.mouse.requestLock();
+    }
+    /** Is the pointer locked to the game canvas? */
+    get pointerLocked() {
+        return this.mouse.locked;
+    }
     /**
      * Marks this frame's press of the action as spent, so consumers that
      * honor consumption (state-machine 'input:' triggers) ignore it. One
@@ -180,12 +219,14 @@ export class Input {
         this.injectedJustDown.clear();
         this.injectedPresses.clear();
         this.used.clear();
+        this.mouse.endStep();
         this.heldAtStepEnd = new Set(this.heldActions());
     }
     dispose() {
         this.injectedHolds.clear();
         this.injectedJustDown.clear();
         this.injectedPresses.clear();
+        this.mouse.dispose();
         window.removeEventListener('keydown', this.onKeyDown);
         window.removeEventListener('keyup', this.onKeyUp);
         window.removeEventListener('blur', this.releaseAll);
@@ -220,17 +261,24 @@ export class Input {
     onKeyDown = (e) => {
         if (e.repeat)
             return;
-        this.down.add(e.code);
-        this.justDown.add(e.code);
+        this.press(e.code);
     };
+    /** A key or mouse button went down. */
+    press(code) {
+        this.down.add(code);
+        this.justDown.add(code);
+    }
     onKeyUp = (e) => {
         this.down.delete(e.code);
     };
 }
-/** An unknown `Gamepad:` code never matches; it is reported once per code per Input. */
-function warnUnknownPadCode(code, warned) {
-    if (!code.startsWith(GAMEPAD_CODE_PREFIX) || warned.has(code) || gamepadControl(code))
+/** An unknown `Gamepad:` or `Mouse:` code never matches; it is reported once per code per Input. */
+function warnUnknownCode(code, warned) {
+    if (warned.has(code))
+        return;
+    const unknownPad = code.startsWith(GAMEPAD_CODE_PREFIX) && !gamepadControl(code);
+    if (!unknownPad && !isUnknownMouseCode(code))
         return;
     warned.add(code);
-    console.warn(`[waica] unknown gamepad binding "${code}": it never matches.`);
+    console.warn(`[waica] unknown ${unknownPad ? 'gamepad' : 'mouse'} binding "${code}": it never matches.`);
 }

package/dist/orbit-camera.d.ts

@@ -0,0 +1,68 @@
+import type * as THREE from 'three/webgpu';
+import type { Entity } from './entity.js';
+import type { Input } from './input.js';
+import type { ResolvedOrbit } from './scene-camera-orbit.js';
+/** How far in front of what blocks the view the camera stops, and how close to the look point it may come (CA-9). */
+export declare const ORBIT_COLLISION_MARGIN = 0.2;
+export declare const ORBIT_MIN_DISTANCE = 0.5;
+/** World units of distance per CSS pixel of wheel (one ~100 px notch is one unit). */
+export declare const ORBIT_WHEEL_ZOOM = 0.01;
+/** A point or direction in world space. */
+export interface OrbitPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+/** The ray from the look point toward the camera, which skips the followed entity's own colliders. */
+export interface OrbitRay {
+    origin: OrbitPoint;
+    direction: OrbitPoint;
+    maxDistance: number;
+    exclude: Entity;
+}
+/** What orbiting reads from the Game each Simulation Step. */
+export interface OrbitHost {
+    find(name: string): Entity | undefined;
+    input(): Input;
+    /** The distance to the first fixed collider along the ray (level geometry: sensors, characters and dynamic bodies never block it); null when nothing is hit. */
+    rayDistance(ray: OrbitRay): number | null;
+}
+/** The orbit's state as the Runtime Snapshot's `view` reports it (CA-10). */
+export interface OrbitView {
+    follow: string;
+    yaw: number;
+    pitch: number;
+    distance: number;
+    distanceActual: number;
+}
+/**
+ * A perspective camera orbiting a followed entity (issue #181, ADR 0031): the
+ * locked mouse, the orbit Actions and the wheel turn and zoom it once per
+ * Simulation Step, and a ray from the look point pulls it in front of a wall
+ * without changing the chosen distance. With no input the orbit holds.
+ */
+export declare class OrbitCamera {
+    readonly settings: ResolvedOrbit;
+    yaw: number;
+    pitch: number;
+    /** The chosen distance: the wheel's, clamped to [minDistance, maxDistance]. */
+    distance: number;
+    /** Where the camera actually sits: the chosen distance, or less in front of a wall. */
+    distanceActual: number;
+    constructor(settings: ResolvedOrbit);
+    /** One Simulation Step: turn and zoom by this step's input, then place `camera`. No followed entity: nothing moves, and false. */
+    step(camera: THREE.PerspectiveCamera, host: OrbitHost, dt: number): boolean;
+    /** Places `camera` on the orbit as it stands, with no input (a scene load); false, and nothing moves, with no followed entity. */
+    place(camera: THREE.PerspectiveCamera, host: OrbitHost): boolean;
+    /** The camera at the chosen distance from the look point, or in front of what the ray hits (CA-9). */
+    private placeAround;
+    /** The orbit for the Runtime Snapshot's view. */
+    view(): OrbitView;
+    /** The step's locked mouse movement times `sensitivity`, plus the orbit Actions at `orbitSpeed`; pitch clamped. */
+    private turn;
+    /** The orbit Actions as -1..1 turns: right minus left for yaw, down minus up for pitch. */
+    private actionTurn;
+    private lookPoint;
+    /** The unit direction from the look point to the camera: yaw 0 puts it on +z, yaw 90 on -x. */
+    private awayFromLook;
+}

package/dist/orbit-camera.js

@@ -0,0 +1,92 @@
+/** How far in front of what blocks the view the camera stops, and how close to the look point it may come (CA-9). */
+export const ORBIT_COLLISION_MARGIN = 0.2;
+export const ORBIT_MIN_DISTANCE = 0.5;
+/** World units of distance per CSS pixel of wheel (one ~100 px notch is one unit). */
+export const ORBIT_WHEEL_ZOOM = 0.01;
+const RAD = Math.PI / 180;
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/** A yaw in degrees wrapped to (-180, 180], so two equal views report the same number. */
+const wrapYaw = (degrees) => degrees - 360 * Math.ceil((degrees - 180) / 360);
+/**
+ * A perspective camera orbiting a followed entity (issue #181, ADR 0031): the
+ * locked mouse, the orbit Actions and the wheel turn and zoom it once per
+ * Simulation Step, and a ray from the look point pulls it in front of a wall
+ * without changing the chosen distance. With no input the orbit holds.
+ */
+export class OrbitCamera {
+    settings;
+    yaw;
+    pitch;
+    /** The chosen distance: the wheel's, clamped to [minDistance, maxDistance]. */
+    distance;
+    /** Where the camera actually sits: the chosen distance, or less in front of a wall. */
+    distanceActual;
+    constructor(settings) {
+        this.settings = settings;
+        this.yaw = wrapYaw(settings.yaw);
+        this.pitch = clamp(settings.pitch, settings.minPitch, settings.maxPitch);
+        this.distance = clamp(settings.distance, settings.minDistance, settings.maxDistance);
+        this.distanceActual = this.distance;
+    }
+    /** One Simulation Step: turn and zoom by this step's input, then place `camera`. No followed entity: nothing moves, and false. */
+    step(camera, host, dt) {
+        const followed = host.find(this.settings.follow);
+        if (!followed)
+            return false;
+        this.turn(host.input(), dt);
+        this.distance = clamp(this.distance + host.input().wheelDelta() * ORBIT_WHEEL_ZOOM, this.settings.minDistance, this.settings.maxDistance);
+        this.placeAround(camera, host, followed);
+        return true;
+    }
+    /** Places `camera` on the orbit as it stands, with no input (a scene load); false, and nothing moves, with no followed entity. */
+    place(camera, host) {
+        const followed = host.find(this.settings.follow);
+        if (!followed)
+            return false;
+        this.placeAround(camera, host, followed);
+        return true;
+    }
+    /** The camera at the chosen distance from the look point, or in front of what the ray hits (CA-9). */
+    placeAround(camera, host, followed) {
+        const look = this.lookPoint(followed);
+        const away = this.awayFromLook();
+        const hit = host.rayDistance({ origin: look, direction: away, maxDistance: this.distance, exclude: followed });
+        this.distanceActual =
+            hit === null ? this.distance : Math.min(this.distance, Math.max(hit - ORBIT_COLLISION_MARGIN, ORBIT_MIN_DISTANCE));
+        camera.position.set(look.x + away.x * this.distanceActual, look.y + away.y * this.distanceActual, look.z + away.z * this.distanceActual);
+        camera.lookAt(look.x, look.y, look.z);
+        camera.updateMatrixWorld();
+    }
+    /** The orbit for the Runtime Snapshot's view. */
+    view() {
+        const { yaw, pitch, distance, distanceActual } = this;
+        return { follow: this.settings.follow, yaw, pitch, distance, distanceActual };
+    }
+    /** The step's locked mouse movement times `sensitivity`, plus the orbit Actions at `orbitSpeed`; pitch clamped. */
+    turn(input, dt) {
+        const { sensitivity, orbitSpeed, invertY, minPitch, maxPitch } = this.settings;
+        const mouse = input.mouseMovement();
+        const actions = this.actionTurn(input);
+        this.yaw = wrapYaw(this.yaw + mouse.x * sensitivity + actions.yaw * orbitSpeed * dt);
+        const mousePitch = (invertY ? -mouse.y : mouse.y) * sensitivity;
+        this.pitch = clamp(this.pitch + mousePitch + actions.pitch * orbitSpeed * dt, minPitch, maxPitch);
+    }
+    /** The orbit Actions as -1..1 turns: right minus left for yaw, down minus up for pitch. */
+    actionTurn(input) {
+        const { orbitLeftAction, orbitRightAction, orbitUpAction, orbitDownAction } = this.settings;
+        return {
+            yaw: input.value(orbitRightAction) - input.value(orbitLeftAction),
+            pitch: input.value(orbitDownAction) - input.value(orbitUpAction),
+        };
+    }
+    lookPoint(followed) {
+        const { x, y, z } = followed.position;
+        return { x, y: y + this.settings.lookHeight, z };
+    }
+    /** The unit direction from the look point to the camera: yaw 0 puts it on +z, yaw 90 on -x. */
+    awayFromLook() {
+        const yaw = this.yaw * RAD;
+        const pitch = this.pitch * RAD;
+        return { x: -Math.sin(yaw) * Math.cos(pitch), y: Math.sin(pitch), z: Math.cos(yaw) * Math.cos(pitch) };
+    }
+}

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

@@ -6,15 +6,24 @@ export interface Point3d {
     y: number;
     z: number;
 }
-/** A volume `game.query.area` tests sensor colliders against. */
+/**
+ * Which colliders `game.query.area` reads: the sensors (the default, ADR
+ * 0015's trigger domain) or every collider, solid ones included — what a
+ * melee strike hits (issue #181).
+ */
+export type QueryColliders3d = 'sensors' | 'all';
+/** A volume `game.query.area` tests colliders against; a box may turn by `yaw` degrees about +y. */
 export type QueryVolume3d = {
     shape: 'box';
     center: Point3d;
     size: Point3d;
+    yaw?: number;
+    colliders?: QueryColliders3d;
 } | {
     shape: 'sphere';
     center: Point3d;
     radius: number;
+    colliders?: QueryColliders3d;
 };
 /** One collider a ray reaches: whose it is, how far, where and which way its surface faces. */
 export interface WorldRayHit {

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

@@ -1,4 +1,8 @@
-const IDENTITY = { x: 0, y: 0, z: 0, w: 1 };
+/** The rotation of a box turned `yaw` degrees about +y (none for a sphere or an unturned box). */
+function rotationOf(volume) {
+    const half = volume.shape === 'box' ? ((volume.yaw ?? 0) * Math.PI) / 360 : 0;
+    return { x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) };
+}
 /**
  * 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
@@ -42,7 +46,7 @@ export function recordsInVolume(world, volume, accepts) {
         ? 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) => {
+    raw.intersectionsWithShape(volume.center, rotationOf(volume), shape, (collider) => {
         const record = world.recordOfCollider(collider.handle);
         if (record)
             found.push(record);

package/dist/runtime-bridge.d.ts

@@ -25,9 +25,10 @@ export type RuntimeMode = 'paused' | 'real-time';
  * 0025) announces that every metadata carries `backend`: the Render Backend
  * once the renderer is ready, null before — a Run Session waits for it — and
  * that a renderer that fails to initialize reports through the activation's
- * `fail`.
+ * `fail`. `look` (issue #181) announces the `look` operation: a mouse delta
+ * the next Simulation Step reads as locked mouse movement.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions', 'render-backend'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions', 'render-backend', 'look'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -63,6 +64,12 @@ export type RuntimeControlRequest = {
 } | {
     operation: 'scene';
     scene: string;
+}
+/** Adds `dx`, `dy` CSS px of mouse movement to the next Simulation Step, as if the pointer were locked. */
+ | {
+    operation: 'look';
+    dx: number;
+    dy: number;
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
@@ -108,6 +115,8 @@ export interface RuntimeBridgeHost {
     resume(onStep: () => void): void;
     pause(): void;
     injectAction(action: string, operation: 'press' | 'hold' | 'release', value?: number): boolean;
+    /** Adds a mouse movement to the next Simulation Step, as if the pointer were locked. */
+    look(dx: number, dy: number): void;
     availableActions(): string[];
     heldActions(): string[];
     actionValues(): Record<string, number>;
@@ -137,6 +146,7 @@ export declare class EngineRuntimeBridge implements RuntimeBridge {
     private injectAction;
     /** Advances whole Simulation Steps while paused. */
     private step;
+    private look;
     private loadScene;
     /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
     private advance;

package/dist/runtime-bridge.js

@@ -24,7 +24,8 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * 0025) announces that every metadata carries `backend`: the Render Backend
  * once the renderer is ready, null before — a Run Session waits for it — and
  * that a renderer that fails to initialize reports through the activation's
- * `fail`.
+ * `fail`. `look` (issue #181) announces the `look` operation: a mouse delta
+ * the next Simulation Step reads as locked mouse movement.
  */
 export const RUNTIME_BRIDGE_CAPABILITIES = [
     'click',
@@ -34,6 +35,7 @@ export const RUNTIME_BRIDGE_CAPABILITIES = [
     'camera-effects',
     'analog-actions',
     'render-backend',
+    'look',
 ];
 export class RuntimeBridgeOperationError extends Error {
     code;
@@ -122,6 +124,9 @@ export class EngineRuntimeBridge {
             case 'scene':
                 this.loadScene(request.scene);
                 break;
+            case 'look':
+                this.look(request);
+                break;
             default: {
                 const unsupported = request;
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
@@ -160,6 +165,12 @@ export class EngineRuntimeBridge {
             this.host.step(() => this.advance());
         }
     }
+    look(request) {
+        if (!Number.isFinite(request.dx) || !Number.isFinite(request.dy)) {
+            throw new RuntimeBridgeOperationError('runtime-operation-failed', 'dx and dy must be finite numbers.');
+        }
+        this.host.look(request.dx, request.dy);
+    }
     loadScene(scene) {
         if (this.host.loadScene(scene))
             return;

package/dist/runtime-inspection.js

@@ -1,4 +1,4 @@
-import { cameraEffectsSnapshot, viewSnapshot } from './runtime-view-snapshot.js';
+import { 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';
@@ -295,7 +295,8 @@ export class RuntimeInspector {
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
-            camera: cameraEffectsSnapshot(this.game),
+            // The shake offset applies in both spaces since a perspective camera shakes too (issue #181 CA-11).
+            camera: this.game.cameraEffects.state,
             space: this.game.space,
             view: viewSnapshot(this.game),
             lighting: lightingSnapshot(this.game, (entity) => this.idFor(entity)),

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

@@ -1,5 +1,5 @@
-import type { CameraEffectsState } from './camera-effects.js';
 import type { Game } from './game.js';
+import type { OrbitView } from './orbit-camera.js';
 import type { Vec3Json } from './scene-camera-3d.js';
 /**
  * The view the scene is drawn from (issue #154 CA-16), beside the Camera
@@ -10,16 +10,13 @@ export type RuntimeSnapshotView = {
     kind: 'orthographic';
     position: [number, number];
     zoom: number;
-} | {
+} | PerspectiveView | (PerspectiveView & OrbitView);
+/** A perspective camera's pose; a following one adds its whole orbit (issue #181 CA-10), so `'follow' in view` narrows to it. */
+type PerspectiveView = {
     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;
+export {};

package/dist/runtime-view-snapshot.js

@@ -13,19 +13,22 @@ export function viewSnapshot(game) {
     }
     camera.updateMatrixWorld();
     const ahead = camera.getWorldDirection(new THREE.Vector3()).multiplyScalar(game.cameraRig.lookDistance);
-    return {
+    const pose = {
         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;
+    const orbit = game.cameraRig.orbitView;
+    if (!orbit)
+        return pose;
+    // A following camera's orbit (issue #181 CA-10): the chosen distance and the placed one.
+    return {
+        ...pose,
+        follow: orbit.follow,
+        yaw: clean(orbit.yaw),
+        pitch: clean(orbit.pitch),
+        distance: clean(orbit.distance),
+        distanceActual: clean(orbit.distanceActual),
+    };
 }

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

@@ -1,11 +1,15 @@
 import type * as THREE from 'three/webgpu';
+import { type OrbitCameraJson, type ResolvedOrbit } from './scene-camera-orbit.js';
+import { type SceneFieldIssue } from './scene-field-issues.js';
 /** 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`.
+ * A scene's perspective camera (3D scenes, ADR 0027). Without `follow` it is
+ * fixed by the scene and game code may move it: Y is up and the camera looks
+ * from `position` at `target`. With `follow` it orbits that entity once per
+ * Simulation Step (issue #181, ADR 0031; the orbit fields are OrbitCameraJson's).
  */
-export interface PerspectiveSceneCameraJson {
+export interface PerspectiveSceneCameraJson extends OrbitCameraJson {
     kind: 'perspective';
     /** Where the camera sits. Default `[0, 5, 10]`. */
     position?: Vec3Json;
@@ -18,7 +22,6 @@ export interface PerspectiveSceneCameraJson {
     /** Far clipping plane, above `near`. Default 1000. */
     far?: number;
     zoom?: never;
-    follow?: never;
     deadzoneWidth?: never;
     deadzoneHeight?: never;
     lookahead?: never;
@@ -33,6 +36,8 @@ export interface ResolvedPerspectiveCamera {
     fov: number;
     near: number;
     far: number;
+    /** The orbit around `follow`; absent for a fixed camera. */
+    orbit?: ResolvedOrbit;
 }
 export declare const PERSPECTIVE_DEFAULTS: {
     readonly position: Vec3Json;
@@ -49,18 +54,12 @@ export declare function isPerspectiveCameraJson(json: {
 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;
+export { isFiniteNumber, shown, type SceneFieldIssue } from './scene-field-issues.js';
 /**
  * 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.
+ * (0, 180), `near` above 0, `far` above `near`, `position` and `target`
+ * three finite numbers, the orbit fields (orbitCameraIssues), and none of the
+ * orthographic block's other fields. Anything that is not a perspective block
+ * reports none.
  */
 export declare function perspectiveCameraIssues(camera: unknown): SceneFieldIssue[];