@waica/engine 0.27.0 → 0.29.0

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;
+    };
+}

package/dist/input.d.ts

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

package/dist/input.js

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

package/dist/orbit-camera.d.ts

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

package/dist/orbit-camera.js

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

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

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

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

@@ -1,4 +1,8 @@
-const IDENTITY = { x: 0, y: 0, z: 0, w: 1 };
+/** The rotation of a box turned `yaw` degrees about +y (none for a sphere or an unturned box). */
+function rotationOf(volume) {
+    const half = volume.shape === 'box' ? ((volume.yaw ?? 0) * Math.PI) / 360 : 0;
+    return { x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) };
+}
 /**
  * Rapier's predicate for a query: only colliders whose body record `accepts`.
  * It runs inside Rapier's borrow of the world, so `accepts` must be a plain
@@ -42,7 +46,7 @@ export function recordsInVolume(world, volume, accepts) {
         ? new R.Cuboid(volume.size.x / 2, volume.size.y / 2, volume.size.z / 2)
         : new R.Ball(volume.radius);
     const found = [];
-    raw.intersectionsWithShape(volume.center, IDENTITY, shape, (collider) => {
+    raw.intersectionsWithShape(volume.center, rotationOf(volume), shape, (collider) => {
         const record = world.recordOfCollider(collider.handle);
         if (record)
             found.push(record);

package/dist/pointer-raycast.d.ts

@@ -1,17 +1,35 @@
 import * as THREE from 'three/webgpu';
 import type { Entity } from './entity.js';
-import type { PointerPick } from './pointer.js';
 /** A position inside the letterboxed game viewport, as fractions of its width and height. */
 export interface ViewportFraction {
     nx: number;
     ny: number;
 }
+/** What an extra target picks: an entity (an editor's icon for it), or the scene camera's icon. */
+export type PickedTarget = Entity | 'camera';
+/** An object a ray is also tested against, and what a hit on it picks (issue #173 CA-2). */
+export interface PickTarget<Picked extends PickedTarget = PickedTarget> {
+    readonly object: THREE.Object3D;
+    readonly entity: Picked;
+}
+/** A 3D pick: the hit's world point, and the entity (or extra target) hit, or null on the ground. */
+export interface RaycastPick<Picked extends PickedTarget = Entity> {
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly entity: Entity | Picked | null;
+}
 /**
  * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
  * letterboxed point, intersected with the roots of every live Model
- * (recursively, so a glTF's meshes count and a glTF still loading does not).
- * The nearest hit wins, with its world-space point. With no hit the pick has
- * no entity and the point where the ray meets the ground plane y = 0; a ray
- * that never meets it (it looks at the sky) yields no pick.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). The nearest hit wins, with its
+ * world-space point. With no hit the pick has no entity and the point where
+ * the ray meets the ground plane y = 0; a ray that never meets it (it looks
+ * at the sky) yields no pick.
  */
-export declare function raycastPick(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[]): PointerPick | null;
+export declare function raycastPick<Picked extends PickedTarget = Entity>(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[], extra?: readonly PickTarget<Picked>[]): RaycastPick<Picked> | null;