three-gamepad-controls 0.25.5 → 0.25.6

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/package.json

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