three-gamepad-controls 0.5.0 → 0.7.0

package/README.md

@@ -38,7 +38,9 @@ bun add three-gamepad-controls
 
 - [Core](./docs/core.md) — The fundamental building blocks.
 - [GamepadControls](./docs/gamepad-controls.md) — Abstract base class for custom gamepad controls.
+- [GamepadFirstPersonControls](./docs/gamepad-first-person-controls.md) — Gamepad support for `FirstPersonControls`.
 - [GamepadFlyControls](./docs/gamepad-fly-controls.md) — Gamepad support for `FlyControls`.
 - [GamepadMapControls](./docs/gamepad-map-controls.md) — Gamepad support for `MapControls`.
 - [GamepadOrbitControls](./docs/gamepad-orbit-controls.md) — Gamepad support for `OrbitControls`.
 - [GamepadPointerLockControls](./docs/gamepad-pointer-lock-controls.md) — Gamepad support for `PointerLockControls`.
+- [GamepadTrackballControls](./docs/gamepad-trackball-controls.md) — Gamepad support for `TrackballControls`.

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

@@ -0,0 +1,81 @@
+import { GamepadControls } from "./gamepad-controls.js";
+import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.js";
+
+//#region src/gamepad-first-person-controls.d.ts
+/**
+ * Configuration for {@link GamepadFirstPersonControls}.
+ *
+ * Every property has a sensible default, so you only need to pass the properties you want to override.
+ */
+type GamepadFirstPersonControlsOptions = {
+  /**
+   * Multiplier on `FirstPersonControls.movementSpeed` for translation.
+   * @default 1.0
+   */
+  moveSpeed: number;
+  /**
+   * Multiplier on `FirstPersonControls.lookSpeed` for camera look.
+   * @default 1.0
+   */
+  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
+   */
+  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;
+  /**
+   * Button index for **moving up** (analog trigger value used for proportional speed).
+   * @default 6 - Left trigger
+   */
+  buttonMoveUp: number;
+  /**
+   * Button index for **moving down** (analog trigger value used for proportional speed).
+   * @default 7 - Right trigger
+   */
+  buttonMoveDown: number;
+};
+/**
+ * Adds gamepad support to Three.js `FirstPersonControls`.
+ *
+ * Gamepad input is additive with keyboard/mouse input - call
+ * `gamepadControls.update(delta)` before `controls.update(delta)` each frame.
+ * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
+ */
+declare class GamepadFirstPersonControls extends GamepadControls {
+  #private;
+  /**
+   * @param controls - A Three.js `FirstPersonControls` instance.
+   * @param options - Optional overrides for the default behavior.
+   *                  Any property not provided falls back to its default value.
+   */
+  constructor(controls: FirstPersonControls, options?: Partial<GamepadFirstPersonControlsOptions>);
+  /**
+   * Maps the current gamepad state to `FirstPersonControls` translation and look.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   * @param gamepad - Fresh gamepad snapshot provided by the base class.
+   */
+  protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
+}
+//#endregion
+export { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions };

package/dist/gamepad-first-person-controls.js

@@ -0,0 +1,124 @@
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { GamepadControls } from "./gamepad-controls.js";
+import { MathUtils, Spherical, Vector3 } from "three";
+//#region src/gamepad-first-person-controls.ts
+/**
+* Default options merged in the constructor when no explicit configuration is provided.
+*/
+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,
+	buttonMoveUp: GAMEPAD_BUTTON.LeftTrigger,
+	buttonMoveDown: GAMEPAD_BUTTON.RightTrigger
+};
+const LOOK_SPEED_SCALE = 36e3;
+/**
+* Adds gamepad support to Three.js `FirstPersonControls`.
+*
+* Gamepad input is additive with keyboard/mouse input - call
+* `gamepadControls.update(delta)` before `controls.update(delta)` each frame.
+* Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
+*/
+var GamepadFirstPersonControls = class extends GamepadControls {
+	#controls;
+	#options;
+	#lookDirection;
+	#spherical;
+	#targetPosition;
+	/**
+	* @param controls - A Three.js `FirstPersonControls` instance.
+	* @param options - Optional overrides for the default behavior.
+	*                  Any property not provided falls back to its default value.
+	*/
+	constructor(controls, options) {
+		super();
+		this.#controls = controls;
+		this.#options = {
+			...DEFAULT_FIRST_PERSON_OPTIONS,
+			...options
+		};
+		this.#lookDirection = new Vector3();
+		this.#spherical = new Spherical();
+		this.#targetPosition = new Vector3();
+	}
+	/**
+	* Maps the current gamepad state to `FirstPersonControls` translation and look.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot provided by the base class.
+	*/
+	onUpdate(deltaTime, gamepad) {
+		const { moveSpeed, lookSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonMoveUp, buttonMoveDown } = this.#options;
+		this.#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown);
+		this.#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY);
+	}
+	#applyMovement(deltaTime, gamepad, moveSpeed, deadzone, axisMoveForward, axisMoveRight, buttonMoveUp, buttonMoveDown) {
+		const controls = this.#controls;
+		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
+		const forward = this.#applyDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
+		if (forward !== 0) {
+			let distance = forward * moveMult;
+			if (forward < 0 && controls.heightSpeed) {
+				const heightDelta = MathUtils.clamp(controls.object.position.y, controls.heightMin, controls.heightMax) - controls.heightMin;
+				distance -= -forward * deltaTime * heightDelta * controls.heightCoef * moveSpeed;
+			}
+			controls.object.translateZ(distance);
+		}
+		const strafe = this.#applyDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		if (strafe !== 0) controls.object.translateX(strafe * moveMult);
+		const up = gamepad.buttons[buttonMoveUp]?.value ?? 0;
+		const down = gamepad.buttons[buttonMoveDown]?.value ?? 0;
+		if (up > deadzone) controls.object.translateY(up * moveMult);
+		if (down > deadzone) controls.object.translateY(-down * moveMult);
+	}
+	#applyLook(deltaTime, gamepad, lookSpeed, deadzone, axisLookX, axisLookY) {
+		const lookX = this.#applyDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
+		const lookY = this.#applyDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
+		if (lookX === 0 && lookY === 0) return;
+		const controls = this.#controls;
+		const actualLookSpeed = controls.lookSpeed * lookSpeed * deltaTime * LOOK_SPEED_SCALE;
+		let { lat, lon } = this.#getOrientation();
+		let verticalLookRatio = 1;
+		const verticalRange = controls.verticalMax - controls.verticalMin;
+		if (controls.constrainVertical && verticalRange !== 0) verticalLookRatio = Math.PI / verticalRange;
+		lon -= lookX * actualLookSpeed;
+		if (controls.lookVertical) lat -= lookY * actualLookSpeed * verticalLookRatio;
+		lat = Math.max(-85, Math.min(85, lat));
+		let phi = MathUtils.degToRad(90 - lat);
+		const theta = MathUtils.degToRad(lon);
+		if (controls.constrainVertical) phi = MathUtils.mapLinear(phi, 0, Math.PI, controls.verticalMin, controls.verticalMax);
+		this.#targetPosition.setFromSphericalCoords(1, phi, theta).add(controls.object.position);
+		controls.object.lookAt(this.#targetPosition);
+		controls._lat = lat;
+		controls._lon = lon;
+	}
+	#getOrientation() {
+		const { _lat, _lon } = this.#controls;
+		if (Number.isFinite(_lat) && Number.isFinite(_lon)) return {
+			lat: _lat,
+			lon: _lon
+		};
+		this.#lookDirection.set(0, 0, -1).applyQuaternion(this.#controls.object.quaternion);
+		this.#spherical.setFromVector3(this.#lookDirection);
+		return {
+			lat: 90 - MathUtils.radToDeg(this.#spherical.phi),
+			lon: MathUtils.radToDeg(this.#spherical.theta)
+		};
+	}
+	/**
+	* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
+	*
+	* @param value - Raw axis or trigger value, typically in `[-1, 1]`.
+	* @param threshold - Dead zone size; values below this magnitude are zeroed.
+	*/
+	#applyDeadzone(value, threshold) {
+		return Math.abs(value) < threshold ? 0 : value;
+	}
+};
+//#endregion
+export { GamepadFirstPersonControls };

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

@@ -0,0 +1,85 @@
+import { GamepadControls } from "./gamepad-controls.js";
+import { TrackballControls } from "three/addons/controls/TrackballControls.js";
+
+//#region src/gamepad-trackball-controls.d.ts
+/**
+ * Configuration for {@link GamepadTrackballControls}.
+ *
+ * Every property has a sensible default, so you only need to pass the properties you want to override.
+ */
+type GamepadTrackballControlsOptions = {
+  /**
+   * Multiplier on `TrackballControls.rotateSpeed` for rotation.
+   * @default 1.0
+   */
+  rotateSpeed: number;
+  /**
+   * Multiplier on `TrackballControls.panSpeed` for panning.
+   * @default 1.0
+   */
+  panSpeed: number;
+  /**
+   * Multiplier on `TrackballControls.zoomSpeed` for zooming.
+   * @default 1.0
+   */
+  zoomSpeed: number;
+  /**
+   * Axis dead zone threshold in the range `[0, 1]`.
+   * @default 0.1
+   */
+  deadzone: number;
+  /**
+   * Axis index for **horizontal** trackball rotation.
+   * @default 0 - Left stick X
+   */
+  axisRotateX: number;
+  /**
+   * Axis index for **vertical** trackball rotation.
+   * @default 1 - Left stick Y
+   */
+  axisRotateY: number;
+  /**
+   * Axis index for **horizontal** panning.
+   * @default 2 - Right stick X
+   */
+  axisPanX: number;
+  /**
+   * Axis index for **vertical** panning.
+   * @default 3 - Right stick Y
+   */
+  axisPanY: number;
+  /**
+   * Button index for zooming **in** (analog trigger value used for proportional zoom).
+   * @default 6 - Left trigger
+   */
+  buttonZoomIn: number;
+  /**
+   * Button index for zooming **out** (analog trigger value used for proportional zoom).
+   * @default 7 - Right trigger
+   */
+  buttonZoomOut: number;
+};
+/**
+ * Adds gamepad support to Three.js `TrackballControls`.
+ *
+ * Call `update()` inside the render loop **before** `TrackballControls.update()`.
+ * Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+ */
+declare class GamepadTrackballControls extends GamepadControls {
+  #private;
+  /**
+   * @param controls - A Three.js `TrackballControls` instance.
+   * @param options - Optional overrides for the default behavior.
+   *                  Any property not provided falls back to its default value.
+   */
+  constructor(controls: TrackballControls, options?: Partial<GamepadTrackballControlsOptions>);
+  /**
+   * Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   * @param gamepad - Fresh gamepad snapshot provided by the base class.
+   */
+  protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
+}
+//#endregion
+export { GamepadTrackballControls, GamepadTrackballControlsOptions };

package/dist/gamepad-trackball-controls.js

@@ -0,0 +1,102 @@
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { GamepadControls } from "./gamepad-controls.js";
+//#region src/gamepad-trackball-controls.ts
+/**
+* Default options merged in the constructor when no explicit configuration is provided.
+*/
+const DEFAULT_TRACKBALL_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,
+	buttonZoomIn: GAMEPAD_BUTTON.LeftTrigger,
+	buttonZoomOut: GAMEPAD_BUTTON.RightTrigger
+};
+/**
+* Adds gamepad support to Three.js `TrackballControls`.
+*
+* Call `update()` inside the render loop **before** `TrackballControls.update()`.
+* Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+*/
+var GamepadTrackballControls = class extends GamepadControls {
+	#controls;
+	#options;
+	/**
+	* @param controls - A Three.js `TrackballControls` instance.
+	* @param options - Optional overrides for the default behavior.
+	*                  Any property not provided falls back to its default value.
+	*/
+	constructor(controls, options) {
+		super();
+		this.#controls = controls;
+		this.#options = {
+			...DEFAULT_TRACKBALL_OPTIONS,
+			...options
+		};
+	}
+	/**
+	* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot provided by the base class.
+	*/
+	onUpdate(deltaTime, gamepad) {
+		const { rotateSpeed, panSpeed, zoomSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut } = this.#options;
+		this.#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY);
+		this.#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY);
+		this.#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
+	}
+	#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
+		const controls = this.#controls;
+		if (controls.noRotate) {
+			controls._movePrev.copy(controls._moveCurr);
+			controls._lastAngle = 0;
+			return;
+		}
+		const rotX = this.#applyDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
+		const rotY = this.#applyDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
+		if (rotX === 0 && rotY === 0) return;
+		const scale = rotateSpeed * deltaTime * Math.PI;
+		controls._moveCurr.x += rotX * scale;
+		controls._moveCurr.y += -rotY * scale;
+	}
+	#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY) {
+		const controls = this.#controls;
+		if (controls.noPan) {
+			controls._panStart.copy(controls._panEnd);
+			return;
+		}
+		const panX = this.#applyDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone);
+		const panY = this.#applyDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone);
+		if (panX === 0 && panY === 0) return;
+		const scale = panSpeed * deltaTime;
+		controls._panEnd.x += panX * scale;
+		controls._panEnd.y += panY * scale;
+	}
+	#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
+		const controls = this.#controls;
+		if (controls.noZoom) {
+			controls._zoomStart.copy(controls._zoomEnd);
+			return;
+		}
+		const triggerIn = gamepad.buttons[buttonZoomIn]?.value ?? 0;
+		const triggerOut = gamepad.buttons[buttonZoomOut]?.value ?? 0;
+		if (triggerIn <= deadzone && triggerOut <= deadzone) return;
+		controls._zoomEnd.y += (triggerOut - triggerIn) * zoomSpeed * deltaTime;
+	}
+	/**
+	* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
+	*
+	* @param value - Raw axis or trigger value, typically in `[-1, 1]`.
+	* @param threshold - Dead zone size; values below this magnitude are zeroed.
+	*/
+	#applyDeadzone(value, threshold) {
+		return Math.abs(value) < threshold ? 0 : value;
+	}
+};
+//#endregion
+export { GamepadTrackballControls };

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue } from "./core.js";
 import { GamepadControls, GamepadControlsEventMap } from "./gamepad-controls.js";
+import { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions } from "./gamepad-first-person-controls.js";
 import { GamepadFlyControls, GamepadFlyControlsOptions } from "./gamepad-fly-controls.js";
 import { GamepadOrbitControls, GamepadOrbitControlsOptions } from "./gamepad-orbit-controls.js";
 import { GamepadMapControls } from "./gamepad-map-controls.js";
 import { GamepadPointerLockControls, GamepadPointerLockControlsOptions } from "./gamepad-pointer-lock-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadFlyControls, GamepadFlyControlsOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions };
+import { GamepadTrackballControls, GamepadTrackballControlsOptions } from "./gamepad-trackball-controls.js";
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadTrackballControls, GamepadTrackballControlsOptions };

package/dist/index.js

@@ -1,7 +1,9 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadFirstPersonControls } from "./gamepad-first-person-controls.js";
 import { GamepadFlyControls } from "./gamepad-fly-controls.js";
 import { GamepadOrbitControls } from "./gamepad-orbit-controls.js";
 import { GamepadMapControls } from "./gamepad-map-controls.js";
 import { GamepadPointerLockControls } from "./gamepad-pointer-lock-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadControls, GamepadFlyControls, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls };
+import { GamepadTrackballControls } from "./gamepad-trackball-controls.js";
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls };

package/package.json

@@ -2,7 +2,7 @@
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
   "author": "Kasnix",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/luckasnix/three-gamepad-controls.git"