@directivegames/genesys.js 3.1.24

package/dist/src/systems/InputManager.d.ts

@@ -0,0 +1,511 @@
+/**
+ * InputManager centralizes keyboard, mouse, gamepad, and touch handling for Genesys.
+ *
+ * Detailed explanation:
+ * - Listens to DOM events and distributes them to registered `IInputHandler` implementations.
+ * - Tracks current input state, pointer lock, and provides helper queries for button presses.
+ * - Manages gamepad connections and polling so gameplay code can be agnostic of the hardware.
+ * - Provides touch input support with virtual joystick using nipplejs for mobile devices.
+ * - Detects and reports swipe and tap gestures with configurable thresholds.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Instantiate once per world and add your custom handlers via `addInputHandler`.
+ * - Use `requestPointerLock` in response to user interaction if your controls need exclusive mouse input.
+ * - Touch input is automatically enabled on mobile browsers detected by `isMobileBrowser()`.
+ * - Virtual joystick provides movement input for mobile devices and can be customized via options.
+ * - Swipe and tap gestures can be detected by implementing handleSwipe/handleTap or subscribing to onSwipe/onTap delegates.
+ * - Avoid directly reading DOM events; rely on this manager to ensure consistent behavior across platforms.
+ */
+import * as THREE from 'three';
+import { Delegate } from '../utils/Delegate.js';
+import type { World } from '../game/World';
+export type KeyboardEventDelegate = Delegate<[KeyboardEvent], boolean>;
+export type MouseEventDelegate = Delegate<[MouseButton, MouseEvent], boolean>;
+export type GamepadEventDelegate = Delegate<[Gamepad], void>;
+export type GamepadButtonEventDelegate = Delegate<[number, GamepadButton, number], boolean>;
+export type GamepadAxisEventDelegate = Delegate<[number, GamepadAxis, number], boolean>;
+export type VirtualJoystickEventDelegate = Delegate<[VirtualJoystickIndex, VirtualJoystickData], boolean>;
+export type SwipeEventDelegate = Delegate<[SwipeData], boolean>;
+export type TapEventDelegate = Delegate<[TapData], boolean>;
+/**
+ * Enum for mouse buttons
+ * @enum {number}
+ */
+export declare enum MouseButton {
+    Left = 0,
+    Middle = 1,
+    Right = 2
+}
+export declare enum VirtualJoystickIndex {
+    Left = 0,
+    Right = 1
+}
+/**
+ * Virtual joystick input data from nipplejs
+ */
+export interface VirtualJoystickData {
+    /** The type of joystick event */
+    type: 'start' | 'move' | 'end';
+    /** Joystick position */
+    position: THREE.Vector2;
+}
+/**
+ * Swipe direction enum
+ */
+export declare enum SwipeDirection {
+    Up = "up",
+    Down = "down",
+    Left = "left",
+    Right = "right"
+}
+/**
+ * Swipe gesture data
+ */
+export interface SwipeData {
+    /** The direction of the swipe */
+    direction: SwipeDirection;
+    /** The starting position of the swipe in screen coordinates */
+    startPosition: THREE.Vector2;
+    /** The ending position of the swipe in screen coordinates */
+    endPosition: THREE.Vector2;
+    /** The distance of the swipe in pixels */
+    distance: number;
+    /** The duration of the swipe in milliseconds */
+    duration: number;
+    /** The velocity of the swipe in pixels per second */
+    velocity: number;
+    /** The underlying touch event */
+    event: TouchEvent;
+}
+/**
+ * Tap gesture data
+ */
+export interface TapData {
+    /** The position of the tap in screen coordinates */
+    position: THREE.Vector2;
+    /** The position of the tap in NDC (Normalized Device Coordinates) */
+    normalizedPosition: THREE.Vector2;
+    /** The underlying touch event */
+    event: TouchEvent;
+}
+/**
+ * Interface for handling input events in the engine
+ * Implement this interface to create custom input handlers that can receive
+ * and process keyboard, mouse, gamepad, and touch events from the InputManager
+ */
+export interface IInputHandler {
+    /**
+     * Called when a key is pressed down
+     * @param e - The keyboard event containing key information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleKeyDown(e: KeyboardEvent): boolean;
+    /**
+     * Called when a key is released
+     * @param e - The keyboard event containing key information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleKeyUp(e: KeyboardEvent): boolean;
+    /**
+     * Called when a mouse button is pressed down
+     * @param button - The mouse button that was pressed
+     * @param e - The mouse event containing button and position information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleMouseDown(button: MouseButton, e: MouseEvent): boolean;
+    /**
+     * Called when a mouse button is released
+     * @param button - The mouse button that was released
+     * @param e - The mouse event containing button and position information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleMouseUp(button: MouseButton, e: MouseEvent): boolean;
+    /**
+     * Called when the mouse is moved
+     * @param e - The mouse event containing movement and position information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleMouseMove(e: MouseEvent): boolean;
+    /**
+     * Called when a mouse click is detected (down + up on same element)
+     * @param button - The mouse button that was clicked
+     * @param e - The mouse event containing click information
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleMouseClick(button: MouseButton, e: MouseEvent): boolean;
+    /**
+     * Called when a gamepad button is pressed down
+     * @param gamepadIndex - The index of the gamepad
+     * @param buttonIndex - The index of the button
+     * @param value - The value of the button press (0.0 to 1.0)
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleGamepadButtonDown?(gamepadIndex: number, buttonIndex: GamepadButton, value: number): boolean;
+    /**
+     * Called when a gamepad button is released
+     * @param gamepadIndex - The index of the gamepad
+     * @param buttonIndex - The index of the button
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleGamepadButtonUp?(gamepadIndex: number, buttonIndex: GamepadButton): boolean;
+    /**
+     * Called when a gamepad axis changes value
+     * @param gamepadIndex - The index of the gamepad
+     * @param axisIndex - The index of the axis
+     * @param value - The value of the axis (-1.0 to 1.0)
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleGamepadAxisChange?(gamepadIndex: number, axisIndex: GamepadAxis, value: number): boolean;
+    /**
+     * Called when a virtual joystick event occurs (from nipplejs)
+     * @param index - The index of the virtual joystick
+     * @param joystickData - The virtual joystick data containing position, distance, and angle
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleVirtualJoystick?(index: VirtualJoystickIndex, joystickData: VirtualJoystickData): boolean;
+    /**
+     * Called when a swipe gesture is detected
+     * @param swipeData - The swipe data containing direction, distance, velocity, etc.
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleSwipe?(swipeData: SwipeData): boolean;
+    /**
+     * Called when a tap gesture is detected
+     * @param tapData - The tap data containing position and normalized coordinates
+     * @returns Should return true to stop event propagation to other handlers,
+     *          or false to allow other handlers to process the event
+     */
+    handleTap?(tapData: TapData): boolean;
+    /**
+     * Called when the handler is added to or removed from an InputManager
+     * @param manager - The InputManager instance when being added,
+     *                  or null when being removed
+     */
+    setInputManager(manager: InputManager | null): void;
+}
+/**
+ * Enumeration for standard gamepad buttons
+ */
+export declare enum GamepadButton {
+    FaceBottom = 0,// Usually A on Xbox, X on PlayStation
+    FaceRight = 1,// Usually B on Xbox, Circle on PlayStation
+    FaceLeft = 2,// Usually X on Xbox, Square on PlayStation
+    FaceTop = 3,// Usually Y on Xbox, Triangle on PlayStation
+    LeftBumper = 4,
+    RightBumper = 5,
+    LeftTrigger = 6,
+    RightTrigger = 7,
+    Select = 8,
+    Start = 9,
+    LeftStick = 10,
+    RightStick = 11,
+    DpadUp = 12,
+    DpadDown = 13,
+    DpadLeft = 14,
+    DpadRight = 15
+}
+/**
+ * Enumeration for standard gamepad axes
+ */
+export declare enum GamepadAxis {
+    LeftStickX = 0,
+    LeftStickY = 1,
+    RightStickX = 2,
+    RightStickY = 3
+}
+/**
+ * Configuration options for initializing an InputManager instance
+ */
+export interface InputManagerOptions {
+    /**
+     * The DOM element that will receive mouse input events
+     * Typically this is the renderer's DOM element
+     */
+    rendererDomElement: HTMLElement;
+    /**
+     * The DOM element that will receive touch input events
+     * Typically this is the game container
+     */
+    gameContainer: HTMLElement;
+    /**
+     * The World instance that this input manager belongs to
+     * Used to check play state before processing input events
+     */
+    world: WeakRef<World>;
+    /**
+     * Whether to enable gamepad support
+     * Default: true
+     */
+    enableGamepad?: boolean;
+    /**
+     * Configuration for the virtual joystick
+     */
+    virtualJoystickOptions?: {
+        /** Size of the joystick in pixels */
+        size?: number;
+        /** Opacity of the joystick (0.0 to 1.0) */
+        opacity?: number;
+        /** Color of the joystick */
+        color?: string;
+        /** Whether the joystick should be static or dynamic */
+        mode?: 'static' | 'dynamic';
+        /** Whether to show the joystick only when touching */
+        fadeTime?: number;
+        /** Whether to hide/disable the virtual joystick (default: false) */
+        hidden?: boolean;
+    };
+    /**
+     * Configuration for swipe gesture detection
+     */
+    swipeOptions?: {
+        /** Minimum distance in pixels for a swipe to be recognized (default: 50) */
+        minDistance?: number;
+        /** Maximum duration in milliseconds for a swipe (default: 1000) */
+        maxDuration?: number;
+        /** Minimum velocity in pixels per second for a swipe (default: 100) */
+        minVelocity?: number;
+    };
+    /**
+     * Configuration for tap gesture detection
+     */
+    tapOptions?: {
+        /** Maximum duration in milliseconds for a tap (default: 300) */
+        maxDuration?: number;
+        /** Maximum movement in pixels for a tap (default: 10) */
+        maxMovement?: number;
+    };
+}
+/**
+ * Options for configuring pointer lock behavior
+ */
+export interface PointerLockOptions {
+    /**
+     * When true, uses raw/unadjusted movement values which can be useful for
+     * first-person controls that need to ignore OS-level mouse acceleration
+     * @default false
+     */
+    unadjustedMovement?: boolean;
+}
+/**
+ * Centralized input management system for handling keyboard, mouse, gamepad, and touch input
+ *
+ * Features:
+ * - Distributes input events to registered handlers
+ * - Tracks current input state (keys pressed, mouse buttons, position)
+ * - Provides pointer lock functionality
+ * - Normalizes mouse coordinates to NDC (Normalized Device Coordinates)
+ * - Manages gamepad connections and input
+ * - Handles touch input with normalized coordinates and pressure data
+ * - Provides virtual joystick support for mobile devices using nipplejs
+ * - Detects swipe gestures with configurable distance, velocity, and duration thresholds
+ * - Detects tap gestures with configurable duration and movement thresholds
+ * - Automatically enables touch input on mobile browsers
+ */
+export declare class InputManager {
+    readonly options: InputManagerOptions;
+    private keys;
+    private mousePosition;
+    private mouseButtons;
+    private inputHandlers;
+    private pointerLockOptions;
+    private inputEnabled;
+    private connectedGamepads;
+    private previousButtonStates;
+    private previousAxisValues;
+    private gamepadDeadzone;
+    private isPollingGamepads;
+    private gamepadRafId;
+    private boundHandleGamepadConnected;
+    private boundHandleGamepadDisconnected;
+    readonly onGamepadConnected: GamepadEventDelegate;
+    readonly onGamepadDisconnected: GamepadEventDelegate;
+    private virtualJoysticks;
+    private leftJoystickZone;
+    private rightJoystickZone;
+    private touchStartPosition;
+    private touchStartTime;
+    private touchMoved;
+    private swipeMinDistance;
+    private swipeMaxDuration;
+    private swipeMinVelocity;
+    private tapMaxDuration;
+    private tapMaxMovement;
+    readonly onSwipe: SwipeEventDelegate;
+    readonly onTap: TapEventDelegate;
+    private abortController;
+    /**
+       * Creates a new InputManager instance
+       * @param options - Required configuration including DOM element and World reference
+       */
+    constructor(options: InputManagerOptions);
+    beginPlay(): void;
+    endPlay(): void;
+    /**
+     * Cleans up resources used by the input manager
+     */
+    destroy(): void;
+    /**
+       * Requests pointer lock on the renderer element
+       * @param options - Optional configuration for pointer lock behavior
+       * @remarks
+       * Pointer lock hides the cursor and provides raw mouse movement data,
+       * which is useful for first-person controls
+       */
+    requestPointerLock(options?: PointerLockOptions): void;
+    /**
+       * Registers an input handler to receive input events
+       * @param handler - The handler to add
+       * @remarks
+       * Handlers are called in the order they were added until one returns true
+       */
+    addInputHandler(handler: IInputHandler): void;
+    /**
+       * Unregisters an input handler
+       * @param handler - The handler to remove
+       */
+    removeInputHandler(handler: IInputHandler): void;
+    /**
+       * Enables or disables input processing
+       * @param enabled - When true, input events will be processed; when false, all input events are ignored
+       */
+    setInputEnabled(enabled: boolean): void;
+    /**
+       * Checks if input processing is currently enabled
+       * @returns True if input processing is enabled, false otherwise
+       */
+    isInputEnabled(): boolean;
+    /**
+     * Gets all currently connected gamepads
+     * @returns An array of connected gamepads
+     */
+    getConnectedGamepads(): Gamepad[];
+    /**
+     * Gets a gamepad by its index
+     * @param index The index of the gamepad to get
+     * @returns The gamepad or null if not found
+     */
+    getGamepad(index: number): Gamepad | null;
+    /**
+     * Gets the current value of a gamepad button
+     * @param gamepadIndex The index of the gamepad
+     * @param buttonIndex The index of the button
+     * @returns The button value (0.0 to 1.0) or 0 if not pressed/not found
+     */
+    getGamepadButtonValue(gamepadIndex: number, buttonIndex: number): number;
+    /**
+     * Gets the current value of a gamepad axis
+     * @param gamepadIndex The index of the gamepad
+     * @param axisIndex The index of the axis
+     * @returns The axis value (-1.0 to 1.0) or 0 if not found
+     */
+    getGamepadAxisValue(gamepadIndex: number, axisIndex: number): number;
+    /**
+     * Starts polling for gamepad input
+     */
+    private startGamepadPolling;
+    /**
+     * Stops polling for gamepad input
+     */
+    private stopGamepadPolling;
+    private shouldIgnoreInput;
+    private setupEventListeners;
+    private handleKeyDown;
+    private handleKeyUp;
+    private handleMouseDown;
+    private handleMouseUp;
+    private handleMouseClick;
+    private handleMouseMove;
+    /**
+       * Checks if a specific key is currently pressed
+       * @param key - The key to check (case-sensitive)
+       * @returns True if the key is currently pressed down
+       */
+    isKeyDown(key: string): boolean;
+    /**
+       * Checks if a specific mouse button is currently pressed
+       * @param button - The button index to check (0=left, 1=middle, 2=right)
+       * @returns True if the button is currently pressed down
+       */
+    isMouseButtonDown(button: number): boolean;
+    /**
+       * Gets the current mouse position in Normalized Device Coordinates (NDC)
+       * @returns A Vector2 where:
+       *          - x ranges from -1 (left) to 1 (right)
+       *          - y ranges from -1 (bottom) to 1 (top)
+       */
+    getMousePosition(): THREE.Vector2;
+    /**
+       * Checks if pointer lock is currently active on the renderer element
+       * @returns True if pointer lock is active
+       */
+    isPointerLocked(): boolean;
+    /**
+       * Releases pointer lock if currently active
+       */
+    exitPointerLock(): void;
+    private handleGamepadConnected;
+    private handleGamepadDisconnected;
+    private pollGamepads;
+    private pollStandardGamepads;
+    private handleTouchStart;
+    private handleTouchMove;
+    private handleTouchEnd;
+    private handleTouchCancel;
+    private handleTapGesture;
+    private handleSwipeGesture;
+    private handlePointerLockChange;
+    private setupTouchInput;
+    private destroyTouchInput;
+    private handleVirtualJoystickEvent;
+    /**
+     * Checks if virtual joystick is enabled
+     * @returns True if virtual joystick is enabled
+     */
+    isVirtualJoystickEnabled(): boolean;
+    /**
+     * Shows the virtual joystick by setting visibility to visible
+     * Only works if joysticks have been initialized
+     */
+    showVirtualJoystick(): void;
+    /**
+     * Hides the virtual joystick by setting visibility to hidden
+     * The joystick will still capture events but won't be visible
+     */
+    hideVirtualJoystick(): void;
+    /**
+     * Checks if the virtual joystick is currently visible
+     * @returns True if visible, false if hidden or not initialized
+     */
+    isVirtualJoystickVisible(): boolean;
+}
+/**
+ * Base class for input handlers that provides default implementations for all methods
+ * Subclasses can override specific methods to handle specific input events
+ */
+export declare class BaseInputHandler implements IInputHandler {
+    protected inputManager: InputManager | null;
+    handleKeyDown(e: KeyboardEvent): boolean;
+    handleKeyUp(e: KeyboardEvent): boolean;
+    handleMouseDown(button: MouseButton, e: MouseEvent): boolean;
+    handleMouseUp(button: MouseButton, e: MouseEvent): boolean;
+    handleMouseMove(e: MouseEvent): boolean;
+    handleMouseClick(button: MouseButton, e: MouseEvent): boolean;
+    handleGamepadButtonDown(gamepadIndex: number, buttonIndex: number, value: number): boolean;
+    handleGamepadButtonUp(gamepadIndex: number, buttonIndex: number): boolean;
+    handleGamepadAxisChange(gamepadIndex: number, axisIndex: number, value: number): boolean;
+    handleVirtualJoystick(index: VirtualJoystickIndex, joystickData: VirtualJoystickData): boolean;
+    handleSwipe(swipeData: SwipeData): boolean;
+    handleTap(tapData: TapData): boolean;
+    setInputManager(manager: InputManager | null): void;
+}