three-gamepad-controls 0.19.0 → 0.21.0

package/README.md

@@ -2,6 +2,9 @@
 
 Gamepad support for [Three.js](https://threejs.org) controls, built on top of [Web Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API).
 
+> [!WARNING]
+> This library has not reached version 1.0.0 and should not yet be considered stable. Until 1.0.0, minor releases may include breaking changes.
+
 ## 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")

package/dist/gamepad-arcball-controls.js

@@ -154,9 +154,9 @@ var GamepadArcballControls = class extends GamepadControls {
 		const controls = this.#controls;
 		controls.updateMatrixState();
 		this.#previousUp.copy(controls.object.up);
-		const changed = this.#applyTransform(controls.rotate(axis, angle));
-		if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(axis, -angle);
-		return changed;
+		this.#applyTransform(controls.rotate(axis, angle));
+		controls.object.up.copy(this.#previousUp).applyAxisAngle(axis, -angle);
+		return true;
 	}
 	/**
 	* Applies gamepad pan by converting stick input to Arcball trackball points.
@@ -174,7 +174,8 @@ var GamepadArcballControls = class extends GamepadControls {
 		controls.updateMatrixState();
 		this.#panStart.set(0, 0, 0);
 		this.#panEnd.set(panX * distance, panY * distance, 0);
-		return this.#applyTransform(controls.pan(this.#panStart, this.#panEnd));
+		this.#applyTransform(controls.pan(this.#panStart, this.#panEnd));
+		return true;
 	}
 	/**
 	* Applies trigger-driven zoom around Arcball's gizmo center.
@@ -191,7 +192,10 @@ var GamepadArcballControls = class extends GamepadControls {
 		const size = controls.scaleFactor ** (zoom * zoomSpeed * deltaTime * ZOOM_NOTCHES_PER_SECOND);
 		if (!Number.isFinite(size) || size <= 0 || size === 1) return false;
 		controls.updateMatrixState();
-		return this.#applyTransform(controls.scale(size, controls._gizmos.position));
+		const transformation = controls.scale(size, controls._gizmos.position);
+		if (transformation === void 0) return false;
+		this.#applyTransform(transformation);
+		return true;
 	}
 	/**
 	* Applies shoulder-button rotation around the current camera view axis.
@@ -209,9 +213,9 @@ var GamepadArcballControls = class extends GamepadControls {
 		controls.updateMatrixState();
 		controls.object.getWorldDirection(controls._rotationAxis);
 		this.#previousUp.copy(controls.object.up);
-		const changed = this.#applyTransform(controls.zRotate(controls._gizmos.position, angle));
-		if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(controls._rotationAxis, angle);
-		return changed;
+		this.#applyTransform(controls.zRotate(controls._gizmos.position, angle));
+		controls.object.up.copy(this.#previousUp).applyAxisAngle(controls._rotationAxis, angle);
+		return true;
 	}
 	/**
 	* Focuses ArcballControls on the given point when one was consumed.
@@ -230,14 +234,11 @@ var GamepadArcballControls = class extends GamepadControls {
 	/**
 	* Applies a transformation returned by an Arcball runtime helper.
 	*
-	* @param transformation - Arcball transformation matrices, if any.
-	* @returns `true` when a transformation was applied.
+	* @param transformation - Arcball transformation matrices to apply.
 	*/
 	#applyTransform(transformation) {
-		if (transformation === void 0) return false;
 		this.#controls.applyTransformMatrix(transformation);
 		this.#controls.updateMatrixState();
-		return true;
 	}
 	/**
 	* Consumes a focus-button press and resolves the viewport center hit point.

package/dist/gamepad-drag-controls.js

@@ -80,12 +80,13 @@ var GamepadDragControls = class extends GamepadControls {
 			this.#clearHover();
 			return;
 		}
-		if (this.#selected !== null) {
+		const selected = this.#selected;
+		if (selected !== null) {
 			if (selectStarted) {
 				this.#releaseSelected();
 				return;
 			}
-			this.#updateSelected(deltaTime);
+			this.#updateSelected(selected, deltaTime);
 			return;
 		}
 		const hit = this.#intersectCenter();
@@ -114,17 +115,16 @@ var GamepadDragControls = class extends GamepadControls {
 	/**
 	* Updates the selected object from gamepad drag and rotation input.
 	*
+	* @param selected - Object selected for the current update.
 	* @param deltaTime - Seconds since the last frame.
 	*/
-	#updateSelected(deltaTime) {
-		const selected = this.#selected;
-		if (selected === null) return;
+	#updateSelected(selected, deltaTime) {
 		const { dragSpeed, rotateSpeed, dragStick, rotateStick } = this.#options;
 		const input = this.gamepadInput;
 		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);
+		const dragged = this.#applyDrag(selected, deltaTime, drag.x, drag.y, dragSpeed);
+		const rotated = this.#applyRotation(selected, deltaTime, rotate.x, rotate.y, rotateSpeed);
 		if (dragged || rotated) this.#controls.dispatchEvent({
 			type: "drag",
 			object: selected
@@ -133,34 +133,35 @@ var GamepadDragControls = class extends GamepadControls {
 	/**
 	* Moves the selected object in the camera-facing plane.
 	*
+	* @param selected - Object selected for the current update.
 	* @param deltaTime - Seconds since the last frame.
 	* @param dragX - Horizontal drag input after dead zone processing.
 	* @param dragY - Vertical drag input after dead zone processing.
 	* @param dragSpeed - User-configured drag speed multiplier.
 	* @returns `true` when the selected object moved.
 	*/
-	#applyDrag(deltaTime, dragX, dragY, dragSpeed) {
-		if (this.#selected === null || dragX === 0 && dragY === 0) return false;
+	#applyDrag(selected, deltaTime, dragX, dragY, dragSpeed) {
+		if (dragX === 0 && dragY === 0) return false;
 		this.#updateCameraAxes();
 		this.#updateViewSizeAtSelectedDepth();
 		const scale = dragSpeed * deltaTime;
 		this.#selectedWorldPosition.addScaledVector(this.#cameraRight, dragX * this.#viewSize.x * scale);
 		this.#selectedWorldPosition.addScaledVector(this.#cameraUp, -dragY * this.#viewSize.y * scale);
-		this.#applySelectedWorldPosition();
+		this.#applySelectedWorldPosition(selected);
 		return true;
 	}
 	/**
 	* Rotates the selected object around camera-relative world axes.
 	*
+	* @param selected - Object selected for the current update.
 	* @param deltaTime - Seconds since the last frame.
 	* @param rotateX - Horizontal rotation input after dead zone processing.
 	* @param rotateY - Vertical rotation input after dead zone processing.
 	* @param rotateSpeed - User-configured rotation speed multiplier.
 	* @returns `true` when the selected object rotated.
 	*/
-	#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) {
-		const selected = this.#selected;
-		if (selected === null || rotateX === 0 && rotateY === 0) return false;
+	#applyRotation(selected, deltaTime, rotateX, rotateY, rotateSpeed) {
+		if (rotateX === 0 && rotateY === 0) return false;
 		this.#updateCameraAxes();
 		const scale = this.#controls.rotateSpeed * rotateSpeed * deltaTime * Math.PI;
 		if (rotateX !== 0) selected.rotateOnWorldAxis(this.#cameraUp, rotateX * scale);
@@ -252,9 +253,7 @@ var GamepadDragControls = class extends GamepadControls {
 		}
 		return group;
 	}
-	#applySelectedWorldPosition() {
-		const selected = this.#selected;
-		if (selected === null) return;
+	#applySelectedWorldPosition(selected) {
 		if (selected.parent === null) {
 			selected.position.copy(this.#selectedWorldPosition);
 			selected.updateMatrixWorld();

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

@@ -1,8 +1,19 @@
 //#region src/gamepad-stick-processing.d.ts
 /**
- * Dead zone processing mode for two-dimensional stick reads.
+ * Geometry used when processing two-dimensional stick values.
+ *
+ * Axial processing transforms each component independently. Radial processing
+ * transforms vector magnitude while preserving direction.
+ */
+type GamepadStickProcessingMode = "axial" | "radial";
+/**
+ * Built-in response curve applied to stick components or magnitude.
+ */
+type GamepadResponseCurve = "linear" | "quadratic" | "cubic";
+/**
+ * Stick component selection used by inversion processing.
  */
-type GamepadDeadzoneMode = "axial" | "radial";
+type GamepadStickInversionAxis = "x" | "y" | "both";
 /**
  * Two-dimensional gamepad stick value.
  */
@@ -16,6 +27,10 @@ type GamepadStick = {
    */
   y: number;
 };
+/**
+ * Pure custom transformation applied to a gamepad stick.
+ */
+type GamepadStickTransform = (value: Readonly<GamepadStick>) => GamepadStick;
 /**
  * Pure, stateless transformation applied to a gamepad stick.
  *
@@ -32,28 +47,23 @@ type GamepadStickProcessor = {
   process(value: Readonly<GamepadStick>): GamepadStick;
 };
 /**
- * Ordered, reusable sequence of stateless stick processors.
+ * Options for {@link gamepadStickPipeline}.
  */
-type GamepadStickPipeline = GamepadStickProcessor & {
+type GamepadStickPipelineOptions = {
   /**
-   * Processors in execution order.
+   * Default geometry for processing methods that support axial and radial modes.
+   * @default "axial"
    */
-  readonly processors: readonly GamepadStickProcessor[];
+  mode?: GamepadStickProcessingMode;
 };
 /**
- * Options for {@link createGamepadDeadzoneProcessor}.
+ * Options for {@link GamepadStickPipeline.deadzone}.
  */
-type GamepadDeadzoneProcessorOptions = {
+type GamepadDeadzoneOptions = {
   /**
-   * Dead zone threshold.
-   * @default 0.1
+   * Geometry for this dead zone, overriding the pipeline default.
    */
-  threshold?: number;
-  /**
-   * Whether to process each component or the vector magnitude.
-   * @default "axial"
-   */
-  mode?: GamepadDeadzoneMode;
+  mode?: GamepadStickProcessingMode;
   /**
    * Whether to remap values outside the dead zone to the full output range.
    * @default false
@@ -61,19 +71,58 @@ type GamepadDeadzoneProcessorOptions = {
   rescale?: boolean;
 };
 /**
- * Options for {@link createGamepadInversionProcessor}.
+ * Options for {@link GamepadStickPipeline.curve}.
  */
-type GamepadInversionProcessorOptions = {
+type GamepadResponseCurveOptions = {
   /**
-   * Whether to invert the horizontal component.
-   * @default false
+   * Geometry for this response curve, overriding the pipeline default.
+   */
+  mode?: GamepadStickProcessingMode;
+};
+/**
+ * Ordered, reusable sequence of stateless stick processors.
+ *
+ * Every configuration method returns a new frozen pipeline and leaves the
+ * current pipeline unchanged.
+ */
+type GamepadStickPipeline = GamepadStickProcessor & {
+  /**
+   * Appends an axial or radial dead zone.
+   *
+   * @param threshold - Dead zone threshold.
+   * @param options - Optional dead zone configuration.
+   * @returns New pipeline containing the dead zone.
    */
-  invertX?: boolean;
+  deadzone(threshold?: number, options?: GamepadDeadzoneOptions): GamepadStickPipeline;
   /**
-   * Whether to invert the vertical component.
-   * @default false
+   * Appends an axial or radial response curve.
+   *
+   * @param curve - Curve used to transform normalized magnitudes.
+   * @param options - Optional response curve configuration.
+   * @returns New pipeline containing the response curve.
+   */
+  curve(curve: GamepadResponseCurve, options?: GamepadResponseCurveOptions): GamepadStickPipeline;
+  /**
+   * Appends component inversion.
+   *
+   * @param axis - Component or components to invert.
+   * @returns New pipeline containing the inversion.
+   */
+  invert(axis: GamepadStickInversionAxis): GamepadStickPipeline;
+  /**
+   * Appends a custom stick transformation.
+   *
+   * @param operation - Pure transformation applied to the current value.
+   * @returns New pipeline containing the transformation.
    */
-  invertY?: boolean;
+  transform(operation: GamepadStickTransform): GamepadStickPipeline;
+  /**
+   * Appends a reusable stick processor, including another pipeline.
+   *
+   * @param processor - Processor to execute next.
+   * @returns New pipeline containing the processor.
+   */
+  pipe(processor: GamepadStickProcessor): GamepadStickPipeline;
 };
 /**
  * Partial binding for a two-dimensional stick action.
@@ -99,29 +148,16 @@ type GamepadStickBindingOptions = {
  */
 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.
+ * Creates an immutable, fluent stick processing pipeline.
  *
- * @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.
+ * The configured mode becomes the default for dead zones and response curves.
+ * Each fluent method returns a new pipeline, so intermediate pipelines remain
+ * reusable. Processor errors are not caught.
  *
- * @param options - Optional inversion configuration.
- * @returns Stateless inversion processor.
+ * @param options - Optional pipeline defaults.
+ * @returns Frozen stick pipeline.
  */
-declare const createGamepadInversionProcessor: (options?: GamepadInversionProcessorOptions) => GamepadStickProcessor;
+declare const gamepadStickPipeline: (options?: GamepadStickPipelineOptions) => GamepadStickPipeline;
 /**
  * Historical stick processing used when no custom pipeline is supplied.
  */
@@ -135,4 +171,4 @@ declare const DEFAULT_GAMEPAD_STICK_PIPELINE: GamepadStickPipeline;
  */
 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 };
+export { DEFAULT_GAMEPAD_STICK_PIPELINE, GamepadDeadzoneOptions, GamepadResponseCurve, GamepadResponseCurveOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickInversionAxis, GamepadStickPipeline, GamepadStickPipelineOptions, GamepadStickProcessingMode, GamepadStickProcessor, GamepadStickTransform, gamepadStickPipeline, resolveGamepadStickBinding };

package/dist/gamepad-stick-processing.js

@@ -1,12 +1,50 @@
 //#region src/gamepad-stick-processing.ts
-const DEFAULT_DEADZONE_PROCESSOR_OPTIONS = {
-	threshold: .1,
-	mode: "axial",
-	rescale: false
+const DEFAULT_GAMEPAD_STICK_PROCESSING_MODE = "axial";
+const DEFAULT_GAMEPAD_DEADZONE_THRESHOLD = .1;
+/**
+* Returns a canonical stick result and preserves the original value when
+* processing produced no change.
+*
+* @param source - Original stick value.
+* @param x - Processed horizontal component.
+* @param y - Processed vertical component.
+* @returns Canonical processed stick value.
+*/
+const createGamepadStickResult = (source, x, y) => {
+	const canonicalX = x === 0 ? 0 : x;
+	const canonicalY = y === 0 ? 0 : y;
+	if (canonicalX === source.x && canonicalY === source.y && !Object.is(source.x, -0) && !Object.is(source.y, -0)) return source;
+	return {
+		x: canonicalX,
+		y: canonicalY
+	};
 };
-const DEFAULT_INVERSION_PROCESSOR_OPTIONS = {
-	invertX: false,
-	invertY: false
+/**
+* Transforms the magnitude of a signed scalar while preserving its sign.
+*
+* @param value - Signed scalar value.
+* @param mapMagnitude - Magnitude transformation.
+* @returns Transformed signed value.
+*/
+const mapGamepadSignedMagnitude = (value, mapMagnitude) => {
+	if (value === 0) return 0;
+	return Math.sign(value) * mapMagnitude(Math.abs(value));
+};
+/**
+* Transforms stick magnitude while preserving vector direction.
+*
+* @param value - Stick value to transform.
+* @param mapMagnitude - Magnitude transformation.
+* @returns Stick with transformed magnitude.
+*/
+const mapGamepadStickMagnitude = (value, mapMagnitude) => {
+	const magnitude = Math.hypot(value.x, value.y);
+	if (magnitude === 0) return createGamepadStickResult(value, 0, 0);
+	const mappedMagnitude = mapMagnitude(magnitude);
+	if (mappedMagnitude === magnitude) return createGamepadStickResult(value, value.x, value.y);
+	if (mappedMagnitude === 0) return createGamepadStickResult(value, 0, 0);
+	const scale = mappedMagnitude / magnitude;
+	return createGamepadStickResult(value, value.x * scale, value.y * scale);
 };
 /**
 * Applies a dead zone and remaps the remaining magnitude to `[0, 1]`.
@@ -20,128 +58,129 @@ const rescaleGamepadDeadzoneMagnitude = (magnitude, threshold) => {
 	return Math.min((magnitude - threshold) / (1 - threshold), 1);
 };
 /**
-* Applies an axial dead zone to one component.
+* Applies a built-in curve to a normalized magnitude.
 *
-* @param value - Signed component value.
-* @param threshold - Dead zone size.
-* @param rescale - Whether to remap the remaining magnitude.
-* @returns Processed signed component.
+* Magnitudes above `1` remain unchanged so response curves do not implicitly
+* clamp or normalize custom processor output.
+*
+* @param magnitude - Non-negative component or vector magnitude.
+* @param curve - Curve to apply.
+* @returns Curved magnitude.
 */
-const applyGamepadAxialDeadzone = (value, threshold, rescale) => {
-	if (value === 0) return 0;
-	const magnitude = Math.abs(value);
-	if (magnitude < threshold) return 0;
-	if (!rescale) return value;
-	const rescaledMagnitude = rescaleGamepadDeadzoneMagnitude(magnitude, threshold);
-	if (rescaledMagnitude === 0) return 0;
-	return Math.sign(value) * rescaledMagnitude;
+const applyGamepadResponseCurve = (magnitude, curve) => {
+	if (magnitude > 1) return magnitude;
+	switch (curve) {
+		case "linear": return magnitude;
+		case "quadratic": return magnitude ** 2;
+		case "cubic": return magnitude ** 3;
+	}
+};
+/**
+* Creates an axial or radial dead zone processor.
+*
+* @param threshold - Dead zone threshold.
+* @param mode - Whether to process components or vector magnitude.
+* @param rescale - Whether to remap values outside the dead zone.
+* @returns Frozen dead zone processor.
+*/
+const createDeadzoneProcessor = (threshold, mode, rescale) => {
+	const mapMagnitude = (magnitude) => {
+		if (magnitude < threshold) return 0;
+		return rescale ? rescaleGamepadDeadzoneMagnitude(magnitude, threshold) : magnitude;
+	};
+	return Object.freeze({ process(value) {
+		if (mode === "axial") return createGamepadStickResult(value, mapGamepadSignedMagnitude(value.x, mapMagnitude), mapGamepadSignedMagnitude(value.y, mapMagnitude));
+		return mapGamepadStickMagnitude(value, mapMagnitude);
+	} });
+};
+/**
+* Creates an axial or radial response curve processor.
+*
+* @param curve - Curve applied to normalized magnitudes.
+* @param mode - Whether to process components or vector magnitude.
+* @returns Frozen response curve processor.
+*/
+const createResponseCurveProcessor = (curve, mode) => {
+	const mapMagnitude = (magnitude) => applyGamepadResponseCurve(magnitude, curve);
+	return Object.freeze({ process(value) {
+		if (mode === "axial") return createGamepadStickResult(value, mapGamepadSignedMagnitude(value.x, mapMagnitude), mapGamepadSignedMagnitude(value.y, mapMagnitude));
+		return mapGamepadStickMagnitude(value, mapMagnitude);
+	} });
 };
 /**
-* Creates an ordered pipeline from stateless stick processors.
+* Creates a processor that inverts selected stick components.
 *
-* The processor list is copied once. Processor errors are not caught, and a
-* processor's result is passed directly to the next processor.
+* @param axis - Component or components to invert.
+* @returns Frozen inversion processor.
+*/
+const createInversionProcessor = (axis) => {
+	const invertX = axis === "x" || axis === "both";
+	const invertY = axis === "y" || axis === "both";
+	return Object.freeze({ process(value) {
+		const x = value.x === 0 ? 0 : invertX ? -value.x : value.x;
+		const y = value.y === 0 ? 0 : invertY ? -value.y : value.y;
+		return createGamepadStickResult(value, x, y);
+	} });
+};
+/**
+* Creates a frozen custom transformation processor.
 *
+* @param operation - Transformation applied to the current pipeline value.
+* @returns Frozen custom processor.
+*/
+const createTransformProcessor = (operation) => {
+	return Object.freeze({ process: operation });
+};
+/**
+* Creates an immutable pipeline over a private processor sequence.
+*
+* @param mode - Default processing mode for new built-in stages.
 * @param processors - Processors in execution order.
-* @returns Reusable stick pipeline.
+* @returns Frozen stick pipeline.
 */
-const createGamepadStickPipeline = (...processors) => {
+const createPipeline = (mode, processors) => {
 	const pipelineProcessors = Object.freeze([...processors]);
+	const append = (processor) => createPipeline(mode, [...pipelineProcessors, processor]);
 	return Object.freeze({
-		processors: pipelineProcessors,
 		process(value) {
 			let processed = value;
 			for (const processor of pipelineProcessors) processed = processor.process(processed);
 			return processed;
+		},
+		deadzone(threshold = DEFAULT_GAMEPAD_DEADZONE_THRESHOLD, options) {
+			return append(createDeadzoneProcessor(threshold, options?.mode ?? mode, options?.rescale ?? false));
+		},
+		curve(curve, options) {
+			return append(createResponseCurveProcessor(curve, options?.mode ?? mode));
+		},
+		invert(axis) {
+			return append(createInversionProcessor(axis));
+		},
+		transform(operation) {
+			return append(createTransformProcessor(operation));
+		},
+		pipe(processor) {
+			return append(processor);
 		}
 	});
 };
 /**
-* Creates an axial or radial dead zone processor.
+* Creates an immutable, fluent stick processing pipeline.
 *
-* @param options - Optional dead zone configuration.
-* @returns Stateless dead zone processor.
-*/
-const createGamepadDeadzoneProcessor = (options) => {
-	const { threshold, mode, rescale } = {
-		...DEFAULT_DEADZONE_PROCESSOR_OPTIONS,
-		...options
-	};
-	return Object.freeze({ process(value) {
-		if (mode === "axial") {
-			const x = applyGamepadAxialDeadzone(value.x, threshold, rescale);
-			const y = applyGamepadAxialDeadzone(value.y, threshold, rescale);
-			if (x === value.x && y === value.y && !Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-			return {
-				x,
-				y
-			};
-		}
-		const magnitude = Math.hypot(value.x, value.y);
-		if (magnitude < threshold) {
-			if (value.x === 0 && value.y === 0 && !Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-			return {
-				x: 0,
-				y: 0
-			};
-		}
-		if (!rescale) {
-			if (!Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-			return {
-				x: value.x === 0 ? 0 : value.x,
-				y: value.y === 0 ? 0 : value.y
-			};
-		}
-		const rescaledMagnitude = rescaleGamepadDeadzoneMagnitude(magnitude, threshold);
-		if (rescaledMagnitude === 0 || magnitude === 0) {
-			if (value.x === 0 && value.y === 0 && !Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-			return {
-				x: 0,
-				y: 0
-			};
-		}
-		const scale = rescaledMagnitude / magnitude;
-		const x = value.x === 0 ? 0 : value.x * scale;
-		const y = value.y === 0 ? 0 : value.y * scale;
-		if (x === value.x && y === value.y && !Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-		return {
-			x,
-			y
-		};
-	} });
-};
-/**
-* Creates a processor that independently inverts stick components.
+* The configured mode becomes the default for dead zones and response curves.
+* Each fluent method returns a new pipeline, so intermediate pipelines remain
+* reusable. Processor errors are not caught.
 *
-* @param options - Optional inversion configuration.
-* @returns Stateless inversion processor.
+* @param options - Optional pipeline defaults.
+* @returns Frozen stick pipeline.
 */
-const createGamepadInversionProcessor = (options) => {
-	const { invertX, invertY } = {
-		...DEFAULT_INVERSION_PROCESSOR_OPTIONS,
-		...options
-	};
-	return Object.freeze({ process(value) {
-		if (!invertX && !invertY) {
-			if (!Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-			return {
-				x: value.x === 0 ? 0 : value.x,
-				y: value.y === 0 ? 0 : value.y
-			};
-		}
-		const x = value.x === 0 ? 0 : invertX ? -value.x : value.x;
-		const y = value.y === 0 ? 0 : invertY ? -value.y : value.y;
-		if (x === value.x && y === value.y && !Object.is(value.x, -0) && !Object.is(value.y, -0)) return value;
-		return {
-			x,
-			y
-		};
-	} });
+const gamepadStickPipeline = (options) => {
+	return createPipeline(options?.mode ?? DEFAULT_GAMEPAD_STICK_PROCESSING_MODE, []);
 };
 /**
 * Historical stick processing used when no custom pipeline is supplied.
 */
-const DEFAULT_GAMEPAD_STICK_PIPELINE = createGamepadStickPipeline(createGamepadDeadzoneProcessor());
+const DEFAULT_GAMEPAD_STICK_PIPELINE = gamepadStickPipeline().deadzone();
 /**
 * Resolves a partial stick binding over an action-specific default.
 *
@@ -157,4 +196,4 @@ const resolveGamepadStickBinding = (defaults, options) => {
 	};
 };
 //#endregion
-export { DEFAULT_GAMEPAD_STICK_PIPELINE, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding };
+export { DEFAULT_GAMEPAD_STICK_PIPELINE, gamepadStickPipeline, resolveGamepadStickBinding };

package/dist/gamepad-transform-controls.js

@@ -162,11 +162,13 @@ var GamepadTransformControls = class extends GamepadControls {
 		this.#handleModeAndAxisButtons(startedButtons);
 		if (startedButtons.has(this.#options.buttonReset)) this.#resetActiveTransform();
 		const controls = this.#controls;
-		if (!controls.enabled || controls.object === void 0) {
+		const object = controls.object;
+		if (!controls.enabled || object === void 0) {
 			this.#endTransform(true);
 			return;
 		}
-		if (this.#ensureValidAxis() === null) {
+		const axis = this.#ensureValidAxis();
+		if (axis === null) {
 			this.#endTransform(true);
 			return;
 		}
@@ -176,8 +178,8 @@ var GamepadTransformControls = class extends GamepadControls {
 			this.#endTransform(false);
 			return;
 		}
-		if (!this.#isTransforming && !this.#startTransform()) return;
-		if (this.#applyCurrentTransform(deltaTime, transform.x, transform.y)) {
+		if (!this.#isTransforming) this.#startTransform(object);
+		if (this.#applyCurrentTransform(object, axis, deltaTime, transform.x, transform.y)) {
 			controls.dispatchEvent({ type: "change" });
 			controls.dispatchEvent({ type: "objectChange" });
 		}
@@ -270,7 +272,7 @@ var GamepadTransformControls = class extends GamepadControls {
 		const current = this.#activeAxisByMode[this.#controls.mode];
 		const currentIndex = current === null ? -1 : axes.indexOf(current);
 		const nextIndex = currentIndex === -1 ? 0 : (currentIndex + direction + axes.length) % axes.length;
-		this.#activeAxisByMode[this.#controls.mode] = axes[nextIndex] ?? null;
+		this.#activeAxisByMode[this.#controls.mode] = axes[nextIndex];
 		this.#ensureValidAxis();
 	}
 	/**
@@ -349,12 +351,10 @@ var GamepadTransformControls = class extends GamepadControls {
 	/**
 	* Starts a TransformControls drag interaction for the active object and axis.
 	*
-	* @returns `true` when a transform interaction was started.
+	* @param object - Object attached to TransformControls for this update.
 	*/
-	#startTransform() {
+	#startTransform(object) {
 		const controls = this.#controls;
-		const object = controls.object;
-		if (object === void 0 || controls.axis === null) return false;
 		this.#captureTransformStart(object);
 		controls.dragging = true;
 		this.#isTransforming = true;
@@ -362,7 +362,6 @@ var GamepadTransformControls = class extends GamepadControls {
 			type: "mouseDown",
 			mode: controls.mode
 		});
-		return true;
 	}
 	/**
 	* Ends an active TransformControls drag interaction.
@@ -435,35 +434,36 @@ var GamepadTransformControls = class extends GamepadControls {
 	/**
 	* Dispatches the current stick input to the active TransformControls mode.
 	*
+	* @param object - Object attached to TransformControls for this update.
+	* @param axis - Valid axis selected for the active mode.
 	* @param deltaTime - Seconds since the last frame.
 	* @param transformX - Horizontal transform input after dead zone processing.
 	* @param transformY - Vertical transform input after dead zone processing.
 	* @returns `true` when the attached object changed.
 	*/
-	#applyCurrentTransform(deltaTime, transformX, transformY) {
+	#applyCurrentTransform(object, axis, deltaTime, transformX, transformY) {
 		switch (this.#controls.mode) {
-			case "translate": return this.#applyTranslate(deltaTime, transformX, transformY);
-			case "rotate": return this.#applyRotate(deltaTime, transformX, transformY);
-			case "scale": return this.#applyScale(deltaTime, transformX, transformY);
+			case "translate": return this.#applyTranslate(object, axis, deltaTime, transformX, transformY);
+			case "rotate": return this.#applyRotate(object, axis, deltaTime, transformX, transformY);
+			case "scale": return this.#applyScale(object, axis, deltaTime, transformX, transformY);
 		}
 	}
 	/**
 	* Applies translation in the selected axis, plane, or screen-facing plane.
 	*
+	* @param object - Object attached to TransformControls for this update.
+	* @param axis - Valid translation axis selected for this update.
 	* @param deltaTime - Seconds since the last frame.
 	* @param transformX - Horizontal transform input after dead zone processing.
 	* @param transformY - Vertical transform input after dead zone processing.
 	* @returns `true` when the attached object moved.
 	*/
-	#applyTranslate(deltaTime, transformX, transformY) {
+	#applyTranslate(object, axis, deltaTime, transformX, transformY) {
 		const controls = this.#controls;
-		const object = controls.object;
-		const axis = controls.axis;
-		if (object === void 0 || axis === null) return false;
 		this.#updateCameraState(object);
 		this.#worldDelta.set(0, 0, 0);
-		const scale = controls.axis === "XYZ" ? "world" : controls.space;
-		const speed = controls.axis === "XYZ" ? this.#options.translateSpeed * deltaTime : (this.#viewSize.x + this.#viewSize.y) / 2 * this.#options.translateSpeed * deltaTime;
+		const scale = axis === "XYZ" ? "world" : controls.space;
+		const speed = axis === "XYZ" ? this.#options.translateSpeed * deltaTime : (this.#viewSize.x + this.#viewSize.y) / 2 * this.#options.translateSpeed * deltaTime;
 		if (axis === "XYZ") {
 			this.#worldDelta.addScaledVector(this.#cameraRight, transformX * this.#viewSize.x * speed);
 			this.#worldDelta.addScaledVector(this.#cameraUp, -transformY * this.#viewSize.y * speed);
@@ -542,16 +542,15 @@ var GamepadTransformControls = class extends GamepadControls {
 	/**
 	* Applies rotation for the selected axis or free-rotation mode.
 	*
+	* @param object - Object attached to TransformControls for this update.
+	* @param axis - Valid rotation axis selected for this update.
 	* @param deltaTime - Seconds since the last frame.
 	* @param transformX - Horizontal transform input after dead zone processing.
 	* @param transformY - Vertical transform input after dead zone processing.
 	* @returns `true` when the attached object rotated.
 	*/
-	#applyRotate(deltaTime, transformX, transformY) {
+	#applyRotate(object, axis, deltaTime, transformX, transformY) {
 		const controls = this.#controls;
-		const object = controls.object;
-		const axis = controls.axis;
-		if (object === void 0 || axis === null) return false;
 		this.#updateCameraState(object);
 		const angleScale = this.#options.rotateSpeed * deltaTime * Math.PI;
 		if (axis === "XYZE") {
@@ -564,11 +563,11 @@ var GamepadTransformControls = class extends GamepadControls {
 		if (axis === "E") {
 			this.#axisWorld.copy(this.#cameraForward).normalize();
 			input = this.#getDominantInput(transformX, -transformY);
-		} else if (axis === "X" || axis === "Y" || axis === "Z") {
+		} else {
 			const space = controls.space;
 			this.#getTransformAxisWorld(axis, space, this.#axisWorld);
 			input = this.#getRotationAxisInput(this.#axisWorld, transformX, transformY);
-		} else return false;
+		}
 		this.#rotationAmount += input * angleScale;
 		const angle = this.#snapRotation(this.#rotationAmount);
 		if (axis !== "E" && controls.space === "local") {
@@ -611,16 +610,15 @@ var GamepadTransformControls = class extends GamepadControls {
 	/**
 	* Applies scale along the selected axis or uniformly across all axes.
 	*
+	* @param object - Object attached to TransformControls for this update.
+	* @param axis - Valid scale axis selected for this update.
 	* @param deltaTime - Seconds since the last frame.
 	* @param transformX - Horizontal transform input after dead zone processing.
 	* @param transformY - Vertical transform input after dead zone processing.
 	* @returns `true` when the attached object scaled.
 	*/
-	#applyScale(deltaTime, transformX, transformY) {
+	#applyScale(object, axis, deltaTime, transformX, transformY) {
 		const controls = this.#controls;
-		const object = controls.object;
-		const axis = controls.axis;
-		if (object === void 0 || axis === null) return false;
 		this.#updateCameraState(object);
 		const input = axis === "XYZ" ? this.#getDominantInput(transformX, -transformY) : this.#getProjectedScaleInput(axis, transformX, transformY);
 		const factor = Math.exp(input * this.#options.scaleSpeed * deltaTime);
@@ -647,7 +645,6 @@ var GamepadTransformControls = class extends GamepadControls {
 	* @returns Signed scale input for the current frame.
 	*/
 	#getProjectedScaleInput(axis, transformX, transformY) {
-		if (axis !== "X" && axis !== "Y" && axis !== "Z") return this.#getDominantInput(transformX, -transformY);
 		this.#getTransformAxisWorld(axis, "local", this.#axisWorld);
 		return this.#getProjectedAxisInput(this.#axisWorld, transformX, transformY, this.#getDominantInput(transformX, -transformY));
 	}
@@ -775,9 +772,7 @@ var GamepadTransformControls = class extends GamepadControls {
 	* @param target - Vector to adjust in place.
 	*/
 	#divideByParentScale(target) {
-		target.x = this.#parentScale.x === 0 ? 0 : target.x / this.#parentScale.x;
-		target.y = this.#parentScale.y === 0 ? 0 : target.y / this.#parentScale.y;
-		target.z = this.#parentScale.z === 0 ? 0 : target.z / this.#parentScale.z;
+		target.divide(this.#parentScale);
 	}
 	/**
 	* Writes a unit axis vector into a target vector.

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 { DEFAULT_GAMEPAD_STICK_PIPELINE, GamepadDeadzoneMode, GamepadDeadzoneProcessorOptions, GamepadInversionProcessorOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickPipeline, GamepadStickProcessor, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
+import { DEFAULT_GAMEPAD_STICK_PIPELINE, GamepadDeadzoneOptions, GamepadResponseCurve, GamepadResponseCurveOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickInversionAxis, GamepadStickPipeline, GamepadStickPipelineOptions, GamepadStickProcessingMode, GamepadStickProcessor, GamepadStickTransform, gamepadStickPipeline, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions } from "./gamepad-input.js";
 import { GamepadControls, GamepadControlsEventMap, GamepadControlsOptions } from "./gamepad-controls.js";
 import { GamepadArcballControls, GamepadArcballControlsOptions } from "./gamepad-arcball-controls.js";
@@ -11,4 +11,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 { DEFAULT_GAMEPAD_STICK_PIPELINE, GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadControlsOptions, GamepadDeadzoneMode, GamepadDeadzoneProcessorOptions, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadInversionProcessorOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickPipeline, GamepadStickProcessor, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding };
+export { DEFAULT_GAMEPAD_STICK_PIPELINE, GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisOptions, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadControlsOptions, GamepadDeadzoneOptions, GamepadDragControls, GamepadDragControlsOptions, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadResponseCurve, GamepadResponseCurveOptions, GamepadStick, GamepadStickBinding, GamepadStickBindingOptions, GamepadStickInversionAxis, GamepadStickPipeline, GamepadStickPipelineOptions, GamepadStickProcessingMode, GamepadStickProcessor, GamepadStickTransform, GamepadTrackballControls, GamepadTrackballControlsOptions, GamepadTransformControls, GamepadTransformControlsOptions, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX, gamepadStickPipeline, resolveGamepadStickBinding };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX } from "./core.js";
-import { DEFAULT_GAMEPAD_STICK_PIPELINE, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
+import { DEFAULT_GAMEPAD_STICK_PIPELINE, gamepadStickPipeline, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadInput } from "./gamepad-input.js";
 import { GamepadControls } from "./gamepad-controls.js";
 import { GamepadArcballControls } from "./gamepad-arcball-controls.js";
@@ -11,4 +11,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 { DEFAULT_GAMEPAD_STICK_PIPELINE, GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadControls, GamepadDragControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadInput, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls, GamepadTransformControls, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX, createGamepadDeadzoneProcessor, createGamepadInversionProcessor, createGamepadStickPipeline, resolveGamepadStickBinding };
+export { DEFAULT_GAMEPAD_STICK_PIPELINE, GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadControls, GamepadDragControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadInput, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls, GamepadTransformControls, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX, gamepadStickPipeline, resolveGamepadStickBinding };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {
     "name": "Kasnix",
@@ -46,16 +46,19 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.4",
+    "@biomejs/biome": "2.5.6",
     "@commitlint/cli": "21.2.1",
     "@commitlint/config-conventional": "21.2.0",
     "@commitlint/types": "21.2.0",
     "@types/node": "24.13.3",
     "@types/three": "0.184.0",
+    "@vitest/coverage-v8": "4.1.10",
     "husky": "9.1.7",
+    "jsdom": "29.1.1",
     "three": "0.184.0",
-    "tsdown": "0.22.8",
-    "typescript": "7.0.2"
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
     "@types/three": ">=0.184.0",
@@ -70,6 +73,9 @@
     "lint:write": "biome lint --write",
     "check-all": "biome check",
     "write-all": "biome check --write",
-    "check-ci": "biome ci"
+    "check-ci": "biome ci",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
 }