@waica/engine 0.24.0 → 0.26.0

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/frame-quad.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from 'three/webgpu';
+/** Whether `value` is the scene of a FrameQuad. */
+export declare function isFrameQuad(value: unknown): boolean;
+/**
+ * A full-viewport pass drawn as an ordinary scene with its own camera — not
+ * a THREE.QuadMesh: on the WebGPU backend a QuadMesh drawn to the canvas
+ * marks that render a full-screen pass, and the next render to the canvas in
+ * the same frame then loses everything drawn before it (seen in the issue
+ * #78 e2e). The lit frame draws its Emissive drawables after its multiply
+ * quad, so its quad must be ordinary.
+ */
+export declare class FrameQuad {
+    readonly material: THREE.Material;
+    private readonly scene;
+    private readonly camera;
+    private readonly mesh;
+    constructor(material: THREE.Material);
+    /** Draws the quad into whatever is bound now, inside the current viewport. */
+    render(renderer: THREE.WebGPURenderer): void;
+    dispose(): void;
+}

package/dist/frame-quad.js

@@ -0,0 +1,50 @@
+import * as THREE from 'three/webgpu';
+/** The scenes FrameQuad draws, so a test can tell them from any other render. */
+const quadScenes = new WeakSet();
+/** Whether `value` is the scene of a FrameQuad. */
+export function isFrameQuad(value) {
+    return typeof value === 'object' && value !== null && quadScenes.has(value);
+}
+/**
+ * Two triangles covering the viewport, with three's QuadMesh UV convention
+ * (v = 1 at the bottom), so a render target samples upright on both Render
+ * Backends — three flips a render target's v itself on WebGL2.
+ */
+function quadGeometry() {
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', new THREE.Float32BufferAttribute([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0], 3));
+    geometry.setAttribute('uv', new THREE.Float32BufferAttribute([0, 1, 1, 1, 1, 0, 0, 0], 2));
+    geometry.setIndex([0, 1, 2, 0, 2, 3]);
+    return geometry;
+}
+/**
+ * A full-viewport pass drawn as an ordinary scene with its own camera — not
+ * a THREE.QuadMesh: on the WebGPU backend a QuadMesh drawn to the canvas
+ * marks that render a full-screen pass, and the next render to the canvas in
+ * the same frame then loses everything drawn before it (seen in the issue
+ * #78 e2e). The lit frame draws its Emissive drawables after its multiply
+ * quad, so its quad must be ordinary.
+ */
+export class FrameQuad {
+    material;
+    scene = new THREE.Scene();
+    camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    mesh;
+    constructor(material) {
+        this.material = material;
+        this.mesh = new THREE.Mesh(quadGeometry(), material);
+        this.mesh.position.z = -0.5;
+        this.mesh.frustumCulled = false;
+        this.scene.add(this.mesh);
+        this.scene.matrixWorldAutoUpdate = true;
+        quadScenes.add(this.scene);
+    }
+    /** Draws the quad into whatever is bound now, inside the current viewport. */
+    render(renderer) {
+        renderer.render(this.scene, this.camera);
+    }
+    dispose() {
+        this.mesh.geometry.dispose();
+        this.material.dispose();
+    }
+}

package/dist/game.d.ts

@@ -1,18 +1,28 @@
 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';
 import { GameUi } from './ui.js';
@@ -31,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. */
@@ -51,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 {
@@ -70,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;
@@ -94,6 +112,12 @@ export declare class Game {
     readonly cameraEffects: CameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
+    /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
+    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;
@@ -108,6 +132,8 @@ export declare class Game {
     private readonly resizeObserver;
     /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
     private readonly spriteBatches;
+    /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
+    private readonly frame;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     /**
@@ -123,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). */
@@ -145,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).
      */
@@ -203,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.
@@ -214,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). */
@@ -271,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,15 +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 { projectIsometric, unprojectIsometric } from './projection.js';
+import { FrameComposer } from './lit-frame.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';
@@ -40,7 +49,6 @@ function componentsInOrder(order, byName) {
  */
 export class Game {
     scene = new THREE.Scene();
-    camera;
     input;
     pointer;
     query;
@@ -64,6 +72,12 @@ export class Game {
     cameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
+    /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
+    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 = {};
@@ -78,6 +92,8 @@ export class Game {
     resizeObserver;
     /** Scene-scoped Sprite Batches (ADR 0024); `render.batch: false` opts a scene out. */
     spriteBatches;
+    /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
+    frame;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     /**
@@ -93,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). */
@@ -137,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).
@@ -160,10 +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;
+        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,
@@ -174,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() {
@@ -228,6 +261,8 @@ export class Game {
         // destroyed below, so an owner's own destroy() cancellation is a no-op.
         this.time.cancelSceneScoped();
         this.cameraEffects.unloadScene();
+        this.lighting.unloadScene();
+        this.post.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -235,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.
@@ -243,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);
     }
@@ -332,9 +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;
-        const projection = json?.projection === 'isometric' ? 'isometric' : null;
+        this.lighting.loadScene(json);
+        this.post.loadScene(json);
+        this.physics.enterScene(space);
         if (projection === this.sceneProjection)
             return;
         this.sceneProjection = projection;
@@ -344,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)
@@ -420,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();
     }
@@ -444,11 +513,13 @@ 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
         // cached bases go here, exactly once (ADR 0019).
         this.assets.dispose();
+        this.frame.dispose();
         this.readiness.disposeRenderer();
     }
     /**
@@ -536,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 {
@@ -562,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();
@@ -606,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 {
@@ -618,14 +691,7 @@ export class Game {
             // Before ready() the frame simulated, but three cannot draw yet.
             if (!this.readiness.isReady)
                 return;
-            if (this.resolution) {
-                // Letterbox bars: clear the whole canvas, then render inside the scissor.
-                this.renderer.setScissorTest(false);
-                this.renderer.setClearColor(0x000000, 1);
-                this.renderer.clear(true, false, false);
-                this.renderer.setScissorTest(true);
-            }
-            this.spriteBatches.drawFrame(this.scene, this.camera, () => this.renderer.render(this.scene, this.camera));
+            this.frame.draw();
         }
         finally {
             this.camera.position.x = x;
@@ -676,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;
@@ -735,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));
     }
 }