three-gamepad-controls 0.10.5 → 0.11.0

package/dist/gamepad-input.d.ts

@@ -0,0 +1,156 @@
+import { EventDispatcher } from "three";
+
+//#region src/gamepad-input.d.ts
+/**
+ * Event map for {@link GamepadInput}.
+ */
+type GamepadInputEventMap = {
+  /**
+   * Fired when a gamepad is connected and becomes active.
+   */
+  connected: {
+    /**
+     * Gamepad snapshot that became active.
+     */
+    gamepad: Gamepad;
+  };
+  /**
+   * Fired when the active gamepad is disconnected.
+   */
+  disconnected: {
+    /**
+     * Gamepad snapshot that was active before disconnection.
+     */
+    gamepad: Gamepad;
+  };
+};
+/**
+ * Configuration for {@link GamepadInput}.
+ */
+type GamepadInputOptions = {
+  /**
+   * Default axis dead zone threshold in the range `[0, 1]`.
+   * @default 0.1
+   */
+  deadzone: number;
+};
+/**
+ * Options for axis and stick reads.
+ */
+type GamepadAxisOptions = {
+  /**
+   * Axis dead zone threshold for this read.
+   */
+  deadzone?: number;
+};
+/**
+ * Two-dimensional stick input after dead zone processing.
+ */
+type GamepadStick = {
+  /**
+   * Horizontal stick value.
+   */
+  x: number;
+  /**
+   * Vertical stick value.
+   */
+  y: number;
+};
+/**
+ * Gamepad input state reader for gameplay, menus, and custom actions.
+ *
+ * Call {@link update} once per frame before reading button transitions or axes.
+ */
+declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
+  #private;
+  /**
+   * When `false`, input polling is paused.
+   * @default true
+   */
+  enabled: boolean;
+  /**
+   * Creates a gamepad input reader.
+   *
+   * @param options - Optional overrides for the default input behavior.
+   */
+  constructor(options?: Partial<GamepadInputOptions>);
+  /**
+   * The currently active gamepad, or `null` if no gamepad is connected.
+   *
+   * @returns The active gamepad snapshot, or `null`.
+   */
+  get gamepad(): Gamepad | null;
+  /**
+   * Whether a gamepad is currently active.
+   *
+   * @returns `true` when a gamepad is active, otherwise `false`.
+   */
+  get connected(): boolean;
+  /**
+   * Mapping reported by the active gamepad, or `null` when none is active.
+   *
+   * @returns The active gamepad mapping, or `null`.
+   */
+  get mapping(): GamepadMappingType | null;
+  /**
+   * Raw active gamepad snapshot, or `null` if no gamepad is connected.
+   *
+   * @returns The raw active gamepad snapshot, or `null`.
+   */
+  get rawGamepad(): Gamepad | null;
+  /**
+   * Polls the gamepad and refreshes current and previous button state.
+   */
+  update(): void;
+  /**
+   * Removes all window-level event listeners attached by this input reader.
+   */
+  dispose(): void;
+  /**
+   * Returns whether a button is currently pressed.
+   *
+   * @param button - Button index to inspect.
+   * @returns `true` when the button is currently pressed, otherwise `false`.
+   */
+  isPressed(button: number): boolean;
+  /**
+   * Returns whether a button was pressed during the latest update.
+   *
+   * @param button - Button index to inspect.
+   * @returns `true` only on the frame where the button transitions to pressed.
+   */
+  wasPressed(button: number): boolean;
+  /**
+   * Returns whether a button was released during the latest update.
+   *
+   * @param button - Button index to inspect.
+   * @returns `true` only on the frame where the button transitions to released.
+   */
+  wasReleased(button: number): boolean;
+  /**
+   * Returns the current analog value for a button.
+   *
+   * @param button - Button index to inspect.
+   * @returns The button value, `1` for pressed digital buttons, or `0`.
+   */
+  buttonValue(button: number): number;
+  /**
+   * Returns the current value of an axis after dead zone processing.
+   *
+   * @param axis - Axis index to inspect.
+   * @param options - Optional per-read axis options.
+   * @returns Axis value after dead zone processing, or `0` when unavailable.
+   */
+  axis(axis: number, options?: GamepadAxisOptions): number;
+  /**
+   * Returns a two-axis stick after dead zone processing.
+   *
+   * @param xAxis - Horizontal axis index.
+   * @param yAxis - Vertical axis index.
+   * @param options - Optional per-read axis options.
+   * @returns Object containing processed `x` and `y` values.
+   */
+  stick(xAxis: number, yAxis: number, options?: GamepadAxisOptions): GamepadStick;
+}
+//#endregion
+export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick };

package/dist/gamepad-input.js

@@ -0,0 +1,270 @@
+import { GamepadManager } from "./gamepad-manager.js";
+import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.js";
+import { EventDispatcher } from "three";
+//#region src/gamepad-input.ts
+const DEFAULT_GAMEPAD_INPUT_OPTIONS = { deadzone: .1 };
+/**
+* Gamepad input state reader for gameplay, menus, and custom actions.
+*
+* Call {@link update} once per frame before reading button transitions or axes.
+*/
+var GamepadInput = class extends EventDispatcher {
+	/**
+	* When `false`, input polling is paused.
+	* @default true
+	*/
+	enabled = true;
+	#manager;
+	#options;
+	#pressedButtons;
+	#previousPressedButtons;
+	/**
+	* Bound browser connection listener kept so it can be removed in {@link dispose}.
+	*/
+	#onGamepadConnected;
+	/**
+	* Bound browser disconnection listener kept so it can be removed in {@link dispose}.
+	*/
+	#onGamepadDisconnected;
+	#gamepad = null;
+	/**
+	* Creates a gamepad input reader.
+	*
+	* @param options - Optional overrides for the default input behavior.
+	*/
+	constructor(options) {
+		super();
+		this.#manager = new GamepadManager();
+		this.#options = {
+			...DEFAULT_GAMEPAD_INPUT_OPTIONS,
+			...options
+		};
+		this.#pressedButtons = /* @__PURE__ */ new Set();
+		this.#previousPressedButtons = /* @__PURE__ */ new Set();
+		this.#onGamepadConnected = this.#handleGamepadConnectedEvent.bind(this);
+		this.#onGamepadDisconnected = this.#handleGamepadDisconnectedEvent.bind(this);
+		window.addEventListener("gamepadconnected", this.#onGamepadConnected);
+		window.addEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+	}
+	/**
+	* Forwards a browser connection event to the active-gamepad adoption logic.
+	*
+	* @param event - Browser event containing the connected gamepad snapshot.
+	*/
+	#handleGamepadConnectedEvent(event) {
+		this.#handleGamepadConnected(event.gamepad);
+	}
+	/**
+	* Forwards a browser disconnection event to active-gamepad cleanup.
+	*
+	* @param event - Browser event containing the disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnectedEvent(event) {
+		this.#handleGamepadDisconnected(event.gamepad);
+	}
+	/**
+	* The currently active gamepad, or `null` if no gamepad is connected.
+	*
+	* @returns The active gamepad snapshot, or `null`.
+	*/
+	get gamepad() {
+		return this.#gamepad;
+	}
+	/**
+	* Whether a gamepad is currently active.
+	*
+	* @returns `true` when a gamepad is active, otherwise `false`.
+	*/
+	get connected() {
+		return this.#gamepad !== null;
+	}
+	/**
+	* Mapping reported by the active gamepad, or `null` when none is active.
+	*
+	* @returns The active gamepad mapping, or `null`.
+	*/
+	get mapping() {
+		return this.#gamepad?.mapping ?? null;
+	}
+	/**
+	* Raw active gamepad snapshot, or `null` if no gamepad is connected.
+	*
+	* @returns The raw active gamepad snapshot, or `null`.
+	*/
+	get rawGamepad() {
+		return this.#gamepad;
+	}
+	/**
+	* Polls the gamepad and refreshes current and previous button state.
+	*/
+	update() {
+		if (!this.enabled) return;
+		const { gamepad, connected, disconnected } = this.#manager.update();
+		if (connected !== null) {
+			this.#gamepad = gamepad;
+			this.#syncButtonState({ seedPrevious: true });
+			this.dispatchEvent({
+				type: "connected",
+				gamepad: connected
+			});
+			return;
+		}
+		if (disconnected !== null) {
+			this.#gamepad = null;
+			this.#clearButtonState();
+			this.dispatchEvent({
+				type: "disconnected",
+				gamepad: disconnected
+			});
+			return;
+		}
+		this.#gamepad = gamepad;
+		this.#syncButtonState({ seedPrevious: false });
+	}
+	/**
+	* Removes all window-level event listeners attached by this input reader.
+	*/
+	dispose() {
+		window.removeEventListener("gamepadconnected", this.#onGamepadConnected);
+		window.removeEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+		this.#manager.activeGamepad = null;
+		this.#gamepad = null;
+		this.#clearButtonState();
+		this.enabled = false;
+	}
+	/**
+	* Returns whether a button is currently pressed.
+	*
+	* @param button - Button index to inspect.
+	* @returns `true` when the button is currently pressed, otherwise `false`.
+	*/
+	isPressed(button) {
+		return this.#pressedButtons.has(button);
+	}
+	/**
+	* Returns whether a button was pressed during the latest update.
+	*
+	* @param button - Button index to inspect.
+	* @returns `true` only on the frame where the button transitions to pressed.
+	*/
+	wasPressed(button) {
+		return this.#pressedButtons.has(button) && !this.#previousPressedButtons.has(button);
+	}
+	/**
+	* Returns whether a button was released during the latest update.
+	*
+	* @param button - Button index to inspect.
+	* @returns `true` only on the frame where the button transitions to released.
+	*/
+	wasReleased(button) {
+		return !this.#pressedButtons.has(button) && this.#previousPressedButtons.has(button);
+	}
+	/**
+	* Returns the current analog value for a button.
+	*
+	* @param button - Button index to inspect.
+	* @returns The button value, `1` for pressed digital buttons, or `0`.
+	*/
+	buttonValue(button) {
+		if (this.#gamepad === null) return 0;
+		return getGamepadButtonValue(this.#gamepad, button);
+	}
+	/**
+	* Returns the current value of an axis after dead zone processing.
+	*
+	* @param axis - Axis index to inspect.
+	* @param options - Optional per-read axis options.
+	* @returns Axis value after dead zone processing, or `0` when unavailable.
+	*/
+	axis(axis, options) {
+		return applyGamepadDeadzone(this.#gamepad?.axes[axis] ?? 0, this.#getDeadzone(options));
+	}
+	/**
+	* Returns a two-axis stick after dead zone processing.
+	*
+	* @param xAxis - Horizontal axis index.
+	* @param yAxis - Vertical axis index.
+	* @param options - Optional per-read axis options.
+	* @returns Object containing processed `x` and `y` values.
+	*/
+	stick(xAxis, yAxis, options) {
+		return {
+			x: this.axis(xAxis, options),
+			y: this.axis(yAxis, options)
+		};
+	}
+	/**
+	* Handles a browser connection event and adopts the gamepad when possible.
+	*
+	* Button state is seeded as both current and previous so an already-held
+	* button does not produce a synthetic `wasPressed` transition on connect.
+	*
+	* @param gamepad - Browser-provided connected gamepad snapshot.
+	*/
+	#handleGamepadConnected(gamepad) {
+		if (!this.#manager.connect(gamepad)) return;
+		this.#gamepad = this.#manager.activeGamepad;
+		this.#syncButtonState({ seedPrevious: true });
+		this.dispatchEvent({
+			type: "connected",
+			gamepad
+		});
+	}
+	/**
+	* Handles a browser disconnection event for the active gamepad.
+	*
+	* Button state is cleared instead of diffed so disconnecting a controller
+	* does not produce synthetic `wasReleased` transitions.
+	*
+	* @param gamepad - Browser-provided disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnected(gamepad) {
+		const disconnectedGamepad = this.#manager.disconnect(gamepad);
+		if (disconnectedGamepad === null) return;
+		this.#gamepad = null;
+		this.#clearButtonState();
+		this.dispatchEvent({
+			type: "disconnected",
+			gamepad: disconnectedGamepad
+		});
+	}
+	/**
+	* Refreshes current and previous pressed-button sets from the active snapshot.
+	*
+	* When `seedPrevious` is `true`, the refreshed current state is copied into
+	* the previous state. This intentionally suppresses transition events on the
+	* first frame after adopting a gamepad.
+	*
+	* @param options - Button state synchronization options.
+	* @param options.seedPrevious - Whether to seed previous state from current state.
+	*/
+	#syncButtonState({ seedPrevious }) {
+		this.#previousPressedButtons.clear();
+		for (const button of this.#pressedButtons) this.#previousPressedButtons.add(button);
+		this.#pressedButtons.clear();
+		if (this.#gamepad !== null) {
+			for (let index = 0; index < this.#gamepad.buttons.length; index += 1) if (getGamepadButtonPressed(this.#gamepad, index)) this.#pressedButtons.add(index);
+		}
+		if (!seedPrevious) return;
+		this.#previousPressedButtons.clear();
+		for (const button of this.#pressedButtons) this.#previousPressedButtons.add(button);
+	}
+	/**
+	* Clears all stored button state.
+	*/
+	#clearButtonState() {
+		this.#pressedButtons.clear();
+		this.#previousPressedButtons.clear();
+	}
+	/**
+	* Resolves the dead zone for a single axis or stick read.
+	*
+	* @param options - Optional per-read axis options.
+	* @returns The per-read dead zone when provided, otherwise the instance default.
+	*/
+	#getDeadzone(options) {
+		return options?.deadzone ?? this.#options.deadzone;
+	}
+};
+//#endregion
+export { GamepadInput };

package/dist/gamepad-manager.js

@@ -0,0 +1,104 @@
+//#region src/gamepad-manager.ts
+const EMPTY_UPDATE_RESULT = {
+	gamepad: null,
+	connected: null,
+	disconnected: null
+};
+/**
+* Internal input core that owns active gamepad polling and snapshot refresh.
+*
+* This class intentionally tracks only one active gamepad. Higher-level
+* multi-gamepad selection should be built on top of this lifecycle in a
+* later phase.
+*
+* @internal
+*/
+var GamepadManager = class {
+	/**
+	* The active gamepad snapshot, or `null` when none is active.
+	*/
+	activeGamepad = null;
+	/**
+	* Accepts a gamepad as active when no active gamepad exists.
+	*
+	* Additional connected gamepads are ignored so the current controls keep
+	* using the first active device by default.
+	*
+	* @param gamepad - Gamepad snapshot to activate.
+	* @returns `true` when the gamepad became active, otherwise `false`.
+	*/
+	connect(gamepad) {
+		if (this.activeGamepad !== null || !gamepad.connected) return false;
+		this.activeGamepad = gamepad;
+		return true;
+	}
+	/**
+	* Clears the active gamepad when it matches the disconnecting gamepad index.
+	*
+	* @param gamepad - Gamepad snapshot that disconnected.
+	* @returns The previously active gamepad when it was cleared, otherwise `null`.
+	*/
+	disconnect(gamepad) {
+		if (this.activeGamepad?.index !== gamepad.index) return null;
+		const disconnectedGamepad = this.activeGamepad;
+		this.activeGamepad = null;
+		return disconnectedGamepad;
+	}
+	/**
+	* Polls the Gamepad API and refreshes the active gamepad snapshot.
+	*
+	* The browser exposes gamepad state as snapshots, so polling must replace
+	* the stored reference before controls read axes or buttons.
+	*
+	* @returns The active gamepad and any connect/disconnect transition found.
+	*/
+	update() {
+		if (this.activeGamepad === null) {
+			const connectedGamepad = this.#getFirstConnectedGamepad();
+			if (connectedGamepad === null) return EMPTY_UPDATE_RESULT;
+			this.activeGamepad = connectedGamepad;
+			return {
+				gamepad: connectedGamepad,
+				connected: connectedGamepad,
+				disconnected: null
+			};
+		}
+		const previousGamepad = this.activeGamepad;
+		const nextGamepad = this.#getGamepadByIndex(previousGamepad.index);
+		if (nextGamepad === null) {
+			this.activeGamepad = null;
+			return {
+				gamepad: null,
+				connected: null,
+				disconnected: previousGamepad
+			};
+		}
+		this.activeGamepad = nextGamepad;
+		return {
+			gamepad: nextGamepad,
+			connected: null,
+			disconnected: null
+		};
+	}
+	/**
+	* Reads the latest connected gamepad snapshot at a known index.
+	*
+	* @param index - Browser-assigned gamepad index to refresh.
+	* @returns A connected gamepad snapshot, or `null` if it is gone.
+	*/
+	#getGamepadByIndex(index) {
+		const gamepad = navigator.getGamepads()[index] ?? null;
+		return gamepad?.connected === true ? gamepad : null;
+	}
+	/**
+	* Finds the first currently connected gamepad snapshot.
+	*
+	* @returns The first connected gamepad snapshot, or `null` if none exist.
+	*/
+	#getFirstConnectedGamepad() {
+		for (const gamepad of navigator.getGamepads()) if (gamepad?.connected === true) return gamepad;
+		return null;
+	}
+};
+//#endregion
+export { GamepadManager };

package/dist/gamepad-orbit-controls.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
-import { applyGamepadDeadzone, getGamepadButtonValue } from "./utils.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { applyGamepadDeadzone, getGamepadButtonValue } from "./utils.js";
 //#region src/gamepad-orbit-controls.ts
 /**
 * Default options merged in the constructor when no explicit configuration is provided.

package/dist/gamepad-pointer-lock-controls.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS } from "./core.js";
-import { applyGamepadDeadzone } from "./utils.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { applyGamepadDeadzone } from "./utils.js";
 import { Euler } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
 /**

package/dist/gamepad-trackball-controls.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
-import { applyGamepadDeadzone, getGamepadButtonValue } from "./utils.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { applyGamepadDeadzone, getGamepadButtonValue } from "./utils.js";
 //#region src/gamepad-trackball-controls.ts
 /**
 * Default options merged in the constructor when no explicit configuration is provided.
@@ -51,6 +51,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		this.#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY);
 		this.#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
 	}
+	/**
+	* Queues rotation input into TrackballControls' normalized move state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param rotateSpeed - User-configured rotation speed multiplier.
+	* @param deadzone - Axis dead zone threshold.
+	* @param axisRotateX - Axis index for horizontal rotation.
+	* @param axisRotateY - Axis index for vertical rotation.
+	*/
 	#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
 		const controls = this.#controls;
 		if (controls.noRotate) {
@@ -65,6 +75,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		controls._moveCurr.x += rotX * scale;
 		controls._moveCurr.y += -rotY * scale;
 	}
+	/**
+	* Queues pan input into TrackballControls' normalized pan state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param panSpeed - User-configured pan speed multiplier.
+	* @param deadzone - Axis dead zone threshold.
+	* @param axisPanX - Axis index for horizontal panning.
+	* @param axisPanY - Axis index for vertical panning.
+	*/
 	#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY) {
 		const controls = this.#controls;
 		if (controls.noPan) {
@@ -78,6 +98,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		controls._panEnd.x += panX * scale;
 		controls._panEnd.y += panY * scale;
 	}
+	/**
+	* Queues trigger zoom input into TrackballControls' normalized zoom state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param zoomSpeed - User-configured zoom speed multiplier.
+	* @param deadzone - Trigger dead zone threshold.
+	* @param buttonZoomIn - Button index for zooming in.
+	* @param buttonZoomOut - Button index for zooming out.
+	*/
 	#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
 		const controls = this.#controls;
 		if (controls.noZoom) {
@@ -92,6 +122,8 @@ var GamepadTrackballControls = class extends GamepadControls {
 	/**
 	* Compensates for TrackballControls reapplying queued pan and zoom deltas
 	* while their input state catches up through damping.
+	*
+	* @returns Multiplier that matches TrackballControls' damping mode.
 	*/
 	#getInputDampingFactor() {
 		const controls = this.#controls;