three-gamepad-controls 0.24.1 → 0.24.3

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

@@ -1,7 +1,7 @@
 import { GAMEPAD_AXIS } from "./core.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
-import { Euler } from "three";
+import { Euler, Quaternion } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
 const DEFAULT_POINTER_LOCK_OPTIONS = {
 	moveSpeed: 5,
@@ -23,11 +23,17 @@ const DEFAULT_POINTER_LOCK_OPTIONS = {
 * 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}.
+* Look dispatches `change` on the native controls after an actual orientation
+* change; movement does not dispatch it or alter pointer lock state.
 */
 var GamepadPointerLockControls = class extends GamepadControls {
 	#controls;
 	#options;
 	#euler;
+	/** Reusable orientation snapshot for sign-independent angular change detection. */
+	#previousQuaternion = new Quaternion();
+	/** Blocks recursive input application from native `change` listeners. */
+	#updating = false;
 	/**
 	* @param controls - A Three.js `PointerLockControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -45,7 +51,26 @@ var GamepadPointerLockControls = class extends GamepadControls {
 		this.#euler = new Euler(0, 0, 0, "YXZ");
 	}
 	/**
+	* Polls and applies movement and look, ignoring updates from synchronous listeners.
+	* Gamepad input remains independent of the native pointer lock state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	update(deltaTime) {
+		if (this.#updating) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
 	* Maps the current gamepad state to `PointerLockControls` movement and look.
+	* Dispatches at most one native `change` after look changes orientation by more
+	* than `1e-7` radians, treating opposite quaternion signs as equivalent.
+	* Translation, zero look gain, and pitch-only input held at a clamp do not
+	* dispatch `change`; permitted yaw can still change orientation at a pitch limit.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
@@ -57,14 +82,16 @@ var GamepadPointerLockControls = class extends GamepadControls {
 		if (move.y !== 0) this.#controls.moveForward(-move.y * moveSpeed * deltaTime);
 		if (move.x !== 0) this.#controls.moveRight(move.x * moveSpeed * deltaTime);
 		const look = input.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
-		if (look.x !== 0 || look.y !== 0) {
+		const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
+		if ((look.x !== 0 || look.y !== 0) && scale !== 0) {
 			const camera = this.#controls.object;
-			const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
+			this.#previousQuaternion.copy(camera.quaternion);
 			this.#euler.setFromQuaternion(camera.quaternion);
 			this.#euler.y -= look.x * scale;
 			this.#euler.x -= look.y * 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);
+			if (this.#previousQuaternion.angleTo(camera.quaternion) > 1e-7) this.#controls.dispatchEvent({ type: "change" });
 		}
 	}
 };

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

@@ -34,7 +34,7 @@ export type GamepadTrackballControlsOptions = GamepadControlsOptions & {
    */
   panStick: GamepadStickBindingOptions;
   /**
-   * Dead zone threshold for analog trigger values.
+   * Each analog trigger must be strictly above this threshold before subtraction.
    * @default 0.1
    */
   buttonDeadzone: number;
@@ -54,6 +54,8 @@ export type GamepadTrackballControlsOptions = GamepadControlsOptions & {
  *
  * Call `update()` inside the render loop **before** `TrackballControls.update()`.
  * Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+ * The wrapper dispatches balanced gamepad `start` and `end` events on the native
+ * controls; the native update applies speeds and damping and dispatches `change`.
  */
 export declare class GamepadTrackballControls extends GamepadControls {
   #private;
@@ -64,10 +66,30 @@ export declare class GamepadTrackballControls extends GamepadControls {
    */
   constructor(controls: TrackballControls, options?: Partial<GamepadTrackballControlsOptions>);
   /**
-   * Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+   * Polls the gamepad and queues input, ignoring updates from synchronous listeners.
+   * Pausing through `enabled` retains the owned interaction until input resumes,
+   * the gamepad disconnects, or the wrapper is disposed.
    *
    * @param deltaTime - Seconds since the last frame.
    */
+  update(deltaTime: number): void;
+  /**
+   * Reads each binding once, manages the gamepad session, and adds accepted deltas
+   * to native pointer vectors. Revalidates permissions after the `start` event.
+   *
+   * @param deltaTime - Seconds elapsed for this input frame.
+   */
   protected onUpdate(deltaTime: number): void;
+  /**
+   * Removes gamepad listeners and ends only this wrapper's active interaction.
+   * Repeated calls are safe; native pointer vectors and damping are preserved.
+   */
+  dispose(): void;
+  /**
+   * Ends the owned interaction before forwarding the active gamepad's disconnection.
+   *
+   * @param gamepad - The gamepad that just disconnected.
+   */
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
 //#endregion

package/dist/gamepad-trackball-controls.js

@@ -25,10 +25,18 @@ const DEFAULT_TRACKBALL_OPTIONS = {
 *
 * Call `update()` inside the render loop **before** `TrackballControls.update()`.
 * Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+* The wrapper dispatches balanced gamepad `start` and `end` events on the native
+* controls; the native update applies speeds and damping and dispatches `change`.
 */
 var GamepadTrackballControls = class extends GamepadControls {
 	#controls;
 	#options;
+	/** Whether this wrapper owns an active gamepad interaction. */
+	#interacting = false;
+	/** Blocks recursive updates while a frame is being processed. */
+	#updating = false;
+	/** Blocks recursive updates while the owned interaction is ending. */
+	#ending = false;
 	/**
 	* @param controls - A Three.js `TrackballControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -45,76 +53,125 @@ var GamepadTrackballControls = class extends GamepadControls {
 		};
 	}
 	/**
-	* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+	* Polls the gamepad and queues input, ignoring updates from synchronous listeners.
+	* Pausing through `enabled` retains the owned interaction until input resumes,
+	* the gamepad disconnects, or the wrapper is disposed.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
-	onUpdate(deltaTime) {
-		if (!this.#controls.enabled) return;
-		const { rotateSpeed, panSpeed, zoomSpeed, rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut } = this.#options;
-		this.#queueRotation(deltaTime, rotateSpeed, rotateStick);
-		this.#queuePan(deltaTime, panSpeed, panStick);
-		this.#queueZoom(deltaTime, zoomSpeed, buttonDeadzone, buttonZoomIn, buttonZoomOut);
+	update(deltaTime) {
+		if (this.#updating || this.#ending) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
 	}
 	/**
-	* Queues rotation input into TrackballControls' normalized move state.
+	* Reads each binding once, manages the gamepad session, and adds accepted deltas
+	* to native pointer vectors. Revalidates permissions after the `start` event.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param rotateSpeed - User-configured rotation speed multiplier.
-	* @param rotateStick - Resolved stick binding for rotation.
+	* @param deltaTime - Seconds elapsed for this input frame.
 	*/
-	#queueRotation(deltaTime, rotateSpeed, rotateStick) {
+	onUpdate(deltaTime) {
+		if (!this.#controls.enabled) {
+			this.#endInteraction();
+			return;
+		}
+		const { rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut } = this.#options;
+		const input = this.gamepadInput;
+		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
+		const triggerIn = input.buttonValue(buttonZoomIn);
+		const triggerOut = input.buttonValue(buttonZoomOut);
+		const zoom = (triggerOut > buttonDeadzone ? triggerOut : 0) - (triggerIn > buttonDeadzone ? triggerIn : 0);
+		const frame = {
+			rotateX: rotate.x,
+			rotateY: rotate.y,
+			panX: pan.x,
+			panY: pan.y,
+			zoom
+		};
+		let actions = this.#acceptActions(frame, deltaTime);
+		if (actions === null) return;
+		if (!this.#interacting) {
+			this.#interacting = true;
+			this.#controls.dispatchEvent({ type: "start" });
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
 		const controls = this.#controls;
-		if (controls.noRotate) return;
-		const rotate = this.gamepadInput.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
-		if (rotate.x === 0 && rotate.y === 0) return;
-		const scale = rotateSpeed * deltaTime * Math.PI;
-		controls._moveCurr.x += rotate.x * scale;
-		controls._moveCurr.y += -rotate.y * scale;
+		controls._moveCurr.x += actions.rotateX;
+		controls._moveCurr.y -= actions.rotateY;
+		controls._panEnd.x += actions.panX;
+		controls._panEnd.y += actions.panY;
+		controls._zoomEnd.y += actions.zoom;
 	}
 	/**
-	* Queues pan input into TrackballControls' normalized pan state.
-	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param panSpeed - User-configured pan speed multiplier.
-	* @param panStick - Resolved stick binding for panning.
+	* Removes gamepad listeners and ends only this wrapper's active interaction.
+	* Repeated calls are safe; native pointer vectors and damping are preserved.
 	*/
-	#queuePan(deltaTime, panSpeed, panStick) {
-		const controls = this.#controls;
-		if (controls.noPan) return;
-		const pan = this.gamepadInput.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
-		if (pan.x === 0 && pan.y === 0) return;
-		const scale = panSpeed * deltaTime * this.#getInputDampingFactor();
-		controls._panEnd.x += pan.x * scale;
-		controls._panEnd.y += pan.y * scale;
+	dispose() {
+		super.dispose();
+		this.#endInteraction();
 	}
 	/**
-	* Queues trigger zoom input into TrackballControls' normalized zoom state.
+	* Ends the owned interaction before forwarding the active gamepad's disconnection.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param zoomSpeed - User-configured zoom speed multiplier.
-	* @param buttonDeadzone - Trigger dead zone threshold.
-	* @param buttonZoomIn - Button index for zooming in.
-	* @param buttonZoomOut - Button index for zooming out.
+	* @param gamepad - The gamepad that just disconnected.
 	*/
-	#queueZoom(deltaTime, zoomSpeed, buttonDeadzone, buttonZoomIn, buttonZoomOut) {
-		const controls = this.#controls;
-		if (controls.noZoom) return;
-		const input = this.gamepadInput;
-		const triggerIn = input.buttonValue(buttonZoomIn);
-		const triggerOut = input.buttonValue(buttonZoomOut);
-		if (triggerIn <= buttonDeadzone && triggerOut <= buttonDeadzone) return;
-		controls._zoomEnd.y += (triggerOut - triggerIn) * zoomSpeed * deltaTime * this.#getInputDampingFactor();
+	onGamepadDisconnected(gamepad) {
+		this.#endInteraction();
+		super.onGamepadDisconnected(gamepad);
 	}
 	/**
-	* Compensates for TrackballControls reapplying queued pan and zoom deltas
-	* while their input state catches up through damping.
+	* Resolves a cached frame against current permissions, wrapper speeds, and damping.
+	* Native speeds only gate acceptance here; Trackball applies them during its update.
+	* Native disable or lack of actionable input ends the owned session; a wrapper
+	* pause stops application while retaining it. Geometric limits do not erase intent.
 	*
-	* @returns Multiplier that matches TrackballControls' damping mode.
+	* @param input - Already processed sticks and independently filtered trigger difference.
+	* @param delta - Frame duration in seconds.
+	* @returns Accepted pointer-coordinate deltas, or `null` when application must stop.
 	*/
-	#getInputDampingFactor() {
+	#acceptActions(input, delta) {
 		const controls = this.#controls;
-		return controls.staticMoving ? 1 : controls.dynamicDampingFactor;
+		if (!controls.enabled) {
+			this.#endInteraction();
+			return null;
+		}
+		if (!this.enabled || this.gamepad === null) return null;
+		const damping = controls.staticMoving ? 1 : controls.dynamicDampingFactor;
+		const rotate = !controls.noRotate && controls.rotateSpeed !== 0 ? this.#options.rotateSpeed * delta * Math.PI : 0;
+		const pan = !controls.noPan && controls.panSpeed !== 0 ? this.#options.panSpeed * delta * damping : 0;
+		const zoom = !controls.noZoom && controls.zoomSpeed !== 0 ? this.#options.zoomSpeed * delta * damping : 0;
+		const actions = {
+			rotateX: input.rotateX * rotate,
+			rotateY: input.rotateY * rotate,
+			panX: input.panX * pan,
+			panY: input.panY * pan,
+			zoom: input.zoom * zoom
+		};
+		if (!Object.values(actions).some((value) => value !== 0)) {
+			this.#endInteraction();
+			return null;
+		}
+		return actions;
+	}
+	/**
+	* Releases session ownership before dispatching the native `end` event once.
+	* Blocks recursive updates during finalization without clearing native pointer vectors.
+	*/
+	#endInteraction() {
+		if (!this.#interacting) return;
+		this.#interacting = false;
+		this.#ending = true;
+		try {
+			this.#controls.dispatchEvent({ type: "end" });
+		} finally {
+			this.#ending = false;
+		}
 	}
 };
 //#endregion