three-gamepad-controls 0.10.6 → 0.11.0

package/dist/gamepad-input.js

@@ -0,0 +1,270 @@
+import { GamepadManager } from "./gamepad-manager.js";
+import { applyGamepadDeadzone, getGamepadButtonPressed, getGamepadButtonValue } from "./utils.js";
+import { EventDispatcher } from "three";
+//#region src/gamepad-input.ts
+const DEFAULT_GAMEPAD_INPUT_OPTIONS = { deadzone: .1 };
+/**
+* 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-trackball-controls.js

@@ -51,6 +51,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		this.#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY);
 		this.#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
 	}
+	/**
+	* Queues rotation input into TrackballControls' normalized move state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @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, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
 		const controls = this.#controls;
 		if (controls.noRotate) {
@@ -65,6 +75,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		controls._moveCurr.x += rotX * scale;
 		controls._moveCurr.y += -rotY * scale;
 	}
+	/**
+	* Queues pan input into TrackballControls' normalized pan state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @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, gamepad, panSpeed, deadzone, axisPanX, axisPanY) {
 		const controls = this.#controls;
 		if (controls.noPan) {
@@ -78,6 +98,16 @@ var GamepadTrackballControls = class extends GamepadControls {
 		controls._panEnd.x += panX * scale;
 		controls._panEnd.y += panY * scale;
 	}
+	/**
+	* Queues trigger zoom input into TrackballControls' normalized zoom state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot to read from.
+	* @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, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
 		const controls = this.#controls;
 		if (controls.noZoom) {
@@ -92,6 +122,8 @@ var GamepadTrackballControls = class extends GamepadControls {
 	/**
 	* 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;