@waica/engine 0.27.0 → 0.29.0

package/dist/pointer-raycast.js

@@ -16,33 +16,63 @@ function modelRoots(entities) {
     }
     return roots;
 }
-/** The entity whose Model root `object` hangs under. */
-function ownerOf(object, roots) {
+/** What `object` picks: the target or Model root it hangs under, nearest first. */
+function ownerOf(object, owners) {
     for (let node = object; node; node = node.parent) {
-        const entity = roots.get(node);
-        if (entity)
-            return entity;
+        const owner = owners.get(node);
+        if (owner)
+            return owner;
     }
     return null;
 }
+/** Whether `target` is drawn and still picks something: itself and every ancestor visible, and its entity alive. */
+function isPickable(target) {
+    if (target.entity !== 'camera' && !target.entity.alive)
+        return false;
+    for (let node = target.object; node; node = node.parent) {
+        if (!node.visible)
+            return false;
+    }
+    return true;
+}
+/** The extra targets' hits: tested whatever their layers, since an editor overlay lives on the Emissive layer alone. */
+function extraHits(targets) {
+    if (targets.length === 0)
+        return [];
+    const own = raycaster.layers.mask;
+    raycaster.layers.enableAll();
+    try {
+        return raycaster.intersectObjects(targets.filter(isPickable).map((target) => target.object), true);
+    }
+    finally {
+        raycaster.layers.mask = own;
+    }
+}
 /**
  * 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.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). 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) {
+// eslint-disable-next-line max-params -- the signature spec #173 fixes: the Pointer's three inputs plus the optional extra targets; bundling them would be an unrelated bag
+export function raycastPick(camera, at, entities, extra = []) {
     camera.updateMatrixWorld();
     raycaster.setFromCamera(new THREE.Vector2(at.nx * 2 - 1, 1 - at.ny * 2), camera);
     const roots = modelRoots(entities);
+    const owners = new Map(roots);
+    for (const target of extra)
+        owners.set(target.object, target.entity);
     // 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);
+    for (const object of owners.keys())
+        object.updateWorldMatrix(true, true);
+    const [hit] = [...raycaster.intersectObjects([...roots.keys()], true), ...extraHits(extra)].sort((a, b) => a.distance - b.distance);
     if (hit)
-        return { entity: ownerOf(hit.object, roots), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
+        return { entity: ownerOf(hit.object, owners), 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/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

@@ -6,25 +6,29 @@ function vector(value) {
     return [clean(value.x), clean(value.y), clean(value.z)];
 }
 export function viewSnapshot(game) {
-    const camera = game.camera;
+    // The scene's own camera: a host's view camera is not part of the simulated game, and `lookDistance` is the scene camera's.
+    const camera = game.cameraRig.sceneCamera;
     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 {
+    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[];

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

@@ -1,3 +1,5 @@
+import { orbitCameraIssues, resolveOrbit } from './scene-camera-orbit.js';
+import { isFiniteNumber, shown } from './scene-field-issues.js';
 export const PERSPECTIVE_DEFAULTS = {
     position: [0, 5, 10],
     target: [0, 0, 0],
@@ -18,8 +20,13 @@ export function resolvePerspectiveCamera(json = { kind: 'perspective' }) {
         fov: json.fov ?? PERSPECTIVE_DEFAULTS.fov,
         near: json.near ?? PERSPECTIVE_DEFAULTS.near,
         far: json.far ?? PERSPECTIVE_DEFAULTS.far,
+        ...orbitOf(json),
     };
 }
+function orbitOf(json) {
+    const orbit = resolveOrbit(json);
+    return orbit ? { orbit } : {};
+}
 /** Points `camera` as the resolved block says, at the given aspect ratio. */
 export function placePerspectiveCamera(camera, resolved, aspect) {
     camera.fov = resolved.fov;
@@ -31,11 +38,7 @@ export function placePerspectiveCamera(camera, resolved, aspect) {
     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);
-}
+export { isFiniteNumber, shown } from './scene-field-issues.js';
 function vectorIssue(field, value, issues) {
     if (value === undefined)
         return;
@@ -76,9 +79,8 @@ function planeIssues(near, far, issues) {
         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. */
+/** The orthographic block's fields, which a perspective block does not accept (`follow` it does, issue #181). */
 const ORTHOGRAPHIC_ONLY_FIELDS = [
-    'follow',
     'zoom',
     'deadzoneWidth',
     'deadzoneHeight',
@@ -96,9 +98,10 @@ function orthographicFieldIssues(block, issues) {
 }
 /**
  * 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 function perspectiveCameraIssues(camera) {
     if (typeof camera !== 'object' || camera === null)
@@ -113,5 +116,6 @@ export function perspectiveCameraIssues(camera) {
     aimIssue(block, issues);
     planeIssues(block.near, block.far, issues);
     orthographicFieldIssues(block, issues);
+    issues.push(...orbitCameraIssues(block));
     return issues;
 }

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

@@ -0,0 +1,72 @@
+import { type SceneFieldIssue } from './scene-field-issues.js';
+/**
+ * The orbit fields of a scene's perspective camera block (issue #181, ADR
+ * 0031): with `follow`, the camera orbits that entity instead of staying
+ * where `position` and `target` put it. Angles are degrees; `yaw` 0 looks
+ * toward -z (the camera sits on +z), 90 toward +x; `pitch` is the camera's
+ * height above the look point, positive looking down.
+ */
+export interface OrbitCameraJson {
+    /** The entity to orbit; absent or empty keeps the camera fixed. */
+    follow?: string;
+    /** The chosen distance from the look point. Default 6. */
+    distance?: number;
+    /** The wheel's closest distance. Default 2. */
+    minDistance?: number;
+    /** The wheel's farthest distance. Default 12. */
+    maxDistance?: number;
+    /** Initial yaw, in degrees. Default 0. */
+    yaw?: number;
+    /** Initial pitch, in degrees, in (-89, 89). Default 20. */
+    pitch?: number;
+    /** Lowest pitch, in (-89, 89). Default -10. */
+    minPitch?: number;
+    /** Highest pitch, in (-89, 89). Default 70. */
+    maxPitch?: number;
+    /** How far above the followed entity's position the camera looks. Default 1.2. */
+    lookHeight?: number;
+    /** Degrees of orbit per CSS pixel of locked mouse movement. Default 0.2. */
+    sensitivity?: number;
+    /** Degrees per second the orbit Actions turn at full value. Default 120. */
+    orbitSpeed?: number;
+    /** Flips the mouse's vertical orbit. Default false. */
+    invertY?: boolean;
+    /** The Action that orbits left (yaw down). Default `look_left`. */
+    orbitLeftAction?: string;
+    /** The Action that orbits right (yaw up). Default `look_right`. */
+    orbitRightAction?: string;
+    /** The Action that looks up (pitch down). Default `look_up`. */
+    orbitUpAction?: string;
+    /** The Action that looks down (pitch up). Default `look_down`. */
+    orbitDownAction?: string;
+}
+/** Every orbit field resolved; `follow` names the entity. */
+export type ResolvedOrbit = Required<OrbitCameraJson>;
+export declare const ORBIT_DEFAULTS: {
+    readonly distance: 6;
+    readonly minDistance: 2;
+    readonly maxDistance: 12;
+    readonly yaw: 0;
+    readonly pitch: 20;
+    readonly minPitch: -10;
+    readonly maxPitch: 70;
+    readonly lookHeight: 1.2;
+    readonly sensitivity: 0.2;
+    readonly orbitSpeed: 120;
+    readonly invertY: false;
+    readonly orbitLeftAction: 'look_left';
+    readonly orbitRightAction: 'look_right';
+    readonly orbitUpAction: 'look_up';
+    readonly orbitDownAction: 'look_down';
+};
+/** The orbit a block declares with its defaults filled, or null for a fixed camera (no `follow`). */
+export declare function resolveOrbit(json: OrbitCameraJson): ResolvedOrbit | null;
+/**
+ * Every orbit field of a perspective block outside its range: the numbers
+ * (distances above 0, pitches in (-89, 89), speeds at least 0), `invertY`,
+ * the Action names, and a `minDistance` or `minPitch` above its maximum
+ * (errors); and a following camera's initial `distance` or `pitch` outside
+ * its own range (warnings). Whether `follow` names an entity of the scene is
+ * the scene validator's.
+ */
+export declare function orbitCameraIssues(block: Record<string, unknown>): SceneFieldIssue[];

package/dist/scene-camera-orbit.js

@@ -0,0 +1,155 @@
+import { isFiniteNumber, shown } from './scene-field-issues.js';
+const ACTION_FIELDS = ['orbitLeftAction', 'orbitRightAction', 'orbitUpAction', 'orbitDownAction'];
+export const ORBIT_DEFAULTS = {
+    distance: 6,
+    minDistance: 2,
+    maxDistance: 12,
+    yaw: 0,
+    pitch: 20,
+    minPitch: -10,
+    maxPitch: 70,
+    lookHeight: 1.2,
+    sensitivity: 0.2,
+    orbitSpeed: 120,
+    invertY: false,
+    orbitLeftAction: 'look_left',
+    orbitRightAction: 'look_right',
+    orbitUpAction: 'look_up',
+    orbitDownAction: 'look_down',
+};
+/** The orbit a block declares with its defaults filled, or null for a fixed camera (no `follow`). */
+export function resolveOrbit(json) {
+    if (!json.follow)
+        return null;
+    return { follow: json.follow, ...resolveFraming(json), ...resolveControls(json) };
+}
+/** Where the camera sits: distances, angles and the look height. */
+function resolveFraming(json) {
+    return {
+        distance: json.distance ?? ORBIT_DEFAULTS.distance,
+        minDistance: json.minDistance ?? ORBIT_DEFAULTS.minDistance,
+        maxDistance: json.maxDistance ?? ORBIT_DEFAULTS.maxDistance,
+        yaw: json.yaw ?? ORBIT_DEFAULTS.yaw,
+        pitch: json.pitch ?? ORBIT_DEFAULTS.pitch,
+        minPitch: json.minPitch ?? ORBIT_DEFAULTS.minPitch,
+        maxPitch: json.maxPitch ?? ORBIT_DEFAULTS.maxPitch,
+        lookHeight: json.lookHeight ?? ORBIT_DEFAULTS.lookHeight,
+    };
+}
+/** How input turns it: the mouse, the orbit Actions and their speed. */
+function resolveControls(json) {
+    return {
+        sensitivity: json.sensitivity ?? ORBIT_DEFAULTS.sensitivity,
+        orbitSpeed: json.orbitSpeed ?? ORBIT_DEFAULTS.orbitSpeed,
+        invertY: json.invertY ?? ORBIT_DEFAULTS.invertY,
+        orbitLeftAction: json.orbitLeftAction ?? ORBIT_DEFAULTS.orbitLeftAction,
+        orbitRightAction: json.orbitRightAction ?? ORBIT_DEFAULTS.orbitRightAction,
+        orbitUpAction: json.orbitUpAction ?? ORBIT_DEFAULTS.orbitUpAction,
+        orbitDownAction: json.orbitDownAction ?? ORBIT_DEFAULTS.orbitDownAction,
+    };
+}
+/** The rule each numeric orbit field must meet, and how its message says it. */
+const NUMBER_RULES = [
+    { field: 'distance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'minDistance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'maxDistance', accepts: (value) => value > 0, rule: 'a number above 0' },
+    { field: 'yaw', accepts: () => true, rule: 'a finite number' },
+    { field: 'pitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'minPitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'maxPitch', accepts: (value) => Math.abs(value) < 89, rule: 'a number above -89 and below 89' },
+    { field: 'lookHeight', accepts: () => true, rule: 'a finite number' },
+    { field: 'sensitivity', accepts: (value) => value >= 0, rule: 'a number of at least 0' },
+    { field: 'orbitSpeed', accepts: (value) => value >= 0, rule: 'a number of at least 0' },
+];
+function numberIssues(block, issues) {
+    for (const { field, accepts, rule } of NUMBER_RULES) {
+        const value = block[field];
+        if (value === undefined || (isFiniteNumber(value) && accepts(value)))
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} must be ${rule}; got ${shown(value)}.` });
+    }
+}
+function actionIssues(block, issues) {
+    for (const field of ACTION_FIELDS) {
+        const value = block[field];
+        if (value === undefined || (typeof value === 'string' && value.length > 0))
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} must be an Action name; got ${shown(value)}.` });
+    }
+}
+function fieldIssues(block, issues) {
+    if (block.follow !== undefined && typeof block.follow !== 'string') {
+        issues.push({ field: 'camera.follow', message: `camera.follow must be an entity name; got ${shown(block.follow)}.` });
+    }
+    numberIssues(block, issues);
+    if (block.invertY !== undefined && typeof block.invertY !== 'boolean') {
+        issues.push({ field: 'camera.invertY', message: `camera.invertY must be true or false; got ${shown(block.invertY)}.` });
+    }
+    actionIssues(block, issues);
+}
+function rangeIssue(block, [low, high], issues) {
+    const min = block[low];
+    const max = block[high];
+    const fallback = ORBIT_DEFAULTS;
+    const lowValue = min ?? fallback[low];
+    const highValue = max ?? fallback[high];
+    if (!isFiniteNumber(lowValue) || !isFiniteNumber(highValue) || lowValue <= highValue)
+        return;
+    issues.push({
+        field: `camera.${low}`,
+        message: `camera.${low} (${lowValue}) must not exceed camera.${high} (${highValue}).`,
+    });
+}
+/** A declared value or its default, when it is a number its rule accepts (else the field is already an error). */
+function numberOr(block, field) {
+    const fallback = ORBIT_DEFAULTS;
+    const value = block[field] ?? fallback[field];
+    const rule = NUMBER_RULES.find((entry) => entry.field === field);
+    return isFiniteNumber(value) && (rule?.accepts(value) ?? true) ? value : null;
+}
+/** The range each initial orbit number starts inside. */
+const START_RANGES = {
+    distance: ['minDistance', 'maxDistance'],
+    pitch: ['minPitch', 'maxPitch'],
+};
+/**
+ * A following camera's declared initial `distance` or `pitch` outside its
+ * valid range [low, high]: the camera clamps it, so it starts elsewhere than
+ * the scene says, a warning (issue #181, maintainer decision). An invalid
+ * value or an inverted range is already an error and is not repeated.
+ */
+function startIssue(block, field) {
+    const [low, high] = START_RANGES[field];
+    const value = block[field] === undefined ? null : numberOr(block, field);
+    const min = numberOr(block, low);
+    const max = numberOr(block, high);
+    if (!block.follow || value === null || min === null || max === null || min > max)
+        return null;
+    if (value >= min && value <= max)
+        return null;
+    return {
+        field: `camera.${field}`,
+        message: `camera.${field} (${value}) is outside [camera.${low} (${min}), camera.${high} (${max})]; the camera starts at ${Math.min(Math.max(value, min), max)}.`,
+        severity: 'warning',
+    };
+}
+/**
+ * Every orbit field of a perspective block outside its range: the numbers
+ * (distances above 0, pitches in (-89, 89), speeds at least 0), `invertY`,
+ * the Action names, and a `minDistance` or `minPitch` above its maximum
+ * (errors); and a following camera's initial `distance` or `pitch` outside
+ * its own range (warnings). Whether `follow` names an entity of the scene is
+ * the scene validator's.
+ */
+export function orbitCameraIssues(block) {
+    const issues = [];
+    fieldIssues(block, issues);
+    rangeIssue(block, ['minDistance', 'maxDistance'], issues);
+    rangeIssue(block, ['minPitch', 'maxPitch'], issues);
+    for (const field of ['distance', 'pitch']) {
+        const start = startIssue(block, field);
+        if (start)
+            issues.push(start);
+    }
+    return issues;
+}

package/dist/scene-field-issues.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the scene validators share (the camera, orbit, render and simulation
+ * blocks): the issue they report and how a message quotes a JSON value. A
+ * leaf module, so the orbit fields can use them without importing the
+ * perspective camera that imports them.
+ */
+/** One field of a scene's render, camera or entity transform that is invalid, for validate_project: an error unless it is a `'warning'`. */
+export interface SceneFieldIssue {
+    field: string;
+    message: string;
+    /** A field the runtime accepts as written but adjusts (a clamp): reported as a warning. */
+    severity?: 'warning';
+}
+/** 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;

package/dist/scene-field-issues.js

@@ -0,0 +1,11 @@
+/**
+ * What the scene validators share (the camera, orbit, render and simulation
+ * blocks): the issue they report and how a message quotes a JSON value. A
+ * leaf module, so the orbit fields can use them without importing the
+ * perspective camera that imports them.
+ */
+/** 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);
+}

package/dist/scene.js

@@ -133,14 +133,16 @@ export function loadScene(game, scene, registry) {
     game.registry = registry;
     game.setSceneRender(scene.render);
     game.setSceneSimulation(scene.simulation);
-    // A perspective camera has no follow target to wait for: components see it from their first onReady.
+    // A perspective camera is adopted first, so components see it from their first onReady.
     const adoptsBeforeSpawns = game.space === '3d';
     if (adoptsBeforeSpawns)
         game.setSceneCamera(scene.camera);
     for (const entityJson of scene.entities)
         spawnFromJson(game, entityJson, registry);
-    // After the spawns: with a follow target, the orthographic camera starts centered on it.
-    if (!adoptsBeforeSpawns)
+    // After the spawns, with a follow target: the orthographic camera starts centered on it, an orbit camera on its orbit.
+    if (adoptsBeforeSpawns)
+        game.placeSceneCamera();
+    else
         game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);