three-gamepad-controls 0.14.0 → 0.16.0

package/dist/core.d.ts

@@ -1,4 +1,17 @@
 //#region src/core.d.ts
+/**
+ * Smallest valid browser-assigned gamepad index.
+ *
+ * Gamepad slots cannot be negative.
+ */
+declare const MIN_GAMEPAD_INDEX = 0;
+/**
+ * Largest valid browser-assigned gamepad index.
+ *
+ * `Gamepad.index` is a Web IDL `long`, a signed 32-bit integer. Because
+ * gamepad slots cannot be negative, the largest valid index is 2^31 - 1.
+ */
+declare const MAX_GAMEPAD_INDEX = 2147483647;
 /**
  * Button indices for the W3C Standard Gamepad mapping.
  * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
@@ -49,4 +62,4 @@ type GamepadAxisKey = keyof typeof GAMEPAD_AXIS;
  */
 type GamepadAxisValue = (typeof GAMEPAD_AXIS)[keyof typeof GAMEPAD_AXIS];
 //#endregion
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };

package/dist/core.js

@@ -1,5 +1,18 @@
 //#region src/core.ts
 /**
+* Smallest valid browser-assigned gamepad index.
+*
+* Gamepad slots cannot be negative.
+*/
+const MIN_GAMEPAD_INDEX = 0;
+/**
+* Largest valid browser-assigned gamepad index.
+*
+* `Gamepad.index` is a Web IDL `long`, a signed 32-bit integer. Because
+* gamepad slots cannot be negative, the largest valid index is 2^31 - 1.
+*/
+const MAX_GAMEPAD_INDEX = 2147483647;
+/**
 * Button indices for the W3C Standard Gamepad mapping.
 * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
 */
@@ -33,4 +46,4 @@ const GAMEPAD_AXIS = {
 	RightY: 3
 };
 //#endregion
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { ArcballControls } from "three/addons/controls/ArcballControls.js";
-
 //#region src/gamepad-arcball-controls.d.ts
 /**
  * Configuration for {@link GamepadArcballControls}.

package/dist/gamepad-controls.d.ts

@@ -1,6 +1,5 @@
 import { GamepadInput, GamepadInputOptions } from "./gamepad-input.js";
 import { EventDispatcher } from "three";
-
 //#region src/gamepad-controls.d.ts
 /**
  * Event map for {@link GamepadControls}.
@@ -53,8 +52,8 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    * Creates the base input reader and attaches lifecycle listeners.
    *
    * @param options - Shared gamepad selection options.
-   * @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
-   * range `[0, 2147483647]`.
+   * @throws {RangeError} When `gamepadIndex` is not an integer from
+   * `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
    */
   constructor(options?: GamepadControlsOptions);
   /**

package/dist/gamepad-controls.js

@@ -24,8 +24,8 @@ var GamepadControls = class extends EventDispatcher {
 	* Creates the base input reader and attaches lifecycle listeners.
 	*
 	* @param options - Shared gamepad selection options.
-	* @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
-	* range `[0, 2147483647]`.
+	* @throws {RangeError} When `gamepadIndex` is not an integer from
+	* `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
 	*/
 	constructor(options) {
 		super();

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { DragControls } from "three/addons/controls/DragControls.js";
-
 //#region src/gamepad-drag-controls.d.ts
 /**
  * Configuration for {@link GamepadDragControls}.

package/dist/gamepad-first-person-controls.d.ts

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.js";
-
 //#region src/gamepad-first-person-controls.d.ts
 /**
  * Configuration for {@link GamepadFirstPersonControls}.

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FlyControls } from "three/addons/controls/FlyControls.js";
-
 //#region src/gamepad-fly-controls.d.ts
 /**
  * Configuration for {@link GamepadFlyControls}.

package/dist/gamepad-input.d.ts

@@ -1,5 +1,4 @@
 import { EventDispatcher } from "three";
-
 //#region src/gamepad-input.d.ts
 /**
  * Event map for {@link GamepadInput}.
@@ -37,14 +36,15 @@ type GamepadInputOptions = {
    * Browser-assigned gamepad slot to use.
    *
    * When omitted, the connected gamepad with the lowest index is selected.
-   * The index must be an integer in the inclusive range `[0, 2147483647]`.
+   * The index must be an integer from `MIN_GAMEPAD_INDEX` through
+   * `MAX_GAMEPAD_INDEX`.
    * A valid but empty slot keeps this input disconnected without falling back
    * to another gamepad.
    */
   gamepadIndex?: number;
 };
 /**
- * Options for axis and stick reads.
+ * Options for axis reads.
  */
 type GamepadAxisOptions = {
   /**
@@ -52,6 +52,24 @@ type GamepadAxisOptions = {
    */
   deadzone?: number;
 };
+/**
+ * Options for two-dimensional stick reads.
+ */
+type GamepadStickOptions = GamepadAxisOptions & {
+  /**
+   * Dead zone shape for this read.
+   *
+   * `"axial"` processes each axis independently, while `"radial"` processes
+   * the stick magnitude.
+   * @default "axial"
+   */
+  deadzoneMode?: "axial" | "radial";
+  /**
+   * Whether to remap values outside the dead zone to the full output range.
+   * @default false
+   */
+  rescale?: boolean;
+};
 /**
  * Two-dimensional stick input after dead zone processing.
  */
@@ -81,8 +99,8 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    * Creates a gamepad input reader.
    *
    * @param options - Optional overrides for the default input behavior.
-   * @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
-   * range `[0, 2147483647]`.
+   * @throws {RangeError} When `gamepadIndex` is not an integer from
+   * `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
    */
   constructor(options?: Partial<GamepadInputOptions>);
   /**
@@ -166,10 +184,10 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    *
    * @param xAxis - Horizontal axis index.
    * @param yAxis - Vertical axis index.
-   * @param options - Optional per-read axis options.
+   * @param options - Optional per-read stick options.
    * @returns Object containing processed `x` and `y` values.
    */
-  stick(xAxis: number, yAxis: number, options?: GamepadAxisOptions): GamepadStick;
+  stick(xAxis: number, yAxis: number, options?: GamepadStickOptions): GamepadStick;
   /**
    * Plays an effect through the active gamepad's primary vibration actuator.
    *
@@ -193,4 +211,4 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
   resetVibration(): Promise<GamepadHapticsResult | null>;
 }
 //#endregion
-export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick };
+export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick, GamepadStickOptions };

package/dist/gamepad-input.js

@@ -4,17 +4,62 @@ 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`.
+* Applies a dead zone and remaps the remaining magnitude to `[0, 1]`.
 *
-* Kept private to this module because `GamepadInput` is the only public API
-* that currently exposes processed axis values.
+* @param magnitude - Non-negative input magnitude.
+* @param threshold - Dead zone size.
+* @returns Rescaled magnitude, or `0` when inside a fully closed dead zone.
+*/
+const rescaleGamepadDeadzoneMagnitude = (magnitude, threshold) => {
+	if (magnitude <= threshold || threshold >= 1) return 0;
+	return Math.min((magnitude - threshold) / (1 - threshold), 1);
+};
+/**
+* Applies an axial dead zone, optionally rescaling the remaining range.
+*
+* @param value - Raw axis value.
+* @param threshold - Dead zone size.
+* @param rescale - Whether to remap the remaining magnitude to `[0, 1]`.
+* @returns Processed signed axis value.
+*/
+const applyGamepadAxialDeadzone = (value, threshold, rescale) => {
+	const magnitude = Math.abs(value);
+	if (magnitude < threshold) return 0;
+	if (!rescale) return value;
+	return Math.sign(value) * rescaleGamepadDeadzoneMagnitude(magnitude, threshold);
+};
+/**
+* Returns the stick unchanged, or centered if its magnitude is below the dead
+* zone `threshold`.
 *
-* @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`.
+* @param x - Raw horizontal stick value.
+* @param y - Raw vertical stick value.
+* @param threshold - Radial dead zone size.
+* @param rescale - Whether to remap the remaining magnitude to `[0, 1]`.
+* @returns The processed stick, or `{ x: 0, y: 0 }` inside the dead zone.
 */
-const applyGamepadDeadzone = (value, threshold) => {
-	return Math.abs(value) < threshold ? 0 : value;
+const applyGamepadRadialDeadzone = (x, y, threshold, rescale) => {
+	const magnitude = Math.hypot(x, y);
+	if (magnitude < threshold) return {
+		x: 0,
+		y: 0
+	};
+	if (rescale) {
+		const rescaledMagnitude = rescaleGamepadDeadzoneMagnitude(magnitude, threshold);
+		if (rescaledMagnitude === 0 || magnitude === 0) return {
+			x: 0,
+			y: 0
+		};
+		const scale = rescaledMagnitude / magnitude;
+		return {
+			x: x * scale,
+			y: y * scale
+		};
+	}
+	return {
+		x,
+		y
+	};
 };
 /**
 * Returns whether a gamepad button is currently pressed.
@@ -66,8 +111,8 @@ var GamepadInput = class extends EventDispatcher {
 	* Creates a gamepad input reader.
 	*
 	* @param options - Optional overrides for the default input behavior.
-	* @throws {RangeError} When `gamepadIndex` is not an integer in the inclusive
-	* range `[0, 2147483647]`.
+	* @throws {RangeError} When `gamepadIndex` is not an integer from
+	* `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
 	*/
 	constructor(options) {
 		super();
@@ -224,20 +269,26 @@ var GamepadInput = class extends EventDispatcher {
 	* @returns Axis value after dead zone processing, or `0` when unavailable.
 	*/
 	axis(axis, options) {
-		return applyGamepadDeadzone(this.#gamepad?.axes[axis] ?? 0, this.#getDeadzone(options));
+		const value = this.#gamepad?.axes[axis] ?? 0;
+		return applyGamepadAxialDeadzone(value, this.#getDeadzone(options), false);
 	}
 	/**
 	* 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.
+	* @param options - Optional per-read stick options.
 	* @returns Object containing processed `x` and `y` values.
 	*/
 	stick(xAxis, yAxis, options) {
+		const rescale = options?.rescale ?? false;
+		const threshold = this.#getDeadzone(options);
+		const x = this.#gamepad?.axes[xAxis] ?? 0;
+		const y = this.#gamepad?.axes[yAxis] ?? 0;
+		if (options?.deadzoneMode === "radial") return applyGamepadRadialDeadzone(x, y, threshold, rescale);
 		return {
-			x: this.axis(xAxis, options),
-			y: this.axis(yAxis, options)
+			x: applyGamepadAxialDeadzone(x, threshold, rescale),
+			y: applyGamepadAxialDeadzone(y, threshold, rescale)
 		};
 	}
 	/**

package/dist/gamepad-manager.js

@@ -1,5 +1,5 @@
+import { MAX_GAMEPAD_INDEX } from "./core.js";
 //#region src/gamepad-manager.ts
-const MAX_GAMEPAD_INDEX = 2147483647;
 const EMPTY_UPDATE_RESULT = {
 	gamepad: null,
 	connected: null,
@@ -151,11 +151,11 @@ var GamepadManager = class {
 	* @param gamepadIndex - Browser-assigned gamepad index option.
 	* @returns Internal active-gamepad selection mode.
 	* @throws {RangeError} When the explicit index is not an integer in the
-	* inclusive range `[0, 2147483647]`.
+	* inclusive range [{@link MIN_GAMEPAD_INDEX}, {@link MAX_GAMEPAD_INDEX}].
 	*/
 	#resolveSelection(gamepadIndex) {
 		if (gamepadIndex === void 0) return { type: "first-available" };
-		if (!Number.isInteger(gamepadIndex) || gamepadIndex < 0 || gamepadIndex > MAX_GAMEPAD_INDEX) throw new RangeError(`gamepadIndex must be an integer between 0 and ${MAX_GAMEPAD_INDEX}.`);
+		if (!Number.isInteger(gamepadIndex) || gamepadIndex < 0 || gamepadIndex > 2147483647) throw new RangeError(`gamepadIndex must be an integer between 0 and ${MAX_GAMEPAD_INDEX}.`);
 		return {
 			type: "index",
 			index: gamepadIndex

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

@@ -1,6 +1,5 @@
 import { GamepadOrbitControls, GamepadOrbitControlsOptions } from "./gamepad-orbit-controls.js";
 import { MapControls } from "three/addons/controls/MapControls.js";
-
 //#region src/gamepad-map-controls.d.ts
 /**
  * Adds gamepad support to Three.js `MapControls`.

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
-
 //#region src/gamepad-orbit-controls.d.ts
 /**
  * Configuration for {@link GamepadOrbitControls}.

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { PointerLockControls } from "three/addons/controls/PointerLockControls.js";
-
 //#region src/gamepad-pointer-lock-controls.d.ts
 /**
  * Configuration for {@link GamepadPointerLockControls}.

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { TrackballControls } from "three/addons/controls/TrackballControls.js";
-
 //#region src/gamepad-trackball-controls.d.ts
 /**
  * Configuration for {@link GamepadTrackballControls}.

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

@@ -1,6 +1,5 @@
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { TransformControls } from "three/addons/controls/TransformControls.js";
-
 //#region src/gamepad-transform-controls.d.ts
 /**
  * Configuration for {@link GamepadTransformControls}.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue } from "./core.js";
-import { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick } from "./gamepad-input.js";
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX } from "./core.js";
+import { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick, GamepadStickOptions } from "./gamepad-input.js";
 import { GamepadControls, GamepadControlsEventMap, GamepadControlsOptions } from "./gamepad-controls.js";
 import { GamepadArcballControls, GamepadArcballControlsOptions } from "./gamepad-arcball-controls.js";
 import { GamepadDragControls, GamepadDragControlsOptions } from "./gamepad-drag-controls.js";
@@ -10,4 +10,4 @@ import { GamepadMapControls } from "./gamepad-map-controls.js";
 import { GamepadPointerLockControls, GamepadPointerLockControlsOptions } from "./gamepad-pointer-lock-controls.js";
 import { GamepadTrackballControls, GamepadTrackballControlsOptions } from "./gamepad-trackball-controls.js";
 import { GamepadTransformControls, GamepadTransformControlsOptions } from "./gamepad-transform-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadControlsOptions, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadStick, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadControlsOptions, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadStick, GamepadStickOptions, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX } from "./core.js";
 import { GamepadInput } from "./gamepad-input.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { GamepadArcballControls } from "./gamepad-arcball-controls.js";
@@ -10,4 +10,4 @@ import { GamepadMapControls } from "./gamepad-map-controls.js";
 import { GamepadPointerLockControls } from "./gamepad-pointer-lock-controls.js";
 import { GamepadTrackballControls } from "./gamepad-trackball-controls.js";
 import { GamepadTransformControls } from "./gamepad-transform-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadControls, GamepadDragControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadInput, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls, GamepadTransformControls };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadControls, GamepadDragControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadInput, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls, GamepadTransformControls, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {
     "name": "Kasnix",
@@ -46,16 +46,16 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.1",
-    "@commitlint/cli": "21.2.0",
+    "@biomejs/biome": "2.5.4",
+    "@commitlint/cli": "21.2.1",
     "@commitlint/config-conventional": "21.2.0",
     "@commitlint/types": "21.2.0",
-    "@types/node": "24.13.2",
+    "@types/node": "24.13.3",
     "@types/three": "0.184.0",
     "husky": "9.1.7",
     "three": "0.184.0",
-    "tsdown": "0.22.3",
-    "typescript": "6.0.3"
+    "tsdown": "0.22.8",
+    "typescript": "7.0.2"
   },
   "peerDependencies": {
     "@types/three": ">=0.184.0",