three-gamepad-controls 0.25.1 → 0.25.3

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

@@ -9,7 +9,8 @@ import { DragControls } from "three/addons/controls/DragControls.js";
  */
 export type GamepadDragControlsOptions = GamepadControlsOptions & {
   /**
-   * Screen-relative translation speed multiplier.
+   * Screen-relative translation speed multiplier. At full processed input,
+   * `1` moves one effective viewport width or height per second on each axis.
    * @default 1.0
    */
   dragSpeed: number;

package/dist/gamepad-drag-controls.js

@@ -1,6 +1,7 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { getCameraViewSize } from "./three-utils.js";
 import { Matrix4, Vector2, Vector3 } from "three";
 //#region src/gamepad-drag-controls.ts
 const DEFAULT_DRAG_OPTIONS = {
@@ -32,8 +33,6 @@ var GamepadDragControls = class extends GamepadControls {
 	#parentInverse;
 	#selectedWorldPosition;
 	#selectedLocalPosition;
-	#cameraWorldPosition;
-	#cameraForward;
 	#cameraRight;
 	#cameraUp;
 	#cameraToSelected;
@@ -59,8 +58,6 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#parentInverse = new Matrix4();
 		this.#selectedWorldPosition = new Vector3();
 		this.#selectedLocalPosition = new Vector3();
-		this.#cameraWorldPosition = new Vector3();
-		this.#cameraForward = new Vector3();
 		this.#cameraRight = new Vector3();
 		this.#cameraUp = new Vector3();
 		this.#cameraToSelected = new Vector3();
@@ -151,8 +148,7 @@ var GamepadDragControls = class extends GamepadControls {
 	*/
 	#applyDrag(selected, deltaTime, dragX, dragY, dragSpeed) {
 		if (dragX === 0 && dragY === 0) return false;
-		this.#updateCameraAxes();
-		this.#updateViewSizeAtSelectedDepth();
+		this.#updateDragCameraState();
 		const scale = dragSpeed * deltaTime;
 		this.#selectedWorldPosition.addScaledVector(this.#cameraRight, dragX * this.#viewSize.x * scale);
 		this.#selectedWorldPosition.addScaledVector(this.#cameraUp, -dragY * this.#viewSize.y * scale);
@@ -185,6 +181,7 @@ var GamepadDragControls = class extends GamepadControls {
 	#intersectCenter() {
 		const controls = this.#controls;
 		this.#intersections.length = 0;
+		controls.object.updateWorldMatrix(true, false);
 		controls.raycaster.setFromCamera(this.#centerNdc, controls.object);
 		controls.raycaster.intersectObjects(controls.objects, controls.recursive, this.#intersections);
 		return this.#intersections[0];
@@ -276,42 +273,17 @@ var GamepadDragControls = class extends GamepadControls {
 	}
 	#updateCameraAxes() {
 		const camera = this.#controls.object;
+		camera.updateWorldMatrix(true, false);
 		this.#cameraRight.set(1, 0, 0).applyQuaternion(camera.quaternion).normalize();
 		this.#cameraUp.set(0, 1, 0).applyQuaternion(camera.quaternion).normalize();
-		camera.getWorldDirection(this.#cameraForward).normalize();
 	}
-	#updateViewSizeAtSelectedDepth() {
+	#updateDragCameraState() {
 		const camera = this.#controls.object;
-		if (this.#isOrthographicCamera(camera)) {
-			this.#viewSize.set(Math.abs(camera.right - camera.left) / camera.zoom, Math.abs(camera.top - camera.bottom) / camera.zoom);
-			return;
-		}
-		if (this.#isPerspectiveCamera(camera)) {
-			camera.getWorldPosition(this.#cameraWorldPosition);
-			const depth = Math.max(Number.EPSILON, this.#cameraToSelected.copy(this.#selectedWorldPosition).sub(this.#cameraWorldPosition).dot(this.#cameraForward));
-			const height = 2 * Math.tan(camera.fov * Math.PI / 360) * depth;
-			this.#viewSize.set(height * camera.aspect, height);
-			return;
-		}
-		this.#viewSize.set(1, 1);
-	}
-	/**
-	* Narrows a Three.js camera to `PerspectiveCamera`.
-	*
-	* @param camera - Camera to inspect.
-	* @returns `true` when the camera is perspective.
-	*/
-	#isPerspectiveCamera(camera) {
-		return camera.isPerspectiveCamera === true;
-	}
-	/**
-	* Narrows a Three.js camera to `OrthographicCamera`.
-	*
-	* @param camera - Camera to inspect.
-	* @returns `true` when the camera is orthographic.
-	*/
-	#isOrthographicCamera(camera) {
-		return camera.isOrthographicCamera === true;
+		camera.updateWorldMatrix(true, false);
+		const view = camera.matrixWorldInverse.elements;
+		this.#cameraRight.set(view[0], view[4], view[8]).normalize();
+		this.#cameraUp.set(view[1], view[5], view[9]).normalize();
+		getCameraViewSize(camera, this.#selectedWorldPosition, this.#viewSize, this.#cameraToSelected);
 	}
 };
 //#endregion

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;
@@ -49,6 +50,8 @@ export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
  * `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

@@ -28,6 +28,8 @@ const LOOK_SPEED_SCALE = 36e3;
 * `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 {
@@ -67,8 +69,9 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	}
 	/**
 	* 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.
+	* 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.
@@ -80,25 +83,32 @@ 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);
-		if (move.x !== 0 || move.y !== 0) {
+		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);
-			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;
 				forwardDistance += forward * deltaTime * heightDelta * controls.heightCoef * moveSpeed;
 			}
-			const strafeDistance = move.x * moveMult;
+			const strafeDistance = strafe * moveMult;
 			controls.object.position.x += sinYaw * forwardDistance - cosYaw * strafeDistance;
 			controls.object.position.z += cosYaw * forwardDistance + sinYaw * strafeDistance;
 		}
-		const up = input.buttonValue(buttonMoveUp);
-		const down = input.buttonValue(buttonMoveDown);
-		const climb = (up > buttonDeadzone ? up : 0) - (down > buttonDeadzone ? down : 0);
 		if (climb !== 0) controls.object.position.y += climb * moveMult;
 	}
 	/**

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

@@ -9,7 +9,9 @@ import { TransformControls } from "three/addons/controls/TransformControls.js";
  */
 export type GamepadTransformControlsOptions = GamepadControlsOptions & {
   /**
-   * Screen-relative translation speed multiplier.
+   * Screen-relative translation speed multiplier. `XYZ` uses effective viewport
+   * width and height per second; constrained axes use their mean in world units
+   * per second. Both are multiplied by the processed stick input.
    * @default 1.0
    */
   translateSpeed: number;

package/dist/gamepad-transform-controls.js

@@ -1,6 +1,7 @@
 import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
+import { getCameraViewSize } from "./three-utils.js";
 import { Matrix4, Quaternion, Vector2, Vector3 } from "three";
 //#region src/gamepad-transform-controls.ts
 const DEFAULT_TRANSFORM_OPTIONS = {
@@ -73,6 +74,7 @@ var GamepadTransformControls = class extends GamepadControls {
 	#viewSize;
 	#parentInverse;
 	#cameraWorldPosition;
+	#cameraSpacePosition;
 	#cameraForward;
 	#cameraRight;
 	#cameraUp;
@@ -135,6 +137,7 @@ var GamepadTransformControls = class extends GamepadControls {
 		this.#viewSize = new Vector2();
 		this.#parentInverse = new Matrix4();
 		this.#cameraWorldPosition = new Vector3();
+		this.#cameraSpacePosition = new Vector3();
 		this.#cameraForward = new Vector3();
 		this.#cameraRight = new Vector3();
 		this.#cameraUp = new Vector3();
@@ -847,7 +850,7 @@ var GamepadTransformControls = class extends GamepadControls {
 	*/
 	#updateCameraState(object) {
 		const camera = this.#controls.camera;
-		camera.updateMatrixWorld();
+		camera.updateWorldMatrix(true, false);
 		object.updateWorldMatrix(true, false);
 		this.#cameraRight.setFromMatrixColumn(camera.matrixWorld, 0).normalize();
 		this.#cameraUp.setFromMatrixColumn(camera.matrixWorld, 1).normalize();
@@ -855,25 +858,7 @@ var GamepadTransformControls = class extends GamepadControls {
 		camera.getWorldPosition(this.#cameraWorldPosition);
 		this.#worldPosition.setFromMatrixPosition(object.matrixWorld);
 		this.#eye.copy(this.#cameraWorldPosition).sub(this.#worldPosition).normalize();
-		this.#updateViewSizeAtObjectDepth(camera);
-	}
-	/**
-	* Computes world-space viewport size at the attached object's depth.
-	*
-	* @param camera - TransformControls camera.
-	*/
-	#updateViewSizeAtObjectDepth(camera) {
-		if (this.#isOrthographicCamera(camera)) {
-			this.#viewSize.set(Math.abs(camera.right - camera.left) / camera.zoom, Math.abs(camera.top - camera.bottom) / camera.zoom);
-			return;
-		}
-		if (this.#isPerspectiveCamera(camera)) {
-			const depth = Math.max(Number.EPSILON, this.#worldPosition.subVectors(this.#worldPosition, this.#cameraWorldPosition).dot(this.#cameraForward));
-			const height = 2 * Math.tan(camera.fov * Math.PI / 360) * depth;
-			this.#viewSize.set(height * camera.aspect, height);
-			return;
-		}
-		this.#viewSize.set(1, 1);
+		getCameraViewSize(camera, this.#worldPosition, this.#viewSize, this.#cameraSpacePosition);
 	}
 	/**
 	* Resolves a transform axis letter to a normalized world-space direction.
@@ -1078,24 +1063,6 @@ var GamepadTransformControls = class extends GamepadControls {
 		for (const button of buttons) if (input.wasPressed(button)) startedButtons.add(button);
 		return startedButtons;
 	}
-	/**
-	* Narrows a Three.js camera to `PerspectiveCamera`.
-	*
-	* @param camera - Camera to inspect.
-	* @returns `true` when the camera is perspective.
-	*/
-	#isPerspectiveCamera(camera) {
-		return camera.isPerspectiveCamera === true;
-	}
-	/**
-	* Narrows a Three.js camera to `OrthographicCamera`.
-	*
-	* @param camera - Camera to inspect.
-	* @returns `true` when the camera is orthographic.
-	*/
-	#isOrthographicCamera(camera) {
-		return camera.isOrthographicCamera === true;
-	}
 };
 //#endregion
 export { GamepadTransformControls };

package/dist/three-utils.js

@@ -0,0 +1,27 @@
+//#region src/three-utils.ts
+/**
+* Reads the effective viewport dimensions at a world-space point.
+*
+* The caller updates camera world and projection matrices and owns both reusable
+* vectors. View offsets change dimensions, not the point's accumulated position.
+*
+* @param camera - Camera whose current projection is used.
+* @param worldPosition - World-space point, left unchanged.
+* @param target - Receives viewport width and height in world units.
+* @param cameraPosition - Scratch vector for camera-space depth.
+* @returns The target vector, or a unit viewport for an unknown camera type.
+*/
+const getCameraViewSize = (camera, worldPosition, target, cameraPosition) => {
+	if (camera.isOrthographicCamera === true) {
+		const projection = camera.projectionMatrix.elements;
+		return target.set(Math.abs(2 / projection[0]), Math.abs(2 / projection[5]));
+	}
+	if (camera.isPerspectiveCamera === true) {
+		cameraPosition.copy(worldPosition).applyMatrix4(camera.matrixWorldInverse);
+		const depth = Math.max(Number.EPSILON, -cameraPosition.z);
+		return camera.getViewSize(depth, target);
+	}
+	return target.set(1, 1);
+};
+//#endregion
+export { getCameraViewSize };

package/package.json

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