@waica/engine 0.28.0 → 0.29.1

package/dist/game.d.ts

@@ -135,15 +135,8 @@ export declare class Game {
     /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
     private readonly frame;
     private readonly updateFns;
-    private readonly invalidUpdateCompositions;
-    /**
-     * componentUpdateSchedule's result for the last composition signature seen
-     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
-     * for a fixed composition, so a signature match skips it entirely. Only
-     * ever holds a successful resolution — an invalid composition is never
-     * cached, since invalidUpdateCompositions already dedupes its console.error.
-     */
-    private readonly updateScheduleCache;
+    /** Each entity's Component Update Schedule (ADR 0004), resolved once per composition. */
+    private readonly updateSchedules;
     private readonly resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     private readonly baseViewHeight;
@@ -247,12 +240,20 @@ export declare class Game {
      * simulating, follows/clamps per its settings. Called by loadScene.
      */
     setSceneCamera(json?: SceneCameraJson): void;
+    /** Puts a following perspective camera on its orbit; loadScene calls it after the spawns, so the first frame is framed (issue #181). */
+    placeSceneCamera(): void;
     start(): void;
     stop(): void;
     /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity: Entity): void;
     /** The scene's render projection; null keeps logical and render space identical. */
     get projection(): 'isometric' | null;
+    /**
+     * The yaw of the scene's orbit camera in degrees — 0 looks toward -z, 90
+     * toward +x — or null when the scene camera follows nothing (issue #181);
+     * what a camera-relative mover rotates its input by.
+     */
+    get cameraYaw(): number | null;
     /** 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, or a host's view camera over a 3D one (`cameraRig.setViewCamera`). */
@@ -309,7 +310,7 @@ export declare class Game {
      */
     private runFrame;
     /**
-     * One Simulation Step: the pad is read first (issue #75 CA-6), then
+     * One Simulation Step: the pad and the mouse are read first (issue #75 CA-6, issue #181 CA-2), then
      * game.time's start-of-step pass (ADR 0017, CA-3), then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
@@ -321,7 +322,8 @@ export declare class Game {
     private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     private renderSurface;
-    private componentUpdateSchedule;
+    /** True while a simulating scene's camera orbits a followed entity: what the pointer lock is for. */
+    private get orbitPlays();
     private updateSceneCamera;
     private renderPoint;
     private resize;

package/dist/game.js

@@ -6,9 +6,10 @@ 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';
+import { EntityUpdateSchedules } from './entity-update-schedules.js';
 import { Emitter } from './events.js';
+import { RigidBody } from './components/rigid-body.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';
@@ -34,15 +35,6 @@ import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { anchoredPiecesOf, GameUi } from './ui.js';
 import { componentClassOf } from './component-registry.js';
-/** Maps a resolved update order back to the entity's components; the order only names components it was built from. */
-function componentsInOrder(order, byName) {
-    return order.map((name) => {
-        const component = byName.get(name);
-        if (!component)
-            throw new Error(`Component update schedule names "${name}", which is not on the entity`);
-        return component;
-    });
-}
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -95,15 +87,8 @@ export class Game {
     /** Off, lit or through the Post Effects: how each frame is drawn (ADR 0026). */
     frame;
     updateFns = new Set();
-    invalidUpdateCompositions = new WeakMap();
-    /**
-     * componentUpdateSchedule's result for the last composition signature seen
-     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
-     * for a fixed composition, so a signature match skips it entirely. Only
-     * ever holds a successful resolution — an invalid composition is never
-     * cached, since invalidUpdateCompositions already dedupes its console.error.
-     */
-    updateScheduleCache = new WeakMap();
+    /** Each entity's Component Update Schedule (ADR 0004), resolved once per composition. */
+    updateSchedules = new EntityUpdateSchedules();
     resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     baseViewHeight;
@@ -119,6 +104,9 @@ export class Game {
         find: (name) => this.find(name),
         renderPoint: (x, y) => this.renderPoint(x, y),
         viewHeight: () => this.viewHeight,
+        input: () => this.input,
+        // Fixed level geometry only (a Collider with no RigidBody): a character or a crate crossing behind the Player never moves the camera.
+        rayDistance: ({ origin, direction, maxDistance, exclude }) => this.query.ray(origin, direction, maxDistance, { exclude, without: [RigidBody] })?.distance ?? null,
     };
     renderSort = null;
     sceneProjection = null;
@@ -146,7 +134,14 @@ export class Game {
         this.baseViewHeight = viewHeight;
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
-        this.input = new Input(options.bindings, { gamepadDeadZone: options.gamepadDeadZone });
+        this.input = new Input(options.bindings, {
+            gamepadDeadZone: options.gamepadDeadZone,
+            canvas,
+            // A click takes the pointer lock only while an orbit camera plays (never in the editor's edit mode).
+            lockOnClick: () => this.orbitPlays,
+            // The wheel zooms the orbit; any other scene leaves the page's scroll alone (CA-2 as amended).
+            preventsWheelScroll: () => this.orbitPlays,
+        });
         this.query = createSpatialQuery(this);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
@@ -410,6 +405,10 @@ export class Game {
         this.camera.position.y = center.y;
         this.setViewHeight(cam.zoom);
     }
+    /** Puts a following perspective camera on its orbit; loadScene calls it after the spawns, so the first frame is framed (issue #181). */
+    placeSceneCamera() {
+        this.cameraRig.placeOrbit(this.followHost);
+    }
     start() {
         if (this.disposed)
             return;
@@ -422,6 +421,7 @@ export class Game {
                     resume: (onStep) => this.resumeRuntime(onStep),
                     pause: () => this.stop(),
                     injectAction: (action, operation, value) => this.input.injectAction(action, operation, value),
+                    look: (dx, dy) => this.input.injectLook(dx, dy),
                     availableActions: () => this.input.availableActions(),
                     heldActions: () => this.input.heldActions(),
                     actionValues: () => this.input.actionValues(),
@@ -465,6 +465,14 @@ export class Game {
     get projection() {
         return this.sceneProjection;
     }
+    /**
+     * The yaw of the scene's orbit camera in degrees — 0 looks toward -z, 90
+     * toward +x — or null when the scene camera follows nothing (issue #181);
+     * what a camera-relative mover rotates its input by.
+     */
+    get cameraYaw() {
+        return this.cameraRig.orbitView?.yaw ?? null;
+    }
     /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
     get space() {
         return this.sceneSpace;
@@ -604,6 +612,9 @@ export class Game {
                 this.finishStep();
             }
             this.audio.setActive(this.simulate);
+            // The pointer lock belongs to a playing orbit: a pause, a swap or an unload gives the cursor back.
+            if (!this.orbitPlays)
+                this.input.releasePointerLock();
             // 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.
@@ -615,19 +626,20 @@ export class Game {
         }
     }
     /**
-     * One Simulation Step: the pad is read first (issue #75 CA-6), then
+     * One Simulation Step: the pad and the mouse are read first (issue #75 CA-6, issue #181 CA-2), then
      * game.time's start-of-step pass (ADR 0017, CA-3), then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */
     simulateStep() {
         this.input.pollGamepad();
+        this.input.pollMouse();
         advanceGameTime(this.time);
         // Existing drains advance before entity updates, so one detached during
         // this step begins on the next Simulation Step (ADR 0022).
         sceneDrainsOf(this).advance(SIMULATION_STEP);
         for (const entity of [...this.entities]) {
-            const schedule = this.componentUpdateSchedule(entity);
+            const schedule = this.updateSchedules.of(entity, this.registry?.components);
             if (!schedule)
                 continue;
             for (const component of schedule)
@@ -681,11 +693,7 @@ export class Game {
         // 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;
-        // 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;
+        const restoreBase = this.cameraRig.shake(this.cameraEffects.state.shake, this.viewHeight);
         try {
             anchoredPiecesOf(this.ui).place();
             // Before ready() the frame simulated, but three cannot draw yet.
@@ -694,57 +702,15 @@ export class Game {
             this.frame.draw();
         }
         finally {
-            this.camera.position.x = x;
-            this.camera.position.y = y;
+            restoreBase();
         }
     }
-    componentUpdateSchedule(entity) {
-        const components = [...entity.components];
-        const byName = new Map();
-        const names = [];
-        const signatureParts = [];
-        for (const component of components) {
-            const Class = componentClassOf(component);
-            const name = Class.componentName;
-            names.push(name);
-            byName.set(name, component);
-            signatureParts.push(`${name}:${implementsOnUpdate(Class) ? 'updates' : 'passive'}:` +
-                [...new Set(Class.updateAfter ?? [])].sort().join(','));
-        }
-        const signature = signatureParts.sort().join('|');
-        // The resolve below (duplicate check + Tarjan SCC + Kahn sort) is pure
-        // for a fixed composition, and this method now runs once per entity per
-        // Simulation Step rather than once per rendered frame: skip it entirely
-        // when nothing about this entity's components changed since last time.
-        const cached = this.updateScheduleCache.get(entity);
-        if (cached && cached.signature === signature) {
-            return componentsInOrder(cached.order, byName);
-        }
-        const registry = {
-            ...(this.registry?.components ?? {}),
-        };
-        for (const component of components) {
-            const Class = componentClassOf(component);
-            registry[Class.componentName] = Class;
-        }
-        const result = resolveComponentUpdateSchedule(names, registry);
-        if (!result.ok) {
-            this.updateScheduleCache.delete(entity);
-            if (this.invalidUpdateCompositions.get(entity) !== signature) {
-                this.invalidUpdateCompositions.set(entity, signature);
-                console.error(`[waica] invalid component update schedule for "${entity.name}": ` +
-                    result.issues.map((issue) => issue.cause).join(' '));
-            }
-            return null;
-        }
-        this.invalidUpdateCompositions.delete(entity);
-        this.updateScheduleCache.set(entity, { signature, order: result.order });
-        return componentsInOrder(result.order, byName);
+    /** True while a simulating scene's camera orbits a followed entity: what the pointer lock is for. */
+    get orbitPlays() {
+        return this.simulate && this.cameraRig.orbiting;
     }
     updateSceneCamera(dt) {
-        if (!this.sceneCamera)
-            return;
-        this.cameraRig.follow(this.sceneCamera, this.followHost, dt);
+        this.cameraRig.step(this.sceneCamera, this.followHost, dt);
     }
     renderPoint(x, y) {
         return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };

package/dist/index.d.ts

@@ -30,6 +30,9 @@ export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game
 export type { SceneCameraJson, OrthographicSceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
 export type { PerspectiveSceneCameraJson, ResolvedPerspectiveCamera, SceneFieldIssue, Vec3Json, } from './scene-camera-3d.js';
+export { ORBIT_DEFAULTS, resolveOrbit } from './scene-camera-orbit.js';
+export type { OrbitCameraJson, ResolvedOrbit } from './scene-camera-orbit.js';
+export type { OrbitView } from './orbit-camera.js';
 export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
 export type { GameCamera, NormalizedPoint, ViewCamera, WorldPoint } from './camera-projection.js';
 export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
@@ -47,6 +50,7 @@ export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export type { ComponentUpdateCycleIssue, ComponentUpdateRegistry, ComponentUpdateScheduleIssue, ComponentUpdateScheduleResult, DuplicateComponentUpdateIssue, InvalidComponentUpdateConstraintIssue, InvalidComponentUpdateSchedule, InvalidUpdateConstraintReason, ValidComponentUpdateSchedule, } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export type { ActionName, InjectedActionOperation, InputBindings, InputOptions } from './input.js';
+export type { MouseMovement } from './input-mouse.js';
 export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export type { GamepadControl } from './gamepad.js';
 export { Pointer } from './pointer.js';
@@ -59,7 +63,8 @@ export type { RenderBackend } from './render-readiness.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export type { RuntimeSnapshotLight, RuntimeSnapshotLighting, RuntimeSnapshotPointLight, RuntimeSnapshotSun, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotCamera, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
-export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
+export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, SceneArchetypeNeeds, } from './archetype.js';
+export { sceneArchetypeNeeds } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';
 export { GameUi } from './ui.js';
@@ -106,7 +111,7 @@ export type { TilemapCell, TilemapCellBounds, TilemapGridSpec, } from './tilemap
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
 export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit, SpatialQuery, SpatialQueryFilter, } from './spatial-query.js';
-export type { Point3d, QueryVolume3d, RayHit3d } from './spatial-query-3d.js';
+export type { Point3d, QueryColliders3d, QueryVolume3d, RayHit3d } from './spatial-query-3d.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
 export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, SceneLightingJson, ScenePostJson, PrefabJson, } from './scene.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
 export { CameraEffects } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
+export { ORBIT_DEFAULTS, resolveOrbit } from './scene-camera-orbit.js';
 export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
 export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
 export { applyTransformJson } from './entity-transform.js';
@@ -27,6 +28,7 @@ export { Pointer } from './pointer.js';
 export { raycastPick } from './pointer-raycast.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
+export { sceneArchetypeNeeds } from './archetype.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';

package/dist/input-mouse.d.ts

@@ -0,0 +1,83 @@
+/** The prefix of a mouse button's binding code, beside keys and `Gamepad:` codes (issue #181). */
+export declare const MOUSE_CODE_PREFIX = "Mouse:";
+/** A mouse movement or wheel reading, in CSS pixels. */
+export interface MouseMovement {
+    readonly x: number;
+    readonly y: number;
+}
+/** What the mouse reports to the Input it belongs to: a button code going down or up, and whether an Action binds a code. */
+export interface MouseButtonSink {
+    press(code: string): void;
+    release(code: string): void;
+    binds(code: string): boolean;
+}
+export interface MouseInputOptions {
+    /** The game canvas: buttons, the wheel and the pointer lock are read on it. Without one, only injected movement counts. */
+    canvas?: HTMLCanvasElement;
+    /** Asked on a press over the canvas while it is unlocked: true asks for the lock with that press, which presses nothing once granted (CA-3) and goes through when refused. */
+    lockOnClick?: () => boolean;
+    /** Asked on each wheel over the canvas: true keeps the page from scrolling (an orbit camera zooms with it); false by default (CA-2). */
+    preventsWheelScroll?: () => boolean;
+}
+/** True for a `Mouse:` code no button reports, which therefore never matches. */
+export declare function isUnknownMouseCode(code: string): boolean;
+/**
+ * The mouse as an Input source (issue #181): its buttons as `Mouse:` binding
+ * codes, its movement while the pointer is locked to the game canvas, the
+ * wheel over the canvas, and the pointer lock itself. Movement and wheel
+ * accumulate between Simulation Steps, are frozen by `poll()` at a step's
+ * start and read zero again after `endStep()`.
+ */
+export declare class MouseInput {
+    private readonly buttons;
+    private pendingMove;
+    private pendingWheel;
+    private move;
+    private wheel;
+    private readonly preventsWheelScroll;
+    private readonly canvas;
+    private readonly lockOnClick;
+    /** Set by dispose(): a lock the browser grants after it is given straight back. */
+    private disposed;
+    /** The codes whose press asked for the lock, awaiting the browser's answer: true while still held. */
+    private readonly askedLock;
+    constructor(buttons: MouseButtonSink, options?: MouseInputOptions);
+    /** Is the pointer locked to the game canvas right now? */
+    get locked(): boolean;
+    /** The locked movement of the current Simulation Step; zero between steps. */
+    movement(): MouseMovement;
+    /** The wheel delta of the current Simulation Step, in CSS px (positive scrolls down); zero between steps. */
+    wheelDelta(): number;
+    /** Freezes what accumulated since the last step as this step's movement and wheel. */
+    poll(): void;
+    /** The step is over: its movement and wheel read zero until the next poll. */
+    endStep(): void;
+    /** Adds a movement as if the pointer were locked (the Runtime Bridge's `look`, CA-4). */
+    inject(dx: number, dy: number): void;
+    /** Exits the pointer lock when the game canvas holds it; a lock on any other element is left alone. */
+    releaseLock(): void;
+    /** Asks the browser to lock the pointer to the game canvas; a refusal (or no Pointer Lock API) leaves it unlocked. */
+    requestLock(): void;
+    /**
+     * The presses that asked for a lock the browser refused (or cannot give)
+     * reach their `Mouse:` codes after all (maintainer decision on issue #181):
+     * still held, or as a tap when the button was let go before the answer.
+     */
+    private pressRefused;
+    /** Stops listening, and releases the pointer lock if this canvas holds it (a Game that goes away, the editor's Play stopping). */
+    dispose(): void;
+    /** `document.pointerLockElement`, which a browser without the Pointer Lock API (or a test DOM) lacks. */
+    private lockElement;
+    private onPointerDown;
+    private onPointerUp;
+    /**
+     * A button going down or up while another is held fires `pointermove`, not
+     * `pointerdown`/`pointerup` (Pointer Events' chorded buttons). Its bit in
+     * `buttons` tells which; a press counts over the canvas only, like the first.
+     */
+    private onPointerChord;
+    /** The browser menu would swallow the release of a bound `Mouse:Right`; other games keep their menu. */
+    private onContextMenu;
+    private onWheel;
+    private onMouseMove;
+}

package/dist/input-mouse.js

@@ -0,0 +1,205 @@
+/** The prefix of a mouse button's binding code, beside keys and `Gamepad:` codes (issue #181). */
+export const MOUSE_CODE_PREFIX = 'Mouse:';
+/** `PointerEvent.button` → the binding code of the buttons an Action can bind. */
+const MOUSE_BUTTON_CODES = new Map([
+    [0, 'Mouse:Left'],
+    [2, 'Mouse:Right'],
+]);
+const KNOWN_MOUSE_CODES = new Set(MOUSE_BUTTON_CODES.values());
+/** `PointerEvent.button` → its bit in `PointerEvent.buttons`, which tells a chorded press from a chorded release. */
+const MOUSE_BUTTON_BITS = new Map([
+    [0, 1],
+    [2, 2],
+]);
+/** Wheel deltas reported in lines or pages, in CSS pixels (the units of `deltaMode` 0). */
+const WHEEL_LINE_PX = 16;
+const WHEEL_PAGE_PX = 800;
+/** Touch and pen pointers are not the mouse: `Mouse:` codes ignore them (no mobile support, issue #181). */
+const fromMouse = (event) => event.pointerType !== 'touch' && event.pointerType !== 'pen';
+/** True for a `Mouse:` code no button reports, which therefore never matches. */
+export function isUnknownMouseCode(code) {
+    return code.startsWith(MOUSE_CODE_PREFIX) && !KNOWN_MOUSE_CODES.has(code);
+}
+function wheelPixels(event) {
+    if (event.deltaMode === 1)
+        return event.deltaY * WHEEL_LINE_PX;
+    if (event.deltaMode === 2)
+        return event.deltaY * WHEEL_PAGE_PX;
+    return event.deltaY;
+}
+/**
+ * The mouse as an Input source (issue #181): its buttons as `Mouse:` binding
+ * codes, its movement while the pointer is locked to the game canvas, the
+ * wheel over the canvas, and the pointer lock itself. Movement and wheel
+ * accumulate between Simulation Steps, are frozen by `poll()` at a step's
+ * start and read zero again after `endStep()`.
+ */
+export class MouseInput {
+    buttons;
+    pendingMove = { x: 0, y: 0 };
+    pendingWheel = 0;
+    move = { x: 0, y: 0 };
+    wheel = 0;
+    preventsWheelScroll;
+    canvas;
+    lockOnClick;
+    /** Set by dispose(): a lock the browser grants after it is given straight back. */
+    disposed = false;
+    /** The codes whose press asked for the lock, awaiting the browser's answer: true while still held. */
+    askedLock = new Map();
+    constructor(buttons, options = {}) {
+        this.buttons = buttons;
+        this.canvas = options.canvas ?? null;
+        this.lockOnClick = options.lockOnClick ?? (() => false);
+        this.preventsWheelScroll = options.preventsWheelScroll ?? (() => false);
+        this.canvas?.addEventListener('pointerdown', this.onPointerDown);
+        this.canvas?.addEventListener('wheel', this.onWheel, { passive: false });
+        this.canvas?.addEventListener('contextmenu', this.onContextMenu);
+        // A release anywhere counts, so a button let go off the canvas never stays held.
+        window.addEventListener('pointerup', this.onPointerUp);
+        window.addEventListener('pointermove', this.onPointerChord);
+        document.addEventListener('mousemove', this.onMouseMove);
+    }
+    /** Is the pointer locked to the game canvas right now? */
+    get locked() {
+        return this.canvas !== null && this.lockElement() === this.canvas;
+    }
+    /** The locked movement of the current Simulation Step; zero between steps. */
+    movement() {
+        return this.move;
+    }
+    /** The wheel delta of the current Simulation Step, in CSS px (positive scrolls down); zero between steps. */
+    wheelDelta() {
+        return this.wheel;
+    }
+    /** Freezes what accumulated since the last step as this step's movement and wheel. */
+    poll() {
+        this.move = { ...this.pendingMove };
+        this.wheel = this.pendingWheel;
+        this.pendingMove = { x: 0, y: 0 };
+        this.pendingWheel = 0;
+    }
+    /** The step is over: its movement and wheel read zero until the next poll. */
+    endStep() {
+        this.move = { x: 0, y: 0 };
+        this.wheel = 0;
+    }
+    /** Adds a movement as if the pointer were locked (the Runtime Bridge's `look`, CA-4). */
+    inject(dx, dy) {
+        this.pendingMove.x += dx;
+        this.pendingMove.y += dy;
+    }
+    /** Exits the pointer lock when the game canvas holds it; a lock on any other element is left alone. */
+    releaseLock() {
+        if (this.locked && 'exitPointerLock' in document)
+            document.exitPointerLock();
+    }
+    /** Asks the browser to lock the pointer to the game canvas; a refusal (or no Pointer Lock API) leaves it unlocked. */
+    requestLock() {
+        const canvas = this.canvas;
+        if (!canvas || !('requestPointerLock' in canvas)) {
+            this.pressRefused();
+            return;
+        }
+        try {
+            Promise.resolve(canvas.requestPointerLock()).then(() => {
+                // The press that asked took the lock, and presses nothing (CA-3).
+                this.askedLock.clear();
+                // Granted after this Input went away (the editor's Play stopped meanwhile): the lock is no longer the game's.
+                if (this.disposed)
+                    this.releaseLock();
+            }, () => {
+                // Refused (no user gesture, a sandboxed iframe, the cooldown after Esc): the press goes through; the next click asks again.
+                this.pressRefused();
+            });
+        }
+        catch {
+            // Older browsers throw synchronously instead of rejecting; same outcome.
+            this.pressRefused();
+        }
+    }
+    /**
+     * The presses that asked for a lock the browser refused (or cannot give)
+     * reach their `Mouse:` codes after all (maintainer decision on issue #181):
+     * still held, or as a tap when the button was let go before the answer.
+     */
+    pressRefused() {
+        for (const [code, held] of this.askedLock) {
+            this.buttons.press(code);
+            if (!held)
+                this.buttons.release(code);
+        }
+        this.askedLock.clear();
+    }
+    /** Stops listening, and releases the pointer lock if this canvas holds it (a Game that goes away, the editor's Play stopping). */
+    dispose() {
+        this.disposed = true;
+        this.releaseLock();
+        this.canvas?.removeEventListener('pointerdown', this.onPointerDown);
+        this.canvas?.removeEventListener('wheel', this.onWheel);
+        window.removeEventListener('pointerup', this.onPointerUp);
+        document.removeEventListener('mousemove', this.onMouseMove);
+        this.canvas?.removeEventListener('contextmenu', this.onContextMenu);
+        window.removeEventListener('pointermove', this.onPointerChord);
+    }
+    /** `document.pointerLockElement`, which a browser without the Pointer Lock API (or a test DOM) lacks. */
+    lockElement() {
+        return 'pointerLockElement' in document ? document.pointerLockElement : null;
+    }
+    onPointerDown = (event) => {
+        if (!fromMouse(event))
+            return;
+        const code = MOUSE_BUTTON_CODES.get(event.button);
+        if (!this.locked && this.lockOnClick()) {
+            // This press asks for the lock (G-17): it reaches its code only if the browser refuses.
+            if (code)
+                this.askedLock.set(code, true);
+            this.requestLock();
+            return;
+        }
+        if (code)
+            this.buttons.press(code);
+    };
+    onPointerUp = (event) => {
+        if (!fromMouse(event))
+            return;
+        const code = MOUSE_BUTTON_CODES.get(event.button);
+        if (!code)
+            return;
+        // Let go before the lock's answer: a refusal then delivers a tap.
+        if (this.askedLock.has(code))
+            this.askedLock.set(code, false);
+        this.buttons.release(code);
+    };
+    /**
+     * A button going down or up while another is held fires `pointermove`, not
+     * `pointerdown`/`pointerup` (Pointer Events' chorded buttons). Its bit in
+     * `buttons` tells which; a press counts over the canvas only, like the first.
+     */
+    onPointerChord = (event) => {
+        const bit = MOUSE_BUTTON_BITS.get(event.button);
+        if (bit === undefined || !fromMouse(event))
+            return;
+        if ((event.buttons & bit) === 0)
+            this.onPointerUp(event);
+        else if (event.target === this.canvas)
+            this.onPointerDown(event);
+    };
+    /** The browser menu would swallow the release of a bound `Mouse:Right`; other games keep their menu. */
+    onContextMenu = (event) => {
+        if (this.buttons.binds('Mouse:Right'))
+            event.preventDefault();
+    };
+    onWheel = (event) => {
+        // Over the game canvas only, and only while something zooms with it (an orbit camera, issue #181): otherwise the page still scrolls.
+        if (this.preventsWheelScroll())
+            event.preventDefault();
+        this.pendingWheel += wheelPixels(event);
+    };
+    onMouseMove = (event) => {
+        if (!this.locked)
+            return;
+        this.pendingMove.x += event.movementX;
+        this.pendingMove.y += event.movementY;
+    };
+}