three-gamepad-controls 0.25.5 → 0.25.7

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

@@ -51,6 +51,8 @@ export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
  * and climbing along Y, independent of camera pitch and roll.
  * Combined gamepad movement is limited to unit magnitude before speed and
  * forward height gains, preserving smaller analog intentions unchanged.
+ * Applied backward movement suppresses only the automatic target for the next
+ * native update; native inertia and manual input remain intact.
  * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
  */
 export declare class GamepadFirstPersonControls extends GamepadControls {
@@ -61,6 +63,20 @@ export declare class GamepadFirstPersonControls extends GamepadControls {
    *                  Any property not provided falls back to its default value.
    */
   constructor(controls: FirstPersonControls, options?: Partial<GamepadFirstPersonControlsOptions>);
+  /**
+   * Starts a fresh input frame, dropping unconsumed auto-forward suppression.
+   * Recursive updates are ignored; failed input frames retain no suppression.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   */
+  update(deltaTime: number): void;
+  /**
+   * Releases this instance's update adapter without disposing the native control.
+   * Later application replacements are preserved. Disposal is terminal.
+   */
+  dispose(): void;
+  /** Releases pending suppression before notifying disconnection listeners. */
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
   /**
    * Maps the current gamepad state to `FirstPersonControls` translation and look.
    *

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

@@ -30,11 +30,21 @@ const LOOK_SPEED_SCALE = 36e3;
 * and climbing along Y, independent of camera pitch and roll.
 * Combined gamepad movement is limited to unit magnitude before speed and
 * forward height gains, preserving smaller analog intentions unchanged.
+* Applied backward movement suppresses only the automatic target for the next
+* native update; native inertia and manual input remain intact.
 * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
 */
 var GamepadFirstPersonControls = class extends GamepadControls {
 	#controls;
 	#options;
+	#originalUpdate;
+	#originalUpdateDescriptor;
+	#nativeUpdate;
+	#backwardObject = null;
+	#backwardGamepad = null;
+	#updating = false;
+	#nativeUpdating = false;
+	#disposed = false;
 	#lookDirection;
 	#spherical;
 	#targetPosition;
@@ -55,6 +65,111 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 		this.#lookDirection = new Vector3();
 		this.#spherical = new Spherical();
 		this.#targetPosition = new Vector3();
+		this.#originalUpdate = controls.update;
+		this.#originalUpdateDescriptor = Object.getOwnPropertyDescriptor(controls, "update");
+		this.#nativeUpdate = (deltaTime) => this.#updateNative(deltaTime);
+		controls.update = this.#nativeUpdate;
+	}
+	/**
+	* Starts a fresh input frame, dropping unconsumed auto-forward suppression.
+	* Recursive updates are ignored; failed input frames retain no suppression.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	update(deltaTime) {
+		if (this.#updating || this.#nativeUpdating || this.#disposed) return;
+		this.#clearBackwardInput();
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} catch (error) {
+			this.#clearBackwardInput();
+			throw error;
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
+	* Releases this instance's update adapter without disposing the native control.
+	* Later application replacements are preserved. Disposal is terminal.
+	*/
+	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#clearBackwardInput();
+		super.dispose();
+		if (this.#controls.update === this.#nativeUpdate) {
+			if (this.#originalUpdateDescriptor === void 0) Reflect.deleteProperty(this.#controls, "update");
+			else Object.defineProperty(this.#controls, "update", this.#originalUpdateDescriptor);
+		}
+	}
+	/** Releases pending suppression before notifying disconnection listeners. */
+	onGamepadDisconnected(gamepad) {
+		this.#clearBackwardInput();
+		super.onGamepadDisconnected(gamepad);
+	}
+	/** Clears the destination and snapshot that received backward movement. */
+	#clearBackwardInput() {
+		this.#backwardObject = null;
+		this.#backwardGamepad = null;
+	}
+	/** Revalidates ownership and permissions after synchronous callbacks. */
+	#canApplyInput(gamepad, object) {
+		return !this.#disposed && this.enabled && this.#controls.enabled && this.gamepadInput.gamepad === gamepad && this.#controls.object === object;
+	}
+	/**
+	* Consumes one backward frame. Masking only autoForward lets the original
+	* update compute manual targets and damp its existing velocity unchanged.
+	* A temporary setter preserves assignments, including explicit false writes;
+	* conditional restoration also preserves application property replacements.
+	*/
+	#updateNative(deltaTime) {
+		if (this.#nativeUpdating || this.#updating) return;
+		const controls = this.#controls;
+		const gamepad = this.#backwardGamepad;
+		const object = this.#backwardObject;
+		this.#clearBackwardInput();
+		this.#nativeUpdating = true;
+		try {
+			if (gamepad === null || deltaTime === 0 || !this.#canApplyInput(gamepad, object)) {
+				this.#originalUpdate.call(controls, deltaTime);
+				return;
+			}
+			const descriptor = Object.getOwnPropertyDescriptor(controls, "autoForward");
+			let value = controls.autoForward;
+			let assigned = false;
+			let suppress = true;
+			const enumerable = descriptor?.enumerable ?? true;
+			const get = () => suppress && this.#canApplyInput(gamepad, object) ? false : value;
+			const set = (next) => {
+				assigned = true;
+				value = next;
+				descriptor?.set?.call(controls, next);
+			};
+			Object.defineProperty(controls, "autoForward", {
+				configurable: true,
+				enumerable,
+				get,
+				set
+			});
+			try {
+				this.#originalUpdate.call(controls, deltaTime);
+			} finally {
+				suppress = false;
+				const current = Object.getOwnPropertyDescriptor(controls, "autoForward");
+				if (current?.get === get && current.set === set && current.configurable === true && current.enumerable === enumerable) {
+					if (descriptor === void 0) {
+						Reflect.deleteProperty(controls, "autoForward");
+						if (assigned) controls.autoForward = value;
+					} else Object.defineProperty(controls, "autoForward", "value" in descriptor ? {
+						...descriptor,
+						value
+					} : descriptor);
+				}
+			}
+		} finally {
+			this.#nativeUpdating = false;
+		}
 	}
 	/**
 	* Maps the current gamepad state to `FirstPersonControls` translation and look.
@@ -64,8 +179,15 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	onUpdate(deltaTime) {
 		if (!this.#controls.enabled) return;
 		const { moveSpeed, lookSpeed, moveStick, lookStick, buttonDeadzone, buttonMoveUp, buttonMoveDown } = this.#options;
-		this.#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown);
-		this.#applyLook(deltaTime, lookSpeed, lookStick);
+		const input = this.gamepadInput;
+		const gamepad = input.gamepad;
+		const object = this.#controls.object;
+		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
+		if (!this.#canApplyInput(gamepad, object)) return;
+		const look = input.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
+		if (!this.#canApplyInput(gamepad, object)) return;
+		this.#applyMovement(deltaTime, moveSpeed, move, buttonDeadzone, buttonMoveUp, buttonMoveDown);
+		this.#applyLook(deltaTime, lookSpeed, look);
 	}
 	/**
 	* Applies translation in the native keyboard frame, using yaw before look.
@@ -75,15 +197,14 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param moveSpeed - User-configured movement speed multiplier.
-	* @param moveStick - Resolved movement stick binding.
+	* @param move - Processed movement stick input.
 	* @param buttonDeadzone - Analog button dead zone threshold.
 	* @param buttonMoveUp - Button index for upward movement.
 	* @param buttonMoveDown - Button index for downward movement.
 	*/
-	#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown) {
+	#applyMovement(deltaTime, moveSpeed, move, buttonDeadzone, buttonMoveUp, buttonMoveDown) {
 		const controls = this.#controls;
 		const input = this.gamepadInput;
-		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);
 		const up = input.buttonValue(buttonMoveUp);
 		const down = input.buttonValue(buttonMoveDown);
 		let strafe = move.x;
@@ -108,6 +229,10 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 			const strafeDistance = strafe * moveMult;
 			controls.object.position.x += sinYaw * forwardDistance - cosYaw * strafeDistance;
 			controls.object.position.z += cosYaw * forwardDistance + sinYaw * strafeDistance;
+			if (forwardDistance < 0) {
+				this.#backwardObject = controls.object;
+				this.#backwardGamepad = input.gamepad;
+			}
 		}
 		if (climb !== 0) controls.object.position.y += climb * moveMult;
 	}
@@ -116,10 +241,10 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param lookSpeed - User-configured look speed multiplier.
-	* @param lookStick - Resolved camera-look stick binding.
+	* @param look - Processed camera-look stick input.
 	*/
-	#applyLook(deltaTime, lookSpeed, lookStick) {
-		const { x: lookX, y: lookY } = this.gamepadInput.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
+	#applyLook(deltaTime, lookSpeed, look) {
+		const { x: lookX, y: lookY } = look;
 		if (lookX === 0 && lookY === 0) return;
 		const controls = this.#controls;
 		const actualLookSpeed = controls.lookSpeed * lookSpeed * deltaTime * LOOK_SPEED_SCALE;

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

@@ -7,8 +7,8 @@ import { MapControls } from "three/addons/controls/MapControls.js";
  * mouse conventions. All options from {@link GamepadOrbitControlsOptions} are available.
  *
  * Call `update()` inside the render loop **before** `MapControls.update()`.
- * Gamepad interaction events, pause semantics, and combined native/wrapper speeds
- * are inherited from {@link GamepadOrbitControls}.
+ * Gamepad interaction events, pause semantics, combined native/wrapper speeds,
+ * and automatic-rotation suspension are inherited from {@link GamepadOrbitControls}.
  */
 export declare class GamepadMapControls extends GamepadOrbitControls {
   /**

package/dist/gamepad-map-controls.js

@@ -18,8 +18,8 @@ const DEFAULT_MAP_OPTIONS = {
 * mouse conventions. All options from {@link GamepadOrbitControlsOptions} are available.
 *
 * Call `update()` inside the render loop **before** `MapControls.update()`.
-* Gamepad interaction events, pause semantics, and combined native/wrapper speeds
-* are inherited from {@link GamepadOrbitControls}.
+* Gamepad interaction events, pause semantics, combined native/wrapper speeds,
+* and automatic-rotation suspension are inherited from {@link GamepadOrbitControls}.
 */
 var GamepadMapControls = class extends GamepadOrbitControls {
 	/**

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

@@ -55,6 +55,8 @@ export type GamepadOrbitControlsOptions = GamepadControlsOptions & {
  * Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
  * The wrapper dispatches balanced gamepad `start` and `end` events on the native
  * controls; native operations and damping remain responsible for `change`.
+ * Accepted input suspends automatic rotation through every native update in the
+ * frame, preserving autoRotate configuration, pointer state, and residual damping.
  */
 export declare class GamepadOrbitControls extends GamepadControls {
   #private;
@@ -81,7 +83,8 @@ export declare class GamepadOrbitControls extends GamepadControls {
   protected onUpdate(deltaTime: number): void;
   /**
    * Removes gamepad listeners and ends only this wrapper's active interaction.
-   * Repeated calls are safe; the native controls and their damping are preserved.
+   * Restores the owned native update adapter even when an end listener throws.
+   * Repeated calls are safe and disposal is terminal; native damping is preserved.
    */
   dispose(): void;
   /**

package/dist/gamepad-orbit-controls.js

@@ -27,10 +27,18 @@ const DEFAULT_ORBIT_OPTIONS = {
 * Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
 * The wrapper dispatches balanced gamepad `start` and `end` events on the native
 * controls; native operations and damping remain responsible for `change`.
+* Accepted input suspends automatic rotation through every native update in the
+* frame, preserving autoRotate configuration, pointer state, and residual damping.
 */
 var GamepadOrbitControls = class extends GamepadControls {
 	#controls;
 	#options;
+	#originalUpdate;
+	#originalUpdateDescriptor;
+	#nativeUpdate;
+	#autoRotationFrame = null;
+	#nativeUpdating = false;
+	#disposed = false;
 	/** Whether this wrapper owns an active gamepad interaction. */
 	#interacting = false;
 	/** Blocks recursive updates while a frame is being processed. */
@@ -51,6 +59,10 @@ var GamepadOrbitControls = class extends GamepadControls {
 			rotateStick: resolveGamepadStickBinding(DEFAULT_ORBIT_OPTIONS.rotateStick, options?.rotateStick),
 			panStick: resolveGamepadStickBinding(DEFAULT_ORBIT_OPTIONS.panStick, options?.panStick)
 		};
+		this.#originalUpdate = controls.update;
+		this.#originalUpdateDescriptor = Object.getOwnPropertyDescriptor(controls, "update");
+		this.#nativeUpdate = (delta) => this.#updateNative(delta);
+		controls.update = this.#nativeUpdate;
 	}
 	/**
 	* Polls the gamepad and applies input, ignoring updates from synchronous listeners.
@@ -60,10 +72,14 @@ var GamepadOrbitControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	update(deltaTime) {
-		if (this.#updating || this.#ending) return;
+		if (this.#updating || this.#ending || this.#nativeUpdating || this.#disposed) return;
+		this.#autoRotationFrame = null;
 		this.#updating = true;
 		try {
 			super.update(deltaTime);
+		} catch (error) {
+			this.#autoRotationFrame = null;
+			throw error;
 		} finally {
 			this.#updating = false;
 		}
@@ -81,59 +97,77 @@ var GamepadOrbitControls = class extends GamepadControls {
 		}
 		const { rotateStick, panStick, buttonDeadzone, buttonDollyIn, buttonDollyOut } = this.#options;
 		const input = this.gamepadInput;
+		const gamepad = input.gamepad;
+		const object = this.#controls.object;
 		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
 		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
 		const triggerIn = input.buttonValue(buttonDollyIn);
 		const triggerOut = input.buttonValue(buttonDollyOut);
 		const frame = {
-			rotateX: rotate.x,
-			rotateY: rotate.y,
-			panX: pan.x,
-			panY: pan.y,
-			dollyIn: triggerIn > buttonDeadzone ? triggerIn : 0,
-			dollyOut: triggerOut > buttonDeadzone ? triggerOut : 0
+			gamepad,
+			object,
+			delta: deltaTime,
+			input: {
+				rotateX: rotate.x,
+				rotateY: rotate.y,
+				panX: pan.x,
+				panY: pan.y,
+				dollyIn: triggerIn > buttonDeadzone ? triggerIn : 0,
+				dollyOut: triggerOut > buttonDeadzone ? triggerOut : 0
+			}
 		};
-		let actions = this.#acceptActions(frame, deltaTime);
+		let actions = this.#acceptActions(frame);
 		if (actions === null) return;
 		if (!this.#interacting) {
 			this.#interacting = true;
 			this.#controls.dispatchEvent({ type: "start" });
-			actions = this.#acceptActions(frame, deltaTime);
+			actions = this.#acceptActions(frame);
 			if (actions === null) return;
 		}
 		const controls = this.#controls;
 		if (actions.rotateX !== 0) {
 			controls.rotateLeft(actions.rotateX);
-			actions = this.#acceptActions(frame, deltaTime);
+			actions = this.#acceptActions(frame);
 			if (actions === null) return;
 		}
 		if (actions.rotateY !== 0) {
 			controls.rotateUp(actions.rotateY);
-			actions = this.#acceptActions(frame, deltaTime);
+			actions = this.#acceptActions(frame);
 			if (actions === null) return;
 		}
 		if (actions.panX !== 0 || actions.panY !== 0) {
 			controls.pan(actions.panX, actions.panY);
-			actions = this.#acceptActions(frame, deltaTime);
+			actions = this.#acceptActions(frame);
 			if (actions === null) return;
 		}
 		if (actions.dollyIn !== 0) {
 			controls.dollyIn(1 / (1 + actions.dollyIn));
-			actions = this.#acceptActions(frame, deltaTime);
+			actions = this.#acceptActions(frame);
 			if (actions === null) return;
 		}
 		if (actions.dollyOut !== 0) {
 			controls.dollyOut(1 / (1 + actions.dollyOut));
-			this.#acceptActions(frame, deltaTime);
+			this.#acceptActions(frame);
 		}
 	}
 	/**
 	* Removes gamepad listeners and ends only this wrapper's active interaction.
-	* Repeated calls are safe; the native controls and their damping are preserved.
+	* Restores the owned native update adapter even when an end listener throws.
+	* Repeated calls are safe and disposal is terminal; native damping is preserved.
 	*/
 	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#autoRotationFrame = null;
 		super.dispose();
-		this.#endInteraction();
+		try {
+			this.#endInteraction();
+		} finally {
+			if (this.#controls.update === this.#nativeUpdate) {
+				if (this.#originalUpdateDescriptor === void 0) Reflect.deleteProperty(this.#controls, "update");
+				else Object.defineProperty(this.#controls, "update", this.#originalUpdateDescriptor);
+			}
+		}
 	}
 	/**
 	* Ends the owned interaction before forwarding the active gamepad's disconnection.
@@ -149,17 +183,29 @@ var GamepadOrbitControls = class extends GamepadControls {
 	* 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.
 	*
-	* @param input - Already processed sticks and filtered triggers for this frame.
-	* @param delta - Frame duration in seconds.
+	* @param frame - Cached input and the destination that owns it.
 	* @returns Accepted frame deltas, or `null` when input application must stop.
 	*/
-	#acceptActions(input, delta) {
-		const controls = this.#controls;
-		if (!controls.enabled) {
+	#acceptActions(frame) {
+		if (!this.#controls.enabled) {
 			this.#endInteraction();
 			return null;
 		}
-		if (!this.enabled || this.gamepad === null) return null;
+		if (!this.#ownsFrame(frame)) {
+			this.#autoRotationFrame = null;
+			return null;
+		}
+		const actions = this.#resolveActions(frame.input, frame.delta);
+		if (actions === null) {
+			this.#endInteraction();
+			return null;
+		}
+		this.#autoRotationFrame = frame;
+		return actions;
+	}
+	/** Resolves current permissions and gains without events or pipeline reads. */
+	#resolveActions(input, delta) {
+		const controls = this.#controls;
 		const rotate = controls.enableRotate ? controls.rotateSpeed * this.#options.rotateSpeed * delta * Math.PI : 0;
 		const pan = controls.enablePan ? controls.panSpeed * this.#options.panSpeed * delta * 500 : 0;
 		const zoom = controls.enableZoom ? controls.zoomSpeed * this.#options.zoomSpeed * delta : 0;
@@ -171,17 +217,68 @@ var GamepadOrbitControls = class extends GamepadControls {
 			dollyIn: input.dollyIn * zoom,
 			dollyOut: input.dollyOut * zoom
 		};
-		if (!Object.values(actions).some((value) => value !== 0)) {
-			this.#endInteraction();
-			return null;
-		}
+		if (!Object.values(actions).some((value) => value !== 0)) return null;
 		return actions;
 	}
+	/** Checks the live wrapper, selected snapshot, and camera after callbacks. */
+	#ownsFrame(frame) {
+		return !this.#disposed && this.enabled && this.gamepad === frame.gamepad && this.#controls.object === frame.object;
+	}
+	/** Releases invalid intent without ending a paused interaction or repolling. */
+	#suppressAutoRotation() {
+		const frame = this.#autoRotationFrame;
+		if (frame === null) return false;
+		if (!this.#controls.enabled || !this.#ownsFrame(frame) || this.#resolveActions(frame.input, frame.delta) === null) {
+			this.#autoRotationFrame = null;
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Masks only the automatic angle for this call, retaining intent for subsequent
+	* internal and external updates. Native pointer gating and damping stay intact.
+	* Restores owned descriptors and makes retained masks inert even on failure.
+	*/
+	#updateNative(delta) {
+		if (this.#nativeUpdating) return false;
+		const controls = this.#controls;
+		this.#nativeUpdating = true;
+		try {
+			if (!this.#suppressAutoRotation()) return this.#originalUpdate.call(controls, delta);
+			const descriptor = Object.getOwnPropertyDescriptor(controls, "_getAutoRotationAngle");
+			const original = controls._getAutoRotationAngle;
+			const enumerable = descriptor?.enumerable ?? false;
+			let masking = true;
+			const angle = (delta) => masking && this.#suppressAutoRotation() ? 0 : original.call(controls, delta);
+			Object.defineProperty(controls, "_getAutoRotationAngle", {
+				configurable: true,
+				enumerable,
+				writable: true,
+				value: angle
+			});
+			try {
+				return this.#originalUpdate.call(controls, delta);
+			} finally {
+				masking = false;
+				const current = Object.getOwnPropertyDescriptor(controls, "_getAutoRotationAngle");
+				if (current?.value === angle && current.configurable === true && current.enumerable === enumerable && current.writable === true) {
+					if (descriptor === void 0) Reflect.deleteProperty(controls, "_getAutoRotationAngle");
+					else Object.defineProperty(controls, "_getAutoRotationAngle", descriptor);
+				}
+			}
+		} catch (error) {
+			this.#autoRotationFrame = null;
+			throw error;
+		} finally {
+			this.#nativeUpdating = false;
+		}
+	}
 	/**
 	* Releases session ownership before dispatching the native `end` event once.
 	* Blocks recursive updates during finalization without clearing native input or damping.
 	*/
 	#endInteraction() {
+		this.#autoRotationFrame = null;
 		if (!this.#interacting) return;
 		this.#interacting = false;
 		this.#ending = true;

package/package.json

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