three-gamepad-controls 0.18.0 → 0.20.0

package/dist/gamepad-input.d.ts

@@ -1,3 +1,4 @@
+import { GamepadStick, GamepadStickPipeline } from "./gamepad-stick-processing.js";
 import { EventDispatcher } from "three";
 //#region src/gamepad-input.d.ts
 /**
@@ -23,39 +24,20 @@ type GamepadInputEventMap = {
     gamepad: Gamepad;
   };
 };
-/**
- * Dead zone processing mode for two-dimensional stick reads.
- */
-type GamepadDeadzoneMode = "axial" | "radial";
 /**
  * Configuration for {@link GamepadInput}.
  */
 type GamepadInputOptions = {
   /**
-   * Default axis dead zone threshold in the range `[0, 1]`.
+   * Default dead zone threshold for {@link GamepadInput.axis} reads.
    * @default 0.1
    */
-  deadzone: number;
-  /**
-   * Default dead zone mode for stick reads.
-   * @default "axial"
-   */
-  deadzoneMode: GamepadDeadzoneMode;
-  /**
-   * Whether stick reads rescale values outside the dead zone by default.
-   * @default false
-   */
-  rescale: boolean;
-  /**
-   * Whether the horizontal component of stick reads is inverted by default.
-   * @default false
-   */
-  invertX: boolean;
+  axisDeadzone: number;
   /**
-   * Whether the vertical component of stick reads is inverted by default.
-   * @default false
+   * Default stateless processing pipeline for stick reads.
+   * @default DEFAULT_GAMEPAD_STICK_PIPELINE
    */
-  invertY: boolean;
+  stickPipeline: GamepadStickPipeline;
   /**
    * Browser-assigned gamepad slot to use.
    *
@@ -76,47 +58,6 @@ 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?: GamepadDeadzoneMode;
-  /**
-   * Whether to remap values outside the dead zone to the full output range.
-   * @default false
-   */
-  rescale?: boolean;
-  /**
-   * Whether to invert the processed component from `xAxis`.
-   * @default false
-   */
-  invertX?: boolean;
-  /**
-   * Whether to invert the processed component from `yAxis`.
-   * @default false
-   */
-  invertY?: boolean;
-};
-/**
- * Two-dimensional stick input after configured stick processing.
- */
-type GamepadStick = {
-  /**
-   * Processed horizontal stick value.
-   */
-  x: number;
-  /**
-   * Processed vertical stick value.
-   */
-  y: number;
-};
 /**
  * Gamepad input state reader for gameplay, menus, and custom actions.
  *
@@ -214,14 +155,14 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    */
   axis(axis: number, options?: GamepadAxisOptions): number;
   /**
-   * Returns a two-axis stick after dead zone, rescale, and inversion processing.
+   * Returns a two-axis stick after applying a stateless processing pipeline.
    *
    * @param xAxis - Horizontal axis index.
    * @param yAxis - Vertical axis index.
-   * @param options - Optional per-read stick options.
+   * @param pipeline - Optional pipeline replacing the instance default.
    * @returns Object containing processed `x` and `y` values.
    */
-  stick(xAxis: number, yAxis: number, options?: GamepadStickOptions): GamepadStick;
+  stick(xAxis: number, yAxis: number, pipeline?: GamepadStickPipeline): GamepadStick;
   /**
    * Plays an effect through the active gamepad's primary vibration actuator.
    *
@@ -245,4 +186,4 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
   resetVibration(): Promise<GamepadHapticsResult | null>;
 }
 //#endregion
-export { GamepadAxisOptions, GamepadDeadzoneMode, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadStick, GamepadStickOptions };
+export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions };

package/dist/gamepad-input.js

@@ -1,71 +1,21 @@
 import { isGamepadVibrationSupported, playGamepadVibrationEffect, resetGamepadVibration } from "./gamepad-haptics.js";
 import { GamepadManager } from "./gamepad-manager.js";
+import { DEFAULT_GAMEPAD_STICK_PIPELINE } from "./gamepad-stick-processing.js";
 import { EventDispatcher } from "three";
 //#region src/gamepad-input.ts
 const DEFAULT_GAMEPAD_INPUT_OPTIONS = {
-	deadzone: .1,
-	deadzoneMode: "axial",
-	rescale: false,
-	invertX: false,
-	invertY: false
+	axisDeadzone: .1,
+	stickPipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
 };
 /**
-* Applies a dead zone and remaps the remaining magnitude to `[0, 1]`.
-*
-* @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.
+* Applies a scalar dead zone without rescaling.
 *
 * @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.
+* @returns The original value outside the dead zone, otherwise `0`.
 */
-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 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 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
-	};
+const applyGamepadAxisDeadzone = (value, threshold) => {
+	return Math.abs(value) < threshold ? 0 : value;
 };
 /**
 * Returns whether a gamepad button is currently pressed.
@@ -276,33 +226,23 @@ var GamepadInput = class extends EventDispatcher {
 	*/
 	axis(axis, options) {
 		const value = this.#gamepad?.axes[axis] ?? 0;
-		return applyGamepadAxialDeadzone(value, this.#getDeadzone(options), false);
+		return applyGamepadAxisDeadzone(value, this.#getAxisDeadzone(options));
 	}
 	/**
-	* Returns a two-axis stick after dead zone, rescale, and inversion processing.
+	* Returns a two-axis stick after applying a stateless processing pipeline.
 	*
 	* @param xAxis - Horizontal axis index.
 	* @param yAxis - Vertical axis index.
-	* @param options - Optional per-read stick options.
+	* @param pipeline - Optional pipeline replacing the instance default.
 	* @returns Object containing processed `x` and `y` values.
 	*/
-	stick(xAxis, yAxis, options) {
-		const deadzoneMode = options?.deadzoneMode ?? this.#options.deadzoneMode;
-		const rescale = options?.rescale ?? this.#options.rescale;
-		const invertX = options?.invertX ?? this.#options.invertX;
-		const invertY = options?.invertY ?? this.#options.invertY;
-		const threshold = this.#getDeadzone(options);
+	stick(xAxis, yAxis, pipeline) {
 		const x = this.#gamepad?.axes[xAxis] ?? 0;
 		const y = this.#gamepad?.axes[yAxis] ?? 0;
-		const processed = deadzoneMode === "radial" ? applyGamepadRadialDeadzone(x, y, threshold, rescale) : {
-			x: applyGamepadAxialDeadzone(x, threshold, rescale),
-			y: applyGamepadAxialDeadzone(y, threshold, rescale)
-		};
-		if (!invertX && !invertY) return processed;
-		return {
-			x: processed.x === 0 ? 0 : invertX ? -processed.x : processed.x,
-			y: processed.y === 0 ? 0 : invertY ? -processed.y : processed.y
-		};
+		return (pipeline ?? this.#options.stickPipeline).process({
+			x,
+			y
+		});
 	}
 	/**
 	* Plays an effect through the active gamepad's primary vibration actuator.
@@ -391,13 +331,13 @@ var GamepadInput = class extends EventDispatcher {
 		this.#previousPressedButtons.clear();
 	}
 	/**
-	* Resolves the dead zone for a single axis or stick read.
+	* Resolves the dead zone for a single-axis 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;
+	#getAxisDeadzone(options) {
+		return options?.deadzone ?? this.#options.axisDeadzone;
 	}
 };
 //#endregion

package/dist/gamepad-manager.js

@@ -69,7 +69,7 @@ var GamepadManager = class {
 	* Polls the Gamepad API and refreshes the active gamepad snapshot.
 	*
 	* Polling re-resolves the browser slot so a disconnected device, a reused
-	* index, or an updated active device is observed before controls read input.
+	* index, or an updated active device is observed before consumers read input.
 	*
 	* @returns The active gamepad and any connect/disconnect transition found.
 	*/

package/dist/gamepad-map-controls.js

@@ -2,10 +2,14 @@ import { GAMEPAD_AXIS } from "./core.js";
 import { GamepadOrbitControls } from "./gamepad-orbit-controls.js";
 //#region src/gamepad-map-controls.ts
 const DEFAULT_MAP_OPTIONS = {
-	axisPanX: GAMEPAD_AXIS.LeftX,
-	axisPanY: GAMEPAD_AXIS.LeftY,
-	axisRotateX: GAMEPAD_AXIS.RightX,
-	axisRotateY: GAMEPAD_AXIS.RightY
+	panStick: {
+		xAxis: GAMEPAD_AXIS.LeftX,
+		yAxis: GAMEPAD_AXIS.LeftY
+	},
+	rotateStick: {
+		xAxis: GAMEPAD_AXIS.RightX,
+		yAxis: GAMEPAD_AXIS.RightY
+	}
 };
 /**
 * Adds gamepad support to Three.js `MapControls`.
@@ -24,7 +28,15 @@ var GamepadMapControls = class extends GamepadOrbitControls {
 	constructor(controls, options) {
 		super(controls, {
 			...DEFAULT_MAP_OPTIONS,
-			...options
+			...options,
+			panStick: {
+				...DEFAULT_MAP_OPTIONS.panStick,
+				...options?.panStick
+			},
+			rotateStick: {
+				...DEFAULT_MAP_OPTIONS.rotateStick,
+				...options?.rotateStick
+			}
 		});
 	}
 };

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
 //#region src/gamepad-orbit-controls.d.ts
@@ -23,30 +24,20 @@ type GamepadOrbitControlsOptions = GamepadControlsOptions & {
    */
   zoomSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
-   * @default 0.1
-   */
-  deadzone: number;
-  /**
-   * Axis index for **horizontal** orbit rotation.
-   * @default 0 — Left stick X
+   * Stick binding used for orbit rotation.
+   * @default Left stick with the default stick pipeline
    */
-  axisRotateX: number;
+  rotateStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **vertical** orbit rotation.
-   * @default 1 — Left stick Y
+   * Stick binding used for panning.
+   * @default Right stick with the default stick pipeline
    */
-  axisRotateY: number;
+  panStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **horizontal** panning.
-   * @default 2 — Right stick X
-   */
-  axisPanX: number;
-  /**
-   * Axis index for **vertical** panning.
-   * @default 3 — Right stick Y
+   * Dead zone threshold for analog trigger values.
+   * @default 0.1
    */
-  axisPanY: number;
+  buttonDeadzone: number;
   /**
    * Button index for zooming **in** (analog trigger value used for proportional zoom).
    * @default 7 — Right trigger

package/dist/gamepad-orbit-controls.js

@@ -1,15 +1,22 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
 //#region src/gamepad-orbit-controls.ts
 const DEFAULT_ORBIT_OPTIONS = {
 	rotateSpeed: 1,
 	panSpeed: 1,
 	zoomSpeed: 1,
-	deadzone: .1,
-	axisRotateX: GAMEPAD_AXIS.LeftX,
-	axisRotateY: GAMEPAD_AXIS.LeftY,
-	axisPanX: GAMEPAD_AXIS.RightX,
-	axisPanY: GAMEPAD_AXIS.RightY,
+	rotateStick: {
+		xAxis: GAMEPAD_AXIS.LeftX,
+		yAxis: GAMEPAD_AXIS.LeftY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	},
+	panStick: {
+		xAxis: GAMEPAD_AXIS.RightX,
+		yAxis: GAMEPAD_AXIS.RightY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	},
+	buttonDeadzone: .1,
 	buttonDollyIn: GAMEPAD_BUTTON.RightTrigger,
 	buttonDollyOut: GAMEPAD_BUTTON.LeftTrigger
 };
@@ -32,7 +39,9 @@ var GamepadOrbitControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_ORBIT_OPTIONS,
-			...options
+			...options,
+			rotateStick: resolveGamepadStickBinding(DEFAULT_ORBIT_OPTIONS.rotateStick, options?.rotateStick),
+			panStick: resolveGamepadStickBinding(DEFAULT_ORBIT_OPTIONS.panStick, options?.panStick)
 		};
 	}
 	/**
@@ -41,19 +50,17 @@ var GamepadOrbitControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
-		const { rotateSpeed, panSpeed, zoomSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonDollyIn, buttonDollyOut } = this.#options;
+		const { rotateSpeed, panSpeed, zoomSpeed, rotateStick, panStick, buttonDeadzone, buttonDollyIn, buttonDollyOut } = this.#options;
 		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 = 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 rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+		if (rotate.x !== 0) this.#controls.rotateLeft(rotate.x * rotateSpeed * deltaTime * Math.PI);
+		if (rotate.y !== 0) this.#controls.rotateUp(rotate.y * rotateSpeed * deltaTime * Math.PI);
+		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
+		if (pan.x !== 0 || pan.y !== 0) this.#controls.pan(pan.x * panSpeed * deltaTime * 500, pan.y * panSpeed * deltaTime * 500);
 		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));
+		if (triggerIn > buttonDeadzone) this.#controls.dollyIn(1 / (1 + zoomSpeed * triggerIn * deltaTime));
+		if (triggerOut > buttonDeadzone) this.#controls.dollyOut(1 / (1 + zoomSpeed * triggerOut * deltaTime));
 	}
 };
 //#endregion

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { PointerLockControls } from "three/addons/controls/PointerLockControls.js";
 //#region src/gamepad-pointer-lock-controls.d.ts
@@ -18,30 +19,15 @@ type GamepadPointerLockControlsOptions = GamepadControlsOptions & {
    */
   lookSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
-   * @default 0.1
+   * Stick binding used for horizontal and forward movement.
+   * @default Left stick with the default stick pipeline
    */
-  deadzone: number;
+  moveStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **forward / backward** movement.
-   * @default 1 — Left stick Y
+   * Stick binding used for yaw and pitch.
+   * @default Right stick with the default stick pipeline
    */
-  axisMoveForward: number;
-  /**
-   * Axis index for **right / left** strafe movement.
-   * @default 0 — Left stick X
-   */
-  axisMoveRight: number;
-  /**
-   * Axis index for **horizontal** camera look (yaw).
-   * @default 2 — Right stick X
-   */
-  axisLookX: number;
-  /**
-   * Axis index for **vertical** camera look (pitch).
-   * @default 3 — Right stick Y
-   */
-  axisLookY: number;
+  lookStick: GamepadStickBindingOptions;
 };
 /**
  * Adds gamepad support to Three.js `PointerLockControls`.

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

@@ -1,15 +1,21 @@
 import { GAMEPAD_AXIS } from "./core.js";
+import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { Euler } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
 const DEFAULT_POINTER_LOCK_OPTIONS = {
 	moveSpeed: 5,
 	lookSpeed: 1,
-	deadzone: .1,
-	axisMoveForward: GAMEPAD_AXIS.LeftY,
-	axisMoveRight: GAMEPAD_AXIS.LeftX,
-	axisLookX: GAMEPAD_AXIS.RightX,
-	axisLookY: GAMEPAD_AXIS.RightY
+	moveStick: {
+		xAxis: GAMEPAD_AXIS.LeftX,
+		yAxis: GAMEPAD_AXIS.LeftY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	},
+	lookStick: {
+		xAxis: GAMEPAD_AXIS.RightX,
+		yAxis: GAMEPAD_AXIS.RightY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	}
 };
 /**
 * Adds gamepad support to Three.js `PointerLockControls`.
@@ -32,7 +38,9 @@ var GamepadPointerLockControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_POINTER_LOCK_OPTIONS,
-			...options
+			...options,
+			moveStick: resolveGamepadStickBinding(DEFAULT_POINTER_LOCK_OPTIONS.moveStick, options?.moveStick),
+			lookStick: resolveGamepadStickBinding(DEFAULT_POINTER_LOCK_OPTIONS.lookStick, options?.lookStick)
 		};
 		this.#euler = new Euler(0, 0, 0, "YXZ");
 	}
@@ -42,20 +50,18 @@ var GamepadPointerLockControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
-		const { moveSpeed, lookSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY } = this.#options;
+		const { moveSpeed, lookSpeed, moveStick, lookStick } = this.#options;
 		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 = input.axis(axisLookX, { deadzone });
-		const lookY = input.axis(axisLookY, { deadzone });
-		if (lookX !== 0 || lookY !== 0) {
+		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
+		if (move.y !== 0) this.#controls.moveForward(-move.y * moveSpeed * deltaTime);
+		if (move.x !== 0) this.#controls.moveRight(move.x * moveSpeed * deltaTime);
+		const look = input.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
+		if (look.x !== 0 || look.y !== 0) {
 			const camera = this.#controls.object;
 			const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
 			this.#euler.setFromQuaternion(camera.quaternion);
-			this.#euler.y -= lookX * scale;
-			this.#euler.x -= lookY * scale;
+			this.#euler.y -= look.x * scale;
+			this.#euler.x -= look.y * scale;
 			this.#euler.x = Math.max(Math.PI / 2 - this.#controls.maxPolarAngle, Math.min(Math.PI / 2 - this.#controls.minPolarAngle, this.#euler.x));
 			camera.quaternion.setFromEuler(this.#euler);
 		}