three-gamepad-controls 0.25.0 → 0.25.2

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

@@ -10,6 +10,7 @@ import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.j
 export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `FirstPersonControls.movementSpeed` for translation.
+   * Applied after normalizing combined stick and trigger movement.
    * @default 1.0
    */
   moveSpeed: number;
@@ -19,7 +20,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 +33,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 +48,10 @@ 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.
+ * Combined gamepad movement is limited to unit magnitude before speed and
+ * forward height gains, preserving smaller analog intentions unchanged.
  * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
  */
 export declare class GamepadFirstPersonControls extends GamepadControls {

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

@@ -26,6 +26,10 @@ 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.
+* Combined gamepad movement is limited to unit magnitude before speed and
+* forward height gains, preserving smaller analog intentions unchanged.
 * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
 */
 var GamepadFirstPersonControls = class extends GamepadControls {
@@ -64,7 +68,10 @@ 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.
+	* Triggers are filtered independently before the combined movement intent
+	* is limited to unit magnitude. Speed and forward height gains follow this
+	* normalization; height gain uses the initial Y position before climbing.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	* @param moveSpeed - User-configured movement speed multiplier.
@@ -76,23 +83,33 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown) {
 		const controls = this.#controls;
 		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) {
+		const up = input.buttonValue(buttonMoveUp);
+		const down = input.buttonValue(buttonMoveDown);
+		let strafe = move.x;
+		let forward = -move.y;
+		let climb = (up > buttonDeadzone ? up : 0) - (down > buttonDeadzone ? down : 0);
+		const magnitude = Math.hypot(strafe, forward, climb);
+		if (magnitude > 1) {
+			strafe /= magnitude;
+			forward /= magnitude;
+			climb /= magnitude;
+		}
+		const moveMult = deltaTime * controls.movementSpeed * moveSpeed;
+		if (strafe !== 0 || forward !== 0) {
+			const yaw = MathUtils.degToRad(this.#getOrientation().lon);
+			const sinYaw = Math.sin(yaw);
+			const cosYaw = Math.cos(yaw);
+			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 = strafe * 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);
+		if (climb !== 0) controls.object.position.y += climb * moveMult;
 	}
 	/**
 	* Applies camera look input while keeping FirstPersonControls state in sync.

package/package.json

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