three-gamepad-controls 0.10.6 → 0.12.0

package/README.md

@@ -2,6 +2,20 @@
 
 Gamepad support for [Three.js](https://threejs.org) controls, built on top of [Web Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API).
 
+## 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
+```
+
 ## 📦 Installation
 
 npm:
@@ -37,6 +51,7 @@ bun add three-gamepad-controls
 ## 📖 Documentation
 
 - [Core](./docs/core.md) — The fundamental building blocks.
+- [GamepadInput](./docs/gamepad-input.md) - Low-level reader for gamepad buttons, axes, sticks, and transitions.
 - [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

@@ -99,9 +99,8 @@ declare class GamepadArcballControls extends GamepadControls {
    * z-rotation, and center focus.
    *
    * @param deltaTime - Seconds since the last frame.
-   * @param gamepad - Fresh gamepad snapshot provided by the base class.
    */
-  protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
+  protected onUpdate(deltaTime: number): void;
 }
 //#endregion
 export { GamepadArcballControls, GamepadArcballControlsOptions };

package/dist/gamepad-arcball-controls.js

@@ -1,6 +1,5 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
-import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.js";
 import { Vector2, Vector3 } from "three";
 //#region src/gamepad-arcball-controls.ts
 /**
@@ -40,7 +39,6 @@ var GamepadArcballControls = class extends GamepadControls {
 	#cameraForward;
 	#cameraRight;
 	#previousUp;
-	#focusButtonPressed = false;
 	#wasInteracting = false;
 	/**
 	* @param controls - A Three.js `ArcballControls` instance.
@@ -67,22 +65,22 @@ var GamepadArcballControls = class extends GamepadControls {
 	* z-rotation, and center focus.
 	*
 	* @param deltaTime - Seconds since the last frame.
-	* @param gamepad - Fresh gamepad snapshot provided by the base class.
 	*/
-	onUpdate(deltaTime, gamepad) {
+	onUpdate(deltaTime) {
 		const controls = this.#controls;
 		const { rotateSpeed, panSpeed, zoomSpeed, zRotateSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
-		const focusPoint = this.#consumeFocusPoint(gamepad, buttonFocus);
+		const input = this.gamepadInput;
+		const focusPoint = this.#consumeFocusPoint(buttonFocus);
 		if (!controls.enabled) {
 			this.#endInteraction();
 			return;
 		}
-		const rotateX = controls.enableRotate ? applyGamepadDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone) : 0;
-		const rotateY = controls.enableRotate ? applyGamepadDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone) : 0;
-		const panX = controls.enablePan ? applyGamepadDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone) : 0;
-		const panY = controls.enablePan ? applyGamepadDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone) : 0;
-		const zoom = controls.enableZoom ? getGamepadButtonValue(gamepad, buttonZoomIn) - getGamepadButtonValue(gamepad, buttonZoomOut) : 0;
-		const zRotation = controls.enableRotate ? getGamepadButtonValue(gamepad, buttonZRotateLeft) - getGamepadButtonValue(gamepad, buttonZRotateRight) : 0;
+		const rotateX = controls.enableRotate ? input.axis(axisRotateX, { deadzone }) : 0;
+		const rotateY = controls.enableRotate ? input.axis(axisRotateY, { deadzone }) : 0;
+		const panX = controls.enablePan ? input.axis(axisPanX, { deadzone }) : 0;
+		const panY = controls.enablePan ? input.axis(axisPanY, { deadzone }) : 0;
+		const zoom = controls.enableZoom ? input.buttonValue(buttonZoomIn) - input.buttonValue(buttonZoomOut) : 0;
+		const zRotation = controls.enableRotate ? input.buttonValue(buttonZRotateLeft) - input.buttonValue(buttonZRotateRight) : 0;
 		const activeInput = rotateX !== 0 || rotateY !== 0 || panX !== 0 || panY !== 0 || Math.abs(zoom) > deadzone || Math.abs(zRotation) > deadzone;
 		if (!activeInput && focusPoint === null) {
 			this.#endInteraction();
@@ -103,6 +101,15 @@ var GamepadArcballControls = class extends GamepadControls {
 		this.#wasInteracting = activeInput;
 		if (!activeInput) this.#endInteraction();
 	}
+	/**
+	* Applies gamepad stick rotation through Arcball's runtime rotation helper.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param rotateX - Horizontal rotation input after dead zone processing.
+	* @param rotateY - Vertical rotation input after dead zone processing.
+	* @param rotateSpeed - User-configured rotation speed multiplier.
+	* @returns `true` when a rotation was applied.
+	*/
 	#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) {
 		if (rotateX === 0 && rotateY === 0) return false;
 		const controls = this.#controls;
@@ -119,6 +126,13 @@ var GamepadArcballControls = class extends GamepadControls {
 		}
 		return changed;
 	}
+	/**
+	* Applies an Arcball rotation around a specific world axis.
+	*
+	* @param axis - World axis to rotate around.
+	* @param angle - Rotation amount in radians.
+	* @returns `true` when ArcballControls produced and applied a transform.
+	*/
 	#applyRotationAroundAxis(axis, angle) {
 		if (axis.lengthSq() === 0 || angle === 0) return false;
 		const controls = this.#controls;
@@ -128,6 +142,15 @@ var GamepadArcballControls = class extends GamepadControls {
 		if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(axis, -angle);
 		return changed;
 	}
+	/**
+	* Applies gamepad pan by converting stick input to Arcball trackball points.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param panX - Horizontal pan input after dead zone processing.
+	* @param panY - Vertical pan input after dead zone processing.
+	* @param panSpeed - User-configured pan speed multiplier.
+	* @returns `true` when a pan transform was applied.
+	*/
 	#applyPan(deltaTime, panX, panY, panSpeed) {
 		if (panX === 0 && panY === 0) return false;
 		const controls = this.#controls;
@@ -137,6 +160,15 @@ var GamepadArcballControls = class extends GamepadControls {
 		this.#panEnd.set(panX * distance, panY * distance, 0);
 		return this.#applyTransform(controls.pan(this.#panStart, this.#panEnd));
 	}
+	/**
+	* Applies trigger-driven zoom around Arcball's gizmo center.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param zoom - Signed zoom input from the configured trigger pair.
+	* @param zoomSpeed - User-configured zoom speed multiplier.
+	* @param deadzone - Trigger dead zone threshold.
+	* @returns `true` when a zoom transform was applied.
+	*/
 	#applyZoom(deltaTime, zoom, zoomSpeed, deadzone) {
 		if (Math.abs(zoom) <= deadzone || this.#controls.scaleFactor <= 0) return false;
 		const controls = this.#controls;
@@ -145,6 +177,15 @@ var GamepadArcballControls = class extends GamepadControls {
 		controls.updateMatrixState();
 		return this.#applyTransform(controls.scale(size, controls._gizmos.position));
 	}
+	/**
+	* Applies shoulder-button rotation around the current camera view axis.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param zRotation - Signed z-rotation input from the configured buttons.
+	* @param zRotateSpeed - User-configured z-rotation speed multiplier.
+	* @param deadzone - Button value dead zone threshold.
+	* @returns `true` when a z-rotation transform was applied.
+	*/
 	#applyZRotation(deltaTime, zRotation, zRotateSpeed, deadzone) {
 		if (Math.abs(zRotation) <= deadzone) return false;
 		const controls = this.#controls;
@@ -156,6 +197,12 @@ var GamepadArcballControls = class extends GamepadControls {
 		if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(controls._rotationAxis, angle);
 		return changed;
 	}
+	/**
+	* Focuses ArcballControls on the given point when one was consumed.
+	*
+	* @param point - World-space focus point, or `null` when no focus is pending.
+	* @returns `true` when focus was applied.
+	*/
 	#applyFocus(point) {
 		if (point === null) return false;
 		const controls = this.#controls;
@@ -164,20 +211,32 @@ var GamepadArcballControls = class extends GamepadControls {
 		controls.updateMatrixState();
 		return true;
 	}
+	/**
+	* Applies a transformation returned by an Arcball runtime helper.
+	*
+	* @param transformation - Arcball transformation matrices, if any.
+	* @returns `true` when a transformation was applied.
+	*/
 	#applyTransform(transformation) {
 		if (transformation === void 0) return false;
 		this.#controls.applyTransformMatrix(transformation);
 		this.#controls.updateMatrixState();
 		return true;
 	}
-	#consumeFocusPoint(gamepad, buttonFocus) {
+	/**
+	* Consumes a focus-button press and resolves the viewport center hit point.
+	*
+	* @param buttonFocus - Button index configured for focus.
+	* @returns The center hit point, or `null` when focus should not run.
+	*/
+	#consumeFocusPoint(buttonFocus) {
 		const controls = this.#controls;
-		const focusPressed = getGamepadButtonPressed(gamepad, buttonFocus);
-		const shouldFocus = focusPressed && !this.#focusButtonPressed;
-		this.#focusButtonPressed = focusPressed;
-		if (!shouldFocus || !controls.enabled || !controls.enablePan || !controls.enableFocus || controls.scene === null) return null;
+		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,3 +1,4 @@
+import { GamepadInput } from "./gamepad-input.js";
 import { EventDispatcher } from "three";
 
 //#region src/gamepad-controls.d.ts
@@ -12,20 +13,26 @@ type GamepadControlsEventMap = {
    * Fired when a gamepad is connected and set as the active gamepad.
    */
   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;
   };
 };
 /**
  * Abstract base class for Three.js gamepad controls.
  *
- * Handles the gamepad connection lifecycle and input polling so subclasses
- * only need to implement {@link onUpdate}.
+ * Delegates gamepad connection lifecycle and input polling to {@link GamepadInput}
+ * so subclasses can focus on mapping input to the wrapped Three.js control.
  */
 declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEventMap> {
   #private;
@@ -38,7 +45,16 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    * The currently active gamepad, or `null` if no gamepad is connected.
    */
   gamepad: Gamepad | null;
+  /**
+   * Creates the base input reader and attaches lifecycle listeners.
+   */
   constructor();
+  /**
+   * Low-level gamepad input reader used by subclasses.
+   *
+   * @returns The shared input reader for the active gamepad.
+   */
+  protected get gamepadInput(): GamepadInput;
   /**
    * Advances the controller by one frame. Call this inside your render loop.
    *
@@ -53,25 +69,22 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    * Called every frame when a gamepad is available and `enabled` is `true`.
    *
    * @param deltaTime - Seconds since the last frame.
-   * @param gamepad - A fresh snapshot of the currently active gamepad.
    */
-  protected abstract onUpdate(deltaTime: number, gamepad: Gamepad): void;
+  protected abstract onUpdate(deltaTime: number): void;
   /**
-   * Called when any gamepad fires a `gamepadconnected` event.
+   * Called when a gamepad becomes active through the shared input reader.
    *
-   * The default accepts the first gamepad that connects and dispatches `connected`.
-   * Override to customize selection behavior.
+   * The default dispatches a `connected` event.
    *
-   * @param gamepad - The gamepad that just connected.
+   * @param gamepad - The gamepad that became active.
    */
   protected onGamepadConnected(gamepad: Gamepad): void;
   /**
-   * Called when any gamepad fires a `gamepaddisconnected` event.
+   * Called when the active gamepad disconnects through the shared input reader.
    *
-   * The default clears `this.gamepad` and dispatches `disconnected` if the
-   * disconnecting gamepad was the active one. Override to add custom cleanup.
+   * The default dispatches a `disconnected` event.
    *
-   * @param gamepad - The gamepad that just disconnected.
+   * @param gamepad - The gamepad that was active before disconnection.
    */
   protected onGamepadDisconnected(gamepad: Gamepad): void;
 }

package/dist/gamepad-controls.js

@@ -1,11 +1,11 @@
-import { GamepadManager } from "./gamepad-manager.js";
+import { GamepadInput } from "./gamepad-input.js";
 import { EventDispatcher } from "three";
 //#region src/gamepad-controls.ts
 /**
 * Abstract base class for Three.js gamepad controls.
 *
-* Handles the gamepad connection lifecycle and input polling so subclasses
-* only need to implement {@link onUpdate}.
+* Delegates gamepad connection lifecycle and input polling to {@link GamepadInput}
+* so subclasses can focus on mapping input to the wrapped Three.js control.
 */
 var GamepadControls = class extends EventDispatcher {
 	/**
@@ -17,20 +17,51 @@ var GamepadControls = class extends EventDispatcher {
 	* The currently active gamepad, or `null` if no gamepad is connected.
 	*/
 	gamepad = null;
-	#manager;
+	#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.
+	*/
 	constructor() {
 		super();
-		this.#manager = new GamepadManager();
-		this.#onGamepadConnected = (event) => {
-			this.onGamepadConnected(event.gamepad);
-		};
-		this.#onGamepadDisconnected = (event) => {
-			this.onGamepadDisconnected(event.gamepad);
-		};
-		window.addEventListener("gamepadconnected", this.#onGamepadConnected);
-		window.addEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+		this.#gamepadInput = new GamepadInput();
+		this.#onGamepadConnected = this.#handleGamepadConnected.bind(this);
+		this.#onGamepadDisconnected = this.#handleGamepadDisconnected.bind(this);
+		this.#gamepadInput.addEventListener("connected", this.#onGamepadConnected);
+		this.#gamepadInput.addEventListener("disconnected", this.#onGamepadDisconnected);
+	}
+	/**
+	* Low-level gamepad input reader used by subclasses.
+	*
+	* @returns The shared input reader for the active gamepad.
+	*/
+	get gamepadInput() {
+		return this.#gamepadInput;
+	}
+	/**
+	* Forwards an input connection event to the overridable lifecycle hook.
+	*
+	* @param event - Input event containing the connected gamepad snapshot.
+	*/
+	#handleGamepadConnected(event) {
+		this.gamepad = this.#gamepadInput.gamepad;
+		this.onGamepadConnected(event.gamepad);
+	}
+	/**
+	* Forwards an input disconnection event to the overridable lifecycle hook.
+	*
+	* @param event - Input event containing the disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnected(event) {
+		this.gamepad = this.#gamepadInput.gamepad;
+		this.onGamepadDisconnected(event.gamepad);
 	}
 	/**
 	* Advances the controller by one frame. Call this inside your render loop.
@@ -39,69 +70,45 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	update(deltaTime) {
 		if (!this.enabled) return;
-		this.#manager.activeGamepad = this.gamepad;
-		const { gamepad, connected, disconnected } = this.#manager.update();
-		if (connected !== null) {
-			this.#manager.activeGamepad = this.gamepad;
-			this.onGamepadConnected(connected);
-			this.#manager.activeGamepad = this.gamepad;
-		} else if (disconnected !== null) {
-			this.#manager.activeGamepad = this.gamepad;
-			this.onGamepadDisconnected(disconnected);
-			this.#manager.activeGamepad = this.gamepad;
-			return;
-		} else {
-			this.gamepad = gamepad;
-			this.#manager.activeGamepad = this.gamepad;
-		}
+		this.#gamepadInput.update();
+		this.gamepad = this.#gamepadInput.gamepad;
 		if (this.gamepad === null) return;
-		this.onUpdate(deltaTime, this.gamepad);
+		this.onUpdate(deltaTime);
 	}
 	/**
 	* Removes all event listeners attached by this controller. Call when no longer needed.
 	*/
 	dispose() {
-		window.removeEventListener("gamepadconnected", this.#onGamepadConnected);
-		window.removeEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+		this.#gamepadInput.removeEventListener("connected", this.#onGamepadConnected);
+		this.#gamepadInput.removeEventListener("disconnected", this.#onGamepadDisconnected);
+		this.#gamepadInput.dispose();
 		this.gamepad = null;
-		this.#manager.activeGamepad = null;
 		this.enabled = false;
 	}
 	/**
-	* Called when any gamepad fires a `gamepadconnected` event.
+	* Called when a gamepad becomes active through the shared input reader.
 	*
-	* The default accepts the first gamepad that connects and dispatches `connected`.
-	* Override to customize selection behavior.
+	* The default dispatches a `connected` event.
 	*
-	* @param gamepad - The gamepad that just connected.
+	* @param gamepad - The gamepad that became active.
 	*/
 	onGamepadConnected(gamepad) {
-		this.#manager.activeGamepad = this.gamepad;
-		if (!this.#manager.connect(gamepad)) return;
-		const connectedGamepad = this.#manager.activeGamepad;
-		if (connectedGamepad === null) return;
-		this.gamepad = connectedGamepad;
 		this.dispatchEvent({
 			type: "connected",
-			gamepad: connectedGamepad
+			gamepad
 		});
 	}
 	/**
-	* Called when any gamepad fires a `gamepaddisconnected` event.
+	* Called when the active gamepad disconnects through the shared input reader.
 	*
-	* The default clears `this.gamepad` and dispatches `disconnected` if the
-	* disconnecting gamepad was the active one. Override to add custom cleanup.
+	* The default dispatches a `disconnected` event.
 	*
-	* @param gamepad - The gamepad that just disconnected.
+	* @param gamepad - The gamepad that was active before disconnection.
 	*/
 	onGamepadDisconnected(gamepad) {
-		this.#manager.activeGamepad = this.gamepad;
-		const disconnectedGamepad = this.#manager.disconnect(gamepad);
-		if (disconnectedGamepad === null) return;
-		this.gamepad = this.#manager.activeGamepad;
 		this.dispatchEvent({
 			type: "disconnected",
-			gamepad: disconnectedGamepad
+			gamepad
 		});
 	}
 };

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

@@ -68,9 +68,8 @@ declare class GamepadDragControls extends GamepadControls {
    * and rotate behavior.
    *
    * @param deltaTime - Seconds since the last frame.
-   * @param gamepad - Fresh gamepad snapshot provided by the base class.
    */
-  protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
+  protected onUpdate(deltaTime: number): void;
   /**
    * Releases any selected object and removes hover state before disposing the
    * gamepad lifecycle listeners.