@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/look.d.ts

@@ -0,0 +1,327 @@
+import { type InputClock } from './clock.js';
+import type { GyroSource } from './gyro.js';
+import { type PointerDispatcher } from './pointer-dispatch.js';
+import type { GamepadLike, PointerTransform } from './types.js';
+/** Where the move stick lives on a touch screen. */
+export type MoveZone = 'left' | 'right' | 'none';
+export interface LookTouchOptions {
+    /**
+     * The half of the attached element where a touch becomes the move stick (`'none'`: every touch
+     * looks). Default `'left'`.
+     */
+    moveZone?: MoveZone;
+    /** Stick deadzone as a fraction of `radius` (0..1). Default 0.12. */
+    deadzone?: number;
+    /** CSS px from the stick's origin to full deflection; the stick clamps there. Default 56. */
+    radius?: number;
+    /** Radians per CSS px a look touch drags. Default: `LookOptions.sensitivity`. */
+    sensitivity?: number;
+}
+/** Key codes (`KeyboardEvent.code`) that move. No defaults: the game names them. */
+export interface LookKeys {
+    forward?: readonly string[];
+    back?: readonly string[];
+    left?: readonly string[];
+    right?: readonly string[];
+}
+/** Which pad control zooms. */
+export type LookZoomPad = 'rightStickY' | 'shoulders' | 'none';
+/**
+ * How the mouse (and pen) look (ws/input-3). `'locked'`: pointer-locked `movementX/Y` after
+ * `request()`. `'orbit'`: a button-down drag on the attached element turns the view at the same
+ * `sensitivity`, no lock is ever requested, and the drag never reaches the linked `Gestures`.
+ */
+export type LookMode = 'locked' | 'orbit';
+export interface LookZoomOptions {
+    /** The mouse wheel zooms (one notch, 100 px or `stepPx`, is 1). Default true. */
+    wheel?: boolean;
+    /**
+     * A second finger beside a look drag pinches: the change in finger distance over `stepPx` is
+     * the zoom. Default true.
+     */
+    pinch?: boolean;
+    /**
+     * `'rightStickY'`: the right stick's vertical axis zooms (`PAD_ZOOM_PER_S` units per second at
+     * full deflection) and no longer pitches the look. `'shoulders'`: the shoulder buttons (standard
+     * mapping 4 and 5) read -1 and +1 per tick while held. Default `'none'`.
+     */
+    pad?: LookZoomPad;
+    /** CSS px per zoom unit for the wheel (`deltaMode` pixels) and the pinch. Default 100. */
+    stepPx?: number;
+}
+export interface LookOptions {
+    /** The zoom axis (`Look.zoom`). Default: wheel and pinch on, pad `'none'`. */
+    zoom?: LookZoomOptions;
+    /** Radians per CSS px of pointer-locked mouse movement. Default 0.0025. */
+    sensitivity?: number;
+    /** Radians per second at full right-stick deflection. Default 3. */
+    padSensitivity?: number;
+    /** Flip vertical look (mouse, touch and stick). Default false. */
+    invertY?: boolean;
+    /** The touch layout. */
+    touch?: LookTouchOptions;
+    /** Stick deadzone (0..1, radial) for both pad sticks. Default 0.15. */
+    padDeadzone?: number;
+    /** Which pad; omitted = the first connected one. */
+    pad?: number;
+    /**
+     * Gamepad source. Default `navigator.getGamepads()` (guarded); linked to an `Input`, the
+     * default is the input's pads for the tick instead (ws/input-9), so a recording captures and a
+     * playback replaces the look's sticks with the rest. A source given here is always read
+     * as is, linked or not, and is not replaced by a playback.
+     */
+    getGamepads?: () => readonly (GamepadLike | null)[];
+    /**
+     * Keys that move (read through the linked `Input`'s raw key state; `Look` has no key listener
+     * of its own). `forward` is `move.y` +1, `right` is `move.x` +1.
+     */
+    keys?: LookKeys;
+    /** While true everything reads zero and the pointer lock is released. `Input.setLook` replaces it. */
+    blocked?: () => boolean;
+    /** Clock in ms, for the stick's `dt`. Default `performance.now()`. The older spelling of `clock`; `clock` wins. */
+    now?: () => number;
+    /**
+     * The clock the look is timed on (ws/input-8): the pad stick's turn and zoom rate (`dt`) and
+     * `onTap`'s `maxMs`. Pass the gestures' `createTickClock()` so both run on game time.
+     * Default `performance.now()`.
+     */
+    clock?: InputClock;
+    /**
+     * A mouse (or pen) `pointerdown` on the attached element while the lock is not held calls
+     * `request()`, so the first click into the game locks the pointer and, after the player
+     * presses Escape, the next click locks it again. Touches never lock. Blocked, nothing is
+     * requested. Default false: the game calls `request()` from its own click handler.
+     */
+    lockOnFirstClick?: boolean;
+    /**
+     * `'locked'` (default) or `'orbit'` (see `LookMode`). In orbit mode `lockOnFirstClick` is
+     * ignored (with one warning) and `request()` resolves false without asking. `setMode` switches
+     * at runtime.
+     */
+    mode?: LookMode;
+    /** Gyro aim (ws/input-5): its delta is added to the look every tick. See `createGyroSource`. */
+    gyro?: GyroSource;
+    /** The tap `onTap` reports (ws/input-5). */
+    tap?: LookTapOptions;
+}
+/** `Look.onTap` thresholds (ws/input-5). */
+export interface LookTapOptions {
+    /** Most CSS px a pointer may travel (summed) and still tap. Default 10, the gestures' pan threshold. */
+    maxMove?: number;
+    /** Longest press, ms on the look's clock, that still taps. Default 450, the gestures' long press. */
+    maxMs?: number;
+}
+/** A `Look.onTap` listener: (x, y) in the router's units (through the pointer transform). */
+export type LookTapListener = (x: number, y: number, device: 'mouse' | 'touch' | 'pen') => void;
+/** `Look` events. */
+export interface LookEvents {
+    /** The pointer lock on the attached element was taken (`true`) or lost (`false`). */
+    lockChange: boolean;
+}
+/** The touch move stick, client CSS px (for drawing it). */
+export interface LookStick {
+    active: boolean;
+    /** Where the finger landed. */
+    originX: number;
+    originY: number;
+    /** Where the finger is now, clamped to `radius` from the origin. */
+    x: number;
+    y: number;
+}
+/** Zoom units per second the right stick reports at full deflection (`zoom.pad: 'rightStickY'`). */
+export declare const PAD_ZOOM_PER_S = 4;
+/**
+ * First- and third-person look and move. Each tick it reports `look` (yaw and pitch deltas in
+ * radians) and `move` (x, y in -1..1) from whichever device the player uses: pointer-locked mouse,
+ * a two-zone touch layout (a virtual move stick in one half, look drags anywhere else), the pad's
+ * sticks and the move keys. Link it with `input.setLook(look)` so it shares `blocked()`, attaches
+ * with `Input.attach` and advances in `Input.update()`.
+ *
+ * Signs: `look.dx` > 0 turns right, `look.dy` > 0 looks up (`invertY` flips it); `move.x` > 0 is
+ * right, `move.y` > 0 is forward. `zoom` > 0 is closer (wheel up, fingers apart). No allocation
+ * per tick.
+ */
+export declare class Look {
+    /** This tick's look delta, radians. */
+    readonly look: {
+        dx: number;
+        dy: number;
+    };
+    /** This tick's move, each axis -1..1, length at most 1. */
+    readonly move: {
+        x: number;
+        y: number;
+    };
+    /**
+     * This tick's zoom: wheel notches, pinch distance over `stepPx`, or stick units; positive is
+     * closer. `Follow` reads it when linked.
+     */
+    zoom: number;
+    /** The touch move stick (client CSS px). */
+    readonly stick: LookStick;
+    /** True while the attached element holds the pointer lock. */
+    locked: boolean;
+    blocked: () => boolean;
+    /** Raw key state the move keys are read from; `Input.setLook` installs its own. */
+    keyHeld: ((code: string) => boolean) | null;
+    sensitivity: number;
+    padSensitivity: number;
+    invertY: boolean;
+    moveZone: MoveZone;
+    deadzone: number;
+    radius: number;
+    touchSensitivity: number | undefined;
+    padDeadzone: number;
+    keys: LookKeys;
+    zoomWheel: boolean;
+    zoomPinch: boolean;
+    zoomPad: LookZoomPad;
+    zoomStepPx: number;
+    /** Gyro aim added to the look each tick (`LookOptions.gyro`), or null. */
+    gyro: GyroSource | null;
+    /** `onTap` thresholds. */
+    tapMaxMove: number;
+    tapMaxMs: number;
+    /**
+     * Client → game-space mapping for `onTap` coordinates; `Input.setLook` and
+     * `Input.setPointerTransform` keep it in step with the input's. `null`: the dispatcher's units.
+     */
+    pointerTransform: PointerTransform | null;
+    private readonly tapFns;
+    /** The pointer that may still tap, or null. */
+    private tapId;
+    private tapDevice;
+    private tapAt;
+    private tapLastX;
+    private tapLastY;
+    private tapTravel;
+    private readonly gyroOut;
+    private readonly stickOut;
+    private readonly stickOpts;
+    private readonly pad;
+    private readonly getGamepads;
+    private readonly now;
+    /** The clock (`LookOptions.clock`, or one wrapping `now`, or the wall clock). */
+    readonly clock: InputClock;
+    private readonly events;
+    private lastTime;
+    private mouseX;
+    private mouseY;
+    private touchX;
+    private touchY;
+    private moveId;
+    private lookId;
+    private lookLastX;
+    private lookLastY;
+    private pinchId;
+    private pinchX;
+    private pinchY;
+    private pinchDist;
+    private zoomAcc;
+    private target;
+    private detachFn;
+    private readonly lockOnFirstClick;
+    private modeValue;
+    private warnedLockOnFirstClick;
+    /** The orbit drag in progress (client CSS px), or NaN when none. */
+    private orbitX;
+    private orbitY;
+    /**
+     * True once a linked `Input` feeds the orbit drag through its own pointer feed (so the drag is
+     * recorded and replayed); the DOM listener here then leaves mouse and pen alone. Set by
+     * `Input.setLook`.
+     */
+    orbitFromInput: boolean;
+    /**
+     * The linked `Input`'s pads for this tick (ws/input-9), read instead of the default
+     * `navigator.getGamepads()` so a playback's recorded pads turn the look. Ignored when
+     * `LookOptions.getGamepads` was given. Set by `Input.setLook`.
+     */
+    padsFromInput: (() => readonly (GamepadLike | null)[]) | null;
+    /** True when `LookOptions.getGamepads` was given: it wins over `padsFromInput`. */
+    private readonly ownPads;
+    constructor(opts?: LookOptions);
+    /**
+     * Call `fn` on a tap (ws/input-5): a primary-button press and release that travels at most
+     * `tap.maxMove` px within `tap.maxMs`, on a pointer the look took (an orbit-mode mouse or pen,
+     * a look-drag touch) or, in locked mode, on any pointer over the attached element except the
+     * move-stick touch. A second finger landing cancels it. (x, y) are in the router's units (the
+     * pointer transform's game space). Returns the remover.
+     */
+    onTap(fn: LookTapListener): () => void;
+    /** The look mode (`LookOptions.mode`); change it with `setMode`. */
+    get mode(): LookMode;
+    /**
+     * Switch between pointer-locked and orbit look at runtime. Into orbit the lock is released;
+     * into locked a drag in progress ends (the game asks for the lock from its next click).
+     */
+    setMode(mode: LookMode): void;
+    /** True when the look takes mouse and pen pointers for itself (orbit mode), so gestures must not. */
+    claimsPointer(device: 'mouse' | 'touch' | 'pen'): boolean;
+    /** True while an orbit drag is in progress. */
+    get orbiting(): boolean;
+    /** Subscribe to `lockChange`. Returns the unsubscriber. */
+    on<K extends keyof LookEvents>(type: K, fn: (payload: LookEvents[K]) => void): () => void;
+    /** Shorthand for `on('lockChange', fn)`. */
+    onLockChange(fn: (locked: boolean) => void): () => void;
+    /** Advance one tick. `Input.update()` calls this when linked; don't call it twice. */
+    update(): void;
+    private padState;
+    /** Pointer-locked mouse movement, CSS px (`movementX/Y`). The DOM listener feeds it only while locked. */
+    mouseMove(dx: number, dy: number): void;
+    /**
+     * An orbit drag began at client (x, y) (mouse or pen, primary button). Nothing in locked mode.
+     * A linked `Input` feeds these from its own `buttonDown`, `pointerAt` and `buttonUp`.
+     */
+    orbitDown(x: number, y: number): void;
+    /** The orbit pointer moved to client (x, y): the delta turns the view at `sensitivity`. */
+    orbitMove(x: number, y: number): void;
+    /** The orbit drag ended. */
+    orbitUp(): void;
+    /** Zoom units (wheel notches) to add to this tick's `zoom`; positive is closer. */
+    wheel(units: number): void;
+    /**
+     * A touch went down at client (x, y); `inMoveZone` says whether it landed in the move zone. A
+     * touch that neither takes the stick nor starts a look drag pinches against the drag in progress
+     * when `zoom.pinch` is on.
+     */
+    touchDown(id: number, x: number, y: number, inMoveZone: boolean): void;
+    touchMove(id: number, x: number, y: number): void;
+    touchUp(id: number): void;
+    /** The distance between the look and pinch fingers changed: fingers apart is closer. */
+    private pinchMoved;
+    /** Drop every touch (blur, hidden tab, blocked). Fingers still down are ignored until lifted. */
+    cancelAll(): void;
+    private voidTouches;
+    /**
+     * Ask for the pointer lock on the attached element. Browsers grant it only inside a user
+     * gesture, so call this from a click or tap. Resolves with whether the lock is held; never
+     * rejects. False when detached, blocked or unsupported.
+     */
+    request(): Promise<boolean>;
+    /** Give the pointer lock back, if the attached element holds it. */
+    release(): void;
+    private syncLock;
+    /**
+     * Listen on the element: touch pointers (zones, pinch), the wheel (passive), pointer-locked
+     * mouse movement and the lock's change and error events. `Input.setLook` calls this from
+     * `Input.attach`.
+     */
+    attach(target: HTMLElement, dispatcher?: PointerDispatcher): void;
+    /** The dispatcher the look consumes from while attached (shared or private). */
+    private dispatcher;
+    /**
+     * The dispatcher consumer: touch pointers feed the zones and pinch; in orbit mode a mouse or
+     * pen primary button claims its pointer (so gestures and the router leave it alone) and, unless
+     * a linked `Input` feeds the drag, drives the orbit.
+     */
+    private readonly consumer;
+    /** A pointer went down: it may tap if it is the only one and the look takes it (see `onTap`). */
+    private tapDown;
+    private tapMove;
+    private tapUp;
+    /** Stop listening, release the lock and drop every touch. */
+    detach(): void;
+}
+/** `new Look(opts)`: look controls, on `opts.clock` when given (ws/input-8). */
+export declare function createLook(opts?: LookOptions): Look;