@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/pointer-router.js

@@ -0,0 +1,533 @@
+/**
+ * The pointer router: every pointing source (mouse, pen, touch, the pad cursor, XR controllers
+ * and hands through `XrPointerSource`) becomes a world-space ray through the active camera; the
+ * game's `HitTester`s say what each ray hits; the router keeps the nearest hit per pointer and
+ * reports `hit`, `hitEnd`, `select` and `secondary`. A game reads the hit and the `select`
+ * action; it never sees which device pointed.
+ */
+import { Emitter } from '../core/events.js';
+import { ScreenPointers, } from './pointer-sources.js';
+import { createHit, createRay, } from './rays.js';
+const XR_BUTTONS = ['trigger', 'squeeze', 'pinch'];
+/**
+ * Routes pointers to hits. Call `update()` once per tick (an `Input` linked with
+ * `input.setPointers(router)` calls it from its own `update()`).
+ */
+export class PointerRouter {
+    /** The built-in source for mouse, pen and touch (attached by `attach`). */
+    screen = new ScreenPointers();
+    /** Live pointers this tick (empty while blocked). Reused array. */
+    pointers = [];
+    /** The pointer that moved or pressed most recently, or `null`. */
+    primary = null;
+    blocked;
+    selectAction;
+    secondaryAction;
+    /**
+     * 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`.
+     */
+    events = new Emitter();
+    cameraOpt;
+    testers = [];
+    sources = [];
+    tracks = [];
+    pool = [];
+    tick = 0;
+    isBlocked = false;
+    /**
+     * 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.
+     */
+    mutes = [];
+    /** Sources a mute's end just woke: their pointers held through the mute are not new presses. */
+    waking = [];
+    target = null;
+    best = createHit(undefined);
+    bestNormal = [0, 0, 0];
+    evHit = { pointer: null, hit: null };
+    evEnd = { pointer: null, hit: null };
+    evSelect = { pointer: null, hit: null };
+    evMoved = { pointer: null, hit: null };
+    evReleased = { pointer: null, hit: null };
+    constructor(opts = {}) {
+        this.cameraOpt = opts.camera ?? null;
+        this.blocked = opts.blocked ?? (() => false);
+        this.selectAction = opts.selectAction ?? 'select';
+        this.secondaryAction = opts.secondaryAction ?? 'secondary';
+        this.sources.push(this.screen);
+        for (const s of opts.sources ?? [])
+            this.sources.push(s);
+        for (const t of opts.testers ?? [])
+            this.testers.push(t);
+    }
+    /** The camera rays go through now. */
+    get camera() {
+        const c = this.cameraOpt;
+        return typeof c === 'function' ? c() : c;
+    }
+    /** Set the camera, or a getter read each tick. */
+    set camera(c) {
+        this.cameraOpt = c;
+    }
+    /** The primary pointer's hit, or `null`. */
+    get hit() {
+        return this.primary?.hit ?? null;
+    }
+    on(type, fn) {
+        return this.events.on(type, fn);
+    }
+    /**
+     * Add a hit tester; returns its remover. The nearest hit over all testers wins; equal
+     * distances go to the tester added first.
+     */
+    addTester(t) {
+        this.testers.push(t);
+        return () => {
+            const i = this.testers.indexOf(t);
+            if (i >= 0)
+                this.testers.splice(i, 1);
+        };
+    }
+    /** Add a pointer source (a `PadCursor`, an `XrPointerSource`); returns its remover. */
+    addSource(s) {
+        this.sources.push(s);
+        if (this.target)
+            s.attach?.(this.target);
+        return () => {
+            const i = this.sources.indexOf(s);
+            if (i < 0)
+                return;
+            this.sources.splice(i, 1);
+            s.detach?.();
+        };
+    }
+    /**
+     * 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) {
+        const entry = sources ? sources.slice() : null;
+        this.mutes.push(entry);
+        return () => {
+            const i = this.mutes.indexOf(entry);
+            if (i < 0)
+                return;
+            const before = this.mutedNow();
+            this.mutes.splice(i, 1);
+            this.wake(before);
+        };
+    }
+    /**
+     * 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() {
+        if (this.mutes.length === 0)
+            return;
+        const before = this.mutedNow();
+        this.mutes.length = 0;
+        this.wake(before);
+    }
+    /** True while `source` is muted (by `mute()` or `mute([source])`). */
+    isMuted(source) {
+        const mutes = this.mutes;
+        for (let i = 0; i < mutes.length; i++) {
+            const m = mutes[i];
+            if (m === null || m.includes(source))
+                return true;
+        }
+        return false;
+    }
+    /** The sources muted now (current sources for a mute-all, listed ones otherwise). */
+    mutedNow() {
+        const out = [];
+        for (const s of this.sources)
+            if (this.isMuted(s))
+                out.push(s);
+        for (const m of this.mutes) {
+            if (m)
+                for (const s of m)
+                    if (!out.includes(s))
+                        out.push(s);
+        }
+        return out;
+    }
+    /** Mark every source of `before` that is no longer muted as just woken. */
+    wake(before) {
+        for (const s of before) {
+            if (!this.isMuted(s) && !this.waking.includes(s))
+                this.waking.push(s);
+        }
+    }
+    /** Client → camera screen units for the screen source (`Input.setPointers` shares the input's). */
+    setPointerTransform(fn) {
+        this.screen.setPointerTransform(fn);
+    }
+    /** Gestures whose magnify aim steers a single touch (`Input.setPointers` shares the input's). */
+    setGestures(g) {
+        this.screen.setGestures(g);
+    }
+    /** Listen on `target` (every source with an `attach`). `Input.attach` does this when linked. */
+    attach(target, dispatcher) {
+        this.detach();
+        this.target = target;
+        for (const s of this.sources)
+            s.attach?.(target, dispatcher);
+    }
+    detach() {
+        if (!this.target)
+            return;
+        this.target = null;
+        for (const s of this.sources)
+            s.detach?.();
+    }
+    // ---------------------------------------------------------------- queries
+    /**
+     * 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) {
+        for (const t of this.tracks)
+            if (button === 'select' ? t.select : t.secondary)
+                return true;
+        return false;
+    }
+    /** True when a pointer pressed `button` this tick (never while blocked). */
+    fired(button) {
+        for (const p of this.pointers) {
+            const t = p;
+            if (button === 'select' ? t.pressSelect : t.pressSecondary)
+                return true;
+        }
+        return false;
+    }
+    /** True while an XR pointer (in `hand`, or either) holds `button`. Raw, like `held`. */
+    xrHeld(button, hand) {
+        for (const t of this.tracks) {
+            if (t.xr && (!hand || t.hand === hand) && t.xr[button])
+                return true;
+        }
+        return false;
+    }
+    /** True when an XR pointer (in `hand`, or either) pressed `button` this tick. */
+    xrFired(button, hand) {
+        if (this.isBlocked)
+            return false;
+        for (const p of this.pointers) {
+            const t = p;
+            if (t.xr && (!hand || t.hand === hand) && t.xr[button] && !t.xrPrev[button])
+                return true;
+        }
+        return false;
+    }
+    // ---------------------------------------------------------------- tick
+    /**
+     * 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() {
+        this.poll();
+        this.resolve(null);
+    }
+    /**
+     * First half of `update()`: sources, rays, hits, `hit`/`hitEnd`. `Input` calls it before
+     * evaluating `{ pointer }` and `{ xr }` bindings.
+     */
+    poll() {
+        this.tick++;
+        const blocked = this.blocked();
+        this.isBlocked = blocked;
+        const camera = this.camera;
+        for (const t of this.tracks)
+            t.seen = false;
+        for (const src of this.sources) {
+            const samples = src.poll(camera);
+            const muted = this.isMuted(src);
+            const woken = this.waking.includes(src);
+            for (let i = 0; i < samples.length; i++) {
+                const s = samples[i];
+                if (muted && !s.synthetic)
+                    continue;
+                this.route(src, s, blocked, woken);
+            }
+        }
+        this.waking.length = 0;
+        // Pointers that were not reported have ended.
+        for (let i = 0; i < this.tracks.length; i++) {
+            const t = this.tracks[i];
+            if (t.seen)
+                continue;
+            this.endHit(t);
+            // A muted pointer holding a button lets go over nothing, never a stuck press.
+            if ((t.select || t.secondary) && this.isMuted(t.source))
+                this.release(t, blocked);
+            if (this.primary === t)
+                this.primary = null;
+            this.tracks.splice(i--, 1);
+            this.pool.push(t);
+        }
+        const list = this.pointers;
+        list.length = 0;
+        if (blocked) {
+            this.primary = null;
+            return;
+        }
+        let primary = null;
+        for (const t of this.tracks) {
+            list.push(t);
+            if (!primary || t.active > primary.active)
+                primary = t;
+        }
+        this.primary = primary;
+    }
+    /**
+     * 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) {
+        if (this.pointers.length === 0)
+            return;
+        this.resolveButton('select', this.selectAction, actions);
+        this.resolveButton('secondary', this.secondaryAction, actions);
+    }
+    resolveButton(kind, action, actions) {
+        const ev = this.evSelect;
+        if (actions?.bound(action)) {
+            const p = this.primary;
+            if (!p || !actions.pressed(action))
+                return;
+            ev.pointer = p;
+            ev.hit = p.hit;
+            this.events.emit(kind, ev);
+            return;
+        }
+        for (const p of this.pointers) {
+            const t = p;
+            if (!(kind === 'select' ? t.pressSelect : t.pressSecondary))
+                continue;
+            ev.pointer = t;
+            ev.hit = t.hit;
+            this.events.emit(kind, ev);
+        }
+    }
+    /** End `t`'s held buttons and report `released` (over nothing) unless blocked. */
+    release(t, blocked) {
+        t.prevSelect = t.select;
+        t.prevSecondary = t.secondary;
+        t.select = false;
+        t.secondary = false;
+        t.pressSelect = false;
+        t.pressSecondary = false;
+        if (t.xr)
+            for (const b of XR_BUTTONS)
+                t.xrPrev[b] = t.xr[b] = false;
+        if (blocked)
+            return;
+        const ev = this.evReleased;
+        ev.pointer = t;
+        ev.hit = null;
+        this.events.emit('released', ev);
+    }
+    /**
+     * `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.
+     */
+    route(src, s, blocked, quiet) {
+        let t = null;
+        for (const c of this.tracks) {
+            if (c.source === src && c.key === s.key) {
+                t = c;
+                break;
+            }
+        }
+        const isNew = t === null;
+        if (!t) {
+            t = this.pool.pop() ?? this.newTrack();
+            t.source = src;
+            t.key = s.key;
+            t.maskSelect = quiet && s.select;
+            t.maskSecondary = quiet && s.secondary;
+            for (const b of XR_BUTTONS)
+                t.xrMask[b] = quiet && s.xr?.[b] === true;
+            t.hit = null;
+            this.tracks.push(t);
+        }
+        else {
+            t.prevSelect = t.select;
+            t.prevSecondary = t.secondary;
+        }
+        t.seen = true;
+        if (!s.select)
+            t.maskSelect = false;
+        if (!s.secondary)
+            t.maskSecondary = false;
+        const select = s.select && !t.maskSelect;
+        const secondary = s.secondary && !t.maskSecondary;
+        if (isNew) {
+            t.prevSelect = select && blocked;
+            t.prevSecondary = secondary && blocked;
+        }
+        const ray = t.ray;
+        const moved = isNew ||
+            s.x !== t.x ||
+            s.y !== t.y ||
+            s.ray.origin[0] !== ray.origin[0] ||
+            s.ray.origin[1] !== ray.origin[1] ||
+            s.ray.origin[2] !== ray.origin[2] ||
+            s.ray.dir[0] !== ray.dir[0] ||
+            s.ray.dir[1] !== ray.dir[1] ||
+            s.ray.dir[2] !== ray.dir[2];
+        t.device = s.device;
+        t.hand = s.hand;
+        t.x = s.x;
+        t.y = s.y;
+        for (let i = 0; i < 3; i++) {
+            ray.origin[i] = s.ray.origin[i];
+            ray.dir[i] = s.ray.dir[i];
+        }
+        if (s.xr) {
+            const prev = t.xr ? t.xrStore : null;
+            for (const b of XR_BUTTONS) {
+                if (!s.xr[b])
+                    t.xrMask[b] = false;
+                const v = s.xr[b] && !t.xrMask[b];
+                t.xrPrev[b] = prev ? prev[b] : blocked && v;
+                t.xrStore[b] = v;
+            }
+            t.xr = t.xrStore;
+        }
+        else {
+            t.xr = null;
+        }
+        // While blocked buttons track (so a press held through the block is not a new press), but
+        // nothing is pressed and nothing is hit.
+        t.select = select;
+        t.secondary = secondary;
+        t.pressSelect = !blocked && select && !t.prevSelect;
+        t.pressSecondary = !blocked && secondary && !t.prevSecondary;
+        if (moved || t.pressSelect || t.pressSecondary)
+            t.active = this.tick;
+        if (blocked) {
+            this.endHit(t);
+            return;
+        }
+        this.test(t);
+        if (moved) {
+            const ev = this.evMoved;
+            ev.pointer = t;
+            ev.hit = t.hit;
+            this.events.emit('moved', ev);
+        }
+        if ((t.prevSelect && !select) || (t.prevSecondary && !secondary)) {
+            const ev = this.evReleased;
+            ev.pointer = t;
+            ev.hit = t.hit;
+            this.events.emit('released', ev);
+        }
+    }
+    /** Nearest hit for `t`'s ray; report `hitEnd`/`hit` when the target changes. */
+    test(t) {
+        const best = this.best;
+        let found = false;
+        for (const tester of this.testers) {
+            const h = tester(t.ray);
+            if (!h || (found && h.distance >= best.distance))
+                continue;
+            found = true;
+            copyHit(best, this.bestNormal, h);
+        }
+        const prev = t.hit;
+        if (!found) {
+            this.endHit(t);
+            return;
+        }
+        const changed = !prev || prev.target !== best.target;
+        if (changed)
+            this.endHit(t);
+        copyHit(t.store, t.storeNormal, best);
+        t.hit = t.store;
+        if (changed) {
+            const ev = this.evHit;
+            ev.pointer = t;
+            ev.hit = t.hit;
+            this.events.emit('hit', ev);
+        }
+    }
+    endHit(t) {
+        if (!t.hit)
+            return;
+        copyHit(t.ended, t.endedNormal, t.hit);
+        t.hit = null;
+        const ev = this.evEnd;
+        ev.pointer = t;
+        ev.hit = t.ended;
+        this.events.emit('hitEnd', ev);
+    }
+    newTrack() {
+        return {
+            source: this.screen,
+            key: 0,
+            device: 'mouse',
+            hand: null,
+            x: Number.NaN,
+            y: Number.NaN,
+            ray: createRay(),
+            select: false,
+            secondary: false,
+            xr: null,
+            hit: null,
+            store: createHit(undefined),
+            storeNormal: [0, 0, 0],
+            ended: createHit(undefined),
+            endedNormal: [0, 0, 0],
+            xrStore: { trigger: false, squeeze: false, pinch: false },
+            xrPrev: { trigger: false, squeeze: false, pinch: false },
+            seen: false,
+            prevSelect: false,
+            prevSecondary: false,
+            maskSelect: false,
+            maskSecondary: false,
+            xrMask: { trigger: false, squeeze: false, pinch: false },
+            pressSelect: false,
+            pressSecondary: false,
+            active: 0,
+        };
+    }
+}
+function copyHit(dst, normal, src) {
+    dst.point[0] = src.point[0];
+    dst.point[1] = src.point[1];
+    dst.point[2] = src.point[2];
+    dst.distance = src.distance;
+    dst.target = src.target;
+    if (src.normal) {
+        normal[0] = src.normal[0];
+        normal[1] = src.normal[1];
+        normal[2] = src.normal[2];
+        dst.normal = normal;
+    }
+    else {
+        dst.normal = null;
+    }
+}
+/**
+ * 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 function createPointerRouter(opts = {}) {
+    return new PointerRouter(opts);
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Pointer sources for the router (`pointer-router.ts`): the `PointerSource` seam, the screen
+ * source (mouse, pen, touch from DOM pointer events) and the pad cursor (a virtual pointer moved
+ * by a gamepad stick). XR controllers and hands are `XrPointerSource` (`xr-source.ts`),
+ * which `createGame({ xr })` adds.
+ */
+import type { Gestures } from './gestures.js';
+import { type PointerDispatcher } from './pointer-dispatch.js';
+import { type Ray, type RayCamera } from './rays.js';
+import type { GamepadLike, Hand, PointerTransform } from './types.js';
+/** What made a routed pointer. */
+export type PointerDevice = 'mouse' | 'touch' | 'pen' | 'gamepad' | 'xr';
+/** XR button state of one controller or hand (pressed or not; the source applies thresholds). */
+export interface XrButtons {
+    trigger: boolean;
+    squeeze: boolean;
+    pinch: boolean;
+}
+/**
+ * One pointer at one tick, as a source reports it. The source owns the object and reuses it.
+ */
+export interface PointerSample {
+    /** Unique within its source and stable while the pointer lives (a pointer id, 0, a hand index). */
+    key: number;
+    device: PointerDevice;
+    /** The hand of an XR pointer; `null` for everything else. */
+    hand: Hand | null;
+    /** World-space ray, `dir` unit length. */
+    readonly ray: Ray;
+    /** The screen point the ray goes through (camera screen units), or `NaN` for XR pointers. */
+    x: number;
+    y: number;
+    /** Primary button held: mouse 0, a touch or pen contact, the pad cursor's press, XR trigger or pinch. */
+    select: boolean;
+    /** Secondary button held: mouse 2, the pad cursor's second button, XR squeeze. */
+    secondary: boolean;
+    /** XR button state; `null` for pointers that are not XR. */
+    xr: XrButtons | null;
+    /**
+     * A replay made this pointer (`Input.replayPointer`; ws/input-11): `PointerRouter.mute` never
+     * drops it. Absent or false for real pointers.
+     */
+    synthetic?: boolean;
+}
+/**
+ * Something that points. The router polls every source once per tick, before hit testing.
+ *
+ * `poll` returns this tick's live pointers. The source owns the array and the samples and reuses
+ * them (no allocation per tick); the router reads them before the next `poll`. A pointer whose
+ * `key` is missing from a poll has ended. `camera` is the router's active camera (or `null`):
+ * screen sources build their rays through it, world-space sources (XR) ignore it.
+ *
+ * Optional hooks: `attach`/`detach` when the router attaches to (or leaves) a pointer target.
+ */
+export interface PointerSource {
+    poll(camera: RayCamera | null): readonly PointerSample[];
+    /** `dispatcher` is the one the linked `Input` built (ws/input-4); absent when attached alone. */
+    attach?(target: HTMLElement, dispatcher?: PointerDispatcher): void;
+    detach?(): void;
+}
+export declare function createSample(key: number, device: PointerDevice): PointerSample;
+interface Contact {
+    id: number;
+    device: 'mouse' | 'touch' | 'pen';
+    /** Client CSS px (or target-relative without a transform). */
+    cx: number;
+    cy: number;
+    select: boolean;
+    secondary: boolean;
+    /** The select button went down since the last poll (a press shorter than a tick still counts). */
+    tapped: boolean;
+    /** The pointer ended; it is reported once more (its last position), then dropped. */
+    gone: boolean;
+    /** Ended by a cancel or a hover leaving: dropped without the last report. */
+    cancelled: boolean;
+    /** Made by a replay (`PointerRecord.synthetic`); see `PointerSample.synthetic`. */
+    synthetic: boolean;
+    sample: PointerSample;
+}
+/**
+ * Mouse, pen and touch as router pointers. Mouse and pen hover (a pointer while over the
+ * target); touch is a pointer only while the finger is down, plus one more tick after it lifts so
+ * a tap's tick still sees what it was on. Positions go through the pointer transform into the
+ * camera's screen units. With linked `Gestures` that have `magnify`, a single touch points at the
+ * gesture's aim (the snapped target's centre, else the lifted aim point) instead of the finger.
+ *
+ * Feed methods (`pointerDown`, `pointerMove`, `pointerUp`, `pointerLeave`, `pointerCancel`,
+ * `cancelAll`) take client coordinates and are public for tests and replays. `synthetic` on
+ * `pointerDown`/`pointerMove` marks a replayed pointer (see `PointerSample.synthetic`).
+ */
+export declare class ScreenPointers implements PointerSource {
+    private transform;
+    private gestures;
+    private readonly contacts;
+    private readonly out;
+    private detachFn;
+    /**
+     * Hides a pointer from `poll` while it reads true: installed by `attach` with a dispatcher as
+     * "claimed and not `hoverWhileClaimed`", so an orbit drag or a touch-zone thumb produces no
+     * hits until it is released. Public so tests can stand one in.
+     */
+    claim: ((id: number) => boolean) | null;
+    setPointerTransform(fn: PointerTransform | null): void;
+    setGestures(g: Gestures | null): void;
+    pointerDown(id: number, x: number, y: number, device?: Contact['device'], button?: number, synthetic?: boolean): void;
+    pointerMove(id: number, x: number, y: number, device?: Contact['device'], synthetic?: boolean): void;
+    pointerUp(id: number, x: number, y: number, button?: number): void;
+    /** A hovering mouse or pen left the target. */
+    pointerLeave(id: number): void;
+    pointerCancel(id: number): void;
+    cancelAll(): void;
+    poll(camera: RayCamera | null): readonly PointerSample[];
+    /**
+     * Listen to pointer events on `target` (the router calls this from its `attach`). Positions are
+     * client px with a transform, target-relative px without one.
+     */
+    attach(target: HTMLElement, dispatcher?: PointerDispatcher): void;
+    private ownDispatcher;
+    private readonly consumer;
+    detach(): void;
+    private find;
+    private contact;
+}
+export interface PadCursorOptions {
+    /** Gamepad source. Default: `navigator.getGamepads()` (guarded). */
+    getGamepads?: () => readonly (GamepadLike | null)[];
+    /** Pad index; omitted = any pad (the first deflected stick wins). */
+    pad?: number;
+    /** Stick axes [x, y]. Default [0, 1] (the left stick). */
+    axes?: readonly [number, number];
+    /** Stick deflection ignored below this. Default 0.2. */
+    deadzone?: number;
+    /**
+     * Travel per tick at full deflection, as a fraction of the screen's shorter side. Default
+     * 0.012 (about 0.7 of it per second at 60 ticks).
+     */
+    speed?: number;
+    /** Standard-mapping button that is the cursor's `select`. Default 0 (A / Cross). */
+    selectButton?: number;
+    /** Button that is the cursor's `secondary`. Default 2 (X / Square). */
+    secondaryButton?: number;
+}
+/**
+ * A virtual pointer a gamepad stick moves over the camera's screen, so a pad aims like a mouse.
+ * It appears (at the screen centre) the first time its stick passes the deadzone or its select
+ * button is pressed, then stays until `hide()`. `x`, `y` are camera screen units.
+ */
+export declare class PadCursor implements PointerSource {
+    x: number;
+    y: number;
+    /** True while the cursor is shown (it reports a pointer). */
+    active: boolean;
+    private readonly getGamepads;
+    private readonly opts;
+    private readonly sample;
+    private readonly out;
+    constructor(opts?: PadCursorOptions);
+    /** Put the cursor at a screen point and show it. */
+    moveTo(x: number, y: number): void;
+    /** Hide the cursor (for example when the mouse moves); the stick shows it again. */
+    hide(): void;
+    poll(camera: RayCamera | null): readonly PointerSample[];
+}
+export {};