three-gamepad-controls 0.10.5 → 0.11.0

package/README.md

@@ -37,6 +37,7 @@ bun add three-gamepad-controls
 ## 📖 Documentation
 
 - [Core](./docs/core.md) — The fundamental building blocks.
+- [GamepadInput](./docs/gamepad-input.md) - Gamepad input state reader for gameplay and menus.
 - [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.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
-import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.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
 /**
@@ -103,6 +103,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 +128,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 +144,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 +162,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 +179,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 +199,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,12 +213,25 @@ 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;
 	}
+	/**
+	* Consumes a focus-button press and resolves the viewport center hit point.
+	*
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param buttonFocus - Button index configured for focus.
+	* @returns The center hit point, or `null` when focus should not run.
+	*/
 	#consumeFocusPoint(gamepad, buttonFocus) {
 		const controls = this.#controls;
 		const focusPressed = getGamepadButtonPressed(gamepad, buttonFocus);
@@ -178,6 +240,9 @@ var GamepadArcballControls = class extends GamepadControls {
 		if (!shouldFocus || !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

@@ -12,12 +12,18 @@ 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;
   };
 };
@@ -38,6 +44,9 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    * The currently active gamepad, or `null` if no gamepad is connected.
    */
   gamepad: Gamepad | null;
+  /**
+   * Creates the base gamepad lifecycle manager and attaches browser listeners.
+   */
   constructor();
   /**
    * Advances the controller by one frame. Call this inside your render loop.

package/dist/gamepad-controls.js

@@ -1,4 +1,4 @@
-import { getFirstConnectedGamepad, getGamepadByIndex } from "./utils.js";
+import { GamepadManager } from "./gamepad-manager.js";
 import { EventDispatcher } from "three";
 //#region src/gamepad-controls.ts
 /**
@@ -17,37 +17,63 @@ var GamepadControls = class extends EventDispatcher {
 	* The currently active gamepad, or `null` if no gamepad is connected.
 	*/
 	gamepad = null;
+	#manager;
+	/**
+	* 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;
+	/**
+	* Creates the base gamepad lifecycle manager and attaches browser listeners.
+	*/
 	constructor() {
 		super();
-		this.#onGamepadConnected = (event) => {
-			this.onGamepadConnected(event.gamepad);
-		};
-		this.#onGamepadDisconnected = (event) => {
-			this.onGamepadDisconnected(event.gamepad);
-		};
+		this.#manager = new GamepadManager();
+		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 overridable lifecycle hook.
+	*
+	* @param event - Browser event containing the connected gamepad snapshot.
+	*/
+	#handleGamepadConnectedEvent(event) {
+		this.onGamepadConnected(event.gamepad);
+	}
+	/**
+	* Forwards a browser disconnection event to the overridable lifecycle hook.
+	*
+	* @param event - Browser event containing the disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnectedEvent(event) {
+		this.onGamepadDisconnected(event.gamepad);
+	}
+	/**
 	* Advances the controller by one frame. Call this inside your render loop.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	update(deltaTime) {
 		if (!this.enabled) return;
-		if (this.gamepad === null) {
-			const connectedGamepad = getFirstConnectedGamepad();
-			if (connectedGamepad !== null) this.onGamepadConnected(connectedGamepad);
+		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 {
-			const previousGamepad = this.gamepad;
-			const nextGamepad = getGamepadByIndex(previousGamepad.index);
-			if (nextGamepad === null) {
-				this.onGamepadDisconnected(previousGamepad);
-				return;
-			}
-			this.gamepad = nextGamepad;
+			this.gamepad = gamepad;
+			this.#manager.activeGamepad = this.gamepad;
 		}
 		if (this.gamepad === null) return;
 		this.onUpdate(deltaTime, this.gamepad);
@@ -59,6 +85,7 @@ var GamepadControls = class extends EventDispatcher {
 		window.removeEventListener("gamepadconnected", this.#onGamepadConnected);
 		window.removeEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
 		this.gamepad = null;
+		this.#manager.activeGamepad = null;
 		this.enabled = false;
 	}
 	/**
@@ -70,11 +97,14 @@ var GamepadControls = class extends EventDispatcher {
 	* @param gamepad - The gamepad that just connected.
 	*/
 	onGamepadConnected(gamepad) {
-		if (this.gamepad !== null) return;
-		this.gamepad = 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
+			gamepad: connectedGamepad
 		});
 	}
 	/**
@@ -86,12 +116,13 @@ var GamepadControls = class extends EventDispatcher {
 	* @param gamepad - The gamepad that just disconnected.
 	*/
 	onGamepadDisconnected(gamepad) {
-		if (this.gamepad?.index !== gamepad.index) return;
-		const disconnected = this.gamepad;
-		this.gamepad = null;
+		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: disconnected
+			gamepad: disconnectedGamepad
 		});
 	}
 };

package/dist/gamepad-drag-controls.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
-import { applyGamepadDeadzone, getGamepadButtonPressed } from "./utils.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { applyGamepadDeadzone, getGamepadButtonPressed } from "./utils.js";
 import { Matrix4, Vector2, Vector3 } from "three";
 //#region src/gamepad-drag-controls.ts
 /**
@@ -111,6 +111,12 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#clearHover();
 		super.onGamepadDisconnected(gamepad);
 	}
+	/**
+	* Updates the selected object from gamepad drag and rotation input.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	*/
 	#updateSelected(deltaTime, gamepad) {
 		const selected = this.#selected;
 		if (selected === null) return;
@@ -126,6 +132,15 @@ var GamepadDragControls = class extends GamepadControls {
 			object: selected
 		});
 	}
+	/**
+	* Moves the selected object in the camera-facing plane.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param dragX - Horizontal drag input after dead zone processing.
+	* @param dragY - Vertical drag input after dead zone processing.
+	* @param dragSpeed - User-configured drag speed multiplier.
+	* @returns `true` when the selected object moved.
+	*/
 	#applyDrag(deltaTime, dragX, dragY, dragSpeed) {
 		if (this.#selected === null || dragX === 0 && dragY === 0) return false;
 		this.#updateCameraAxes();
@@ -136,6 +151,15 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#applySelectedWorldPosition();
 		return true;
 	}
+	/**
+	* Rotates the selected object around camera-relative world axes.
+	*
+	* @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 the selected object rotated.
+	*/
 	#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) {
 		const selected = this.#selected;
 		if (selected === null || rotateX === 0 && rotateY === 0) return false;
@@ -145,6 +169,11 @@ var GamepadDragControls = class extends GamepadControls {
 		if (rotateY !== 0) selected.rotateOnWorldAxis(this.#cameraRight, rotateY * scale);
 		return true;
 	}
+	/**
+	* Raycasts from the center of the viewport into DragControls objects.
+	*
+	* @returns The closest center hit, or `undefined` when nothing is hit.
+	*/
 	#intersectCenter() {
 		const controls = this.#controls;
 		this.#intersections.length = 0;
@@ -152,6 +181,11 @@ var GamepadDragControls = class extends GamepadControls {
 		controls.raycaster.intersectObjects(controls.objects, controls.recursive, this.#intersections);
 		return this.#intersections[0];
 	}
+	/**
+	* Updates DragControls hover state for the object under the center reticle.
+	*
+	* @param object - Object currently under the reticle, or `null`.
+	*/
 	#updateHover(object) {
 		if (this.#hovered === object) return;
 		this.#clearHover();
@@ -162,6 +196,9 @@ 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;
@@ -171,6 +208,11 @@ var GamepadDragControls = class extends GamepadControls {
 			object
 		});
 	}
+	/**
+	* Selects an object and dispatches DragControls `dragstart`.
+	*
+	* @param object - Object hit by the center reticle.
+	*/
 	#grabObject(object) {
 		const selected = this.#getSelectedObject(object);
 		selected.updateWorldMatrix(true, false);
@@ -181,6 +223,9 @@ 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;
@@ -190,10 +235,22 @@ var GamepadDragControls = class extends GamepadControls {
 			object: selected
 		});
 	}
+	/**
+	* Resolves which object should be dragged for a reticle hit.
+	*
+	* @param object - Object hit by the center reticle.
+	* @returns The hit object, or its outermost group when group dragging is enabled.
+	*/
 	#getSelectedObject(object) {
 		if (!this.#controls.transformGroup) return object;
 		return this.#findOutermostGroup(object) ?? object;
 	}
+	/**
+	* Finds the highest ancestor that is a Three.js `Group`.
+	*
+	* @param object - Object where the ancestor search starts.
+	* @returns The outermost group ancestor, or `null` when none exists.
+	*/
 	#findOutermostGroup(object) {
 		let group = null;
 		let current = object;
@@ -203,6 +260,9 @@ 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;
@@ -217,12 +277,18 @@ 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)) {
@@ -238,9 +304,21 @@ var GamepadDragControls = class extends GamepadControls {
 		}
 		this.#viewSize.set(1, 1);
 	}
+	/**
+	* Narrows a Three.js camera to `PerspectiveCamera`.
+	*
+	* @param camera - Camera to inspect.
+	* @returns `true` when the camera is perspective.
+	*/
 	#isPerspectiveCamera(camera) {
 		return camera.isPerspectiveCamera === true;
 	}
+	/**
+	* Narrows a Three.js camera to `OrthographicCamera`.
+	*
+	* @param camera - Camera to inspect.
+	* @returns `true` when the camera is orthographic.
+	*/
 	#isOrthographicCamera(camera) {
 		return camera.isOrthographicCamera === true;
 	}

package/dist/gamepad-first-person-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";
 import { MathUtils, Spherical, Vector3 } from "three";
 //#region src/gamepad-first-person-controls.ts
 /**
@@ -58,6 +58,18 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		this.#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown);
 		this.#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY);
 	}
+	/**
+	* Applies local translation input to FirstPersonControls' object.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param moveSpeed - User-configured movement speed multiplier.
+	* @param deadzone - Axis and trigger dead zone threshold.
+	* @param axisMoveForward - Axis index for forward and backward movement.
+	* @param axisMoveRight - Axis index for right and left strafe movement.
+	* @param buttonMoveUp - Button index for upward movement.
+	* @param buttonMoveDown - Button index for downward movement.
+	*/
 	#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown) {
 		const controls = this.#controls;
 		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
@@ -77,6 +89,16 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		if (up > deadzone) controls.object.translateY(up * moveMult);
 		if (down > deadzone) controls.object.translateY(-down * moveMult);
 	}
+	/**
+	* Applies camera look input while keeping FirstPersonControls state in sync.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @param lookSpeed - User-configured look speed multiplier.
+	* @param deadzone - Axis dead zone threshold.
+	* @param axisLookX - Axis index for yaw input.
+	* @param axisLookY - Axis index for pitch input.
+	*/
 	#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY) {
 		const lookX = applyGamepadDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
 		const lookY = applyGamepadDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
@@ -98,6 +120,11 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		controls._lat = lat;
 		controls._lon = lon;
 	}
+	/**
+	* Reads the current FirstPersonControls orientation, deriving it if needed.
+	*
+	* @returns Current latitude and longitude in degrees.
+	*/
 	#getOrientation() {
 		const { _lat, _lon } = this.#controls;
 		if (Number.isFinite(_lat) && Number.isFinite(_lon)) return {

package/dist/gamepad-fly-controls.js

@@ -1,6 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
-import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.js";
 import { Quaternion } from "three";
 //#region src/gamepad-fly-controls.ts
 /**