three-gamepad-controls 0.10.6 → 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

@@ -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

@@ -18,21 +18,42 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	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.#manager = new GamepadManager();
-		this.#onGamepadConnected = (event) => {
-			this.onGamepadConnected(event.gamepad);
-		};
-		this.#onGamepadDisconnected = (event) => {
-			this.onGamepadDisconnected(event.gamepad);
-		};
+		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.

package/dist/gamepad-drag-controls.js

@@ -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

@@ -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-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 };