@codexo/exojs 0.7.12 → 0.8.0

package/dist/esm/input/Gamepad.d.ts

@@ -1,12 +1,13 @@
 import { Signal } from '@/core/Signal';
-import type { GamepadChannel } from './GamepadChannels';
+import { InputBinding } from './InputBinding';
+import type { GamepadAxis } from './GamepadAxis';
+import type { GamepadButton } from './GamepadButton';
+import type { GamepadButtonChannel } from './GamepadButton';
+import type { GamepadAxisChannel } from './GamepadAxis';
 import type { BrowserGamepad, ResolvedGamepadDefinition } from './GamepadDefinitions';
 import type { GamepadMappingFamily, GamepadMapping } from './GamepadMapping';
-/**
- * Human-readable identity metadata for a connected gamepad.
- * Populated from a {@link ResolvedGamepadDefinition} on connect and available
- * through the matching getters on {@link Gamepad}.
- */
+import type { InputBindingOptions, InputChannel } from './InputBinding';
+/** Identity metadata for a connected gamepad. Populated from a {@link ResolvedGamepadDefinition}. */
 export interface GamepadInfo {
     name: string;
     label: string;
@@ -14,80 +15,181 @@ export interface GamepadInfo {
     productId: string | null;
     productKey: string | null;
 }
+/** Effect parameters for {@link Gamepad.vibrate}. */
+export interface GamepadVibrationOptions {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Low-frequency rumble intensity 0..1. Default 1. */
+    weakMagnitude?: number;
+    /** High-frequency rumble intensity 0..1. Default 1. */
+    strongMagnitude?: number;
+    /** Delay before rumble starts in ms. Default 0. */
+    startDelay?: number;
+}
 /**
- * Runtime wrapper for a single browser gamepad slot.
+ * One of four stable gamepad slots. Lives for the entire `Application`
+ * lifetime even when no physical pad is attached — a "mailbox" that
+ * physical hardware moves into and out of.
  *
- * Owns the slot's {@link GamepadMapping}, reads raw button and axis values from
- * the browser's Gamepad API each frame via {@link update}, and writes transformed
- * values into the shared `Float32Array` channel buffer. Emits {@link onConnect},
- * {@link onDisconnect}, and per-channel {@link onUpdate} signals so consumers can
- * react without polling.
+ * Subscribe to {@link onConnect} / {@link onDisconnect} for hardware
+ * lifecycle, {@link onButtonDown} / {@link onButtonUp} / {@link onAxisChange}
+ * for granular per-event notifications, or call {@link onTrigger} /
+ * {@link onActive} / {@link onStart} / {@link onStop} to register
+ * stateful {@link InputBinding}s pinned to this slot.
+ *
+ * Listeners survive disconnect/reconnect cycles — a binding registered when
+ * the slot was empty will automatically activate when a pad connects.
  */
 export declare class Gamepad {
-    readonly onConnect: Signal<[Gamepad]>;
-    readonly onDisconnect: Signal<[Gamepad]>;
-    readonly onUpdate: Signal<[GamepadChannel, number, Gamepad]>;
-    private readonly indexValue;
-    private readonly channelsValue;
-    private readonly channelOffset;
-    private mappingValue;
-    private browserGamepad;
-    private info;
-    constructor(index: number, channels: Float32Array, mapping: GamepadMapping);
-    constructor(gamepad: BrowserGamepad, channels: Float32Array, definition: ResolvedGamepadDefinition);
-    get mapping(): GamepadMapping;
-    set mapping(mapping: GamepadMapping);
-    /** The {@link GamepadMappingFamily} of the currently active mapping. */
-    get mappingFamily(): GamepadMappingFamily;
-    get channels(): Float32Array;
-    get gamepad(): BrowserGamepad | null;
-    get index(): number;
-    /** Whether a browser gamepad is currently attached to this slot. */
+    /** Fires when a physical pad connects to this slot. */
+    readonly onConnect: Signal<[]>;
+    /** Fires when the physical pad in this slot disconnects. */
+    readonly onDisconnect: Signal<[]>;
+    /** Fires for every button transition from inactive to active. */
+    readonly onButtonDown: Signal<[GamepadButton, number]>;
+    /** Fires for every button transition from active to inactive. */
+    readonly onButtonUp: Signal<[GamepadButton, number]>;
+    /** Fires whenever an axis crosses its activation threshold. */
+    readonly onAxisChange: Signal<[GamepadAxis, number]>;
+    /**
+     * Fires when this slot's physical pad has been replaced by a previously
+     * higher-numbered slot's pad, after a `'compact'`-strategy disconnect.
+     * Dispatched with the source slot index the pad came from. Listeners
+     * remain attached and the channel buffer is preserved across the move.
+     */
+    readonly onPadReassigned: Signal<[fromSlot: 0 | 1 | 2 | 3]>;
+    private readonly _slot;
+    private readonly _channels;
+    private readonly _bindings;
+    private readonly _detacher;
+    private readonly _channelOffset;
+    private _mapping;
+    private _info;
+    private _browserGamepad;
+    constructor(slot: 0 | 1 | 2 | 3, channels: Float32Array);
+    /** This pad's stable slot (0..3). */
+    get slot(): 0 | 1 | 2 | 3;
+    /** `true` while a physical pad is attached to this slot. */
     get connected(): boolean;
-    get name(): string;
-    get label(): string;
-    get vendorId(): string | null;
-    get productId(): string | null;
-    get productKey(): string | null;
+    /** The active mapping, or `null` when disconnected. */
+    get mapping(): GamepadMapping | null;
+    /** The {@link GamepadMappingFamily}, or `null` when disconnected. */
+    get mappingFamily(): GamepadMappingFamily | null;
+    /** Identity metadata, or `null` when disconnected. */
+    get info(): GamepadInfo | null;
+    /** The underlying browser gamepad object, or `null` when disconnected. */
+    get browserGamepad(): BrowserGamepad | null;
+    /**
+     * Browser-assigned hardware index from `navigator.getGamepads()` (i.e.
+     * `Gamepad.index`), or `null` when no pad is attached. Stable for the
+     * lifetime of a single physical connection but may change across
+     * disconnect/reconnect. Low-level escape hatch for advanced consumers
+     * that need to correlate slots with the raw browser API; prefer
+     * {@link slot} for stable per-application pad identity.
+     */
+    get internalIndex(): number | null;
+    /** `true` when the connected pad supports rumble via the Web Gamepad API. */
+    get canVibrate(): boolean;
+    /**
+     * Returns `true` when this pad's mapping declares the requested channel.
+     * Use to gate listener registration on optional hardware (e.g. Joy-Con
+     * solo lacks a right stick — `pad.hasChannel(GamepadAxis.RightStickX)`
+     * returns `false`).
+     */
+    hasChannel(channel: GamepadButtonChannel | GamepadAxisChannel): boolean;
+    /**
+     * Trigger a rumble effect on this pad. Resolves when the effect finishes.
+     * Silent no-op when the pad is disconnected or the platform does not
+     * support haptic feedback. Use {@link canVibrate} to detect support.
+     */
+    vibrate(options: GamepadVibrationOptions): Promise<void>;
+    /** Stop any active rumble on this pad. Silent no-op when unsupported. */
+    stopVibration(): void;
+    /**
+     * Register a callback fired once when any of `channels` becomes active.
+     * Listener survives disconnect/reconnect; call `.unbind()` on the
+     * returned {@link InputBinding} to detach.
+     */
+    onStart(channel: InputChannel | ReadonlyArray<InputChannel>, callback: (value: number) => void, options?: InputBindingOptions): InputBinding;
+    /**
+     * Register a callback fired every frame while any of `channels` is active.
+     * Receives the channel value (0..1 for buttons, -1..1 for bipolar axes).
+     */
+    onActive(channel: InputChannel | ReadonlyArray<InputChannel>, callback: (value: number) => void, options?: InputBindingOptions): InputBinding;
+    /** Register a callback fired once when all of `channels` become inactive. */
+    onStop(channel: InputChannel | ReadonlyArray<InputChannel>, callback: (value: number) => void, options?: InputBindingOptions): InputBinding;
+    /**
+     * Register a callback fired when the input is released within
+     * {@link InputBindingOptions.threshold} ms of activation (a "tap").
+     */
+    onTrigger(channel: InputChannel | ReadonlyArray<InputChannel>, callback: (value: number) => void, options?: InputBindingOptions): InputBinding;
+    /**
+     * Attach a physical browser gamepad to this slot. Called by
+     * {@link InputManager} on connect.
+     *
+     * @internal
+     */
+    _bind(gamepad: BrowserGamepad, definition: ResolvedGamepadDefinition): void;
+    /**
+     * Detach the physical gamepad and clear its channels.
+     *
+     * @internal
+     */
+    _unbind(): void;
     /**
-     * Replaces the gamepad's identity metadata.
-     * Called automatically during construction when a {@link BrowserGamepad} is
-     * provided; exposed publicly to allow runtime overrides.
+     * Detach the physical gamepad and clear channels without firing
+     * {@link onDisconnect}. Used by {@link InputManager} during the compact
+     * slot-shift to silently vacate a slot before another pad shifts into
+     * its place; the disconnect signal is fired separately on the slot that
+     * ends up empty after compaction.
+     *
+     * @internal
      */
-    setInfo(info: GamepadInfo): this;
+    _silentUnbind(): void;
     /**
-     * Attaches a live browser gamepad to this slot and dispatches {@link onConnect}
-     * if the slot was previously disconnected.
+     * Dispatch this slot's {@link onDisconnect} signal without altering its
+     * state. Used by {@link InputManager} after a compact-mode shift, when a
+     * slot has already been emptied by {@link _rebindFrom} and now needs to
+     * notify subscribers that its mailbox is no longer occupied.
+     *
+     * @internal
      */
-    connect(gamepad: BrowserGamepad): this;
+    _dispatchDisconnect(): void;
     /**
-     * Detaches the browser gamepad, zeros all mapped channels, and dispatches
-     * {@link onDisconnect}. No-op when already disconnected.
+     * Reassign this slot to take over another slot's physical gamepad without
+     * firing the full disconnect / connect cycle. Used by {@link InputManager}
+     * when the `'compact'` slot strategy shuffles pads after a disconnect.
+     *
+     * @internal
      */
-    disconnect(): this;
+    _rebindFrom(other: Gamepad): void;
     /**
-     * Samples the browser gamepad's current state and writes transformed values
-     * into the shared channel buffer, dispatching {@link onUpdate} for each channel
-     * whose value changed. Should be called once per frame by the engine's input loop.
-     * No-op when disconnected.
+     * Sample the browser gamepad's current state and write transformed values
+     * into the shared channel buffer, dispatching transition events when
+     * channel activity crosses thresholds. Called once per frame by the
+     * engine's input loop. No-op when disconnected.
+     *
+     * @internal
      */
-    update(): this;
-    /** Zeroes all channel buffer entries that belong to this gamepad's mapping. */
-    clearChannels(): this;
+    update(): void;
     /**
-     * Disconnects the gamepad, clears its channels, and destroys all signals.
-     * The instance must not be used after this call.
+     * Tear down this gamepad slot. Called on application shutdown.
      */
     destroy(): void;
     /**
-     * Converts a {@link GamepadChannel} to its absolute index in the shared channel
-     * buffer for this gamepad instance.
+     * Convert a slot-relative channel value to its absolute index in the
+     * shared channel buffer for this slot.
      */
-    resolveChannelOffset(channel: GamepadChannel): number;
+    resolveChannelOffset(channel: GamepadButtonChannel | GamepadAxisChannel): number;
     /**
-     * Converts a gamepad slot index and {@link GamepadChannel} to an absolute
-     * channel buffer offset without requiring a {@link Gamepad} instance.
+     * Static counterpart to {@link Gamepad.resolveChannelOffset} — resolves
+     * an absolute channel-buffer offset for a given slot index without
+     * requiring a Gamepad instance.
      */
-    static resolveChannelOffset(gamepadIndex: number, channel: GamepadChannel): number;
-    private clearMappedChannels;
+    static resolveChannelOffset(slot: number, channel: GamepadButtonChannel | GamepadAxisChannel): number;
+    private _resolveOffset;
+    private _clearMappedChannels;
+    private _createBinding;
+    private _resolveExternalChannel;
+    private _updateBindings;
 }