three-gamepad-controls 0.12.0 → 0.13.0

package/README.md

@@ -4,54 +4,58 @@ Gamepad support for [Three.js](https://threejs.org) controls, built on top of [W
 
 ## Architecture
 
-```mermaid
-flowchart TD
-  GamepadManager["GamepadManager<br/>(internal polling and active device lifecycle)"]
-  GamepadInput["GamepadInput<br/>(public low-level input state)"]
-  GamepadControls["GamepadControls<br/>(abstract Three.js wrapper base)"]
-  Wrappers["Specific wrappers<br/>(Orbit, Map, Fly, Transform, etc.)"]
-
-  GamepadManager --> GamepadInput
-  GamepadInput --> GamepadControls
-  GamepadControls --> Wrappers
-```
+![Architecture diagram showing GamepadManager used by GamepadInput, GamepadInput used by GamepadControls, and specific wrappers extending GamepadControls.](./assets/architecture-diagram.webp "Three.js Gamepad Controls architecture")
 
 ## 📦 Installation
 
 npm:
 
 ```bash
-npm i three-gamepad-controls
+npm i three three-gamepad-controls
+npm i -D @types/three # optional: for TypeScript projects
 ```
 
 pnpm:
 
 ```bash
-pnpm add three-gamepad-controls
+pnpm add three three-gamepad-controls
+pnpm add -D @types/three # optional: for TypeScript projects
 ```
 
 Yarn:
 
 ```bash
-yarn add three-gamepad-controls
+yarn add three three-gamepad-controls
+yarn add -D @types/three # optional: for TypeScript projects
 ```
 
 Deno:
 
+When using `deno.json`, Deno stores dependencies in `imports` and does not separate `devDependencies`; `-D` only applies when writing to `package.json`.
+
+```bash
+# deno.json
+deno add three @types/three three-gamepad-controls
+```
+
 ```bash
-deno add npm:three-gamepad-controls
+# package.json
+deno add --package-json three three-gamepad-controls
+deno add --package-json -D @types/three # optional: for TypeScript projects
 ```
 
 Bun:
 
 ```bash
-bun add three-gamepad-controls
+bun add three three-gamepad-controls
+bun add -d @types/three # optional: for TypeScript projects
 ```
 
 ## 📖 Documentation
 
 - [Core](./docs/core.md) — The fundamental building blocks.
 - [GamepadInput](./docs/gamepad-input.md) - Low-level reader for gamepad buttons, axes, sticks, and transitions.
+- [Multiple Gamepads](./docs/multiple-gamepads.md) - Assign different gamepads to controls, players, and gameplay inputs.
 - [GamepadControls](./docs/gamepad-controls.md) — Abstract base class for custom gamepad controls.
 - [GamepadArcballControls](./docs/gamepad-arcball-controls.md) - Gamepad support for `ArcballControls`.
 - [GamepadDragControls](./docs/gamepad-drag-controls.md) - Gamepad support for `DragControls`.

package/dist/gamepad-arcball-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { ArcballControls } from "three/addons/controls/ArcballControls.js";
 
 //#region src/gamepad-arcball-controls.d.ts
@@ -7,7 +7,7 @@ import { ArcballControls } from "three/addons/controls/ArcballControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadArcballControlsOptions = {
+type GamepadArcballControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `ArcballControls.rotateSpeed` for rotation.
    * @default 1.0

package/dist/gamepad-arcball-controls.js

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Vector2, Vector3 } from "three";
 //#region src/gamepad-arcball-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_ARCBALL_OPTIONS = {
 	rotateSpeed: 1,
 	panSpeed: 1,
@@ -46,7 +43,7 @@ var GamepadArcballControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_ARCBALL_OPTIONS,
@@ -234,9 +231,6 @@ var GamepadArcballControls = class extends GamepadControls {
 		if (!this.gamepadInput.wasPressed(buttonFocus) || !controls.enabled || !controls.enablePan || !controls.enableFocus || controls.scene === null) return null;
 		return controls.unprojectOnObj(this.#centerNdc, controls.object);
 	}
-	/**
-	* Dispatches Arcball's `end` event when an active gamepad interaction stops.
-	*/
 	#endInteraction() {
 		if (!this.#wasInteracting) return;
 		this.#controls.dispatchEvent({ type: "end" });

package/dist/gamepad-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadInput } from "./gamepad-input.js";
+import { GamepadInput, GamepadInputOptions } from "./gamepad-input.js";
 import { EventDispatcher } from "three";
 
 //#region src/gamepad-controls.d.ts
@@ -19,7 +19,7 @@ type GamepadControlsEventMap = {
     gamepad: Gamepad;
   };
   /**
-   * Fired when the active gamepad is disconnected.
+   * Fired when the active gamepad is disconnected or replaced in its slot.
    */
   disconnected: {
     /**
@@ -28,6 +28,10 @@ type GamepadControlsEventMap = {
     gamepad: Gamepad;
   };
 };
+/**
+ * Shared configuration for Three.js gamepad control wrappers.
+ */
+type GamepadControlsOptions = Pick<GamepadInputOptions, "gamepadIndex">;
 /**
  * Abstract base class for Three.js gamepad controls.
  *
@@ -47,8 +51,12 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
   gamepad: Gamepad | null;
   /**
    * Creates the base input reader and attaches lifecycle listeners.
+   *
+   * @param options - Shared gamepad selection options.
+   * @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
+   * range `[0, 2147483647]`.
    */
-  constructor();
+  constructor(options?: GamepadControlsOptions);
   /**
    * Low-level gamepad input reader used by subclasses.
    *
@@ -80,7 +88,8 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    */
   protected onGamepadConnected(gamepad: Gamepad): void;
   /**
-   * Called when the active gamepad disconnects through the shared input reader.
+   * Called when the active gamepad disconnects or is replaced through the
+   * shared input reader.
    *
    * The default dispatches a `disconnected` event.
    *
@@ -89,4 +98,4 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
   protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
 //#endregion
-export { GamepadControls, GamepadControlsEventMap };
+export { GamepadControls, GamepadControlsEventMap, GamepadControlsOptions };

package/dist/gamepad-controls.js

@@ -18,20 +18,18 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	gamepad = null;
 	#gamepadInput;
-	/**
-	* Bound input connection listener kept so it can be removed in {@link dispose}.
-	*/
 	#onGamepadConnected;
-	/**
-	* Bound input disconnection listener kept so it can be removed in {@link dispose}.
-	*/
 	#onGamepadDisconnected;
 	/**
 	* Creates the base input reader and attaches lifecycle listeners.
+	*
+	* @param options - Shared gamepad selection options.
+	* @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
+	* range `[0, 2147483647]`.
 	*/
-	constructor() {
+	constructor(options) {
 		super();
-		this.#gamepadInput = new GamepadInput();
+		this.#gamepadInput = new GamepadInput(options);
 		this.#onGamepadConnected = this.#handleGamepadConnected.bind(this);
 		this.#onGamepadDisconnected = this.#handleGamepadDisconnected.bind(this);
 		this.#gamepadInput.addEventListener("connected", this.#onGamepadConnected);
@@ -99,7 +97,8 @@ var GamepadControls = class extends EventDispatcher {
 		});
 	}
 	/**
-	* Called when the active gamepad disconnects through the shared input reader.
+	* Called when the active gamepad disconnects or is replaced through the
+	* shared input reader.
 	*
 	* The default dispatches a `disconnected` event.
 	*

package/dist/gamepad-drag-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { DragControls } from "three/addons/controls/DragControls.js";
 
 //#region src/gamepad-drag-controls.d.ts
@@ -7,7 +7,7 @@ import { DragControls } from "three/addons/controls/DragControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadDragControlsOptions = {
+type GamepadDragControlsOptions = GamepadControlsOptions & {
   /**
    * Screen-relative translation speed multiplier.
    * @default 1.0

package/dist/gamepad-drag-controls.js

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Matrix4, Vector2, Vector3 } from "three";
 //#region src/gamepad-drag-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_DRAG_OPTIONS = {
 	dragSpeed: 1,
 	rotateSpeed: 1,
@@ -43,7 +40,7 @@ var GamepadDragControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_DRAG_OPTIONS,
@@ -191,9 +188,6 @@ var GamepadDragControls = class extends GamepadControls {
 			object
 		});
 	}
-	/**
-	* Clears the current hover object and dispatches `hoveroff` when needed.
-	*/
 	#clearHover() {
 		if (this.#hovered === null) return;
 		const object = this.#hovered;
@@ -218,9 +212,6 @@ var GamepadDragControls = class extends GamepadControls {
 			object: selected
 		});
 	}
-	/**
-	* Releases the selected object and dispatches DragControls `dragend`.
-	*/
 	#releaseSelected() {
 		if (this.#selected === null) return;
 		const selected = this.#selected;
@@ -255,9 +246,6 @@ var GamepadDragControls = class extends GamepadControls {
 		}
 		return group;
 	}
-	/**
-	* Writes the accumulated world-space selected position back to the object.
-	*/
 	#applySelectedWorldPosition() {
 		const selected = this.#selected;
 		if (selected === null) return;
@@ -272,18 +260,12 @@ var GamepadDragControls = class extends GamepadControls {
 		selected.position.copy(this.#selectedLocalPosition);
 		selected.updateMatrixWorld();
 	}
-	/**
-	* Refreshes camera-relative axes used for dragging and rotation.
-	*/
 	#updateCameraAxes() {
 		const camera = this.#controls.object;
 		this.#cameraRight.set(1, 0, 0).applyQuaternion(camera.quaternion).normalize();
 		this.#cameraUp.set(0, 1, 0).applyQuaternion(camera.quaternion).normalize();
 		camera.getWorldDirection(this.#cameraForward).normalize();
 	}
-	/**
-	* Computes the world-space viewport size at the selected object's depth.
-	*/
 	#updateViewSizeAtSelectedDepth() {
 		const camera = this.#controls.object;
 		if (this.#isOrthographicCamera(camera)) {

package/dist/gamepad-first-person-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.js";
 
 //#region src/gamepad-first-person-controls.d.ts
@@ -7,7 +7,7 @@ import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.j
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadFirstPersonControlsOptions = {
+type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `FirstPersonControls.movementSpeed` for translation.
    * @default 1.0

package/dist/gamepad-first-person-controls.js

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { MathUtils, Spherical, Vector3 } from "three";
 //#region src/gamepad-first-person-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_FIRST_PERSON_OPTIONS = {
 	moveSpeed: 1,
 	lookSpeed: 1,
@@ -36,7 +33,7 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_FIRST_PERSON_OPTIONS,

package/dist/gamepad-fly-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FlyControls } from "three/addons/controls/FlyControls.js";
 
 //#region src/gamepad-fly-controls.d.ts
@@ -7,7 +7,7 @@ import { FlyControls } from "three/addons/controls/FlyControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadFlyControlsOptions = {
+type GamepadFlyControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `FlyControls.movementSpeed` for translation.
    * @default 1.0

package/dist/gamepad-fly-controls.js

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Quaternion } from "three";
 //#region src/gamepad-fly-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_FLY_OPTIONS = {
 	moveSpeed: 1,
 	rotateSpeed: 1,
@@ -35,7 +32,7 @@ var GamepadFlyControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_FLY_OPTIONS,

package/dist/gamepad-input.d.ts

@@ -15,7 +15,7 @@ type GamepadInputEventMap = {
     gamepad: Gamepad;
   };
   /**
-   * Fired when the active gamepad is disconnected.
+   * Fired when the active gamepad is disconnected or replaced in its slot.
    */
   disconnected: {
     /**
@@ -33,6 +33,15 @@ type GamepadInputOptions = {
    * @default 0.1
    */
   deadzone: number;
+  /**
+   * Browser-assigned gamepad slot to use.
+   *
+   * When omitted, the connected gamepad with the lowest index is selected.
+   * The index must be an integer in the inclusive range `[0, 2147483647]`.
+   * A valid but empty slot keeps this input disconnected without falling back
+   * to another gamepad.
+   */
+  gamepadIndex?: number;
 };
 /**
  * Options for axis and stick reads.
@@ -72,6 +81,8 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    * Creates a gamepad input reader.
    *
    * @param options - Optional overrides for the default input behavior.
+   * @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
+   * range `[0, 2147483647]`.
    */
   constructor(options?: Partial<GamepadInputOptions>);
   /**

package/dist/gamepad-input.js

@@ -58,27 +58,23 @@ var GamepadInput = class extends EventDispatcher {
 	#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.
+	* @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
+	* range `[0, 2147483647]`.
 	*/
 	constructor(options) {
 		super();
-		this.#manager = new GamepadManager();
 		this.#options = {
 			...DEFAULT_GAMEPAD_INPUT_OPTIONS,
 			...options
 		};
+		this.#manager = new GamepadManager({ gamepadIndex: this.#options.gamepadIndex });
 		this.#pressedButtons = /* @__PURE__ */ new Set();
 		this.#previousPressedButtons = /* @__PURE__ */ new Set();
 		this.#onGamepadConnected = this.#handleGamepadConnectedEvent.bind(this);
@@ -242,12 +238,13 @@ var GamepadInput = class extends EventDispatcher {
 	* @param gamepad - Browser-provided connected gamepad snapshot.
 	*/
 	#handleGamepadConnected(gamepad) {
-		if (!this.#manager.connect(gamepad)) return;
-		this.#gamepad = this.#manager.activeGamepad;
+		const connectedGamepad = this.#manager.connect(gamepad);
+		if (connectedGamepad === null) return;
+		this.#gamepad = connectedGamepad;
 		this.#syncButtonState({ seedPrevious: true });
 		this.dispatchEvent({
 			type: "connected",
-			gamepad
+			gamepad: connectedGamepad
 		});
 	}
 	/**
@@ -289,9 +286,6 @@ var GamepadInput = class extends EventDispatcher {
 		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();

package/dist/gamepad-manager.js

@@ -1,4 +1,5 @@
 //#region src/gamepad-manager.ts
+const MAX_GAMEPAD_INDEX = 2147483647;
 const EMPTY_UPDATE_RESULT = {
 	gamepad: null,
 	connected: null,
@@ -7,54 +8,74 @@ const EMPTY_UPDATE_RESULT = {
 /**
 * 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.
+* Each manager instance tracks one active gamepad, optionally selected by its
+* browser-assigned `Gamepad.index`.
 *
 * @internal
 */
 var GamepadManager = class {
+	activeGamepad = null;
+	#connectionDeferredUntilUpdate = false;
+	#selection;
 	/**
-	* The active gamepad snapshot, or `null` when none is active.
+	* Creates an active-gamepad manager.
+	*
+	* @param options - Optional active gamepad selection options.
+	* @throws {RangeError} When `gamepadIndex` is outside the valid Web IDL
+	* `long` range for a gamepad index.
 	*/
-	activeGamepad = null;
+	constructor(options) {
+		this.#selection = this.#resolveSelection(options?.gamepadIndex);
+	}
 	/**
-	* Accepts a gamepad as active when no active gamepad exists.
+	* Uses a connection event to resolve and activate the configured gamepad.
 	*
-	* Additional connected gamepads are ignored so the current controls keep
-	* using the first active device by default.
+	* In first-available mode, the event is only a signal to inspect the complete
+	* Gamepad API state. The connected gamepad with the lowest index is adopted,
+	* which may differ from the gamepad carried by the event.
+	* Connection events are deferred after losing an active gamepad so its
+	* replacement can only be adopted by the next {@link update}.
 	*
-	* @param gamepad - Gamepad snapshot to activate.
-	* @returns `true` when the gamepad became active, otherwise `false`.
+	* @param gamepad - Gamepad snapshot carried by the connection event.
+	* @returns The gamepad that became active, or `null` when none was adopted.
 	*/
 	connect(gamepad) {
-		if (this.activeGamepad !== null || !gamepad.connected) return false;
-		this.activeGamepad = gamepad;
-		return true;
+		if (this.activeGamepad !== null || this.#connectionDeferredUntilUpdate || !gamepad.connected || !this.#matchesSelection(gamepad)) return null;
+		const selectedGamepad = this.#getSelectableGamepad();
+		if (selectedGamepad === null) return null;
+		this.activeGamepad = selectedGamepad;
+		return selectedGamepad;
 	}
 	/**
-	* Clears the active gamepad when it matches the disconnecting gamepad index.
+	* Clears the active gamepad when it is the disconnecting gamepad instance.
+	*
+	* Identity is intentionally checked in addition to the browser-assigned
+	* index. Indices may be reused, so a late event from a previous device must
+	* not disconnect a replacement that now occupies the same slot.
+	* A matching disconnection defers any replacement until the next update.
 	*
 	* @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;
+		if (this.activeGamepad !== gamepad) return null;
 		const disconnectedGamepad = this.activeGamepad;
 		this.activeGamepad = null;
+		this.#connectionDeferredUntilUpdate = true;
 		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.
+	* Polling re-resolves the browser slot so a disconnected device, a reused
+	* index, or an updated active device is observed before controls read input.
 	*
 	* @returns The active gamepad and any connect/disconnect transition found.
 	*/
 	update() {
 		if (this.activeGamepad === null) {
-			const connectedGamepad = this.#getFirstConnectedGamepad();
+			this.#connectionDeferredUntilUpdate = false;
+			const connectedGamepad = this.#getSelectableGamepad();
 			if (connectedGamepad === null) return EMPTY_UPDATE_RESULT;
 			this.activeGamepad = connectedGamepad;
 			return {
@@ -65,8 +86,9 @@ var GamepadManager = class {
 		}
 		const previousGamepad = this.activeGamepad;
 		const nextGamepad = this.#getGamepadByIndex(previousGamepad.index);
-		if (nextGamepad === null) {
+		if (!previousGamepad.connected || nextGamepad === null || nextGamepad !== previousGamepad) {
 			this.activeGamepad = null;
+			this.#connectionDeferredUntilUpdate = true;
 			return {
 				gamepad: null,
 				connected: null,
@@ -81,6 +103,15 @@ var GamepadManager = class {
 		};
 	}
 	/**
+	* Finds the connected gamepad matching the configured selection.
+	*
+	* @returns A selectable gamepad snapshot, or `null` if none is available.
+	*/
+	#getSelectableGamepad() {
+		if (this.#selection.type === "index") return this.#getGamepadByIndex(this.#selection.index);
+		return this.#getFirstAvailableGamepad();
+	}
+	/**
 	* Reads the latest connected gamepad snapshot at a known index.
 	*
 	* @param index - Browser-assigned gamepad index to refresh.
@@ -91,13 +122,43 @@ var GamepadManager = class {
 		return gamepad?.connected === true ? gamepad : null;
 	}
 	/**
-	* Finds the first currently connected gamepad snapshot.
+	* Finds the connected gamepad with the lowest browser-assigned index.
+	*
+	* The array is normally sparse and ordered by index, but comparing the
+	* reported indices keeps the selection deterministic for API mocks as well.
+	*
+	* @returns The lowest-index connected gamepad, or `null` if none exist.
+	*/
+	#getFirstAvailableGamepad() {
+		let firstAvailableGamepad = null;
+		for (const gamepad of navigator.getGamepads()) if (gamepad?.connected === true && (firstAvailableGamepad === null || gamepad.index < firstAvailableGamepad.index)) firstAvailableGamepad = gamepad;
+		return firstAvailableGamepad;
+	}
+	/**
+	* Checks whether a connection event is relevant to this manager.
 	*
-	* @returns The first connected gamepad snapshot, or `null` if none exist.
+	* @param gamepad - Gamepad snapshot carried by the event.
+	* @returns `true` when the event may trigger configured selection.
 	*/
-	#getFirstConnectedGamepad() {
-		for (const gamepad of navigator.getGamepads()) if (gamepad?.connected === true) return gamepad;
-		return null;
+	#matchesSelection(gamepad) {
+		if (this.#selection.type === "index") return gamepad.index === this.#selection.index;
+		return true;
+	}
+	/**
+	* Resolves a public index option to an immutable internal selection mode.
+	*
+	* @param gamepadIndex - Browser-assigned gamepad index option.
+	* @returns Internal active-gamepad selection mode.
+	* @throws {RangeError} When the explicit index is not an integer in the
+	* inclusive range `[0, 2147483647]`.
+	*/
+	#resolveSelection(gamepadIndex) {
+		if (gamepadIndex === void 0) return { type: "first-available" };
+		if (!Number.isInteger(gamepadIndex) || gamepadIndex < 0 || gamepadIndex > MAX_GAMEPAD_INDEX) throw new RangeError(`gamepadIndex must be an integer between 0 and ${MAX_GAMEPAD_INDEX}.`);
+		return {
+			type: "index",
+			index: gamepadIndex
+		};
 	}
 };
 //#endregion

package/dist/gamepad-map-controls.js

@@ -1,9 +1,6 @@
 import { GAMEPAD_AXIS } from "./core.js";
 import { GamepadOrbitControls } from "./gamepad-orbit-controls.js";
 //#region src/gamepad-map-controls.ts
-/**
-* Axis overrides for {@link GamepadMapControls}: left stick pans, right stick orbits.
-*/
 const DEFAULT_MAP_OPTIONS = {
 	axisPanX: GAMEPAD_AXIS.LeftX,
 	axisPanY: GAMEPAD_AXIS.LeftY,

package/dist/gamepad-orbit-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
 
 //#region src/gamepad-orbit-controls.d.ts
@@ -7,7 +7,7 @@ import { OrbitControls } from "three/addons/controls/OrbitControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadOrbitControlsOptions = {
+type GamepadOrbitControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on orbit rotation speed.
    * @default 1.0

package/dist/gamepad-orbit-controls.js

@@ -1,9 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 //#region src/gamepad-orbit-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_ORBIT_OPTIONS = {
 	rotateSpeed: 1,
 	panSpeed: 1,
@@ -31,7 +28,7 @@ var GamepadOrbitControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_ORBIT_OPTIONS,

package/dist/gamepad-pointer-lock-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { PointerLockControls } from "three/addons/controls/PointerLockControls.js";
 
 //#region src/gamepad-pointer-lock-controls.d.ts
@@ -7,7 +7,7 @@ import { PointerLockControls } from "three/addons/controls/PointerLockControls.j
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadPointerLockControlsOptions = {
+type GamepadPointerLockControlsOptions = GamepadControlsOptions & {
   /**
    * Camera movement speed in world units per second at full stick deflection.
    * @default 5.0

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

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Euler } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_POINTER_LOCK_OPTIONS = {
 	moveSpeed: 5,
 	lookSpeed: 1,
@@ -31,7 +28,7 @@ var GamepadPointerLockControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_POINTER_LOCK_OPTIONS,

package/dist/gamepad-trackball-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { TrackballControls } from "three/addons/controls/TrackballControls.js";
 
 //#region src/gamepad-trackball-controls.d.ts
@@ -7,7 +7,7 @@ import { TrackballControls } from "three/addons/controls/TrackballControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadTrackballControlsOptions = {
+type GamepadTrackballControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `TrackballControls.rotateSpeed` for rotation.
    * @default 1.0

package/dist/gamepad-trackball-controls.js

@@ -1,9 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 //#region src/gamepad-trackball-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_TRACKBALL_OPTIONS = {
 	rotateSpeed: 1,
 	panSpeed: 1,
@@ -31,7 +28,7 @@ var GamepadTrackballControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_TRACKBALL_OPTIONS,

package/dist/gamepad-transform-controls.d.ts

@@ -1,4 +1,4 @@
-import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { TransformControls } from "three/addons/controls/TransformControls.js";
 
 //#region src/gamepad-transform-controls.d.ts
@@ -7,7 +7,7 @@ import { TransformControls } from "three/addons/controls/TransformControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadTransformControlsOptions = {
+type GamepadTransformControlsOptions = GamepadControlsOptions & {
   /**
    * Screen-relative translation speed multiplier.
    * @default 1.0

package/dist/gamepad-transform-controls.js

@@ -2,9 +2,6 @@ import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Matrix4, Quaternion, Vector2, Vector3 } from "three";
 //#region src/gamepad-transform-controls.ts
-/**
-* Default options merged in the constructor when no explicit configuration is provided.
-*/
 const DEFAULT_TRANSFORM_OPTIONS = {
 	translateSpeed: 1,
 	rotateSpeed: 1,
@@ -109,7 +106,7 @@ var GamepadTransformControls = class extends GamepadControls {
 	*                  Any property not provided falls back to its default value.
 	*/
 	constructor(controls, options) {
-		super();
+		super(options);
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_TRANSFORM_OPTIONS,
@@ -226,9 +223,6 @@ var GamepadTransformControls = class extends GamepadControls {
 		this.#controls.setMode(mode);
 		this.#ensureValidAxis();
 	}
-	/**
-	* Toggles TransformControls between local and world transform space.
-	*/
 	#toggleSpace() {
 		const nextSpace = this.#controls.space === "world" ? "local" : "world";
 		this.#endTransform(false);
@@ -245,9 +239,6 @@ var GamepadTransformControls = class extends GamepadControls {
 		this.#activeAxisByMode[this.#controls.mode] = axis;
 		this.#ensureValidAxis();
 	}
-	/**
-	* Cycles through composite axes available in the current mode.
-	*/
 	#cycleCompositeAxis() {
 		const validAxes = this.#getVisibleAxes(COMPOSITE_AXES[this.#controls.mode]);
 		this.#cycleThroughAxes(validAxes, 1);
@@ -386,9 +377,6 @@ var GamepadTransformControls = class extends GamepadControls {
 		}
 		if (clearAxis) this.#setActiveAxis(null);
 	}
-	/**
-	* Resets the active object to TransformControls' captured drag start state.
-	*/
 	#resetActiveTransform() {
 		const object = this.#controls.object;
 		if (!this.#isTransforming || object === void 0) return;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue } from "./core.js";
 import { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick } from "./gamepad-input.js";
-import { GamepadControls, GamepadControlsEventMap } from "./gamepad-controls.js";
+import { GamepadControls, GamepadControlsEventMap, GamepadControlsOptions } from "./gamepad-controls.js";
 import { GamepadArcballControls, GamepadArcballControlsOptions } from "./gamepad-arcball-controls.js";
 import { GamepadDragControls, GamepadDragControlsOptions } from "./gamepad-drag-controls.js";
 import { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions } from "./gamepad-first-person-controls.js";
@@ -10,4 +10,4 @@ import { GamepadMapControls } from "./gamepad-map-controls.js";
 import { GamepadPointerLockControls, GamepadPointerLockControlsOptions } from "./gamepad-pointer-lock-controls.js";
 import { GamepadTrackballControls, GamepadTrackballControlsOptions } from "./gamepad-trackball-controls.js";
 import { GamepadTransformControls, GamepadTransformControlsOptions } from "./gamepad-transform-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadStick, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadControlsOptions, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadStick, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {
     "name": "Kasnix",
@@ -46,15 +46,15 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.0",
-    "@commitlint/cli": "21.0.2",
-    "@commitlint/config-conventional": "21.0.2",
-    "@commitlint/types": "21.0.1",
+    "@biomejs/biome": "2.5.1",
+    "@commitlint/cli": "21.2.0",
+    "@commitlint/config-conventional": "21.2.0",
+    "@commitlint/types": "21.2.0",
     "@types/node": "24.13.2",
     "@types/three": "0.184.0",
     "husky": "9.1.7",
     "three": "0.184.0",
-    "tsdown": "0.22.2",
+    "tsdown": "0.22.3",
     "typescript": "6.0.3"
   },
   "peerDependencies": {