@waica/engine 0.25.0 → 0.27.0

package/dist/components/sun.d.ts

@@ -0,0 +1,46 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+/**
+ * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
+ * that shines along `direction`, in world space — where its entity stands, or
+ * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * in a 2D scene creates nothing. The three light lives in the Game's scene,
+ * moves with its props, and leaves with the entity.
+ */
+export declare class Sun extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        direction: {
+            label: string;
+            kind: "vector3";
+        };
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light: THREE.DirectionalLight | null;
+    private _direction;
+    private _color;
+    private _intensity;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction(): Vec3Json;
+    set direction(value: Vec3Json);
+    get color(): number;
+    set color(value: number);
+    get intensity(): number;
+    set intensity(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    private aim;
+}

package/dist/components/sun.js

@@ -0,0 +1,74 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.js';
+const DEFAULT_DIRECTION = [-1, -2, -1];
+/** Scene JSON is untyped at runtime: only an array of three finite numbers, not all zero, aims a light. */
+const finiteDirection = (value) => Array.isArray(value) && value.length === 3 && value.every(Number.isFinite) && value.some((component) => component !== 0);
+/**
+ * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
+ * that shines along `direction`, in world space — where its entity stands, or
+ * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * in a 2D scene creates nothing. The three light lives in the Game's scene,
+ * moves with its props, and leaves with the entity.
+ */
+export class Sun extends Component {
+    static componentName = 'Sun';
+    static space = '3d';
+    static params = {
+        direction: { label: 'Direction', kind: 'vector3' },
+        color: { label: 'Color', kind: 'color' },
+        intensity: { label: 'Intensity', min: 0, step: 0.1 },
+    };
+    static transient = ['light'];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light = null;
+    _direction = [...DEFAULT_DIRECTION];
+    _color = 0xffffff;
+    _intensity = 1;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction() {
+        return [...this._direction];
+    }
+    set direction(value) {
+        // A zero or unreadable direction keeps the last good one: there is nothing to aim along.
+        if (!finiteDirection(value))
+            return;
+        this._direction = [...value];
+        this.aim();
+    }
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.light?.color.setHex(value);
+    }
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._intensity = value;
+        if (this.light)
+            this.light.intensity = value;
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        const light = new THREE.DirectionalLight(this._color, this._intensity);
+        this.light = light;
+        // The target joins the scene too, or three never updates its world matrix.
+        this.game.scene.add(light, light.target);
+        this.aim();
+    }
+    onDestroy() {
+        this.light?.removeFromParent();
+        this.light?.target.removeFromParent();
+    }
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    aim() {
+        if (!this.light)
+            return;
+        const [x, y, z] = this._direction;
+        this.light.position.set(-x, -y, -z).normalize();
+        this.light.target.position.set(0, 0, 0);
+    }
+}

package/dist/components/tilemap.d.ts

@@ -1,10 +1,11 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { SOLID_SOURCE_SYMBOL, type SolidSource } from '../scene-solids.js';
 import { type TilemapCell, type TilemapCellBounds } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export declare class Tilemap extends Component implements SolidSource {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         color: {
             label: string;

package/dist/components/tilemap.js

@@ -11,6 +11,7 @@ import { TRANSPARENT_TEXEL_ALPHA } from '../render-layers.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
+    static space = '2d';
     static params = {
         color: { label: 'color' },
         cols: { label: 'tileset columns', min: 1, step: 1 },

package/dist/entity-transform.d.ts

@@ -0,0 +1,18 @@
+import type { Entity } from './entity.js';
+/** A scene entity's position: `[x, y]` (z is 0) or `[x, y, z]`. */
+export type PositionJson = [number, number] | [number, number, number];
+/** The transform a scene or prefab entity declares, applied when it spawns. */
+export interface TransformJson {
+    /** `[x, y]` (z = 0) or `[x, y, z]`; in a 3D scene z is a world axis. */
+    position?: PositionJson;
+    /** Euler angles in degrees, order XYZ, applied to the entity's node (3D scenes). */
+    rotation?: [number, number, number];
+    /** Per-axis scale of the entity's node. */
+    scale?: [number, number, number];
+}
+/**
+ * Applies a declared transform to a freshly spawned entity. A two-number
+ * position behaves exactly as it always did (z = 0); `rotation` is converted
+ * from degrees and `scale` replaces the node's unit scale.
+ */
+export declare function applyTransformJson(entity: Entity, json: TransformJson): void;

package/dist/entity-transform.js

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+/**
+ * Applies a declared transform to a freshly spawned entity. A two-number
+ * position behaves exactly as it always did (z = 0); `rotation` is converted
+ * from degrees and `scale` replaces the node's unit scale.
+ */
+export function applyTransformJson(entity, json) {
+    const { position, rotation, scale } = json;
+    if (position)
+        entity.position.set(position[0], position[1], position[2] ?? 0);
+    if (rotation) {
+        const [x, y, z] = rotation;
+        entity.node.rotation.set(THREE.MathUtils.degToRad(x), THREE.MathUtils.degToRad(y), THREE.MathUtils.degToRad(z), 'XYZ');
+    }
+    if (scale)
+        entity.node.scale.set(scale[0], scale[1], scale[2]);
+}

package/dist/game.d.ts

@@ -1,19 +1,27 @@
 import * as THREE from 'three/webgpu';
 import { AssetLoader } from './assets/asset-loader.js';
+import type { ModelBackend } from './assets/model-backend.js';
 import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { type SceneCameraJson } from './camera.js';
+import type { SceneCameraJson } from './camera.js';
+import { type GameCamera, type WorldPoint } from './camera-projection.js';
+import { CameraRig } from './camera-rig.js';
 import { CameraEffects } from './camera-effects.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
+import type { PositionJson } from './entity-transform.js';
 import { Emitter } from './events.js';
 import { GameTime } from './game-time.js';
 import { Input, type InputBindings } from './input.js';
+import { PhysicsHost } from './physics-3d/physics-host.js';
+import type { PhysicsBackend } from './physics-3d/rapier-module.js';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { type RenderBackend } from './render-readiness.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { type SceneSimulationJson } from './scene-simulation.js';
+import { type SceneSpace } from './scene-space.js';
 import { GameLighting } from './scene-lighting.js';
 import { type SpatialQuery } from './spatial-query.js';
 import { Stats, type StatValue } from './stats.js';
@@ -33,7 +41,7 @@ export interface GameOptions {
     /** Fixed resolution (from the project's game.json); absent = fill the canvas. */
     resolution?: GameResolution;
     /** Control overrides (action → key and `Gamepad:` codes) on top of the defaults. */
-    bindings?: InputBindings;
+    bindings?: Readonly<InputBindings>;
     /** Radial stick dead zone of `game.input`, in [0, 1); absent or invalid means 0.2 (ADR 0023). */
     gamepadDeadZone?: number;
     /** Initial stat values (points, lives…) from the project's stats.json. */
@@ -53,11 +61,20 @@ export interface GameOptions {
      * the real backend either way; `game.assets` always exists.
      */
     textures?: TextureBackend;
+    /** Replaces the real `GLTFLoader` implementation behind `game.assets.model` (the same seam, for glTF). */
+    models?: ModelBackend;
+    /**
+     * Where Rapier comes from for a 3D scene (ADR 0013's seam, applied to
+     * physics): resolves to the initialized module. Defaults to the real
+     * dynamic import, which only a 3D scene triggers; a project's own tests
+     * pass the module they initialized once, or a rejecting stub.
+     */
+    physics?: PhysicsBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
     name?: string;
-    position?: [number, number];
+    position?: PositionJson;
 }
 /** The Project's scenes by name (a file's stem), plus the registry shared by all of them. */
 export interface SceneCatalog {
@@ -72,7 +89,6 @@ export type ParamOverrides = Record<string, Record<string, Record<string, number
  */
 export declare class Game {
     readonly scene: THREE.Scene<THREE.Object3DEventMap>;
-    readonly camera: THREE.OrthographicCamera;
     readonly input: Input;
     readonly pointer: Pointer;
     readonly query: SpatialQuery;
@@ -100,6 +116,8 @@ export declare class Game {
     readonly lighting: GameLighting;
     /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
     readonly post: GamePost;
+    /** The live 3D scene's Rapier world and bodies (ADR 0028); package-internal, read by the physics components and the Runtime Snapshot. */
+    readonly physics: PhysicsHost;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -131,8 +149,17 @@ export declare class Game {
     private readonly baseViewHeight;
     private viewHeight;
     private sceneCamera;
+    /** The orthographic camera of 2D scenes and the perspective one of 3D scenes (ADR 0027); read by the Runtime Snapshot, not part of the game-facing API. */
+    readonly cameraRig: CameraRig;
+    private sceneSpace;
+    /** A 3D scene's stereo pan, reading the live camera at every call (built once, not per frame). */
+    private readonly screenPan;
+    /** What following an entity reads from the Game, built once rather than per Simulation Step. */
+    private readonly followHost;
     private renderSort;
     private sceneProjection;
+    /** The Ambient Light of a 3D scene, fed by `lighting.ambient` (ADR 0027). */
+    private readonly ambientLight3d;
     /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     private lastTime;
     /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
@@ -153,7 +180,9 @@ export declare class Game {
     constructor(options: GameOptions);
     /**
      * Resolves once the renderer can draw; rejects, naming both Render
-     * Backends, when neither initializes. Every call returns the same promise.
+     * Backends, when neither initializes. While the live scene is 3D it also
+     * waits for the physics module, and rejects naming its package if that
+     * fails to load (ADR 0028).
      * Frames before it simulate but draw nothing, so a host awaits it before
      * its first frame (ADR 0025).
      */
@@ -211,6 +240,8 @@ export declare class Game {
      * draw order stays layer-banded with spawn-order ties.
      */
     setSceneRender(json?: SceneRenderJson): void;
+    /** Adopts a scene's simulation block (gravity); called by loadScene beside setSceneRender. */
+    setSceneSimulation(json?: SceneSimulationJson): void;
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
@@ -222,7 +253,21 @@ export declare class Game {
     removeEntity(entity: Entity): void;
     /** The scene's render projection; null keeps logical and render space identical. */
     get projection(): 'isometric' | null;
-    /** Visible world height (2D camera zoom). */
+    /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
+    get space(): SceneSpace;
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    get camera(): GameCamera;
+    /**
+     * Where a logical point falls on the canvas, in CSS px from its top-left
+     * corner inside the letterbox; null when a perspective camera cannot see it
+     * (behind its near plane). The one projection Anchored Pieces, spatial
+     * audio and the editor share (CA-6).
+     */
+    worldToScreen(point: WorldPoint): {
+        x: number;
+        y: number;
+    } | null;
+    /** Visible world height (2D camera zoom); a perspective camera does not use it. */
     get view(): number;
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
@@ -279,14 +324,5 @@ export declare class Game {
     private componentUpdateSchedule;
     private updateSceneCamera;
     private renderPoint;
-    /**
-     * The audio listener's position (CA-8) in logical coordinates. The camera
-     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
-     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
-     * inverse of `renderPoint` — without it, distance-based attenuation would
-     * measure render-space distance instead of real game distance.
-     */
-    private audioListenerPosition;
-    private dispatchCollisions;
     private resize;
 }

package/dist/game.js

@@ -2,8 +2,9 @@ import * as THREE from 'three/webgpu';
 import { gameViewport } from './anchored-pieces.js';
 import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
-import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
+import { listenerPosition, screenPanOf } from './audio/spatial.js';
+import { worldToNormalized } from './camera-projection.js';
+import { CameraRig } from './camera-rig.js';
 import { advanceCameraEffects, CameraEffects, layoutCameraEffects } from './camera-effects.js';
 import { implementsOnUpdate, resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
@@ -11,19 +12,23 @@ import { Emitter } from './events.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
 import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
+import { PhysicsHost } from './physics-3d/physics-host.js';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { FrameComposer } from './lit-frame.js';
-import { EMISSIVE_LAYER } from './render-layers.js';
-import { projectIsometric, unprojectIsometric } from './projection.js';
+import { projectIsometric } from './projection.js';
 import { canvasBackground, drawStraightToCanvas, mapUvPerVertex } from './render-output.js';
 import { RenderReadiness } from './render-readiness.js';
 import { applyYSort } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { sceneDrainsOf } from './scene-drains.js';
+import { resolveSceneSimulation } from './scene-simulation.js';
+import { SceneAmbientLight3d } from './scene-lights-3d.js';
+import { resolveRenderPolicy } from './scene-space.js';
 import { GameLighting } from './scene-lighting.js';
+import { runSimulationPhases } from './simulation-phases.js';
 import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
@@ -44,7 +49,6 @@ function componentsInOrder(order, byName) {
  */
 export class Game {
     scene = new THREE.Scene();
-    camera;
     input;
     pointer;
     query;
@@ -72,6 +76,8 @@ export class Game {
     lighting = new GameLighting();
     /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
     post = new GamePost();
+    /** The live 3D scene's Rapier world and bodies (ADR 0028); package-internal, read by the physics components and the Runtime Snapshot. */
+    physics;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -103,8 +109,21 @@ export class Game {
     baseViewHeight;
     viewHeight;
     sceneCamera = null;
+    /** The orthographic camera of 2D scenes and the perspective one of 3D scenes (ADR 0027); read by the Runtime Snapshot, not part of the game-facing API. */
+    cameraRig = new CameraRig();
+    sceneSpace = '2d';
+    /** A 3D scene's stereo pan, reading the live camera at every call (built once, not per frame). */
+    screenPan = screenPanOf(() => this.camera);
+    /** What following an entity reads from the Game, built once rather than per Simulation Step. */
+    followHost = {
+        find: (name) => this.find(name),
+        renderPoint: (x, y) => this.renderPoint(x, y),
+        viewHeight: () => this.viewHeight,
+    };
     renderSort = null;
     sceneProjection = null;
+    /** The Ambient Light of a 3D scene, fed by `lighting.ambient` (ADR 0027). */
+    ambientLight3d = new SceneAmbientLight3d(this.scene);
     /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     lastTime = null;
     /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
@@ -147,11 +166,13 @@ export class Game {
         });
         this.assets = new AssetLoader({
             backend: options.textures,
+            models: options.models,
             // Same late lookup as audio's: preload() resolves through whatever
             // catalog is registered at call time, which outlives every scene.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
         this.spriteBatches = createSpriteBatches(this, this.assets);
+        this.physics = new PhysicsHost(this, options.physics);
         this.cameraEffects = new CameraEffects({
             host: () => canvas.parentElement ?? document.body,
             // One screen pixel in world units: the shake snaps to it (never the base).
@@ -170,14 +191,10 @@ export class Game {
                 activeRuntimeBridgeHook()?.fail?.({ code: 'render-backend-failed', message: error.message });
         });
         this.scene.background = canvasBackground(background);
-        this.camera = new THREE.OrthographicCamera();
-        this.camera.position.z = 10;
-        // Emissive drawables sit on their own layer; an unlit frame draws it in place.
-        this.camera.layers.enable(EMISSIVE_LAYER);
         const { renderer, spriteBatches, resolution } = this;
         this.frame = new FrameComposer({ game: this, renderer, spriteBatches, resolution });
         this.pointer = new Pointer(canvas, {
-            camera: this.camera,
+            camera: () => this.camera,
             resolution: this.resolution,
             projection: () => this.sceneProjection,
             entities: this.entities,
@@ -188,12 +205,14 @@ export class Game {
     }
     /**
      * Resolves once the renderer can draw; rejects, naming both Render
-     * Backends, when neither initializes. Every call returns the same promise.
+     * Backends, when neither initializes. While the live scene is 3D it also
+     * waits for the physics module, and rejects naming its package if that
+     * fails to load (ADR 0028).
      * Frames before it simulate but draw nothing, so a host awaits it before
      * its first frame (ADR 0025).
      */
     ready() {
-        return this.readiness.promise;
+        return this.physics.whenReady(this.readiness.promise);
     }
     /** The Render Backend the renderer settled on; null until ready() resolved. */
     get backend() {
@@ -251,6 +270,8 @@ export class Game {
         // Pointer holds that array by reference, so it must never be reassigned.
         for (const entity of [...this.entities])
             entity.destroy();
+        // After the cascade removed every body: the world goes with its scene.
+        this.physics.unloadScene();
         // Drains transferred by the destruction cascade above are scene-scoped too.
         sceneDrainsOf(this).clear();
         // After the cascade freed every slot: the batches go with their scene.
@@ -259,6 +280,8 @@ export class Game {
         this.renderSort = null;
         this.sceneProjection = null;
         this.sceneCamera = null;
+        this.sceneSpace = '2d';
+        this.cameraRig.reset();
         this.liveSceneName = null;
         this.setViewHeight(this.baseViewHeight);
     }
@@ -348,11 +371,13 @@ export class Game {
      * draw order stays layer-banded with spawn-order ties.
      */
     setSceneRender(json) {
-        this.renderSort = json?.sort === 'y' ? 'y' : null;
+        const { space, sort, projection } = resolveRenderPolicy(json);
+        this.sceneSpace = space;
+        this.renderSort = sort;
         this.spriteBatches.enabled = json?.batch !== false;
         this.lighting.loadScene(json);
         this.post.loadScene(json);
-        const projection = json?.projection === 'isometric' ? 'isometric' : null;
+        this.physics.enterScene(space);
         if (projection === this.sceneProjection)
             return;
         this.sceneProjection = projection;
@@ -362,26 +387,28 @@ export class Game {
                 component.onProjectionChange?.(projection);
         }
     }
+    /** Adopts a scene's simulation block (gravity); called by loadScene beside setSceneRender. */
+    setSceneSimulation(json) {
+        this.physics.setSimulation(resolveSceneSimulation(json));
+    }
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
      */
     setSceneCamera(json) {
-        // No camera block: leave the camera to the host (constructor viewHeight).
-        if (!json) {
-            this.sceneCamera = null;
+        // No orthographic block (none, or a 3D scene): leave the camera to the host.
+        const cam = (this.sceneCamera = this.cameraRig.adopt(json, this.sceneSpace));
+        if (!cam)
             return;
-        }
-        this.sceneCamera = resolveSceneCamera(json);
         // With a follow target the declared position is moot: start centered on
         // the target so play begins framed like the editor shows it.
-        const followed = this.sceneCamera.follow ? this.find(this.sceneCamera.follow) : undefined;
+        const followed = cam.follow ? this.find(cam.follow) : undefined;
         const center = followed
             ? this.renderPoint(followed.position.x, followed.position.y)
-            : { x: this.sceneCamera.position[0], y: this.sceneCamera.position[1] };
+            : { x: cam.position[0], y: cam.position[1] };
         this.camera.position.x = center.x;
         this.camera.position.y = center.y;
-        this.setViewHeight(this.sceneCamera.zoom);
+        this.setViewHeight(cam.zoom);
     }
     start() {
         if (this.disposed)
@@ -438,11 +465,35 @@ export class Game {
     get projection() {
         return this.sceneProjection;
     }
-    /** Visible world height (2D camera zoom). */
+    /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
+    get space() {
+        return this.sceneSpace;
+    }
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    get camera() {
+        return this.cameraRig.camera;
+    }
+    /**
+     * Where a logical point falls on the canvas, in CSS px from its top-left
+     * corner inside the letterbox; null when a perspective camera cannot see it
+     * (behind its near plane). The one projection Anchored Pieces, spatial
+     * audio and the editor share (CA-6).
+     */
+    worldToScreen(point) {
+        const { clientWidth: w, clientHeight: h } = this.renderer.domElement;
+        const view = gameViewport(w, h, this.resolution);
+        const render = this.renderPoint(point.x, point.y);
+        const at = worldToNormalized(this.camera, { x: render.x, y: render.y, z: point.z });
+        return at && { x: view.x + at.nx * view.width, y: view.y + at.ny * view.height };
+    }
+    /** Visible world height (2D camera zoom); a perspective camera does not use it. */
     get view() {
         return this.viewHeight;
     }
     setViewHeight(value) {
+        // A perspective camera frames by its lens, not by a visible height.
+        if (this.sceneSpace === '3d')
+            return;
         this.viewHeight = Math.min(Math.max(value, 2), 80);
         this.resize();
     }
@@ -462,6 +513,7 @@ export class Game {
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        this.physics.dispose();
         sceneDrainsOf(this).clear();
         this.spriteBatches.unload();
         // After the entities: their clones go with the cascade above, the
@@ -555,7 +607,7 @@ export class Game {
             // Positional audio (CA-8): recomputed every frame, on this same pass —
             // never a second walk of `this.entities`, since `this.audio` already
             // holds direct references to whichever entities are tracked.
-            this.audio.updatePlacements(this.audioListenerPosition(), (x, y) => this.renderPoint(x, y));
+            this.audio.updatePlacements(listenerPosition(this.sceneSpace, this.camera, this.sceneProjection), (x, y) => this.renderPoint(x, y), this.sceneSpace === '3d' ? this.screenPan : undefined);
             this.renderSurface();
         }
         finally {
@@ -581,7 +633,7 @@ export class Game {
             for (const component of schedule)
                 component.onUpdate?.(SIMULATION_STEP);
         }
-        this.dispatchCollisions();
+        runSimulationPhases(this);
         this.updateSceneCamera(SIMULATION_STEP);
         advanceCameraEffects(this.cameraEffects);
         this.finishStep();
@@ -625,11 +677,13 @@ export class Game {
         if (this.renderSort === 'y')
             applyYSort(this.entities, sceneDrainsOf(this).participants());
         this.ui.setActive(this.simulate);
+        this.ambientLight3d.sync(this.sceneSpace, this.lighting.ambient);
         // The shake offset exists only while drawing (ADR 0020): Anchored Pieces
         // and the render see the drawn center, then the base comes back exactly,
         // so follow smoothing never starts from its own jitter.
         const { x, y } = this.camera.position;
-        const { shake } = this.cameraEffects.state;
+        // A perspective camera does not shake: the offset is in orthographic world units.
+        const shake = this.sceneSpace === '3d' ? { x: 0, y: 0 } : this.cameraEffects.state.shake;
         this.camera.position.x = x + shake.x;
         this.camera.position.y = y + shake.y;
         try {
@@ -688,48 +742,13 @@ export class Game {
         return componentsInOrder(result.order, byName);
     }
     updateSceneCamera(dt) {
-        const cam = this.sceneCamera;
-        if (!cam)
+        if (!this.sceneCamera)
             return;
-        const followed = cam.follow ? this.find(cam.follow) : undefined;
-        const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
-        const velocity = provider?.getCameraVelocity();
-        const target = followed
-            ? this.renderPoint(followed.position.x, followed.position.y)
-            : null;
-        const renderVelocity = velocity
-            ? this.renderPoint(velocity.vx, velocity.vy)
-            : { x: 0, y: 0 };
-        const next = stepSceneCamera(cam, {
-            x: this.camera.position.x,
-            y: this.camera.position.y,
-            halfW: (this.camera.right - this.camera.left) / 2,
-            halfH: this.viewHeight / 2,
-            target,
-            vx: renderVelocity.x,
-            vy: renderVelocity.y,
-            dt,
-        });
-        this.camera.position.x = next.x;
-        this.camera.position.y = next.y;
+        this.cameraRig.follow(this.sceneCamera, this.followHost, dt);
     }
     renderPoint(x, y) {
         return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };
     }
-    /**
-     * The audio listener's position (CA-8) in logical coordinates. The camera
-     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
-     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
-     * inverse of `renderPoint` — without it, distance-based attenuation would
-     * measure render-space distance instead of real game distance.
-     */
-    audioListenerPosition() {
-        const { x, y } = this.camera.position;
-        return this.sceneProjection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
-    }
-    dispatchCollisions() {
-        dispatchHitboxCollisions(this);
-    }
     resize() {
         const canvas = this.renderer.domElement;
         const { clientWidth: w, clientHeight: h } = canvas;
@@ -747,13 +766,7 @@ export class Game {
             this.renderer.setViewport(vx, vy, vw, vh);
             this.renderer.setScissor(vx, vy, vw, vh);
         }
-        const halfH = this.viewHeight / 2;
-        const halfW = halfH * aspect;
-        this.camera.left = -halfW;
-        this.camera.right = halfW;
-        this.camera.top = halfH;
-        this.camera.bottom = -halfH;
-        this.camera.updateProjectionMatrix();
+        this.cameraRig.fit(aspect, this.viewHeight);
         layoutCameraEffects(this.cameraEffects, gameViewport(w, h, this.resolution));
     }
 }