three-gamepad-controls 0.3.1 → 0.4.0

package/README.md

@@ -38,5 +38,6 @@ 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.
+- [GamepadFlyControls](./docs/gamepad-fly-controls.md) — Gamepad support for `FlyControls`.
 - [GamepadOrbitControls](./docs/gamepad-orbit-controls.md) — Gamepad support for `OrbitControls`.
 - [GamepadPointerLockControls](./docs/gamepad-pointer-lock-controls.md) — Gamepad support for `PointerLockControls`.

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

@@ -0,0 +1,91 @@
+import { GamepadControls } from "./gamepad-controls.js";
+import { FlyControls } from "three/addons/controls/FlyControls.js";
+
+//#region src/gamepad-fly-controls.d.ts
+/**
+ * Configuration for {@link GamepadFlyControls}.
+ *
+ * Every property has a sensible default, so you only need to pass the properties you want to override.
+ */
+type GamepadFlyControlsOptions = {
+  /**
+   * Multiplier on `FlyControls.movementSpeed` for translation.
+   * @default 1.0
+   */
+  moveSpeed: number;
+  /**
+   * Multiplier on `FlyControls.rollSpeed` for rotation.
+   * @default 1.0
+   */
+  rotateSpeed: 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 **rolling left**.
+   * @default 4 — Left shoulder
+   */
+  buttonRollLeft: number;
+  /**
+   * Button index for **rolling right**.
+   * @default 5 — Right shoulder
+   */
+  buttonRollRight: 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 full 6DOF gamepad support to Three.js `FlyControls`.
+ *
+ * Gamepad input is additive with keyboard/mouse input — call both
+ * `gamepadControls.update(delta)` and `controls.update(delta)` each frame.
+ * Bindings and speeds are configurable via {@link GamepadFlyControlsOptions}.
+ */
+declare class GamepadFlyControls extends GamepadControls {
+  #private;
+  /**
+   * @param controls - A Three.js `FlyControls` instance.
+   * @param options - Optional overrides for the default behavior.
+   *                  Any property not provided falls back to its default value.
+   */
+  constructor(controls: FlyControls, options?: Partial<GamepadFlyControlsOptions>);
+  /**
+   * Maps the current gamepad state to `FlyControls` translation and rotation.
+   *
+   * @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 { GamepadFlyControls, GamepadFlyControlsOptions };

package/dist/gamepad-fly-controls.js

@@ -0,0 +1,83 @@
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { GamepadControls } from "./gamepad-controls.js";
+import { Quaternion } from "three";
+//#region src/gamepad-fly-controls.ts
+/**
+* Default options merged in the constructor when no explicit configuration is provided.
+*/
+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,
+	buttonRollLeft: GAMEPAD_BUTTON.LeftShoulder,
+	buttonRollRight: GAMEPAD_BUTTON.RightShoulder,
+	buttonMoveUp: GAMEPAD_BUTTON.LeftTrigger,
+	buttonMoveDown: GAMEPAD_BUTTON.RightTrigger
+};
+/**
+* Adds full 6DOF gamepad support to Three.js `FlyControls`.
+*
+* Gamepad input is additive with keyboard/mouse input — call both
+* `gamepadControls.update(delta)` and `controls.update(delta)` each frame.
+* Bindings and speeds are configurable via {@link GamepadFlyControlsOptions}.
+*/
+var GamepadFlyControls = class extends GamepadControls {
+	#controls;
+	#options;
+	#tmpQuaternion;
+	/**
+	* @param controls - A Three.js `FlyControls` 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_FLY_OPTIONS,
+			...options
+		};
+		this.#tmpQuaternion = new Quaternion();
+	}
+	/**
+	* Maps the current gamepad state to `FlyControls` translation and rotation.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	* @param gamepad - Fresh gamepad snapshot provided by the base class.
+	*/
+	onUpdate(deltaTime, gamepad) {
+		const { moveSpeed, rotateSpeed, deadzone, axisMoveForward, axisMoveRight, axisLookX, axisLookY, buttonRollLeft, buttonRollRight, buttonMoveUp, buttonMoveDown } = this.#options;
+		const moveMult = deltaTime * this.#controls.movementSpeed * moveSpeed;
+		const fwd = this.#applyDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
+		if (fwd !== 0) this.#controls.object.translateZ(fwd * moveMult);
+		const strafe = this.#applyDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		if (strafe !== 0) this.#controls.object.translateX(strafe * moveMult);
+		const up = gamepad.buttons[buttonMoveUp]?.value ?? 0;
+		const down = gamepad.buttons[buttonMoveDown]?.value ?? 0;
+		if (up > deadzone) this.#controls.object.translateY(up * moveMult);
+		if (down > deadzone) this.#controls.object.translateY(-down * moveMult);
+		const rotMult = deltaTime * this.#controls.rollSpeed * rotateSpeed;
+		const pitch = -this.#applyDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
+		const yaw = -this.#applyDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
+		const roll = (gamepad.buttons[buttonRollLeft]?.pressed ? 1 : 0) - (gamepad.buttons[buttonRollRight]?.pressed ? 1 : 0);
+		if (pitch !== 0 || yaw !== 0 || roll !== 0) {
+			this.#tmpQuaternion.set(pitch * rotMult, yaw * rotMult, roll * rotMult, 1).normalize();
+			this.#controls.object.quaternion.multiply(this.#tmpQuaternion);
+		}
+	}
+	/**
+	* 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 { GamepadFlyControls };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue } from "./core.js";
 import { GamepadControls, GamepadControlsEventMap } from "./gamepad-controls.js";
+import { GamepadFlyControls, GamepadFlyControlsOptions } from "./gamepad-fly-controls.js";
 import { GamepadOrbitControls, GamepadOrbitControlsOptions } from "./gamepad-orbit-controls.js";
 import { GamepadPointerLockControls, GamepadPointerLockControlsOptions } from "./gamepad-pointer-lock-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadFlyControls, GamepadFlyControlsOptions, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { GamepadFlyControls } from "./gamepad-fly-controls.js";
 import { GamepadOrbitControls } from "./gamepad-orbit-controls.js";
 import { GamepadPointerLockControls } from "./gamepad-pointer-lock-controls.js";
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadControls, GamepadOrbitControls, GamepadPointerLockControls };
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadControls, GamepadFlyControls, GamepadOrbitControls, GamepadPointerLockControls };

package/package.json

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