three-gamepad-controls 0.10.6 → 0.12.0

package/dist/gamepad-drag-controls.js

@@ -1,6 +1,5 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.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
 /**
@@ -38,7 +37,6 @@ var GamepadDragControls = class extends GamepadControls {
 	#viewSize;
 	#hovered = null;
 	#selected = null;
-	#selectButtonPressed = false;
 	/**
 	* @param controls - A Three.js `DragControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -68,13 +66,10 @@ var GamepadDragControls = class extends GamepadControls {
 	* and rotate behavior.
 	*
 	* @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 selectPressed = getGamepadButtonPressed(gamepad, this.#options.buttonSelect);
-		const selectStarted = selectPressed && !this.#selectButtonPressed;
-		this.#selectButtonPressed = selectPressed;
+		const selectStarted = this.gamepadInput.wasPressed(this.#options.buttonSelect);
 		if (!controls.enabled) {
 			this.#releaseSelected();
 			this.#clearHover();
@@ -85,7 +80,7 @@ var GamepadDragControls = class extends GamepadControls {
 				this.#releaseSelected();
 				return;
 			}
-			this.#updateSelected(deltaTime, gamepad);
+			this.#updateSelected(deltaTime);
 			return;
 		}
 		const hit = this.#intersectCenter();
@@ -111,14 +106,20 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#clearHover();
 		super.onGamepadDisconnected(gamepad);
 	}
-	#updateSelected(deltaTime, gamepad) {
+	/**
+	* Updates the selected object from gamepad drag and rotation input.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	#updateSelected(deltaTime) {
 		const selected = this.#selected;
 		if (selected === null) return;
 		const { dragSpeed, rotateSpeed, deadzone, axisDragX, axisDragY, axisRotateX, axisRotateY } = this.#options;
-		const dragX = applyGamepadDeadzone(gamepad.axes[axisDragX] ?? 0, deadzone);
-		const dragY = applyGamepadDeadzone(gamepad.axes[axisDragY] ?? 0, deadzone);
-		const rotateX = applyGamepadDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
-		const rotateY = applyGamepadDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
+		const input = this.gamepadInput;
+		const dragX = input.axis(axisDragX, { deadzone });
+		const dragY = input.axis(axisDragY, { deadzone });
+		const rotateX = input.axis(axisRotateX, { deadzone });
+		const rotateY = input.axis(axisRotateY, { deadzone });
 		const dragged = this.#applyDrag(deltaTime, dragX, dragY, dragSpeed);
 		const rotated = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed);
 		if (dragged || rotated) this.#controls.dispatchEvent({
@@ -126,6 +127,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 +146,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 +164,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 +176,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 +191,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 +203,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 +218,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 +230,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 +255,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 +272,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 +299,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.d.ts

@@ -73,9 +73,8 @@ declare class GamepadFirstPersonControls extends GamepadControls {
    * Maps the current gamepad state to `FirstPersonControls` translation and look.
    *
    * @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 { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions };

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

@@ -1,6 +1,5 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.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
 /**
@@ -51,17 +50,28 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	* Maps the current gamepad state to `FirstPersonControls` translation and look.
 	*
 	* @param deltaTime - Seconds since the last frame.
-	* @param gamepad - Fresh gamepad snapshot provided by the base class.
 	*/
-	onUpdate(deltaTime, gamepad) {
+	onUpdate(deltaTime) {
 		const { moveSpeed, lookSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonMoveUp, buttonMoveDown } = this.#options;
-		this.#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown);
-		this.#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY);
+		this.#applyMovement(deltaTime, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown);
+		this.#applyLook(deltaTime, lookSpeed, deadzone, axisLookX, axisLookY);
 	}
-	#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown) {
+	/**
+	* Applies local translation input to FirstPersonControls' object.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @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, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown) {
 		const controls = this.#controls;
+		const input = this.gamepadInput;
 		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
-		const forward = applyGamepadDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
+		const forward = input.axis(axisMoveForward, { deadzone });
 		if (forward !== 0) {
 			let distance = forward * moveMult;
 			if (forward < 0 && controls.heightSpeed) {
@@ -70,16 +80,26 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 			}
 			controls.object.translateZ(distance);
 		}
-		const strafe = applyGamepadDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		const strafe = input.axis(axisMoveRight, { deadzone });
 		if (strafe !== 0) controls.object.translateX(strafe * moveMult);
-		const up = getGamepadButtonValue(gamepad, buttonMoveUp);
-		const down = getGamepadButtonValue(gamepad, buttonMoveDown);
+		const up = input.buttonValue(buttonMoveUp);
+		const down = input.buttonValue(buttonMoveDown);
 		if (up > deadzone) controls.object.translateY(up * moveMult);
 		if (down > deadzone) controls.object.translateY(-down * moveMult);
 	}
-	#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY) {
-		const lookX = applyGamepadDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
-		const lookY = applyGamepadDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
+	/**
+	* Applies camera look input while keeping FirstPersonControls state in sync.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @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, lookSpeed, deadzone, axisLookX, axisLookY) {
+		const input = this.gamepadInput;
+		const lookX = input.axis(axisLookX, { deadzone });
+		const lookY = input.axis(axisLookY, { deadzone });
 		if (lookX === 0 && lookY === 0) return;
 		const controls = this.#controls;
 		const actualLookSpeed = controls.lookSpeed * lookSpeed * deltaTime * LOOK_SPEED_SCALE;
@@ -98,6 +118,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.d.ts

@@ -83,9 +83,8 @@ declare class GamepadFlyControls extends GamepadControls {
    * Maps the current gamepad state to `FlyControls` translation and rotation.
    *
    * @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 { GamepadFlyControls, GamepadFlyControlsOptions };

package/dist/gamepad-fly-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 { Quaternion } from "three";
 //#region src/gamepad-fly-controls.ts
 /**
@@ -48,23 +47,23 @@ var GamepadFlyControls = class extends GamepadControls {
 	* Maps the current gamepad state to `FlyControls` translation and rotation.
 	*
 	* @param deltaTime - Seconds since the last frame.
-	* @param gamepad - Fresh gamepad snapshot provided by the base class.
 	*/
-	onUpdate(deltaTime, gamepad) {
+	onUpdate(deltaTime) {
 		const { moveSpeed, rotateSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonRollLeft, buttonRollRight, buttonMoveUp, buttonMoveDown } = this.#options;
+		const input = this.gamepadInput;
 		const moveMult = deltaTime * this.#controls.movementSpeed * moveSpeed;
-		const fwd = applyGamepadDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
+		const fwd = input.axis(axisMoveForward, { deadzone });
 		if (fwd !== 0) this.#controls.object.translateZ(fwd * moveMult);
-		const strafe = applyGamepadDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		const strafe = input.axis(axisMoveRight, { deadzone });
 		if (strafe !== 0) this.#controls.object.translateX(strafe * moveMult);
-		const up = getGamepadButtonValue(gamepad, buttonMoveUp);
-		const down = getGamepadButtonValue(gamepad, buttonMoveDown);
+		const up = input.buttonValue(buttonMoveUp);
+		const down = input.buttonValue(buttonMoveDown);
 		if (up > deadzone) this.#controls.object.translateY(up * moveMult);
 		if (down > deadzone) this.#controls.object.translateY(-down * moveMult);
 		const rotMult = deltaTime * this.#controls.rollSpeed * rotateSpeed;
-		const pitch = -applyGamepadDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
-		const yaw = -applyGamepadDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
-		const roll = (getGamepadButtonPressed(gamepad, buttonRollLeft) ? 1 : 0) - (getGamepadButtonPressed(gamepad, buttonRollRight) ? 1 : 0);
+		const pitch = -input.axis(axisLookY, { deadzone });
+		const yaw = -input.axis(axisLookX, { deadzone });
+		const roll = (input.isPressed(buttonRollLeft) ? 1 : 0) - (input.isPressed(buttonRollRight) ? 1 : 0);
 		if (pitch !== 0 || yaw !== 0 || roll !== 0) {
 			this.#tmpQuaternion.set(pitch * rotMult, yaw * rotMult, roll * rotMult, 1).normalize();
 			this.#controls.object.quaternion.multiply(this.#tmpQuaternion);

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