three-gamepad-controls 0.17.0 → 0.19.0

package/dist/gamepad-input.js

@@ -1,69 +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
+	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.
-*/
-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.
+* @returns The original value outside the dead zone, otherwise `0`.
 */
-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.
@@ -274,27 +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 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 threshold = this.#getDeadzone(options);
+	stick(xAxis, yAxis, pipeline) {
 		const x = this.#gamepad?.axes[xAxis] ?? 0;
 		const y = this.#gamepad?.axes[yAxis] ?? 0;
-		if (deadzoneMode === "radial") return applyGamepadRadialDeadzone(x, y, threshold, rescale);
-		return {
-			x: applyGamepadAxialDeadzone(x, threshold, rescale),
-			y: applyGamepadAxialDeadzone(y, threshold, rescale)
-		};
+		return (pipeline ?? this.#options.stickPipeline).process({
+			x,
+			y
+		});
 	}
 	/**
 	* Plays an effect through the active gamepad's primary vibration actuator.
@@ -383,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);
 		}

package/dist/gamepad-stick-processing.d.ts

@@ -0,0 +1,138 @@
+//#region src/gamepad-stick-processing.d.ts
+/**
+ * Dead zone processing mode for two-dimensional stick reads.
+ */
+type GamepadDeadzoneMode = "axial" | "radial";
+/**
+ * Two-dimensional gamepad stick value.
+ */
+type GamepadStick = {
+  /**
+   * Horizontal stick component.
+   */
+  x: number;
+  /**
+   * Vertical stick component.
+   */
+  y: number;
+};
+/**
+ * Pure, stateless transformation applied to a gamepad stick.
+ *
+ * Implementations must not mutate `value`. Stateful processing such as
+ * smoothing belongs in a separate lifecycle-aware abstraction.
+ */
+type GamepadStickProcessor = {
+  /**
+   * Transforms one stick value.
+   *
+   * @param value - Input value from the previous processor.
+   * @returns Processed stick value.
+   */
+  process(value: Readonly<GamepadStick>): GamepadStick;
+};
+/**
+ * Ordered, reusable sequence of stateless stick processors.
+ */
+type GamepadStickPipeline = GamepadStickProcessor & {
+  /**
+   * Processors in execution order.
+   */
+  readonly processors: readonly GamepadStickProcessor[];
+};
+/**
+ * Options for {@link createGamepadDeadzoneProcessor}.
+ */
+type GamepadDeadzoneProcessorOptions = {
+  /**
+   * Dead zone threshold.
+   * @default 0.1
+   */
+  threshold?: number;
+  /**
+   * Whether to process each component or the vector magnitude.
+   * @default "axial"
+   */
+  mode?: GamepadDeadzoneMode;
+  /**
+   * Whether to remap values outside the dead zone to the full output range.
+   * @default false
+   */
+  rescale?: boolean;
+};
+/**
+ * Options for {@link createGamepadInversionProcessor}.
+ */
+type GamepadInversionProcessorOptions = {
+  /**
+   * Whether to invert the horizontal component.
+   * @default false
+   */
+  invertX?: boolean;
+  /**
+   * Whether to invert the vertical component.
+   * @default false
+   */
+  invertY?: boolean;
+};
+/**
+ * Partial binding for a two-dimensional stick action.
+ *
+ * Omitted fields inherit the action-specific defaults.
+ */
+type GamepadStickBindingOptions = {
+  /**
+   * Axis index used as the horizontal component.
+   */
+  xAxis?: number;
+  /**
+   * Axis index used as the vertical component.
+   */
+  yAxis?: number;
+  /**
+   * Stateless processing pipeline for this action.
+   */
+  pipeline?: GamepadStickPipeline;
+};
+/**
+ * Fully resolved binding used when reading a two-dimensional stick action.
+ */
+type GamepadStickBinding = Required<GamepadStickBindingOptions>;
+/**
+ * Creates an ordered pipeline from stateless stick processors.
+ *
+ * The processor list is copied once. Processor errors are not caught, and a
+ * processor's result is passed directly to the next processor.
+ *
+ * @param processors - Processors in execution order.
+ * @returns Reusable stick pipeline.
+ */
+declare const createGamepadStickPipeline: (...processors: readonly GamepadStickProcessor[]) => GamepadStickPipeline;
+/**
+ * Creates an axial or radial dead zone processor.
+ *
+ * @param options - Optional dead zone configuration.
+ * @returns Stateless dead zone processor.
+ */
+declare const createGamepadDeadzoneProcessor: (options?: GamepadDeadzoneProcessorOptions) => GamepadStickProcessor;
+/**
+ * Creates a processor that independently inverts stick components.
+ *
+ * @param options - Optional inversion configuration.
+ * @returns Stateless inversion processor.
+ */
+declare const createGamepadInversionProcessor: (options?: GamepadInversionProcessorOptions) => GamepadStickProcessor;
+/**
+ * Historical stick processing used when no custom pipeline is supplied.
+ */
+declare const DEFAULT_GAMEPAD_STICK_PIPELINE: GamepadStickPipeline;
+/**
+ * Resolves a partial stick binding over an action-specific default.
+ *
+ * @param defaults - Complete default binding.
+ * @param options - Optional binding overrides.
+ * @returns Complete resolved binding.
+ */
+declare const resolveGamepadStickBinding: (defaults: GamepadStickBinding, options?: GamepadStickBindingOptions) => GamepadStickBinding;
+//#endregion
+export { DEFAULT_GAMEPAD_STICK_PIPELINE, GamepadDeadzoneMode, GamepadDeadzoneProcessorOptions, GamepadInversionProcessorOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickPipeline, GamepadStickProcessor, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding };