three-gamepad-controls 0.2.0 → 0.3.1

package/README.md

@@ -39,3 +39,4 @@ 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.
 - [GamepadOrbitControls](./docs/gamepad-orbit-controls.md) — Gamepad support for `OrbitControls`.
+- [GamepadPointerLockControls](./docs/gamepad-pointer-lock-controls.md) — Gamepad support for `PointerLockControls`.

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

@@ -5,8 +5,7 @@ import { OrbitControls } from "three/addons/controls/OrbitControls.js";
 /**
  * Configuration for {@link GamepadOrbitControls}.
  *
- * Every property has a sensible default (see {@link DEFAULT_ORBIT_OPTIONS}),
- * so you only need to pass the properties you want to override.
+ * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
 type GamepadOrbitControlsOptions = {
   /**

package/dist/gamepad-pointer-lock-controls.d.ts

@@ -0,0 +1,71 @@
+import { GamepadControls } from "./gamepad-controls.js";
+import { PointerLockControls } from "three/addons/controls/PointerLockControls.js";
+
+//#region src/gamepad-pointer-lock-controls.d.ts
+/**
+ * Configuration for {@link GamepadPointerLockControls}.
+ *
+ * Every property has a sensible default, so you only need to pass the properties you want to override.
+ */
+type GamepadPointerLockControlsOptions = {
+  /**
+   * Camera movement speed in world units per second at full stick deflection.
+   * @default 5.0
+   */
+  moveSpeed: number;
+  /**
+   * Multiplier on look rotation speed (combined with `PointerLockControls.pointerSpeed`).
+   * @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;
+};
+/**
+ * Adds gamepad support to Three.js `PointerLockControls`.
+ *
+ * Gamepad input is fully independent of pointer lock state. When the pointer
+ * IS locked, mouse and gamepad look inputs are additive.
+ * Bindings and speeds are configurable via {@link GamepadPointerLockControlsOptions}.
+ */
+declare class GamepadPointerLockControls extends GamepadControls {
+  #private;
+  /**
+   * @param controls - A Three.js `PointerLockControls` instance.
+   * @param options - Optional overrides for the default behavior.
+   *                  Any property not provided falls back to its default value.
+   */
+  constructor(controls: PointerLockControls, options?: Partial<GamepadPointerLockControlsOptions>);
+  /**
+   * Maps the current gamepad state to `PointerLockControls` movement 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 { GamepadPointerLockControls, GamepadPointerLockControlsOptions };

package/dist/gamepad-pointer-lock-controls.js

@@ -0,0 +1,77 @@
+import { GAMEPAD_AXIS } from "./core.js";
+import { GamepadControls } from "./gamepad-controls.js";
+import { Euler } from "three";
+//#region src/gamepad-pointer-lock-controls.ts
+/**
+* Default options merged in the constructor when no explicit configuration is provided.
+*/
+const DEFAULT_POINTER_LOCK_OPTIONS = {
+	moveSpeed: 5,
+	lookSpeed: 1,
+	deadzone: .1,
+	axisMoveForward: GAMEPAD_AXIS.LeftY,
+	axisMoveRight: GAMEPAD_AXIS.LeftX,
+	axisLookX: GAMEPAD_AXIS.RightX,
+	axisLookY: GAMEPAD_AXIS.RightY
+};
+/**
+* Adds gamepad support to Three.js `PointerLockControls`.
+*
+* Gamepad input is fully independent of pointer lock state. When the pointer
+* IS locked, mouse and gamepad look inputs are additive.
+* Bindings and speeds are configurable via {@link GamepadPointerLockControlsOptions}.
+*/
+var GamepadPointerLockControls = class extends GamepadControls {
+	#controls;
+	#options;
+	#euler;
+	/**
+	* @param controls - A Three.js `PointerLockControls` 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_POINTER_LOCK_OPTIONS,
+			...options
+		};
+		this.#euler = new Euler(0, 0, 0, "YXZ");
+	}
+	/**
+	* Maps the current gamepad state to `PointerLockControls` movement 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 } = this.#options;
+		const fwd = this.#applyDeadzone(gamepad.axes[axisMoveForward] ?? 0, deadzone);
+		const strafe = this.#applyDeadzone(gamepad.axes[axisMoveRight] ?? 0, deadzone);
+		if (fwd !== 0) this.#controls.moveForward(-fwd * moveSpeed * deltaTime);
+		if (strafe !== 0) this.#controls.moveRight(strafe * moveSpeed * deltaTime);
+		const lookX = this.#applyDeadzone(gamepad.axes[axisLookX] ?? 0, deadzone);
+		const lookY = this.#applyDeadzone(gamepad.axes[axisLookY] ?? 0, deadzone);
+		if (lookX !== 0 || lookY !== 0) {
+			const camera = this.#controls.object;
+			const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
+			this.#euler.setFromQuaternion(camera.quaternion);
+			this.#euler.y -= lookX * scale;
+			this.#euler.x -= lookY * scale;
+			this.#euler.x = Math.max(Math.PI / 2 - this.#controls.maxPolarAngle, Math.min(Math.PI / 2 - this.#controls.minPolarAngle, this.#euler.x));
+			camera.quaternion.setFromEuler(this.#euler);
+		}
+	}
+	/**
+	* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
+	*
+	* @param value - Raw axis 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 { GamepadPointerLockControls };

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -2,7 +2,7 @@
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
   "author": "Kasnix",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/luckasnix/three-gamepad-controls.git"
@@ -35,15 +35,15 @@
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.15",
-    "@commitlint/cli": "21.0.1",
-    "@commitlint/config-conventional": "21.0.1",
+    "@biomejs/biome": "2.4.16",
+    "@commitlint/cli": "21.0.2",
+    "@commitlint/config-conventional": "21.0.2",
     "@commitlint/types": "21.0.1",
     "@types/node": "24.12.4",
     "@types/three": "0.184.1",
     "husky": "9.1.7",
     "three": "0.184.0",
-    "tsdown": "0.22.0",
+    "tsdown": "0.22.1",
     "typescript": "6.0.3"
   },
   "peerDependencies": {