three-gamepad-controls 0.15.0 → 0.16.0

package/dist/gamepad-input.d.ts

@@ -44,7 +44,7 @@ type GamepadInputOptions = {
   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.
  */
@@ -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.
@@ -225,20 +270,25 @@ var GamepadInput = class extends EventDispatcher {
 	*/
 	axis(axis, options) {
 		const value = this.#gamepad?.axes[axis] ?? 0;
-		return applyGamepadDeadzone(value, this.#getDeadzone(options));
+		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/index.d.ts

@@ -1,5 +1,5 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX } from "./core.js";
-import { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick } from "./gamepad-input.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, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };
+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/package.json

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