three-gamepad-controls 0.17.0 → 0.19.0

package/README.md

@@ -4,7 +4,9 @@ Gamepad support for [Three.js](https://threejs.org) controls, built on top of [W
 
 ## Architecture
 
-![Architecture diagram showing GamepadManager used by GamepadInput, GamepadInput used by GamepadControls, and specific wrappers extending GamepadControls.](./assets/architecture-diagram.webp "Three.js Gamepad Controls architecture")
+![Layered architecture showing the shared gamepad input foundation branching into direct application input and Three.js control integrations.](./assets/architecture-diagram.webp "Three.js Gamepad Controls layered architecture")
+
+The library is organized around a shared input foundation that handles gamepad selection, polling, button states, axes, sticks, haptics, and standard mappings. Applications can consume this input directly for gameplay, menus, and custom interactions, or use `GamepadControls` and its ready-made or custom wrappers to integrate gamepads with Three.js controls.
 
 ## 📦 Installation
 
@@ -55,6 +57,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.
+- [Gamepad Stick Processing](./docs/gamepad-stick-processing.md) - Stateless processors, pipelines, and action bindings.
 - [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.

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { ArcballControls } from "three/addons/controls/ArcballControls.js";
 //#region src/gamepad-arcball-controls.d.ts
@@ -28,30 +29,20 @@ type GamepadArcballControlsOptions = GamepadControlsOptions & {
    */
   zRotateSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
-   * @default 0.1
-   */
-  deadzone: number;
-  /**
-   * Axis index for **horizontal** arcball rotation.
-   * @default 0 - Left stick X
+   * Stick binding used for arcball rotation.
+   * @default Left stick with the default stick pipeline
    */
-  axisRotateX: number;
+  rotateStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **vertical** arcball 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 button and 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-arcball-controls.js

@@ -1,4 +1,5 @@
 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";
 import { Vector2, Vector3 } from "three";
 //#region src/gamepad-arcball-controls.ts
@@ -7,11 +8,17 @@ const DEFAULT_ARCBALL_OPTIONS = {
 	panSpeed: 1,
 	zoomSpeed: 1,
 	zRotateSpeed: 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,
 	buttonZoomIn: GAMEPAD_BUTTON.RightTrigger,
 	buttonZoomOut: GAMEPAD_BUTTON.LeftTrigger,
 	buttonZRotateLeft: GAMEPAD_BUTTON.LeftShoulder,
@@ -47,7 +54,9 @@ var GamepadArcballControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_ARCBALL_OPTIONS,
-			...options
+			...options,
+			rotateStick: resolveGamepadStickBinding(DEFAULT_ARCBALL_OPTIONS.rotateStick, options?.rotateStick),
+			panStick: resolveGamepadStickBinding(DEFAULT_ARCBALL_OPTIONS.panStick, options?.panStick)
 		};
 		this.#centerNdc = new Vector2(0, 0);
 		this.#panStart = new Vector3();
@@ -65,20 +74,30 @@ var GamepadArcballControls = class extends GamepadControls {
 	*/
 	onUpdate(deltaTime) {
 		const controls = this.#controls;
-		const { rotateSpeed, panSpeed, zoomSpeed, zRotateSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
+		const { rotateSpeed, panSpeed, zoomSpeed, zRotateSpeed, rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
 		const input = this.gamepadInput;
 		const focusPoint = this.#consumeFocusPoint(buttonFocus);
 		if (!controls.enabled) {
 			this.#endInteraction();
 			return;
 		}
-		const rotateX = controls.enableRotate ? input.axis(axisRotateX, { deadzone }) : 0;
-		const rotateY = controls.enableRotate ? input.axis(axisRotateY, { deadzone }) : 0;
-		const panX = controls.enablePan ? input.axis(axisPanX, { deadzone }) : 0;
-		const panY = controls.enablePan ? input.axis(axisPanY, { deadzone }) : 0;
+		let rotateX = 0;
+		let rotateY = 0;
+		if (controls.enableRotate) {
+			const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+			rotateX = rotate.x;
+			rotateY = rotate.y;
+		}
+		let panX = 0;
+		let panY = 0;
+		if (controls.enablePan) {
+			const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
+			panX = pan.x;
+			panY = pan.y;
+		}
 		const zoom = controls.enableZoom ? input.buttonValue(buttonZoomIn) - input.buttonValue(buttonZoomOut) : 0;
 		const zRotation = controls.enableRotate ? input.buttonValue(buttonZRotateLeft) - input.buttonValue(buttonZRotateRight) : 0;
-		const activeInput = rotateX !== 0 || rotateY !== 0 || panX !== 0 || panY !== 0 || Math.abs(zoom) > deadzone || Math.abs(zRotation) > deadzone;
+		const activeInput = rotateX !== 0 || rotateY !== 0 || panX !== 0 || panY !== 0 || Math.abs(zoom) > buttonDeadzone || Math.abs(zRotation) > buttonDeadzone;
 		if (!activeInput && focusPoint === null) {
 			this.#endInteraction();
 			return;
@@ -87,8 +106,8 @@ var GamepadArcballControls = class extends GamepadControls {
 		let changed = false;
 		changed = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) || changed;
 		changed = this.#applyPan(deltaTime, panX, panY, panSpeed) || changed;
-		changed = this.#applyZoom(deltaTime, zoom, zoomSpeed, deadzone) || changed;
-		changed = this.#applyZRotation(deltaTime, zRotation, zRotateSpeed, deadzone) || changed;
+		changed = this.#applyZoom(deltaTime, zoom, zoomSpeed, buttonDeadzone) || changed;
+		changed = this.#applyZRotation(deltaTime, zRotation, zRotateSpeed, buttonDeadzone) || changed;
 		changed = this.#applyFocus(focusPoint) || changed;
 		if (changed) {
 			controls.update();
@@ -163,11 +182,11 @@ var GamepadArcballControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	* @param zoom - Signed zoom input from the configured trigger pair.
 	* @param zoomSpeed - User-configured zoom speed multiplier.
-	* @param deadzone - Trigger dead zone threshold.
+	* @param buttonDeadzone - Trigger dead zone threshold.
 	* @returns `true` when a zoom transform was applied.
 	*/
-	#applyZoom(deltaTime, zoom, zoomSpeed, deadzone) {
-		if (Math.abs(zoom) <= deadzone || this.#controls.scaleFactor <= 0) return false;
+	#applyZoom(deltaTime, zoom, zoomSpeed, buttonDeadzone) {
+		if (Math.abs(zoom) <= buttonDeadzone || this.#controls.scaleFactor <= 0) return false;
 		const controls = this.#controls;
 		const size = controls.scaleFactor ** (zoom * zoomSpeed * deltaTime * ZOOM_NOTCHES_PER_SECOND);
 		if (!Number.isFinite(size) || size <= 0 || size === 1) return false;
@@ -180,11 +199,11 @@ var GamepadArcballControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	* @param zRotation - Signed z-rotation input from the configured buttons.
 	* @param zRotateSpeed - User-configured z-rotation speed multiplier.
-	* @param deadzone - Button value dead zone threshold.
+	* @param buttonDeadzone - Button value dead zone threshold.
 	* @returns `true` when a z-rotation transform was applied.
 	*/
-	#applyZRotation(deltaTime, zRotation, zRotateSpeed, deadzone) {
-		if (Math.abs(zRotation) <= deadzone) return false;
+	#applyZRotation(deltaTime, zRotation, zRotateSpeed, buttonDeadzone) {
+		if (Math.abs(zRotation) <= buttonDeadzone) return false;
 		const controls = this.#controls;
 		const angle = zRotation * zRotateSpeed * deltaTime * Math.PI;
 		controls.updateMatrixState();

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { DragControls } from "three/addons/controls/DragControls.js";
 //#region src/gamepad-drag-controls.d.ts
@@ -18,30 +19,15 @@ type GamepadDragControlsOptions = GamepadControlsOptions & {
    */
   rotateSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
-   * @default 0.1
+   * Stick binding used for screen-relative dragging.
+   * @default Left stick with the default stick pipeline
    */
-  deadzone: number;
+  dragStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **horizontal** dragging.
-   * @default 0 - Left stick X
+   * Stick binding used for object rotation.
+   * @default Right stick with the default stick pipeline
    */
-  axisDragX: number;
-  /**
-   * Axis index for **vertical** dragging.
-   * @default 1 - Left stick Y
-   */
-  axisDragY: number;
-  /**
-   * Axis index for **horizontal** object rotation.
-   * @default 2 - Right stick X
-   */
-  axisRotateX: number;
-  /**
-   * Axis index for **vertical** object rotation.
-   * @default 3 - Right stick Y
-   */
-  axisRotateY: number;
+  rotateStick: GamepadStickBindingOptions;
   /**
    * Button index for grabbing and dropping the object under the center reticle.
    * @default 0 - South face button

package/dist/gamepad-drag-controls.js

@@ -1,15 +1,21 @@
 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";
 import { Matrix4, Vector2, Vector3 } from "three";
 //#region src/gamepad-drag-controls.ts
 const DEFAULT_DRAG_OPTIONS = {
 	dragSpeed: 1,
 	rotateSpeed: 1,
-	deadzone: .1,
-	axisDragX: GAMEPAD_AXIS.LeftX,
-	axisDragY: GAMEPAD_AXIS.LeftY,
-	axisRotateX: GAMEPAD_AXIS.RightX,
-	axisRotateY: GAMEPAD_AXIS.RightY,
+	dragStick: {
+		xAxis: GAMEPAD_AXIS.LeftX,
+		yAxis: GAMEPAD_AXIS.LeftY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	},
+	rotateStick: {
+		xAxis: GAMEPAD_AXIS.RightX,
+		yAxis: GAMEPAD_AXIS.RightY,
+		pipeline: DEFAULT_GAMEPAD_STICK_PIPELINE
+	},
 	buttonSelect: GAMEPAD_BUTTON.South
 };
 /**
@@ -44,7 +50,9 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_DRAG_OPTIONS,
-			...options
+			...options,
+			dragStick: resolveGamepadStickBinding(DEFAULT_DRAG_OPTIONS.dragStick, options?.dragStick),
+			rotateStick: resolveGamepadStickBinding(DEFAULT_DRAG_OPTIONS.rotateStick, options?.rotateStick)
 		};
 		this.#centerNdc = new Vector2(0, 0);
 		this.#intersections = [];
@@ -111,14 +119,12 @@ var GamepadDragControls = class extends GamepadControls {
 	#updateSelected(deltaTime) {
 		const selected = this.#selected;
 		if (selected === null) return;
-		const { dragSpeed, rotateSpeed, deadzone, axisDragX, axisDragY, axisRotateX, axisRotateY } = this.#options;
+		const { dragSpeed, rotateSpeed, dragStick, rotateStick } = this.#options;
 		const input = this.gamepadInput;
-		const dragX = input.axis(axisDragX, { deadzone });
-		const dragY = input.axis(axisDragY, { deadzone });
-		const rotateX = input.axis(axisRotateX, { deadzone });
-		const rotateY = input.axis(axisRotateY, { deadzone });
-		const dragged = this.#applyDrag(deltaTime, dragX, dragY, dragSpeed);
-		const rotated = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed);
+		const drag = input.stick(dragStick.xAxis, dragStick.yAxis, dragStick.pipeline);
+		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+		const dragged = this.#applyDrag(deltaTime, drag.x, drag.y, dragSpeed);
+		const rotated = this.#applyRotation(deltaTime, rotate.x, rotate.y, rotateSpeed);
 		if (dragged || rotated) this.#controls.dispatchEvent({
 			type: "drag",
 			object: selected

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.js";
 //#region src/gamepad-first-person-controls.d.ts
@@ -18,30 +19,18 @@ type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
    */
   lookSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
-   * @default 0.1
-   */
-  deadzone: number;
-  /**
-   * Axis index for **forward / backward** movement.
-   * @default 1 - Left stick Y
+   * Movement stick axes and processing pipeline.
    */
-  axisMoveForward: number;
+  moveStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **right / left** strafe movement.
-   * @default 0 - Left stick X
+   * Camera-look stick axes and processing pipeline.
    */
-  axisMoveRight: number;
+  lookStick: GamepadStickBindingOptions;
   /**
-   * 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
+   * Dead zone threshold for analog button values.
+   * @default 0.1
    */
-  axisLookY: number;
+  buttonDeadzone: number;
   /**
    * Button index for **moving up** (analog trigger value used for proportional speed).
    * @default 6 - Left trigger

package/dist/gamepad-first-person-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";
 import { MathUtils, Spherical, Vector3 } from "three";
 //#region src/gamepad-first-person-controls.ts
 const DEFAULT_FIRST_PERSON_OPTIONS = {
 	moveSpeed: 1,
 	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
+	},
+	buttonDeadzone: .1,
 	buttonMoveUp: GAMEPAD_BUTTON.LeftTrigger,
 	buttonMoveDown: GAMEPAD_BUTTON.RightTrigger
 };
@@ -37,7 +44,9 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_FIRST_PERSON_OPTIONS,
-			...options
+			...options,
+			moveStick: resolveGamepadStickBinding(DEFAULT_FIRST_PERSON_OPTIONS.moveStick, options?.moveStick),
+			lookStick: resolveGamepadStickBinding(DEFAULT_FIRST_PERSON_OPTIONS.lookStick, options?.lookStick)
 		};
 		this.#lookDirection = new Vector3();
 		this.#spherical = new Spherical();
@@ -49,26 +58,26 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
-		const { moveSpeed, lookSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonMoveUp, buttonMoveDown } = this.#options;
-		this.#applyMovement(deltaTime, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown);
-		this.#applyLook(deltaTime, lookSpeed, deadzone, axisLookX, axisLookY);
+		const { moveSpeed, lookSpeed, moveStick, lookStick, buttonDeadzone, buttonMoveUp, buttonMoveDown } = this.#options;
+		this.#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown);
+		this.#applyLook(deltaTime, lookSpeed, lookStick);
 	}
 	/**
 	* Applies local translation input to FirstPersonControls' object.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param moveSpeed - User-configured movement speed multiplier.
-	* @param deadzone - Axis and trigger dead zone threshold.
-	* @param axisMoveForward - Axis index for forward and backward movement.
-	* @param axisMoveRight - Axis index for right and left strafe movement.
+	* @param moveStick - Resolved movement stick binding.
+	* @param buttonDeadzone - Analog button dead zone threshold.
 	* @param buttonMoveUp - Button index for upward movement.
 	* @param buttonMoveDown - Button index for downward movement.
 	*/
-	#applyMovement(deltaTime, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown) {
+	#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown) {
 		const controls = this.#controls;
 		const input = this.gamepadInput;
 		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
-		const forward = input.axis(axisMoveForward, { deadzone });
+		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
+		const forward = move.y;
 		if (forward !== 0) {
 			let distance = forward * moveMult;
 			if (forward < 0 && controls.heightSpeed) {
@@ -77,26 +86,22 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 			}
 			controls.object.translateZ(distance);
 		}
-		const strafe = input.axis(axisMoveRight, { deadzone });
+		const strafe = move.x;
 		if (strafe !== 0) controls.object.translateX(strafe * moveMult);
 		const up = input.buttonValue(buttonMoveUp);
 		const down = input.buttonValue(buttonMoveDown);
-		if (up > deadzone) controls.object.translateY(up * moveMult);
-		if (down > deadzone) controls.object.translateY(-down * moveMult);
+		if (up > buttonDeadzone) controls.object.translateY(up * moveMult);
+		if (down > buttonDeadzone) controls.object.translateY(-down * moveMult);
 	}
 	/**
 	* Applies camera look input while keeping FirstPersonControls state in sync.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param lookSpeed - User-configured look speed multiplier.
-	* @param deadzone - Axis dead zone threshold.
-	* @param axisLookX - Axis index for yaw input.
-	* @param axisLookY - Axis index for pitch input.
+	* @param lookStick - Resolved camera-look stick binding.
 	*/
-	#applyLook(deltaTime, lookSpeed, deadzone, axisLookX, axisLookY) {
-		const input = this.gamepadInput;
-		const lookX = input.axis(axisLookX, { deadzone });
-		const lookY = input.axis(axisLookY, { deadzone });
+	#applyLook(deltaTime, lookSpeed, lookStick) {
+		const { x: lookX, y: lookY } = this.gamepadInput.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
 		if (lookX === 0 && lookY === 0) return;
 		const controls = this.#controls;
 		const actualLookSpeed = controls.lookSpeed * lookSpeed * deltaTime * LOOK_SPEED_SCALE;

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

@@ -1,3 +1,4 @@
+import { GamepadStickBindingOptions } from "./gamepad-stick-processing.js";
 import { GamepadControls, GamepadControlsOptions } from "./gamepad-controls.js";
 import { FlyControls } from "three/addons/controls/FlyControls.js";
 //#region src/gamepad-fly-controls.d.ts
@@ -18,30 +19,18 @@ type GamepadFlyControlsOptions = GamepadControlsOptions & {
    */
   rotateSpeed: number;
   /**
-   * Axis dead zone threshold in the range `[0, 1]`.
+   * Dead zone threshold for analog button values.
    * @default 0.1
    */
-  deadzone: number;
+  buttonDeadzone: number;
   /**
-   * Axis index for **forward / backward** movement.
-   * @default 1 — Left stick Y
+   * Movement stick axes and processing pipeline.
    */
-  axisMoveForward: number;
+  moveStick: GamepadStickBindingOptions;
   /**
-   * Axis index for **right / left** strafe movement.
-   * @default 0 — Left stick X
+   * Camera-look stick axes and processing pipeline.
    */
-  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;
   /**
    * Button index for **rolling left**.
    * @default 4 — Left shoulder

package/dist/gamepad-fly-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";
 import { Quaternion } from "three";
 //#region src/gamepad-fly-controls.ts
 const DEFAULT_FLY_OPTIONS = {
 	moveSpeed: 1,
 	rotateSpeed: 1,
-	deadzone: .1,
-	axisMoveForward: GAMEPAD_AXIS.LeftY,
-	axisMoveRight: GAMEPAD_AXIS.LeftX,
-	axisLookX: GAMEPAD_AXIS.RightX,
-	axisLookY: GAMEPAD_AXIS.RightY,
+	buttonDeadzone: .1,
+	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
+	},
 	buttonRollLeft: GAMEPAD_BUTTON.LeftShoulder,
 	buttonRollRight: GAMEPAD_BUTTON.RightShoulder,
 	buttonMoveUp: GAMEPAD_BUTTON.LeftTrigger,
@@ -36,7 +43,9 @@ var GamepadFlyControls = class extends GamepadControls {
 		this.#controls = controls;
 		this.#options = {
 			...DEFAULT_FLY_OPTIONS,
-			...options
+			...options,
+			moveStick: resolveGamepadStickBinding(DEFAULT_FLY_OPTIONS.moveStick, options?.moveStick),
+			lookStick: resolveGamepadStickBinding(DEFAULT_FLY_OPTIONS.lookStick, options?.lookStick)
 		};
 		this.#tmpQuaternion = new Quaternion();
 	}
@@ -46,20 +55,22 @@ var GamepadFlyControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
-		const { moveSpeed, rotateSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonRollLeft, buttonRollRight, buttonMoveUp, buttonMoveDown } = this.#options;
+		const { moveSpeed, rotateSpeed, buttonDeadzone, moveStick, lookStick, buttonRollLeft, buttonRollRight, buttonMoveUp, buttonMoveDown } = this.#options;
 		const input = this.gamepadInput;
+		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
+		const look = input.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
 		const moveMult = deltaTime * this.#controls.movementSpeed * moveSpeed;
-		const fwd = input.axis(axisMoveForward, { deadzone });
+		const fwd = move.y;
 		if (fwd !== 0) this.#controls.object.translateZ(fwd * moveMult);
-		const strafe = input.axis(axisMoveRight, { deadzone });
+		const strafe = move.x;
 		if (strafe !== 0) this.#controls.object.translateX(strafe * moveMult);
 		const up = input.buttonValue(buttonMoveUp);
 		const down = input.buttonValue(buttonMoveDown);
-		if (up > deadzone) this.#controls.object.translateY(up * moveMult);
-		if (down > deadzone) this.#controls.object.translateY(-down * moveMult);
+		if (up > buttonDeadzone) this.#controls.object.translateY(up * moveMult);
+		if (down > buttonDeadzone) this.#controls.object.translateY(-down * moveMult);
 		const rotMult = deltaTime * this.#controls.rollSpeed * rotateSpeed;
-		const pitch = -input.axis(axisLookY, { deadzone });
-		const yaw = -input.axis(axisLookX, { deadzone });
+		const pitch = -look.y;
+		const yaw = -look.x;
 		const roll = (input.isPressed(buttonRollLeft) ? 1 : 0) - (input.isPressed(buttonRollRight) ? 1 : 0);
 		if (pitch !== 0 || yaw !== 0 || roll !== 0) {
 			this.#tmpQuaternion.set(pitch * rotMult, yaw * rotMult, roll * rotMult, 1).normalize();

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,29 +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;
+  axisDeadzone: number;
   /**
-   * Default dead zone mode for stick reads.
-   * @default "axial"
+   * Default stateless processing pipeline for stick reads.
+   * @default DEFAULT_GAMEPAD_STICK_PIPELINE
    */
-  deadzoneMode: GamepadDeadzoneMode;
-  /**
-   * Whether stick reads rescale values outside the dead zone by default.
-   * @default false
-   */
-  rescale: boolean;
+  stickPipeline: GamepadStickPipeline;
   /**
    * Browser-assigned gamepad slot to use.
    *
@@ -66,37 +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;
-};
-/**
- * Two-dimensional stick input after dead zone processing.
- */
-type GamepadStick = {
-  /**
-   * Horizontal stick value.
-   */
-  x: number;
-  /**
-   * Vertical stick value.
-   */
-  y: number;
-};
 /**
  * Gamepad input state reader for gameplay, menus, and custom actions.
  *
@@ -194,14 +155,14 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    */
   axis(axis: number, options?: GamepadAxisOptions): number;
   /**
-   * 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: 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.
    *
@@ -225,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 };