three-gamepad-controls 0.24.3 → 0.25.1

package/README.md

@@ -92,7 +92,7 @@ pn test:coverage
 | --- | --- |
 | `0.184.x` | `<=0.22.x` |
 | `0.185.x` | `0.23.x` |
-| `0.186.x` | `0.24.x` |
+| `0.186.x` | `0.24.x`, `0.25.x` |
 
 ## 📖 Documentation
 

package/dist/gamepad-controls.js

@@ -63,7 +63,7 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	#handleGamepadConnected(event) {
 		this.gamepad = this.#gamepadInput.gamepad;
-		this.onGamepadConnected(event.gamepad);
+		this.onGamepadConnected(event.detail.gamepad);
 	}
 	/**
 	* Forwards an input disconnection event to the overridable lifecycle hook.
@@ -72,7 +72,7 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	#handleGamepadDisconnected(event) {
 		this.gamepad = this.#gamepadInput.gamepad;
-		this.onGamepadDisconnected(event.gamepad);
+		this.onGamepadDisconnected(event.detail.gamepad);
 	}
 	/**
 	* Advances the controller by one frame. Call this inside your render loop.

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

@@ -19,7 +19,7 @@ export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
    */
   lookSpeed: number;
   /**
-   * Movement stick axes and processing pipeline.
+   * Axes and processing pipeline for yaw-based movement in the XZ plane.
    */
   moveStick: GamepadStickBindingOptions;
   /**
@@ -32,12 +32,12 @@ export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
    */
   buttonDeadzone: number;
   /**
-   * Button index for **moving up** (analog trigger value used for proportional speed).
+   * Button index for **moving up** along Y (analog value used for proportional speed).
    * @default 6 - Left trigger
    */
   buttonMoveUp: number;
   /**
-   * Button index for **moving down** (analog trigger value used for proportional speed).
+   * Button index for **moving down** along Y (analog value used for proportional speed).
    * @default 7 - Right trigger
    */
   buttonMoveDown: number;
@@ -47,6 +47,8 @@ export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
  *
  * Gamepad input is additive with keyboard/mouse input - call
  * `gamepadControls.update(delta)` before `controls.update(delta)` each frame.
+ * Movement follows the native keyboard frame: yaw-based translation in XZ
+ * and climbing along Y, independent of camera pitch and roll.
  * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
  */
 export declare class GamepadFirstPersonControls extends GamepadControls {

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

@@ -26,6 +26,8 @@ const LOOK_SPEED_SCALE = 36e3;
 *
 * Gamepad input is additive with keyboard/mouse input - call
 * `gamepadControls.update(delta)` before `controls.update(delta)` each frame.
+* Movement follows the native keyboard frame: yaw-based translation in XZ
+* and climbing along Y, independent of camera pitch and roll.
 * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
 */
 var GamepadFirstPersonControls = class extends GamepadControls {
@@ -64,7 +66,9 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		this.#applyLook(deltaTime, lookSpeed, lookStick);
 	}
 	/**
-	* Applies local translation input to FirstPersonControls' object.
+	* Applies translation in the native keyboard frame, using yaw before look.
+	* Forward height gain uses the initial Y position; triggers are filtered
+	* independently before combining their proportional Y displacement.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param moveSpeed - User-configured movement speed multiplier.
@@ -78,21 +82,24 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		const input = this.gamepadInput;
 		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
 		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
-		const forward = move.y;
-		if (forward !== 0) {
-			let distance = forward * moveMult;
-			if (forward < 0 && controls.heightSpeed) {
+		if (move.x !== 0 || move.y !== 0) {
+			const yaw = MathUtils.degToRad(this.#getOrientation().lon);
+			const sinYaw = Math.sin(yaw);
+			const cosYaw = Math.cos(yaw);
+			const forward = -move.y;
+			let forwardDistance = 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;
+				forwardDistance += forward * deltaTime * heightDelta * controls.heightCoef * moveSpeed;
 			}
-			controls.object.translateZ(distance);
+			const strafeDistance = move.x * moveMult;
+			controls.object.position.x += sinYaw * forwardDistance - cosYaw * strafeDistance;
+			controls.object.position.z += cosYaw * forwardDistance + sinYaw * strafeDistance;
 		}
-		const strafe = move.x;
-		if (strafe !== 0) controls.object.translateX(strafe * moveMult);
 		const up = input.buttonValue(buttonMoveUp);
 		const down = input.buttonValue(buttonMoveDown);
-		if (up > buttonDeadzone) controls.object.translateY(up * moveMult);
-		if (down > buttonDeadzone) controls.object.translateY(-down * moveMult);
+		const climb = (up > buttonDeadzone ? up : 0) - (down > buttonDeadzone ? down : 0);
+		if (climb !== 0) controls.object.position.y += climb * moveMult;
 	}
 	/**
 	* Applies camera look input while keeping FirstPersonControls state in sync.

package/dist/gamepad-input.d.ts

@@ -1,30 +1,33 @@
 import { GamepadStick, GamepadStickPipeline } from "./gamepad-stick-processing.js";
-import { EventDispatcher } from "three";
 //#region src/gamepad-input.d.ts
 /**
- * Event map for {@link GamepadInput}.
+ * Native custom event map for {@link GamepadInput}.
+ * Gamepad snapshots are available through `event.detail.gamepad`.
  */
 export type GamepadInputEventMap = {
   /**
    * Fired when a gamepad is connected and becomes active.
    */
-  connected: {
+  connected: CustomEvent<{
     /**
      * Gamepad snapshot that became active.
      */
     gamepad: Gamepad;
-  };
+  }>;
   /**
    * Fired on a matching browser disconnection event or when polling observes
    * the active slot missing or disconnected. Continuous snapshots in the same
    * slot do not establish a physical-device identity or signal replacement.
    */
-  disconnected: {
+  disconnected: CustomEvent<{
     /**
      * Gamepad snapshot that was active before disconnection.
      */
     gamepad: Gamepad;
-  };
+  }>;
+};
+type GamepadInputEventListener<K extends keyof GamepadInputEventMap> = ((this: GamepadInput, event: GamepadInputEventMap[K]) => void) | {
+  handleEvent(event: GamepadInputEventMap[K]): void;
 };
 /**
  * Configuration for {@link GamepadInput}.
@@ -66,8 +69,13 @@ export type GamepadAxisOptions = {
  * Gamepad input state reader for gameplay, menus, and custom actions.
  *
  * Call {@link update} once per frame before reading button transitions or axes.
+ * Connection notifications are synchronous native `CustomEvent` objects with
+ * the gamepad snapshot in `event.detail.gamepad`. Input state is updated before
+ * listeners run. Inherited `dispatchEvent()` requires an `Event` instance;
+ * listener exceptions are reported by the browser instead of propagating to
+ * the dispatch caller.
  */
-export declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
+export declare class GamepadInput extends EventTarget {
   #private;
   /**
    * When `false`, polling through `update()` is paused and the last observed
@@ -84,6 +92,67 @@ export declare class GamepadInput extends EventDispatcher<GamepadInputEventMap>
    * `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
    */
   constructor(options?: Partial<GamepadInputOptions>);
+  /**
+   * Adds a native event listener with typed connection event details.
+   *
+   * Connection callbacks receive a `CustomEvent` with `detail.gamepad`.
+   * Supports callback functions and objects with `handleEvent`. Registering
+   * the same event type, listener, and capture flag again does not duplicate it.
+   * A regular callback's `this` is this input; a listener object's `this` is
+   * the listener object. Manage subscriptions separately from {@link dispose}.
+   *
+   * @param type - Event name to observe.
+   * @param listener - Callback or listener object, or `null` for a no-op.
+   * @param options - Capture flag (default `false`) or native options including
+   * `capture`, `once`, `passive`, and `signal`.
+   * @example
+   * ```ts
+   * const subscriptions = new AbortController();
+   * input.addEventListener("connected", (event) => {
+   *   console.log(event.detail.gamepad.id);
+   * }, { signal: subscriptions.signal });
+   * subscriptions.abort();
+   * ```
+   */
+  addEventListener<K extends keyof GamepadInputEventMap>(type: K, listener: GamepadInputEventListener<K> | null, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Adds a listener using standard `EventTarget` types for any event name.
+   *
+   * @param type - Event name to observe.
+   * @param listener - Native callback or listener object, or `null` for a no-op.
+   * @param options - Capture flag or native event listener options.
+   */
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Removes a native event listener with the matching capture option.
+   *
+   * The event type, callback or object identity, and capture flag must match
+   * registration. Other registration options do not affect removal. A missing
+   * listener or `null` is a no-op. Removal during dispatch prevents a pending
+   * invocation of that listener.
+   *
+   * @param type - Event name being observed.
+   * @param listener - Previously registered callback or listener object, or `null`.
+   * @param options - Capture flag (default `false`) or an object with `capture`.
+   * @example
+   * ```ts
+   * const onConnected = (event: GamepadInputEventMap["connected"]) => {
+   *   console.log(event.detail.gamepad.id);
+   * };
+   * input.addEventListener("connected", onConnected);
+   * input.removeEventListener("connected", onConnected);
+   * ```
+   */
+  removeEventListener<K extends keyof GamepadInputEventMap>(type: K, listener: GamepadInputEventListener<K> | null, options?: boolean | EventListenerOptions): void;
+  /**
+   * Removes a listener using standard `EventTarget` types for any event name.
+   *
+   * @param type - Event name being observed.
+   * @param listener - Previously registered native callback or listener object,
+   * or `null` for a no-op.
+   * @param options - Capture flag or an object with the matching `capture` flag.
+   */
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
   /**
    * The currently active gamepad, or `null` if no gamepad is connected.
    *

package/dist/gamepad-input.js

@@ -1,7 +1,6 @@
 import { isGamepadVibrationSupported, playGamepadVibrationEffect, resetGamepadVibration } from "./gamepad-haptics.js";
 import { GamepadManager } from "./gamepad-manager.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE } from "./gamepad-stick-processing.js";
-import { EventDispatcher } from "three";
 //#region src/gamepad-input.ts
 const DEFAULT_GAMEPAD_INPUT_OPTIONS = {
 	axisDeadzone: .1,
@@ -49,8 +48,13 @@ const getGamepadButtonValue = (gamepad, button) => {
 * Gamepad input state reader for gameplay, menus, and custom actions.
 *
 * Call {@link update} once per frame before reading button transitions or axes.
+* Connection notifications are synchronous native `CustomEvent` objects with
+* the gamepad snapshot in `event.detail.gamepad`. Input state is updated before
+* listeners run. Inherited `dispatchEvent()` requires an `Event` instance;
+* listener exceptions are reported by the browser instead of propagating to
+* the dispatch caller.
 */
-var GamepadInput = class extends EventDispatcher {
+var GamepadInput = class extends EventTarget {
 	/**
 	* When `false`, polling through `update()` is paused and the last observed
 	* state, including button transitions, is retained. Browser listeners remain
@@ -86,6 +90,12 @@ var GamepadInput = class extends EventDispatcher {
 		window.addEventListener("gamepadconnected", this.#onGamepadConnected);
 		window.addEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
 	}
+	addEventListener(type, listener, options) {
+		super.addEventListener(type, listener, options);
+	}
+	removeEventListener(type, listener, options) {
+		super.removeEventListener(type, listener, options);
+	}
 	/**
 	* Forwards a browser connection event to the active-gamepad adoption logic.
 	*
@@ -156,19 +166,13 @@ var GamepadInput = class extends EventDispatcher {
 		if (connected !== null) {
 			this.#gamepad = gamepad;
 			this.#syncButtonState({ seedPrevious: true });
-			this.dispatchEvent({
-				type: "connected",
-				gamepad: connected
-			});
+			this.dispatchEvent(new CustomEvent("connected", { detail: { gamepad: connected } }));
 			return;
 		}
 		if (disconnected !== null) {
 			this.#gamepad = null;
 			this.#clearButtonState();
-			this.dispatchEvent({
-				type: "disconnected",
-				gamepad: disconnected
-			});
+			this.dispatchEvent(new CustomEvent("disconnected", { detail: { gamepad: disconnected } }));
 			return;
 		}
 		this.#gamepad = gamepad;
@@ -291,10 +295,7 @@ var GamepadInput = class extends EventDispatcher {
 		if (connectedGamepad === null) return;
 		this.#gamepad = connectedGamepad;
 		this.#syncButtonState({ seedPrevious: true });
-		this.dispatchEvent({
-			type: "connected",
-			gamepad: connectedGamepad
-		});
+		this.dispatchEvent(new CustomEvent("connected", { detail: { gamepad: connectedGamepad } }));
 	}
 	/**
 	* Handles a browser disconnection event for the active gamepad.
@@ -309,10 +310,7 @@ var GamepadInput = class extends EventDispatcher {
 		if (disconnectedGamepad === null) return;
 		this.#gamepad = null;
 		this.#clearButtonState();
-		this.dispatchEvent({
-			type: "disconnected",
-			gamepad: disconnectedGamepad
-		});
+		this.dispatchEvent(new CustomEvent("disconnected", { detail: { gamepad: disconnectedGamepad } }));
 	}
 	/**
 	* Refreshes current and previous pressed-button sets from the active snapshot.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.24.3",
+  "version": "0.25.1",
   "license": "MIT",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {