@directivegames/genesys.js 3.1.24

package/src/systems/InputManager.ts

@@ -0,0 +1,1255 @@
+/**
+ * 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 { getEnv, isMobileBrowser, isNode } from '../utils/Utils.js';
+
+import type { World } from '../game/World';
+import type nipplejs from 'nipplejs';
+
+
+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 enum MouseButton {
+  Left = 0,
+  Middle = 1,
+  Right = 2,
+}
+
+export 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 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 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 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 class InputManager {
+  private keys: Set<string> = new Set();
+  private mousePosition: THREE.Vector2 = new THREE.Vector2();
+  private mouseButtons: Set<number> = new Set();
+  private inputHandlers: IInputHandler[] = [];
+  private pointerLockOptions: PointerLockOptions | null = null;
+  private inputEnabled: boolean = true;
+
+  // Gamepad related properties
+  private connectedGamepads: Map<number, Gamepad> = new Map();
+  private previousButtonStates: Map<number, Map<number, boolean>> = new Map();
+  private previousAxisValues: Map<number, Map<number, number>> = new Map();
+  private gamepadDeadzone: number = 0.1;
+  private isPollingGamepads: boolean = false;
+  private gamepadRafId: number | null = null;
+  private boundHandleGamepadConnected: (event: GamepadEvent) => void = () => {};
+  private boundHandleGamepadDisconnected: (event: GamepadEvent) => void = () => {};
+
+
+  public readonly onGamepadConnected: GamepadEventDelegate = new Delegate<[Gamepad], void>();
+  public readonly onGamepadDisconnected: GamepadEventDelegate = new Delegate<[Gamepad], void>();
+
+  // Touch related properties
+  private virtualJoysticks: Map<VirtualJoystickIndex, nipplejs.JoystickManager> = new Map();
+  private leftJoystickZone: HTMLElement | null = null;
+  private rightJoystickZone: HTMLElement | null = null;
+
+  // Gesture detection properties
+  private touchStartPosition: THREE.Vector2 | null = null;
+  private touchStartTime: number = 0;
+  private touchMoved: boolean = false;
+
+  // Gesture thresholds with defaults
+  private swipeMinDistance: number = 50;
+  private swipeMaxDuration: number = 1000;
+  private swipeMinVelocity: number = 100;
+  private tapMaxDuration: number = 300;
+  private tapMaxMovement: number = 10;
+
+  public readonly onSwipe: SwipeEventDelegate = new Delegate<[SwipeData], boolean>();
+  public readonly onTap: TapEventDelegate = new Delegate<[TapData], boolean>();
+
+  private abortController = new AbortController();
+
+  /**
+     * Creates a new InputManager instance
+     * @param options - Required configuration including DOM element and World reference
+     */
+  constructor(readonly options: InputManagerOptions) {
+    // Apply custom swipe options
+    if (options.swipeOptions) {
+      this.swipeMinDistance = options.swipeOptions.minDistance ?? this.swipeMinDistance;
+      this.swipeMaxDuration = options.swipeOptions.maxDuration ?? this.swipeMaxDuration;
+      this.swipeMinVelocity = options.swipeOptions.minVelocity ?? this.swipeMinVelocity;
+    }
+
+    // Apply custom tap options
+    if (options.tapOptions) {
+      this.tapMaxDuration = options.tapOptions.maxDuration ?? this.tapMaxDuration;
+      this.tapMaxMovement = options.tapOptions.maxMovement ?? this.tapMaxMovement;
+    }
+
+    this.setupEventListeners();
+  }
+
+
+  public beginPlay(): void {
+    this.setupTouchInput();
+  }
+
+  public endPlay(): void {
+    this.destroyTouchInput();
+  }
+
+  /**
+   * Cleans up resources used by the input manager
+   */
+  public destroy(): void {
+    this.abortController.abort();
+
+    // Clean up gamepad resources
+    this.stopGamepadPolling();
+    this.connectedGamepads.clear();
+    this.previousButtonStates.clear();
+    this.previousAxisValues.clear();
+
+    // Clean up touch resources
+    this.destroyTouchInput();
+
+    this.inputHandlers = [];
+  }
+
+  /**
+     * 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
+     */
+  public requestPointerLock(options?: PointerLockOptions) {
+    this.pointerLockOptions = options ?? {};
+  }
+
+  /**
+     * 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
+     */
+  public addInputHandler(handler: IInputHandler): void {
+    handler.setInputManager(this);
+    this.inputHandlers.push(handler);
+  }
+
+  /**
+     * Unregisters an input handler
+     * @param handler - The handler to remove
+     */
+  public removeInputHandler(handler: IInputHandler): void {
+    const index = this.inputHandlers.indexOf(handler);
+    if (index !== -1) {
+      handler.setInputManager(null);
+      this.inputHandlers.splice(index, 1);
+    }
+  }
+
+  /**
+     * Enables or disables input processing
+     * @param enabled - When true, input events will be processed; when false, all input events are ignored
+     */
+  public setInputEnabled(enabled: boolean): void {
+    this.inputEnabled = enabled;
+  }
+
+  /**
+     * Checks if input processing is currently enabled
+     * @returns True if input processing is enabled, false otherwise
+     */
+  public isInputEnabled(): boolean {
+    return this.inputEnabled;
+  }
+
+  /**
+   * Gets all currently connected gamepads
+   * @returns An array of connected gamepads
+   */
+  public getConnectedGamepads(): Gamepad[] {
+    return Array.from(this.connectedGamepads.values());
+  }
+
+  /**
+   * Gets a gamepad by its index
+   * @param index The index of the gamepad to get
+   * @returns The gamepad or null if not found
+   */
+  public getGamepad(index: number): Gamepad | null {
+    return this.connectedGamepads.get(index) ?? 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
+   */
+  public getGamepadButtonValue(gamepadIndex: number, buttonIndex: number): number {
+    const gamepad = this.connectedGamepads.get(gamepadIndex);
+    if (!gamepad || buttonIndex >= gamepad.buttons.length) return 0;
+    return gamepad.buttons[buttonIndex].value;
+  }
+
+  /**
+   * 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
+   */
+  public getGamepadAxisValue(gamepadIndex: number, axisIndex: number): number {
+    const gamepad = this.connectedGamepads.get(gamepadIndex);
+    if (!gamepad || axisIndex >= gamepad.axes.length) return 0;
+
+    const value = gamepad.axes[axisIndex];
+    // Apply deadzone
+    return Math.abs(value) < this.gamepadDeadzone ? 0 : value;
+  }
+
+  /**
+   * Starts polling for gamepad input
+   */
+  private startGamepadPolling(): void {
+    if (this.isPollingGamepads) return;
+    this.isPollingGamepads = true;
+    this.pollGamepads();
+  }
+
+  /**
+   * Stops polling for gamepad input
+   */
+  private stopGamepadPolling(): void {
+    if (!this.isPollingGamepads) return;
+    this.isPollingGamepads = false;
+    if (this.gamepadRafId !== null) {
+      cancelAnimationFrame(this.gamepadRafId);
+      this.gamepadRafId = null;
+    }
+  }
+
+  //====================================================================================================
+
+  private shouldIgnoreInput(): boolean {
+    return !this.isInputEnabled() || !this.options.world.deref()?.isPlaying();
+  }
+
+  private setupEventListeners(): void {
+    if (isNode()) {
+      return;
+    }
+
+    const options = { signal: this.abortController.signal };
+    window.addEventListener('keydown', this.handleKeyDown.bind(this), options);
+    window.addEventListener('keyup', this.handleKeyUp.bind(this), options);
+    this.options.rendererDomElement.addEventListener('mousedown', this.handleMouseDown.bind(this), options);
+    this.options.rendererDomElement.addEventListener('mouseup', this.handleMouseUp.bind(this), options);
+    this.options.rendererDomElement.addEventListener('mousemove', this.handleMouseMove.bind(this), options);
+    this.options.rendererDomElement.addEventListener('click', this.handleMouseClick.bind(this), options);
+
+    // Setup touch event listeners for swipe and tap detection
+    this.options.rendererDomElement.addEventListener('touchstart', this.handleTouchStart.bind(this), options);
+    this.options.rendererDomElement.addEventListener('touchmove', this.handleTouchMove.bind(this), options);
+    this.options.rendererDomElement.addEventListener('touchend', this.handleTouchEnd.bind(this), options);
+    this.options.rendererDomElement.addEventListener('touchcancel', this.handleTouchCancel.bind(this), options);
+
+    // Setup pointer lock change listeners
+    document.addEventListener('pointerlockchange', this.handlePointerLockChange.bind(this), options);
+    document.addEventListener('mozpointerlockchange', this.handlePointerLockChange.bind(this), options);
+    document.addEventListener('webkitpointerlockchange', this.handlePointerLockChange.bind(this), options);
+
+    // Setup gamepad listeners if enabled
+    if (this.options.enableGamepad !== false) {
+      // Bind methods once to ensure we can remove them later
+      this.boundHandleGamepadConnected = this.handleGamepadConnected.bind(this);
+      this.boundHandleGamepadDisconnected = this.handleGamepadDisconnected.bind(this);
+
+      window.addEventListener('gamepadconnected', this.boundHandleGamepadConnected, options);
+      window.addEventListener('gamepaddisconnected', this.boundHandleGamepadDisconnected, options);
+
+      // Check for already connected gamepads that may have been missed by the event
+      const gamepads = navigator.getGamepads();
+      for (const gamepad of gamepads) {
+        if (gamepad) {
+          this.handleGamepadConnected({ gamepad } as GamepadEvent);
+        }
+      }
+    }
+  }
+
+  private handleKeyDown(e: KeyboardEvent): void {
+    if (this.shouldIgnoreInput() || this.keys.has(e.key)) {
+      return;
+    }
+    this.keys.add(e.key);
+    for (const handler of this.inputHandlers) {
+      if (handler.handleKeyDown(e)) {
+        break;
+      }
+    }
+  }
+
+  private handleKeyUp(e: KeyboardEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+    this.keys.delete(e.key);
+    for (const handler of this.inputHandlers) {
+      if (handler.handleKeyUp(e)) {
+        break;
+      }
+    }
+  }
+
+  private handleMouseDown(e: MouseEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+    this.mouseButtons.add(e.button);
+    for (const handler of this.inputHandlers) {
+      if (handler.handleMouseDown(e.button, e)) {
+        break;
+      }
+    }
+  }
+
+  private handleMouseUp(e: MouseEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+    this.mouseButtons.delete(e.button);
+    for (const handler of this.inputHandlers) {
+      if (handler.handleMouseUp(e.button, e)) {
+        break;
+      }
+    }
+  }
+
+  private handleMouseClick(e: MouseEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+    if (this.pointerLockOptions && !this.isPointerLocked()) {
+      if (this.options.rendererDomElement.requestPointerLock) {
+        this.options.rendererDomElement.requestPointerLock(this.pointerLockOptions);
+      }
+    }
+    for (const handler of this.inputHandlers) {
+      if (handler.handleMouseClick(e.button, e)) {
+        break;
+      }
+    }
+  }
+
+  private handleMouseMove(e: MouseEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+    const rect = this.options.rendererDomElement.getBoundingClientRect();
+    this.mousePosition.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
+    this.mousePosition.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
+    for (const handler of this.inputHandlers) {
+      if (handler.handleMouseMove(e)) {
+        break;
+      }
+    }
+  }
+
+  /**
+     * 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
+     */
+  public isKeyDown(key: string): boolean {
+    return this.keys.has(key);
+  }
+
+  /**
+     * 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
+     */
+  public isMouseButtonDown(button: number): boolean {
+    return this.mouseButtons.has(button);
+  }
+
+  /**
+     * 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)
+     */
+  public getMousePosition(): THREE.Vector2 {
+    return this.mousePosition.clone();
+  }
+
+  /**
+     * Checks if pointer lock is currently active on the renderer element
+     * @returns True if pointer lock is active
+     */
+  public isPointerLocked(): boolean {
+    return document.pointerLockElement === this.options.rendererDomElement;
+  }
+
+  /**
+     * Releases pointer lock if currently active
+     */
+  public exitPointerLock() {
+    this.pointerLockOptions = null;
+    if (document.exitPointerLock) {
+      document.exitPointerLock();
+    }
+  }
+
+  // Gamepad handling methods
+  private handleGamepadConnected(event: GamepadEvent): void {
+    const gamepad = event.gamepad;
+    this.connectedGamepads.set(gamepad.index, gamepad);
+    this.previousButtonStates.set(gamepad.index, new Map());
+    this.previousAxisValues.set(gamepad.index, new Map());
+
+    // Initialize button states
+    const buttonStates = this.previousButtonStates.get(gamepad.index)!;
+    for (let i = 0; i < gamepad.buttons.length; i++) {
+      buttonStates.set(i, gamepad.buttons[i].pressed);
+    }
+
+    // Initialize axis values
+    const axisValues = this.previousAxisValues.get(gamepad.index)!;
+    for (let i = 0; i < gamepad.axes.length; i++) {
+      axisValues.set(i, gamepad.axes[i]);
+    }
+
+    // Start polling if we have connected gamepads and aren't already polling
+    if (!this.isPollingGamepads && this.connectedGamepads.size > 0) {
+      this.startGamepadPolling();
+    }
+
+    this.onGamepadConnected.invoke(gamepad);
+  }
+
+  private handleGamepadDisconnected(event: GamepadEvent): void {
+    const gamepad = event.gamepad;
+    this.connectedGamepads.delete(gamepad.index);
+    this.previousButtonStates.delete(gamepad.index);
+    this.previousAxisValues.delete(gamepad.index);
+
+    // Stop polling if no gamepads are connected
+    if (this.connectedGamepads.size === 0) {
+      this.stopGamepadPolling();
+    }
+
+    this.onGamepadDisconnected.invoke(gamepad);
+  }
+
+  private pollGamepads(): void {
+    if (!this.isPollingGamepads) return;
+
+    this.gamepadRafId = requestAnimationFrame(this.pollGamepads.bind(this));
+
+    // Skip polling if input is disabled or world is not playing
+    if (this.shouldIgnoreInput()) return;
+
+    // Process standard gamepads
+    this.pollStandardGamepads();
+
+  }
+
+  private pollStandardGamepads(): void {
+    // Get all connected gamepads
+    const gamepads = navigator.getGamepads();
+    if (!gamepads) return;
+
+    // Process each gamepad
+    for (const gamepad of gamepads) {
+      if (!gamepad) continue;
+
+      // Update the stored gamepad reference
+      this.connectedGamepads.set(gamepad.index, gamepad);
+
+      // Check for button changes
+      for (let i = 0; i < gamepad.buttons.length; i++) {
+        const button = gamepad.buttons[i];
+        const buttonStates = this.previousButtonStates.get(gamepad.index)!;
+        const wasPressed = buttonStates.get(i) ?? false;
+        const isPressed = button.pressed;
+
+        // If button state changed
+        if (wasPressed !== isPressed) {
+          buttonStates.set(i, isPressed);
+
+          // Fire appropriate event
+          if (isPressed) {
+            // Button was pressed
+            for (const handler of this.inputHandlers) {
+              if (handler.handleGamepadButtonDown && handler.handleGamepadButtonDown(gamepad.index, i, button.value)) {
+                break;
+              }
+            }
+          } else {
+            // Button was released
+            for (const handler of this.inputHandlers) {
+              if (handler.handleGamepadButtonUp && handler.handleGamepadButtonUp(gamepad.index, i)) {
+                break;
+              }
+            }
+          }
+        }
+      }
+
+      // Check for axis changes
+      for (let i = 0; i < gamepad.axes.length; i++) {
+        const currentValue = gamepad.axes[i];
+        const axisValues = this.previousAxisValues.get(gamepad.index)!;
+        const previousValue = axisValues.get(i) ?? 0;
+
+        // Apply deadzone to both values for comparison
+        const deadzonedCurrent = Math.abs(currentValue) < this.gamepadDeadzone ? 0 : currentValue;
+        const deadzonedPrevious = Math.abs(previousValue) < this.gamepadDeadzone ? 0 : previousValue;
+
+        // If axis value changed significantly
+        if (Math.abs(deadzonedCurrent - deadzonedPrevious) > 0.01) {
+          axisValues.set(i, currentValue);
+
+          // Notify handlers
+          for (const handler of this.inputHandlers) {
+            if (handler.handleGamepadAxisChange && handler.handleGamepadAxisChange(gamepad.index, i, deadzonedCurrent)) {
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+
+
+
+
+
+  // Touch event handlers for swipe and tap detection
+  private handleTouchStart(e: TouchEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+
+    // Only track single touch for swipe/tap detection
+    if (e.touches.length === 1) {
+      const touch = e.touches[0];
+      this.touchStartPosition = new THREE.Vector2(touch.clientX, touch.clientY);
+      this.touchStartTime = performance.now();
+      this.touchMoved = false;
+    }
+  }
+
+  private handleTouchMove(e: TouchEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+
+    // Track if touch has moved
+    if (e.touches.length === 1 && this.touchStartPosition) {
+      const touch = e.touches[0];
+      const currentPosition = new THREE.Vector2(touch.clientX, touch.clientY);
+      const distance = this.touchStartPosition.distanceTo(currentPosition);
+
+      if (distance > this.tapMaxMovement) {
+        this.touchMoved = true;
+      }
+    }
+  }
+
+  private handleTouchEnd(e: TouchEvent): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+
+    if (!this.touchStartPosition) {
+      return;
+    }
+
+    const touch = e.changedTouches[0];
+    const endPosition = new THREE.Vector2(touch.clientX, touch.clientY);
+    const duration = performance.now() - this.touchStartTime;
+    const distance = this.touchStartPosition.distanceTo(endPosition);
+
+    // Check for tap gesture
+    if (!this.touchMoved && duration <= this.tapMaxDuration && distance <= this.tapMaxMovement) {
+      this.handleTapGesture(endPosition, e);
+    }
+    // Check for swipe gesture
+    else if (this.touchMoved && duration <= this.swipeMaxDuration && distance >= this.swipeMinDistance) {
+      const velocity = (distance / duration) * 1000; // Convert to pixels per second
+
+      if (velocity >= this.swipeMinVelocity) {
+        this.handleSwipeGesture(this.touchStartPosition, endPosition, distance, duration, velocity, e);
+      }
+    }
+
+    // Reset touch tracking
+    this.touchStartPosition = null;
+    this.touchStartTime = 0;
+    this.touchMoved = false;
+  }
+
+  private handleTouchCancel(e: TouchEvent): void {
+    // Reset touch tracking on cancel
+    this.touchStartPosition = null;
+    this.touchStartTime = 0;
+    this.touchMoved = false;
+  }
+
+  private handleTapGesture(position: THREE.Vector2, event: TouchEvent): void {
+    // Calculate normalized position (NDC)
+    const rect = this.options.rendererDomElement.getBoundingClientRect();
+    const normalizedPosition = new THREE.Vector2(
+      ((position.x - rect.left) / rect.width) * 2 - 1,
+      -((position.y - rect.top) / rect.height) * 2 + 1
+    );
+
+    const tapData: TapData = {
+      position: position.clone(),
+      normalizedPosition,
+      event
+    };
+
+    // Distribute to handlers
+    for (const handler of this.inputHandlers) {
+      if (handler.handleTap && handler.handleTap(tapData)) {
+        break;
+      }
+    }
+
+    // Invoke delegate
+    this.onTap.invoke(tapData);
+  }
+
+  private handleSwipeGesture(
+    startPosition: THREE.Vector2,
+    endPosition: THREE.Vector2,
+    distance: number,
+    duration: number,
+    velocity: number,
+    event: TouchEvent
+  ): void {
+    // Calculate swipe direction
+    const dx = endPosition.x - startPosition.x;
+    const dy = endPosition.y - startPosition.y;
+    const absDx = Math.abs(dx);
+    const absDy = Math.abs(dy);
+
+    let direction: SwipeDirection;
+    if (absDx > absDy) {
+      // Horizontal swipe
+      direction = dx > 0 ? SwipeDirection.Right : SwipeDirection.Left;
+    } else {
+      // Vertical swipe
+      direction = dy > 0 ? SwipeDirection.Down : SwipeDirection.Up;
+    }
+
+    const swipeData: SwipeData = {
+      direction,
+      startPosition: startPosition.clone(),
+      endPosition: endPosition.clone(),
+      distance,
+      duration,
+      velocity,
+      event
+    };
+
+    // Distribute to handlers
+    for (const handler of this.inputHandlers) {
+      if (handler.handleSwipe && handler.handleSwipe(swipeData)) {
+        break;
+      }
+    }
+
+    // Invoke delegate
+    this.onSwipe.invoke(swipeData);
+  }
+
+  // Handle pointer lock change events
+  private handlePointerLockChange(): void {
+    // This method handles changes to the pointer lock state
+    // It can be used to add additional logic when pointer lock is acquired or released
+  }
+
+  // Touch input setup and management methods
+  private async setupTouchInput(): Promise<void> {
+
+    const debugTouchInput = getEnv('VITE_DEBUG_TOUCH_INPUT') === 'true';
+
+    if (isNode()) {
+      return;
+    }
+
+    if (!isMobileBrowser() && !debugTouchInput) {
+      return;
+    }
+
+    // Check if virtual joystick is explicitly hidden
+    if (this.options.virtualJoystickOptions?.hidden) {
+      return;
+    }
+
+    // cannot import the nipplejs module globally as it requires the window global
+    const nipplejs = await import('nipplejs');
+    const nippleModule = nipplejs.default || nipplejs;
+
+    const defaultOptions = {
+      size: 120,
+      opacity: 0.7,
+      color: 'white',
+      mode: 'static' as const,
+      fadeTime: 250
+    };
+
+    const joystickOptions = {
+      ...defaultOptions,
+      ...this.options.virtualJoystickOptions
+    };
+
+    try {
+      // Calculate joystick zone size based on joystick size plus padding for interaction
+      const zoneSize = joystickOptions.size * 1.5; // Extra space for comfortable interaction
+
+      // Create left joystick zone
+      this.leftJoystickZone = document.createElement('div');
+      this.leftJoystickZone.style.position = 'absolute';
+      this.leftJoystickZone.style.left = '20px';
+      this.leftJoystickZone.style.bottom = '20px';
+      this.leftJoystickZone.style.width = `${zoneSize}px`;
+      this.leftJoystickZone.style.height = `${zoneSize}px`;
+      this.leftJoystickZone.style.pointerEvents = 'auto';
+      if (debugTouchInput) {
+        this.leftJoystickZone.style.border = '2px solid rgba(255, 0, 0, 0.5)';
+        this.leftJoystickZone.style.backgroundColor = 'rgba(255, 0, 0, 0.1)';
+        this.leftJoystickZone.style.boxSizing = 'border-box';
+      }
+      this.options.gameContainer.appendChild(this.leftJoystickZone);
+
+      // Create right joystick zone
+      this.rightJoystickZone = document.createElement('div');
+      this.rightJoystickZone.style.position = 'absolute';
+      this.rightJoystickZone.style.right = '20px';
+      this.rightJoystickZone.style.bottom = '20px';
+      this.rightJoystickZone.style.width = `${zoneSize}px`;
+      this.rightJoystickZone.style.height = `${zoneSize}px`;
+      this.rightJoystickZone.style.pointerEvents = 'auto';
+      if (debugTouchInput) {
+        this.rightJoystickZone.style.border = '2px solid rgba(0, 0, 255, 0.5)';
+        this.rightJoystickZone.style.backgroundColor = 'rgba(0, 0, 255, 0.1)';
+        this.rightJoystickZone.style.boxSizing = 'border-box';
+      }
+      this.options.gameContainer.appendChild(this.rightJoystickZone);
+
+      const leftStick = nippleModule.create({
+        zone: this.leftJoystickZone,
+        mode: joystickOptions.mode,
+        position: { left: '50%', bottom: '50%' },
+        size: joystickOptions.size,
+        color: joystickOptions.color,
+        fadeTime: joystickOptions.fadeTime,
+        restOpacity: joystickOptions.opacity * 0.5,
+        threshold: 0.1,
+        catchDistance: 200,
+      });
+
+      const rightStick = nippleModule.create({
+        zone: this.rightJoystickZone,
+        mode: joystickOptions.mode,
+        position: { left: '50%', bottom: '50%' },
+        size: joystickOptions.size,
+        color: joystickOptions.color,
+        fadeTime: joystickOptions.fadeTime,
+        restOpacity: joystickOptions.opacity * 0.5,
+        threshold: 0.1,
+        catchDistance: 200
+      });
+
+      this.virtualJoysticks.set(VirtualJoystickIndex.Left, leftStick);
+      this.virtualJoysticks.set(VirtualJoystickIndex.Right, rightStick);
+
+      // Bind virtual joystick events
+      const leftHandler = this.handleVirtualJoystickEvent.bind(this, VirtualJoystickIndex.Left);
+      leftStick.on('start', leftHandler);
+      leftStick.on('move', leftHandler);
+      leftStick.on('end', leftHandler);
+
+      const rightHandler = this.handleVirtualJoystickEvent.bind(this, VirtualJoystickIndex.Right);
+      rightStick.on('start', rightHandler);
+      rightStick.on('move', rightHandler);
+      rightStick.on('end', rightHandler);
+    } catch (error) {
+      console.warn('Failed to initialize virtual joystick:', error);
+    }
+  }
+
+  private destroyTouchInput(): void {
+    if (this.leftJoystickZone) {
+      this.leftJoystickZone.remove();
+      this.leftJoystickZone = null;
+    }
+    if (this.rightJoystickZone) {
+      this.rightJoystickZone.remove();
+      this.rightJoystickZone = null;
+    }
+    for (const joystick of this.virtualJoysticks.values()) {
+      joystick.destroy();
+    }
+    this.virtualJoysticks.clear();
+  }
+
+  // Virtual joystick event handlers
+  private handleVirtualJoystickEvent(index: VirtualJoystickIndex, event: nipplejs.EventData, output: nipplejs.JoystickOutputData): void {
+    if (this.shouldIgnoreInput()) {
+      return;
+    }
+
+    if (event.type === 'start' || event.type === 'move' || event.type === 'end') {
+      const joystickData: VirtualJoystickData = {
+        type: event.type,
+        position: new THREE.Vector2(output.position.x, output.position.y),
+      };
+
+      // Distribute to handlers
+      for (const handler of this.inputHandlers) {
+        if (handler.handleVirtualJoystick && handler.handleVirtualJoystick(index, joystickData)) {
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Checks if virtual joystick is enabled
+   * @returns True if virtual joystick is enabled
+   */
+  public isVirtualJoystickEnabled(): boolean {
+    return !!this.virtualJoysticks.values.length;
+  }
+
+  /**
+   * Shows the virtual joystick by setting visibility to visible
+   * Only works if joysticks have been initialized
+   */
+  public showVirtualJoystick(): void {
+    if (this.leftJoystickZone) {
+      this.leftJoystickZone.style.visibility = 'visible';
+    }
+    if (this.rightJoystickZone) {
+      this.rightJoystickZone.style.visibility = 'visible';
+    }
+  }
+
+  /**
+   * Hides the virtual joystick by setting visibility to hidden
+   * The joystick will still capture events but won't be visible
+   */
+  public hideVirtualJoystick(): void {
+    if (this.leftJoystickZone) {
+      this.leftJoystickZone.style.visibility = 'hidden';
+    }
+    if (this.rightJoystickZone) {
+      this.rightJoystickZone.style.visibility = 'hidden';
+    }
+  }
+
+  /**
+   * Checks if the virtual joystick is currently visible
+   * @returns True if visible, false if hidden or not initialized
+   */
+  public isVirtualJoystickVisible(): boolean {
+    if (!this.leftJoystickZone) {
+      return false;
+    }
+    return this.leftJoystickZone.style.visibility !== 'hidden';
+  }
+}
+
+/**
+ * Base class for input handlers that provides default implementations for all methods
+ * Subclasses can override specific methods to handle specific input events
+ */
+export class BaseInputHandler implements IInputHandler {
+  protected inputManager: InputManager | null = null;
+
+  public handleKeyDown(e: KeyboardEvent): boolean {
+    return false;
+  }
+
+  public handleKeyUp(e: KeyboardEvent): boolean {
+    return false;
+  }
+
+  public handleMouseDown(button: MouseButton, e: MouseEvent): boolean {
+    return false;
+  }
+
+  public handleMouseUp(button: MouseButton, e: MouseEvent): boolean {
+    return false;
+  }
+
+  public handleMouseMove(e: MouseEvent): boolean {
+    return false;
+  }
+
+  public handleMouseClick(button: MouseButton, e: MouseEvent): boolean {
+    return false;
+  }
+
+  public handleGamepadButtonDown(gamepadIndex: number, buttonIndex: number, value: number): boolean {
+    return false;
+  }
+
+  public handleGamepadButtonUp(gamepadIndex: number, buttonIndex: number): boolean {
+    return false;
+  }
+
+  public handleGamepadAxisChange(gamepadIndex: number, axisIndex: number, value: number): boolean {
+    return false;
+  }
+
+  public handleVirtualJoystick(index: VirtualJoystickIndex, joystickData: VirtualJoystickData): boolean {
+    return false;
+  }
+
+  public handleSwipe(swipeData: SwipeData): boolean {
+    return false;
+  }
+
+  public handleTap(tapData: TapData): boolean {
+    return false;
+  }
+
+  public setInputManager(manager: InputManager | null): void {
+    this.inputManager = manager;
+  }
+}