three-gamepad-controls 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Alves Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# Three.js Gamepad Controls
+
+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).
+
+## Documentation
+
+- [Core](./docs/core.md) — The fundamental building blocks.
+- [GamepadControls](./docs/gamepad-controls.md) — Abstract base class for custom gamepad controls.

package/dist/core.d.ts

@@ -0,0 +1,52 @@
+//#region src/core.d.ts
+/**
+ * Button indices for the W3C Standard Gamepad mapping.
+ * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
+ */
+declare const GAMEPAD_BUTTON: {
+  readonly South: 0;
+  readonly East: 1;
+  readonly West: 2;
+  readonly North: 3;
+  readonly LeftShoulder: 4;
+  readonly RightShoulder: 5;
+  readonly LeftTrigger: 6;
+  readonly RightTrigger: 7;
+  readonly Select: 8;
+  readonly Start: 9;
+  readonly LeftStick: 10;
+  readonly RightStick: 11;
+  readonly DPadUp: 12;
+  readonly DPadDown: 13;
+  readonly DPadLeft: 14;
+  readonly DPadRight: 15;
+  readonly Home: 16;
+};
+/**
+ * Axis indices for the W3C Standard Gamepad mapping.
+ * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
+ */
+declare const GAMEPAD_AXIS: {
+  readonly LeftX: 0;
+  readonly LeftY: 1;
+  readonly RightX: 2;
+  readonly RightY: 3;
+};
+/**
+ * Union type of all valid {@link GAMEPAD_BUTTON} keys.
+ */
+type GamepadButtonKey = keyof typeof GAMEPAD_BUTTON;
+/**
+ * Union type of all valid {@link GAMEPAD_BUTTON} values.
+ */
+type GamepadButtonValue = (typeof GAMEPAD_BUTTON)[keyof typeof GAMEPAD_BUTTON];
+/**
+ * Union type of all valid {@link GAMEPAD_AXIS} keys.
+ */
+type GamepadAxisKey = keyof typeof GAMEPAD_AXIS;
+/**
+ * Union type of all valid {@link GAMEPAD_AXIS} values.
+ */
+type GamepadAxisValue = (typeof GAMEPAD_AXIS)[keyof typeof GAMEPAD_AXIS];
+//#endregion
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue };

package/dist/core.js

@@ -0,0 +1,36 @@
+//#region src/core.ts
+/**
+* Button indices for the W3C Standard Gamepad mapping.
+* @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
+*/
+const GAMEPAD_BUTTON = {
+	South: 0,
+	East: 1,
+	West: 2,
+	North: 3,
+	LeftShoulder: 4,
+	RightShoulder: 5,
+	LeftTrigger: 6,
+	RightTrigger: 7,
+	Select: 8,
+	Start: 9,
+	LeftStick: 10,
+	RightStick: 11,
+	DPadUp: 12,
+	DPadDown: 13,
+	DPadLeft: 14,
+	DPadRight: 15,
+	Home: 16
+};
+/**
+* Axis indices for the W3C Standard Gamepad mapping.
+* @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
+*/
+const GAMEPAD_AXIS = {
+	LeftX: 0,
+	LeftY: 1,
+	RightX: 2,
+	RightY: 3
+};
+//#endregion
+export { GAMEPAD_AXIS, GAMEPAD_BUTTON };

package/dist/gamepad-controls.d.ts

@@ -0,0 +1,79 @@
+import { EventDispatcher } from "three";
+
+//#region src/gamepad-controls.d.ts
+/**
+ * Event map for {@link GamepadControls}.
+ *
+ * Each key is an event name, and its value is the extra data included in the event object
+ * alongside the standard `type` and `target` fields.
+ */
+type GamepadControlsEventMap = {
+  /**
+   * Fired when a gamepad is connected and set as the active gamepad.
+   */
+  connected: {
+    gamepad: Gamepad;
+  };
+  /**
+   * Fired when the active gamepad is disconnected.
+   */
+  disconnected: {
+    gamepad: Gamepad;
+  };
+};
+/**
+ * Abstract base class for Three.js gamepad controls.
+ *
+ * Handles the gamepad connection lifecycle and input polling so subclasses
+ * only need to implement {@link onUpdate}.
+ */
+declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEventMap> {
+  #private;
+  /**
+   * When `false`, all input processing is paused.
+   * @default true
+   */
+  enabled: boolean;
+  /**
+   * The currently active gamepad, or `null` if no gamepad is connected.
+   */
+  gamepad: Gamepad | null;
+  constructor();
+  /**
+   * Advances the controller by one frame. Call this inside your render loop.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   */
+  update(deltaTime: number): void;
+  /**
+   * Removes all event listeners attached by this controller. Call when no longer needed.
+   */
+  dispose(): void;
+  /**
+   * Called every frame when a gamepad is available and `enabled` is `true`.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   * @param gamepad - A fresh snapshot of the currently active gamepad.
+   */
+  protected abstract onUpdate(deltaTime: number, gamepad: Gamepad): void;
+  /**
+   * Called when any gamepad fires a `gamepadconnected` event.
+   *
+   * The default accepts the first gamepad that connects and dispatches `connected`.
+   * Override to customize selection behavior.
+   *
+   * @param gamepad - The gamepad that just connected.
+   */
+  protected onGamepadConnected(gamepad: Gamepad): void;
+  /**
+   * Called when any gamepad fires a `gamepaddisconnected` event.
+   *
+   * The default clears `this.gamepad` and dispatches `disconnected` if the
+   * disconnecting gamepad was the active one. Override to add custom cleanup.
+   *
+   * @param gamepad - The gamepad that just disconnected.
+   */
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
+}
+//#endregion
+export { GamepadControls, GamepadControlsEventMap };

package/dist/gamepad-controls.js

@@ -0,0 +1,90 @@
+import { EventDispatcher } from "three";
+//#region src/gamepad-controls.ts
+/**
+* Abstract base class for Three.js gamepad controls.
+*
+* Handles the gamepad connection lifecycle and input polling so subclasses
+* only need to implement {@link onUpdate}.
+*/
+var GamepadControls = class extends EventDispatcher {
+	/**
+	* When `false`, all input processing is paused.
+	* @default true
+	*/
+	enabled = true;
+	/**
+	* The currently active gamepad, or `null` if no gamepad is connected.
+	*/
+	gamepad = null;
+	#onGamepadConnected;
+	#onGamepadDisconnected;
+	constructor() {
+		super();
+		this.#onGamepadConnected = (event) => {
+			this.onGamepadConnected(event.gamepad);
+		};
+		this.#onGamepadDisconnected = (event) => {
+			this.onGamepadDisconnected(event.gamepad);
+		};
+		window.addEventListener("gamepadconnected", this.#onGamepadConnected);
+		window.addEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+	}
+	/**
+	* Advances the controller by one frame. Call this inside your render loop.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	update(deltaTime) {
+		if (!this.enabled) return;
+		if (this.gamepad !== null) {
+			const gamepads = navigator.getGamepads();
+			this.gamepad = gamepads[this.gamepad.index] ?? null;
+		}
+		if (this.gamepad === null) return;
+		this.onUpdate(deltaTime, this.gamepad);
+	}
+	/**
+	* Removes all event listeners attached by this controller. Call when no longer needed.
+	*/
+	dispose() {
+		window.removeEventListener("gamepadconnected", this.#onGamepadConnected);
+		window.removeEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
+		this.gamepad = null;
+		this.enabled = false;
+	}
+	/**
+	* Called when any gamepad fires a `gamepadconnected` event.
+	*
+	* The default accepts the first gamepad that connects and dispatches `connected`.
+	* Override to customize selection behavior.
+	*
+	* @param gamepad - The gamepad that just connected.
+	*/
+	onGamepadConnected(gamepad) {
+		if (this.gamepad !== null) return;
+		this.gamepad = gamepad;
+		this.dispatchEvent({
+			type: "connected",
+			gamepad
+		});
+	}
+	/**
+	* Called when any gamepad fires a `gamepaddisconnected` event.
+	*
+	* The default clears `this.gamepad` and dispatches `disconnected` if the
+	* disconnecting gamepad was the active one. Override to add custom cleanup.
+	*
+	* @param gamepad - The gamepad that just disconnected.
+	*/
+	onGamepadDisconnected(gamepad) {
+		if (this.gamepad?.index !== gamepad.index) return;
+		const disconnected = this.gamepad;
+		this.gamepad = null;
+		this.dispatchEvent({
+			type: "disconnected",
+			gamepad: disconnected
+		});
+	}
+};
+//#endregion
+export { GamepadControls };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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 };

package/dist/index.js

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "three-gamepad-controls",
+  "description": "Gamepad support for Three.js controls.",
+  "author": "Kasnix",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luckasnix/three-gamepad-controls.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "javascript",
+    "typescript",
+    "three",
+    "controls",
+    "gamepad"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.15",
+    "@commitlint/cli": "21.0.1",
+    "@commitlint/config-conventional": "21.0.1",
+    "@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",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@types/three": ">=0.184.1",
+    "three": ">=0.184.0"
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "type:check": "tsc --noEmit",
+    "format:check": "biome format",
+    "format:write": "biome format --write",
+    "lint:check": "biome lint",
+    "lint:write": "biome lint --write",
+    "check-all": "biome check",
+    "write-all": "biome check --write",
+    "check-ci": "biome ci"
+  }
+}