three-gamepad-controls 0.13.0 → 0.14.0

package/README.md

@@ -55,6 +55,7 @@ bun add -d @types/three # optional: for TypeScript projects
 
 - [Core](./docs/core.md) — The fundamental building blocks.
 - [GamepadInput](./docs/gamepad-input.md) - Low-level reader for gamepad buttons, axes, sticks, and transitions.
+- [Haptic Feedback](./docs/haptic-feedback.md) - Optional gamepad vibration effects with graceful degradation.
 - [Multiple Gamepads](./docs/multiple-gamepads.md) - Assign different gamepads to controls, players, and gameplay inputs.
 - [GamepadControls](./docs/gamepad-controls.md) — Abstract base class for custom gamepad controls.
 - [GamepadArcballControls](./docs/gamepad-arcball-controls.md) - Gamepad support for `ArcballControls`.

package/dist/gamepad-controls.d.ts

@@ -63,12 +63,41 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    * @returns The shared input reader for the active gamepad.
    */
   protected get gamepadInput(): GamepadInput;
+  /**
+   * Whether the active gamepad exposes a callable primary vibration actuator.
+   *
+   * This does not guarantee support for every {@link GamepadHapticEffectType}.
+   *
+   * @returns `true` when vibration effects can be requested.
+   */
+  get vibrationSupported(): boolean;
   /**
    * Advances the controller by one frame. Call this inside your render loop.
    *
    * @param deltaTime - Seconds since the last frame.
    */
   update(deltaTime: number): void;
+  /**
+   * Plays an effect through the active gamepad's primary vibration actuator.
+   *
+   * Missing browser, gamepad, or effect support is treated as a safe no-op.
+   * Environmental failures such as a hidden document are also ignored.
+   * Invalid parameters and unexpected failures remain rejected.
+   *
+   * @param type - Haptic effect type to play.
+   * @param parameters - Optional parameters describing the effect.
+   * @returns The browser result, or `null` when the effect is ignored.
+   */
+  playVibrationEffect(type: GamepadHapticEffectType, parameters?: GamepadEffectParameters): Promise<GamepadHapticsResult | null>;
+  /**
+   * Stops the active effect on the gamepad's primary vibration actuator.
+   *
+   * Missing or temporarily unavailable haptics are treated as a safe no-op.
+   * Unexpected failures remain rejected.
+   *
+   * @returns The browser result, or `null` when reset is ignored.
+   */
+  resetVibration(): Promise<GamepadHapticsResult | null>;
   /**
    * Removes all event listeners attached by this controller. Call when no longer needed.
    */

package/dist/gamepad-controls.js

@@ -44,6 +44,16 @@ var GamepadControls = class extends EventDispatcher {
 		return this.#gamepadInput;
 	}
 	/**
+	* Whether the active gamepad exposes a callable primary vibration actuator.
+	*
+	* This does not guarantee support for every {@link GamepadHapticEffectType}.
+	*
+	* @returns `true` when vibration effects can be requested.
+	*/
+	get vibrationSupported() {
+		return this.#gamepadInput.vibrationSupported;
+	}
+	/**
 	* Forwards an input connection event to the overridable lifecycle hook.
 	*
 	* @param event - Input event containing the connected gamepad snapshot.
@@ -74,6 +84,31 @@ var GamepadControls = class extends EventDispatcher {
 		this.onUpdate(deltaTime);
 	}
 	/**
+	* Plays an effect through the active gamepad's primary vibration actuator.
+	*
+	* Missing browser, gamepad, or effect support is treated as a safe no-op.
+	* Environmental failures such as a hidden document are also ignored.
+	* Invalid parameters and unexpected failures remain rejected.
+	*
+	* @param type - Haptic effect type to play.
+	* @param parameters - Optional parameters describing the effect.
+	* @returns The browser result, or `null` when the effect is ignored.
+	*/
+	playVibrationEffect(type, parameters) {
+		return this.#gamepadInput.playVibrationEffect(type, parameters);
+	}
+	/**
+	* Stops the active effect on the gamepad's primary vibration actuator.
+	*
+	* Missing or temporarily unavailable haptics are treated as a safe no-op.
+	* Unexpected failures remain rejected.
+	*
+	* @returns The browser result, or `null` when reset is ignored.
+	*/
+	resetVibration() {
+		return this.#gamepadInput.resetVibration();
+	}
+	/**
 	* Removes all event listeners attached by this controller. Call when no longer needed.
 	*/
 	dispose() {

package/dist/gamepad-haptics.js

@@ -0,0 +1,88 @@
+//#region src/gamepad-haptics.ts
+/**
+* Returns the primary vibration actuator exposed by a gamepad at runtime.
+*
+* The DOM types follow the specification and declare `vibrationActuator` as
+* always present, while browsers without haptic support may omit it entirely.
+* Access failures are treated as lack of support.
+*
+* @param gamepad - Active gamepad snapshot, or `null`.
+* @returns The runtime actuator, or `null` when unavailable.
+*/
+const getGamepadVibrationActuator = (gamepad) => {
+	if (gamepad === null) return null;
+	try {
+		return gamepad.vibrationActuator ?? null;
+	} catch {
+		return null;
+	}
+};
+/**
+* Identifies environmental haptics failures that should degrade to a no-op.
+*
+* `NotSupportedError` means the actuator cannot play the requested effect.
+* `InvalidStateError` means the document cannot currently issue the effect,
+* such as while it is hidden. Parameter errors intentionally remain visible.
+*
+* @param error - Rejection reason returned by the browser.
+* @returns Whether the failure should be ignored as unavailable haptics.
+*/
+const isIgnorableHapticsError = (error) => {
+	if (typeof error !== "object" || error === null || !("name" in error)) return false;
+	const { name } = error;
+	return name === "NotSupportedError" || name === "InvalidStateError";
+};
+/**
+* Returns whether the active gamepad exposes the current vibration API.
+*
+* This detects actuator and method availability, not support for a particular
+* haptic effect type.
+*
+* @param gamepad - Active gamepad snapshot, or `null`.
+* @returns `true` when `vibrationActuator.playEffect` is callable.
+*/
+const isGamepadVibrationSupported = (gamepad) => {
+	return typeof getGamepadVibrationActuator(gamepad)?.playEffect === "function";
+};
+/**
+* Plays a haptic effect through the current primary vibration actuator.
+*
+* Unsupported or temporarily unavailable haptics resolve to `null`. Invalid
+* parameters and other unexpected failures remain rejected.
+*
+* @param gamepad - Active gamepad snapshot, or `null`.
+* @param type - Haptic effect type to play.
+* @param parameters - Optional parameters describing the effect.
+* @returns The browser result, or `null` when the effect is ignored.
+*/
+const playGamepadVibrationEffect = async (gamepad, type, parameters) => {
+	const actuator = getGamepadVibrationActuator(gamepad);
+	if (typeof actuator?.playEffect !== "function") return null;
+	try {
+		return await actuator.playEffect(type, parameters);
+	} catch (error) {
+		if (isIgnorableHapticsError(error)) return null;
+		throw error;
+	}
+};
+/**
+* Stops the active effect on the current primary vibration actuator.
+*
+* Unsupported or temporarily unavailable haptics resolve to `null`.
+* Unexpected failures remain rejected.
+*
+* @param gamepad - Active gamepad snapshot, or `null`.
+* @returns The browser result, or `null` when reset is ignored.
+*/
+const resetGamepadVibration = async (gamepad) => {
+	const actuator = getGamepadVibrationActuator(gamepad);
+	if (typeof actuator?.reset !== "function") return null;
+	try {
+		return await actuator.reset();
+	} catch (error) {
+		if (isIgnorableHapticsError(error)) return null;
+		throw error;
+	}
+};
+//#endregion
+export { isGamepadVibrationSupported, playGamepadVibrationEffect, resetGamepadVibration };

package/dist/gamepad-input.d.ts

@@ -109,6 +109,14 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    * @returns The raw active gamepad snapshot, or `null`.
    */
   get rawGamepad(): Gamepad | null;
+  /**
+   * Whether the active gamepad exposes a callable primary vibration actuator.
+   *
+   * This does not guarantee support for every {@link GamepadHapticEffectType}.
+   *
+   * @returns `true` when vibration effects can be requested.
+   */
+  get vibrationSupported(): boolean;
   /**
    * Polls the gamepad and refreshes current and previous button state.
    */
@@ -162,6 +170,27 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    * @returns Object containing processed `x` and `y` values.
    */
   stick(xAxis: number, yAxis: number, options?: GamepadAxisOptions): GamepadStick;
+  /**
+   * Plays an effect through the active gamepad's primary vibration actuator.
+   *
+   * Missing browser, gamepad, or effect support is treated as a safe no-op.
+   * Environmental failures such as a hidden document are also ignored.
+   * Invalid parameters and unexpected failures remain rejected.
+   *
+   * @param type - Haptic effect type to play.
+   * @param parameters - Optional parameters describing the effect.
+   * @returns The browser result, or `null` when the effect is ignored.
+   */
+  playVibrationEffect(type: GamepadHapticEffectType, parameters?: GamepadEffectParameters): Promise<GamepadHapticsResult | null>;
+  /**
+   * Stops the active effect on the gamepad's primary vibration actuator.
+   *
+   * Missing or temporarily unavailable haptics are treated as a safe no-op.
+   * Unexpected failures remain rejected.
+   *
+   * @returns The browser result, or `null` when reset is ignored.
+   */
+  resetVibration(): Promise<GamepadHapticsResult | null>;
 }
 //#endregion
 export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick };

package/dist/gamepad-input.js

@@ -1,3 +1,4 @@
+import { isGamepadVibrationSupported, playGamepadVibrationEffect, resetGamepadVibration } from "./gamepad-haptics.js";
 import { GamepadManager } from "./gamepad-manager.js";
 import { EventDispatcher } from "three";
 //#region src/gamepad-input.ts
@@ -131,6 +132,16 @@ var GamepadInput = class extends EventDispatcher {
 		return this.#gamepad;
 	}
 	/**
+	* Whether the active gamepad exposes a callable primary vibration actuator.
+	*
+	* This does not guarantee support for every {@link GamepadHapticEffectType}.
+	*
+	* @returns `true` when vibration effects can be requested.
+	*/
+	get vibrationSupported() {
+		return isGamepadVibrationSupported(this.#gamepad);
+	}
+	/**
 	* Polls the gamepad and refreshes current and previous button state.
 	*/
 	update() {
@@ -230,6 +241,31 @@ var GamepadInput = class extends EventDispatcher {
 		};
 	}
 	/**
+	* Plays an effect through the active gamepad's primary vibration actuator.
+	*
+	* Missing browser, gamepad, or effect support is treated as a safe no-op.
+	* Environmental failures such as a hidden document are also ignored.
+	* Invalid parameters and unexpected failures remain rejected.
+	*
+	* @param type - Haptic effect type to play.
+	* @param parameters - Optional parameters describing the effect.
+	* @returns The browser result, or `null` when the effect is ignored.
+	*/
+	playVibrationEffect(type, parameters) {
+		return playGamepadVibrationEffect(this.#gamepad, type, parameters);
+	}
+	/**
+	* Stops the active effect on the gamepad's primary vibration actuator.
+	*
+	* Missing or temporarily unavailable haptics are treated as a safe no-op.
+	* Unexpected failures remain rejected.
+	*
+	* @returns The browser result, or `null` when reset is ignored.
+	*/
+	resetVibration() {
+		return resetGamepadVibration(this.#gamepad);
+	}
+	/**
 	* Handles a browser connection event and adopts the gamepad when possible.
 	*
 	* Button state is seeded as both current and previous so an already-held

package/dist/gamepad-manager.js

@@ -47,18 +47,19 @@ var GamepadManager = class {
 		return selectedGamepad;
 	}
 	/**
-	* Clears the active gamepad when it is the disconnecting gamepad instance.
+	* Clears the active gamepad when its browser-assigned index matches the
+	* disconnecting gamepad.
 	*
-	* Identity is intentionally checked in addition to the browser-assigned
-	* index. Indices may be reused, so a late event from a previous device must
-	* not disconnect a replacement that now occupies the same slot.
-	* A matching disconnection defers any replacement until the next update.
+	* Gamepad API snapshots are not guaranteed to preserve JavaScript object
+	* identity between events and polls, so the active device is correlated by
+	* its logical slot. A matching disconnection defers any replacement until
+	* the next update.
 	*
 	* @param gamepad - Gamepad snapshot that disconnected.
 	* @returns The previously active gamepad when it was cleared, otherwise `null`.
 	*/
 	disconnect(gamepad) {
-		if (this.activeGamepad !== gamepad) return null;
+		if (this.activeGamepad === null || this.activeGamepad.index !== gamepad.index) return null;
 		const disconnectedGamepad = this.activeGamepad;
 		this.activeGamepad = null;
 		this.#connectionDeferredUntilUpdate = true;
@@ -86,7 +87,7 @@ var GamepadManager = class {
 		}
 		const previousGamepad = this.activeGamepad;
 		const nextGamepad = this.#getGamepadByIndex(previousGamepad.index);
-		if (!previousGamepad.connected || nextGamepad === null || nextGamepad !== previousGamepad) {
+		if (nextGamepad === null) {
 			this.activeGamepad = null;
 			this.#connectionDeferredUntilUpdate = true;
 			return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {
     "name": "Kasnix",