@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/pointer-router.d.ts

@@ -0,0 +1,204 @@
+import type { Gestures } from './gestures.js';
+import type { PointerDispatcher } from './pointer-dispatch.js';
+import { type PointerDevice, type PointerSource, ScreenPointers, type XrButtons } from './pointer-sources.js';
+import { type HitTester, type PickHit, type Ray, type RayCamera } from './rays.js';
+import type { Hand, PointerButton, PointerTransform, XrButton } from './types.js';
+/** One live pointer after routing: its sample plus its nearest hit. Reused; read, don't keep. */
+export interface RoutedPointer<T = unknown> {
+    readonly source: PointerSource;
+    readonly key: number;
+    readonly device: PointerDevice;
+    readonly hand: Hand | null;
+    /** Camera screen units, or `NaN` for XR pointers. */
+    readonly x: number;
+    readonly y: number;
+    readonly ray: Ray;
+    readonly select: boolean;
+    readonly secondary: boolean;
+    readonly xr: Readonly<XrButtons> | null;
+    /** The nearest hit this tick, or `null`. */
+    readonly hit: PickHit<T> | null;
+}
+/** Payload of every router event. Reused between emits: read it in the listener or copy it. */
+export interface PointerHitEvent<T = unknown> {
+    pointer: RoutedPointer<T>;
+    /** `hit`/`hitEnd`: the hit that started or ended. `select`/`secondary`: the pointer's hit, or `null`. */
+    hit: PickHit<T> | null;
+}
+export interface PointerRouterEvents<T = unknown> {
+    /** A pointer started hitting a target (or moved onto a different one). */
+    hit: PointerHitEvent<T>;
+    /** A pointer stopped hitting a target (moved off, ended, or input was blocked). */
+    hitEnd: PointerHitEvent<T>;
+    /** Select on a pointer (see `PointerRouterOptions.selectAction`). */
+    select: PointerHitEvent<T>;
+    /** Secondary on a pointer (see `PointerRouterOptions.secondaryAction`). */
+    secondary: PointerHitEvent<T>;
+    /**
+     * A pointer moved this tick (position or ray changed), at most once per pointer per tick,
+     * after its `hit`/`hitEnd` (ws/input-4). `hit` is the target under it now, or `null`.
+     */
+    moved: PointerHitEvent<T>;
+    /** A pointer's select or secondary button went up this tick (`hit` is what it is over now). */
+    released: PointerHitEvent<T>;
+}
+export interface PointerRouterOptions<T = unknown> {
+    /** The camera rays go through: a camera, or a getter read each tick (`() => renderer.camera`). */
+    camera?: RayCamera | (() => RayCamera | null) | null;
+    /** Hit testers, in tie-break order (see `addTester`). */
+    testers?: readonly HitTester<T>[];
+    /** Extra sources besides the built-in screen source (`router.screen`), e.g. a `PadCursor`. */
+    sources?: readonly PointerSource[];
+    /**
+     * The action that selects, when the router is linked to an `Input` (`input.setPointers`) whose
+     * bindings have it: `select` then fires on the tick that action is pressed, on the primary
+     * pointer. Unbound or unlinked, `select` fires when a pointer's select button goes down.
+     * Default `'select'`.
+     */
+    selectAction?: string;
+    /** Like `selectAction`, for `secondary`. Default `'secondary'`. */
+    secondaryAction?: string;
+    /** While true no pointer hits anything (a modal is open). `Input.setPointers` shares the input's. */
+    blocked?: () => boolean;
+}
+/** The slice of `Input` the router reads after the actions are evaluated. */
+export interface PointerActions {
+    bound(action: string): boolean;
+    pressed(action: string): boolean;
+}
+/**
+ * Routes pointers to hits. Call `update()` once per tick (an `Input` linked with
+ * `input.setPointers(router)` calls it from its own `update()`).
+ */
+export declare class PointerRouter<T = unknown> {
+    /** The built-in source for mouse, pen and touch (attached by `attach`). */
+    readonly screen: ScreenPointers;
+    /** Live pointers this tick (empty while blocked). Reused array. */
+    readonly pointers: RoutedPointer<T>[];
+    /** The pointer that moved or pressed most recently, or `null`. */
+    primary: RoutedPointer<T> | null;
+    blocked: () => boolean;
+    selectAction: string;
+    secondaryAction: string;
+    /**
+     * Typed over `unknown` targets, so the router is covariant in `T` (ws/input-12): a
+     * `PointerRouter<Target>` is a `PointerRouter<unknown>`, and `EngineCtx<A, S, C, unknown>`
+     * takes any typed ctx. `on` narrows the listeners back to `T`.
+     */
+    private readonly events;
+    private cameraOpt;
+    private readonly testers;
+    private readonly sources;
+    private readonly tracks;
+    private readonly pool;
+    private tick;
+    private isBlocked;
+    /**
+     * Live mutes, one entry per `mute()` call: `null` mutes every source (ones added later
+     * included), a list mutes those sources. A source is muted while any entry names it.
+     */
+    private readonly mutes;
+    /** Sources a mute's end just woke: their pointers held through the mute are not new presses. */
+    private readonly waking;
+    private target;
+    private readonly best;
+    private readonly bestNormal;
+    private readonly evHit;
+    private readonly evEnd;
+    private readonly evSelect;
+    private readonly evMoved;
+    private readonly evReleased;
+    constructor(opts?: PointerRouterOptions<T>);
+    /** The camera rays go through now. */
+    get camera(): RayCamera | null;
+    /** Set the camera, or a getter read each tick. */
+    set camera(c: RayCamera | (() => RayCamera | null) | null);
+    /** The primary pointer's hit, or `null`. */
+    get hit(): PickHit<T> | null;
+    on<K extends keyof PointerRouterEvents<T>>(type: K, fn: (e: PointerRouterEvents<T>[K]) => void): () => void;
+    /**
+     * Add a hit tester; returns its remover. The nearest hit over all testers wins; equal
+     * distances go to the tester added first.
+     */
+    addTester(t: HitTester<T>): () => void;
+    /** Add a pointer source (a `PadCursor`, an `XrPointerSource`); returns its remover. */
+    addSource(s: PointerSource): () => void;
+    /**
+     * Mute pointer sources (ws/input-11): a muted source is still polled, but its pointers are
+     * dropped before routing, so they hit nothing and fire nothing. With no argument every source
+     * is muted, the screen source and sources added later included. Samples marked `synthetic`
+     * (the pointers `Input.replayPointer` dispatches) are never muted, so a replay keeps its own
+     * pointers while the real ones are silenced. A pointer that holds select or secondary when
+     * its source is muted is released on the next tick: `hitEnd`, then `released` with `hit:
+     * null` (it let go over nothing, as a cancel), and `held` reads false.
+     *
+     * Returns the remover (ws/api-core): it lifts this mute only, so a game's mute and a replay's
+     * mute do not clear each other; a source stays muted while another mute names it. Calling it
+     * twice, or after `unmute()`, does nothing.
+     */
+    mute(sources?: readonly PointerSource[]): () => void;
+    /**
+     * Lift every mute, the removers' included. A button a woken pointer still holds reads up (not
+     * held, not pressed) until it is let go, so a press held through the mute never lands as a new
+     * one; its next press does.
+     */
+    unmute(): void;
+    /** True while `source` is muted (by `mute()` or `mute([source])`). */
+    isMuted(source: PointerSource): boolean;
+    /** The sources muted now (current sources for a mute-all, listed ones otherwise). */
+    private mutedNow;
+    /** Mark every source of `before` that is no longer muted as just woken. */
+    private wake;
+    /** Client → camera screen units for the screen source (`Input.setPointers` shares the input's). */
+    setPointerTransform(fn: PointerTransform | null): void;
+    /** Gestures whose magnify aim steers a single touch (`Input.setPointers` shares the input's). */
+    setGestures(g: Gestures | null): void;
+    /** Listen on `target` (every source with an `attach`). `Input.attach` does this when linked. */
+    attach(target: HTMLElement, dispatcher?: PointerDispatcher): void;
+    detach(): void;
+    /**
+     * True while any pointer holds `button`. Raw: it keeps tracking while blocked (as `Input`'s
+     * keys do), so a press held through a block is not a new press after it.
+     */
+    held(button: PointerButton): boolean;
+    /** True when a pointer pressed `button` this tick (never while blocked). */
+    fired(button: PointerButton): boolean;
+    /** True while an XR pointer (in `hand`, or either) holds `button`. Raw, like `held`. */
+    xrHeld(button: XrButton, hand?: Hand): boolean;
+    /** True when an XR pointer (in `hand`, or either) pressed `button` this tick. */
+    xrFired(button: XrButton, hand?: Hand): boolean;
+    /**
+     * Poll every source, hit-test each pointer and report hover changes, then report presses
+     * (button edges; a linked `Input` reports them from its actions instead, see `selectAction`).
+     */
+    update(): void;
+    /**
+     * First half of `update()`: sources, rays, hits, `hit`/`hitEnd`. `Input` calls it before
+     * evaluating `{ pointer }` and `{ xr }` bindings.
+     */
+    poll(): void;
+    /**
+     * Second half of `update()`: `select` and `secondary`. With `actions` (a linked `Input`), an
+     * action the bindings have fires on the primary pointer when pressed; otherwise each pointer
+     * whose button went down fires.
+     */
+    resolve(actions: PointerActions | null): void;
+    private resolveButton;
+    /** End `t`'s held buttons and report `released` (over nothing) unless blocked. */
+    private release;
+    /**
+     * `quiet`: the source was just unmuted, so a button a new track already holds was held through
+     * the mute: it reads up (not held, never a press) until it is let go, as a key held through a
+     * detach does.
+     */
+    private route;
+    /** Nearest hit for `t`'s ray; report `hitEnd`/`hit` when the target changes. */
+    private test;
+    private endHit;
+    private newTrack;
+}
+/**
+ * A pointer router (see `PointerRouter`). Link it to the action map with
+ * `input.setPointers(router)`; add `planeTester`/`aabbTester` or the game's own testers.
+ */
+export declare function createPointerRouter<T = unknown>(opts?: PointerRouterOptions<T>): PointerRouter<T>;