three-gamepad-controls 0.10.6 → 0.12.0

package/dist/gamepad-input.js

@@ -0,0 +1,310 @@
+import { GamepadManager } from "./gamepad-manager.js";
+import { EventDispatcher } from "three";
+//#region src/gamepad-input.ts
+const DEFAULT_GAMEPAD_INPUT_OPTIONS = { deadzone: .1 };
+/**
+* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
+*
+* Kept private to this module because `GamepadInput` is the only public API
+* that currently exposes processed axis values.
+*
+* @param value - Raw axis or trigger value, typically in `[-1, 1]`.
+* @param threshold - Dead zone size; values below this magnitude are zeroed.
+* @returns The original value when outside the dead zone, otherwise `0`.
+*/
+const applyGamepadDeadzone = (value, threshold) => {
+	return Math.abs(value) < threshold ? 0 : value;
+};
+/**
+* Returns whether a gamepad button is currently pressed.
+*
+* Missing buttons are treated as not pressed.
+*
+* @param gamepad - Gamepad snapshot to read from.
+* @param button - Button index to inspect.
+* @returns `true` when the button exists and is pressed, otherwise `false`.
+*/
+const getGamepadButtonPressed = (gamepad, button) => {
+	return gamepad.buttons[button]?.pressed ?? false;
+};
+/**
+* Returns the analog value for a gamepad button.
+*
+* Some digital buttons may report `pressed` without a meaningful non-zero
+* `value`, so pressed buttons fall back to `1`.
+*
+* @param gamepad - Gamepad snapshot to read from.
+* @param button - Button index to inspect.
+* @returns The button value, `1` for pressed digital buttons, or `0` when unavailable.
+*/
+const getGamepadButtonValue = (gamepad, button) => {
+	const gamepadButton = gamepad.buttons[button];
+	if (gamepadButton === void 0) return 0;
+	if (gamepadButton.value !== 0) return gamepadButton.value;
+	return gamepadButton.pressed ? 1 : 0;
+};
+/**
+* Gamepad input state reader for gameplay, menus, and custom actions.
+*
+* Call {@link update} once per frame before reading button transitions or axes.
+*/
+var GamepadInput = class extends EventDispatcher {
+	/**
+	* When `false`, input polling is paused.
+	* @default true
+	*/
+	enabled = true;
+	#manager;
+	#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.
+	*/
+	constructor(options) {
+		super();
+		this.#manager = new GamepadManager();
+		this.#options = {
+			...DEFAULT_GAMEPAD_INPUT_OPTIONS,
+			...options
+		};
+		this.#pressedButtons = /* @__PURE__ */ new Set();
+		this.#previousPressedButtons = /* @__PURE__ */ new Set();
+		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 active-gamepad adoption logic.
+	*
+	* @param event - Browser event containing the connected gamepad snapshot.
+	*/
+	#handleGamepadConnectedEvent(event) {
+		this.#handleGamepadConnected(event.gamepad);
+	}
+	/**
+	* Forwards a browser disconnection event to active-gamepad cleanup.
+	*
+	* @param event - Browser event containing the disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnectedEvent(event) {
+		this.#handleGamepadDisconnected(event.gamepad);
+	}
+	/**
+	* The currently active gamepad, or `null` if no gamepad is connected.
+	*
+	* @returns The active gamepad snapshot, or `null`.
+	*/
+	get gamepad() {
+		return this.#gamepad;
+	}
+	/**
+	* Whether a gamepad is currently active.
+	*
+	* @returns `true` when a gamepad is active, otherwise `false`.
+	*/
+	get connected() {
+		return this.#gamepad !== null;
+	}
+	/**
+	* Mapping reported by the active gamepad, or `null` when none is active.
+	*
+	* @returns The active gamepad mapping, or `null`.
+	*/
+	get mapping() {
+		return this.#gamepad?.mapping ?? null;
+	}
+	/**
+	* Raw active gamepad snapshot, or `null` if no gamepad is connected.
+	*
+	* @returns The raw active gamepad snapshot, or `null`.
+	*/
+	get rawGamepad() {
+		return this.#gamepad;
+	}
+	/**
+	* Polls the gamepad and refreshes current and previous button state.
+	*/
+	update() {
+		if (!this.enabled) return;
+		const { gamepad, connected, disconnected } = this.#manager.update();
+		if (connected !== null) {
+			this.#gamepad = gamepad;
+			this.#syncButtonState({ seedPrevious: true });
+			this.dispatchEvent({
+				type: "connected",
+				gamepad: connected
+			});
+			return;
+		}
+		if (disconnected !== null) {
+			this.#gamepad = null;
+			this.#clearButtonState();
+			this.dispatchEvent({
+				type: "disconnected",
+				gamepad: disconnected
+			});
+			return;
+		}
+		this.#gamepad = gamepad;
+		this.#syncButtonState({ seedPrevious: false });
+	}
+	/**
+	* Removes all window-level event listeners attached by this input reader.
+	*/
+	dispose() {
+		window.removeEventListener("gamepadconnected", this.#onGamepadConnected);
+		window.removeEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+		this.#manager.activeGamepad = null;
+		this.#gamepad = null;
+		this.#clearButtonState();
+		this.enabled = false;
+	}
+	/**
+	* 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) {
+		return this.#pressedButtons.has(button);
+	}
+	/**
+	* 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) {
+		return this.#pressedButtons.has(button) && !this.#previousPressedButtons.has(button);
+	}
+	/**
+	* 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) {
+		return !this.#pressedButtons.has(button) && this.#previousPressedButtons.has(button);
+	}
+	/**
+	* 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) {
+		if (this.#gamepad === null) return 0;
+		return getGamepadButtonValue(this.#gamepad, button);
+	}
+	/**
+	* 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, options) {
+		return applyGamepadDeadzone(this.#gamepad?.axes[axis] ?? 0, this.#getDeadzone(options));
+	}
+	/**
+	* 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, yAxis, options) {
+		return {
+			x: this.axis(xAxis, options),
+			y: this.axis(yAxis, options)
+		};
+	}
+	/**
+	* Handles a browser connection event and adopts the gamepad when possible.
+	*
+	* Button state is seeded as both current and previous so an already-held
+	* button does not produce a synthetic `wasPressed` transition on connect.
+	*
+	* @param gamepad - Browser-provided connected gamepad snapshot.
+	*/
+	#handleGamepadConnected(gamepad) {
+		if (!this.#manager.connect(gamepad)) return;
+		this.#gamepad = this.#manager.activeGamepad;
+		this.#syncButtonState({ seedPrevious: true });
+		this.dispatchEvent({
+			type: "connected",
+			gamepad
+		});
+	}
+	/**
+	* Handles a browser disconnection event for the active gamepad.
+	*
+	* Button state is cleared instead of diffed so disconnecting a controller
+	* does not produce synthetic `wasReleased` transitions.
+	*
+	* @param gamepad - Browser-provided disconnected gamepad snapshot.
+	*/
+	#handleGamepadDisconnected(gamepad) {
+		const disconnectedGamepad = this.#manager.disconnect(gamepad);
+		if (disconnectedGamepad === null) return;
+		this.#gamepad = null;
+		this.#clearButtonState();
+		this.dispatchEvent({
+			type: "disconnected",
+			gamepad: disconnectedGamepad
+		});
+	}
+	/**
+	* Refreshes current and previous pressed-button sets from the active snapshot.
+	*
+	* When `seedPrevious` is `true`, the refreshed current state is copied into
+	* the previous state. This intentionally suppresses transition events on the
+	* first frame after adopting a gamepad.
+	*
+	* @param options - Button state synchronization options.
+	* @param options.seedPrevious - Whether to seed previous state from current state.
+	*/
+	#syncButtonState({ seedPrevious }) {
+		this.#previousPressedButtons.clear();
+		for (const button of this.#pressedButtons) this.#previousPressedButtons.add(button);
+		this.#pressedButtons.clear();
+		if (this.#gamepad !== null) {
+			for (let index = 0; index < this.#gamepad.buttons.length; index += 1) if (getGamepadButtonPressed(this.#gamepad, index)) this.#pressedButtons.add(index);
+		}
+		if (!seedPrevious) return;
+		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();
+	}
+	/**
+	* Resolves the dead zone for a single axis or stick read.
+	*
+	* @param options - Optional per-read axis options.
+	* @returns The per-read dead zone when provided, otherwise the instance default.
+	*/
+	#getDeadzone(options) {
+		return options?.deadzone ?? this.#options.deadzone;
+	}
+};
+//#endregion
+export { GamepadInput };

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

@@ -77,9 +77,8 @@ declare class GamepadOrbitControls extends GamepadControls {
    * Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
    *
    * @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 { GamepadOrbitControls, GamepadOrbitControlsOptions };

package/dist/gamepad-orbit-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";
 //#region src/gamepad-orbit-controls.ts
 /**
 * Default options merged in the constructor when no explicit configuration is provided.
@@ -43,19 +42,19 @@ var GamepadOrbitControls = class extends GamepadControls {
 	* Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
 	*
 	* @param deltaTime - Seconds since the last frame.
-	* @param gamepad - Fresh gamepad snapshot provided by the base class.
 	*/
-	onUpdate(deltaTime, gamepad) {
+	onUpdate(deltaTime) {
 		const { rotateSpeed, panSpeed, zoomSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonDollyIn, buttonDollyOut } = this.#options;
-		const rotX = applyGamepadDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
-		const rotY = applyGamepadDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
+		const input = this.gamepadInput;
+		const rotX = input.axis(axisRotateX, { deadzone });
+		const rotY = input.axis(axisRotateY, { deadzone });
 		if (rotX !== 0) this.#controls.rotateLeft(rotX * rotateSpeed * deltaTime * Math.PI);
 		if (rotY !== 0) this.#controls.rotateUp(rotY * rotateSpeed * deltaTime * Math.PI);
-		const panX = applyGamepadDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone);
-		const panY = applyGamepadDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone);
+		const panX = input.axis(axisPanX, { deadzone });
+		const panY = input.axis(axisPanY, { deadzone });
 		if (panX !== 0 || panY !== 0) this.#controls.pan(panX * panSpeed * deltaTime * 500, panY * panSpeed * deltaTime * 500);
-		const triggerIn = getGamepadButtonValue(gamepad, buttonDollyIn);
-		const triggerOut = getGamepadButtonValue(gamepad, buttonDollyOut);
+		const triggerIn = input.buttonValue(buttonDollyIn);
+		const triggerOut = input.buttonValue(buttonDollyOut);
 		if (triggerIn > deadzone) this.#controls.dollyIn(1 / (1 + zoomSpeed * triggerIn * deltaTime));
 		if (triggerOut > deadzone) this.#controls.dollyOut(1 / (1 + zoomSpeed * triggerOut * deltaTime));
 	}

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

@@ -63,9 +63,8 @@ declare class GamepadPointerLockControls extends GamepadControls {
    * Maps the current gamepad state to `PointerLockControls` movement 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 { GamepadPointerLockControls, GamepadPointerLockControlsOptions };

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

@@ -1,6 +1,5 @@
 import { GAMEPAD_AXIS } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
-import { applyGamepadDeadzone } from "./utils.js";
 import { Euler } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
 /**
@@ -44,16 +43,16 @@ var GamepadPointerLockControls = class extends GamepadControls {
 	* Maps the current gamepad state to `PointerLockControls` movement 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 } = this.#options;
-		const fwd = applyGamepadDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
-		const strafe = applyGamepadDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		const input = this.gamepadInput;
+		const fwd = input.axis(axisMoveForward, { deadzone });
+		const strafe = input.axis(axisMoveRight, { deadzone });
 		if (fwd !== 0) this.#controls.moveForward(-fwd * moveSpeed * deltaTime);
 		if (strafe !== 0) this.#controls.moveRight(strafe * moveSpeed * deltaTime);
-		const lookX = applyGamepadDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
-		const lookY = applyGamepadDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
+		const lookX = input.axis(axisLookX, { deadzone });
+		const lookY = input.axis(axisLookY, { deadzone });
 		if (lookX !== 0 || lookY !== 0) {
 			const camera = this.#controls.object;
 			const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;

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

@@ -77,9 +77,8 @@ declare class GamepadTrackballControls extends GamepadControls {
    * Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
    *
    * @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 { GamepadTrackballControls, GamepadTrackballControlsOptions };

package/dist/gamepad-trackball-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";
 //#region src/gamepad-trackball-controls.ts
 /**
 * Default options merged in the constructor when no explicit configuration is provided.
@@ -43,55 +42,86 @@ var GamepadTrackballControls = class extends GamepadControls {
 	* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
 	*
 	* @param deltaTime - Seconds since the last frame.
-	* @param gamepad - Fresh gamepad snapshot provided by the base class.
 	*/
-	onUpdate(deltaTime, gamepad) {
+	onUpdate(deltaTime) {
 		const { rotateSpeed, panSpeed, zoomSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut } = this.#options;
-		this.#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY);
-		this.#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY);
-		this.#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
+		this.#queueRotation(deltaTime, rotateSpeed, deadzone, axisRotateX, axisRotateY);
+		this.#queuePan(deltaTime, panSpeed, deadzone, axisPanX, axisPanY);
+		this.#queueZoom(deltaTime, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
 	}
-	#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
+	/**
+	* Queues rotation input into TrackballControls' normalized move state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param rotateSpeed - User-configured rotation speed multiplier.
+	* @param deadzone - Axis dead zone threshold.
+	* @param axisRotateX - Axis index for horizontal rotation.
+	* @param axisRotateY - Axis index for vertical rotation.
+	*/
+	#queueRotation(deltaTime, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
 		const controls = this.#controls;
 		if (controls.noRotate) {
 			controls._movePrev.copy(controls._moveCurr);
 			controls._lastAngle = 0;
 			return;
 		}
-		const rotX = applyGamepadDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
-		const rotY = applyGamepadDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
+		const input = this.gamepadInput;
+		const rotX = input.axis(axisRotateX, { deadzone });
+		const rotY = input.axis(axisRotateY, { deadzone });
 		if (rotX === 0 && rotY === 0) return;
 		const scale = rotateSpeed * deltaTime * Math.PI;
 		controls._moveCurr.x += rotX * scale;
 		controls._moveCurr.y += -rotY * scale;
 	}
-	#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY) {
+	/**
+	* Queues pan input into TrackballControls' normalized pan state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param panSpeed - User-configured pan speed multiplier.
+	* @param deadzone - Axis dead zone threshold.
+	* @param axisPanX - Axis index for horizontal panning.
+	* @param axisPanY - Axis index for vertical panning.
+	*/
+	#queuePan(deltaTime, panSpeed, deadzone, axisPanX, axisPanY) {
 		const controls = this.#controls;
 		if (controls.noPan) {
 			controls._panStart.copy(controls._panEnd);
 			return;
 		}
-		const panX = applyGamepadDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone);
-		const panY = applyGamepadDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone);
+		const input = this.gamepadInput;
+		const panX = input.axis(axisPanX, { deadzone });
+		const panY = input.axis(axisPanY, { deadzone });
 		if (panX === 0 && panY === 0) return;
 		const scale = panSpeed * deltaTime * this.#getInputDampingFactor();
 		controls._panEnd.x += panX * scale;
 		controls._panEnd.y += panY * scale;
 	}
-	#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
+	/**
+	* Queues trigger zoom input into TrackballControls' normalized zoom state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param zoomSpeed - User-configured zoom speed multiplier.
+	* @param deadzone - Trigger dead zone threshold.
+	* @param buttonZoomIn - Button index for zooming in.
+	* @param buttonZoomOut - Button index for zooming out.
+	*/
+	#queueZoom(deltaTime, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
 		const controls = this.#controls;
 		if (controls.noZoom) {
 			controls._zoomStart.copy(controls._zoomEnd);
 			return;
 		}
-		const triggerIn = getGamepadButtonValue(gamepad, buttonZoomIn);
-		const triggerOut = getGamepadButtonValue(gamepad, buttonZoomOut);
+		const input = this.gamepadInput;
+		const triggerIn = input.buttonValue(buttonZoomIn);
+		const triggerOut = input.buttonValue(buttonZoomOut);
 		if (triggerIn <= deadzone && triggerOut <= deadzone) return;
 		controls._zoomEnd.y += (triggerOut - triggerIn) * zoomSpeed * deltaTime * this.#getInputDampingFactor();
 	}
 	/**
 	* Compensates for TrackballControls reapplying queued pan and zoom deltas
 	* while their input state catches up through damping.
+	*
+	* @returns Multiplier that matches TrackballControls' damping mode.
 	*/
 	#getInputDampingFactor() {
 		const controls = this.#controls;

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

@@ -114,9 +114,8 @@ declare class GamepadTransformControls extends GamepadControls {
    * translate, rotate, scale, and reset 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;
   /**
    * Ends any active transform before disposing the gamepad lifecycle listeners.
    */