three-gamepad-controls 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,40 @@
 
 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).
 
+## Installation
+
+npm:
+
+```bash
+npm i three-gamepad-controls
+```
+
+pnpm:
+
+```bash
+pnpm add three-gamepad-controls
+```
+
+Yarn:
+
+```bash
+yarn add three-gamepad-controls
+```
+
+Deno:
+
+```bash
+deno add npm:three-gamepad-controls
+```
+
+Bun:
+
+```bash
+bun add three-gamepad-controls
+```
+
 ## Documentation
 
 - [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`.

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

@@ -0,0 +1,86 @@
+import { GamepadControls } from "./gamepad-controls.js";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+
+//#region src/gamepad-orbit-controls.d.ts
+/**
+ * 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.
+ */
+type GamepadOrbitControlsOptions = {
+  /**
+   * Multiplier on orbit rotation speed.
+   * @default 1.0
+   */
+  rotateSpeed: number;
+  /**
+   * Multiplier on pan speed.
+   * @default 1.0
+   */
+  panSpeed: number;
+  /**
+   * Multiplier on zoom (dolly) speed.
+   * @default 1.0
+   */
+  zoomSpeed: number;
+  /**
+   * Axis dead zone threshold in the range `[0, 1]`.
+   * @default 0.1
+   */
+  deadzone: number;
+  /**
+   * Axis index for **horizontal** orbit rotation.
+   * @default 0 — Left stick X
+   */
+  axisRotateX: number;
+  /**
+   * Axis index for **vertical** orbit 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
+   */
+  buttonDollyIn: number;
+  /**
+   * Button index for zooming **out** (analog trigger value used for proportional zoom).
+   * @default 7 — Right trigger
+   */
+  buttonDollyOut: number;
+};
+/**
+ * Adds gamepad support to Three.js `OrbitControls`.
+ *
+ * Call `update()` inside the render loop **before** `OrbitControls.update()`.
+ * Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
+ */
+declare class GamepadOrbitControls extends GamepadControls {
+  #private;
+  /**
+   * @param controls - A Three.js `OrbitControls` instance.
+   * @param options - Optional overrides for the default behavior.
+   *                  Any property not provided falls back to its default value.
+   */
+  constructor(controls: OrbitControls, options?: Partial<GamepadOrbitControlsOptions>);
+  /**
+   * Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
+   *
+   * @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 { GamepadOrbitControls, GamepadOrbitControlsOptions };

package/dist/gamepad-orbit-controls.js

@@ -0,0 +1,72 @@
+import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
+import { GamepadControls } from "./gamepad-controls.js";
+//#region src/gamepad-orbit-controls.ts
+/**
+* Default options merged in the constructor when no explicit configuration is provided.
+*/
+const DEFAULT_ORBIT_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,
+	buttonDollyIn: GAMEPAD_BUTTON.LeftTrigger,
+	buttonDollyOut: GAMEPAD_BUTTON.RightTrigger
+};
+/**
+* Adds gamepad support to Three.js `OrbitControls`.
+*
+* Call `update()` inside the render loop **before** `OrbitControls.update()`.
+* Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
+*/
+var GamepadOrbitControls = class extends GamepadControls {
+	#controls;
+	#options;
+	/**
+	* @param controls - A Three.js `OrbitControls` 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_ORBIT_OPTIONS,
+			...options
+		};
+	}
+	/**
+	* Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
+	*
+	* @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, buttonDollyIn, buttonDollyOut } = this.#options;
+		const rotX = this.#applyDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
+		const rotY = this.#applyDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
+		if (rotX !== 0) this.#controls.rotateLeft(rotX * rotateSpeed * deltaTime * Math.PI);
+		if (rotY !== 0) this.#controls.rotateUp(rotY * rotateSpeed * deltaTime * Math.PI);
+		const panX = this.#applyDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone);
+		const panY = this.#applyDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone);
+		if (panX !== 0 || panY !== 0) this.#controls.pan(panX * panSpeed * deltaTime * 500, panY * panSpeed * deltaTime * 500);
+		const triggerIn = gamepad.buttons[buttonDollyIn]?.value ?? 0;
+		const triggerOut = gamepad.buttons[buttonDollyOut]?.value ?? 0;
+		if (triggerIn > deadzone) this.#controls.dollyIn(1 + zoomSpeed * triggerIn * deltaTime);
+		if (triggerOut > deadzone) this.#controls.dollyOut(1 + zoomSpeed * triggerOut * 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 { GamepadOrbitControls };

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

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