three-gamepad-controls 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/gamepad-arcball-controls.d.ts +107 -0
- package/dist/gamepad-arcball-controls.js +205 -0
- package/dist/gamepad-trackball-controls.d.ts +85 -0
- package/dist/gamepad-trackball-controls.js +102 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.js +3 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -37,9 +37,11 @@ bun add three-gamepad-controls
|
|
|
37
37
|
## Documentation
|
|
38
38
|
|
|
39
39
|
- [Core](./docs/core.md) — The fundamental building blocks.
|
|
40
|
+
- [GamepadArcballControls](./docs/gamepad-arcball-controls.md) - Gamepad support for `ArcballControls`.
|
|
40
41
|
- [GamepadControls](./docs/gamepad-controls.md) — Abstract base class for custom gamepad controls.
|
|
41
42
|
- [GamepadFirstPersonControls](./docs/gamepad-first-person-controls.md) — Gamepad support for `FirstPersonControls`.
|
|
42
43
|
- [GamepadFlyControls](./docs/gamepad-fly-controls.md) — Gamepad support for `FlyControls`.
|
|
43
44
|
- [GamepadMapControls](./docs/gamepad-map-controls.md) — Gamepad support for `MapControls`.
|
|
44
45
|
- [GamepadOrbitControls](./docs/gamepad-orbit-controls.md) — Gamepad support for `OrbitControls`.
|
|
45
46
|
- [GamepadPointerLockControls](./docs/gamepad-pointer-lock-controls.md) — Gamepad support for `PointerLockControls`.
|
|
47
|
+
- [GamepadTrackballControls](./docs/gamepad-trackball-controls.md) — Gamepad support for `TrackballControls`.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { GamepadControls } from "./gamepad-controls.js";
|
|
2
|
+
import { ArcballControls } from "three/addons/controls/ArcballControls.js";
|
|
3
|
+
|
|
4
|
+
//#region src/gamepad-arcball-controls.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* Configuration for {@link GamepadArcballControls}.
|
|
7
|
+
*
|
|
8
|
+
* Every property has a sensible default, so you only need to pass the properties you want to override.
|
|
9
|
+
*/
|
|
10
|
+
type GamepadArcballControlsOptions = {
|
|
11
|
+
/**
|
|
12
|
+
* Multiplier on `ArcballControls.rotateSpeed` for rotation.
|
|
13
|
+
* @default 1.0
|
|
14
|
+
*/
|
|
15
|
+
rotateSpeed: number;
|
|
16
|
+
/**
|
|
17
|
+
* Multiplier on panning speed.
|
|
18
|
+
* @default 1.0
|
|
19
|
+
*/
|
|
20
|
+
panSpeed: number;
|
|
21
|
+
/**
|
|
22
|
+
* Multiplier on zooming speed.
|
|
23
|
+
* @default 1.0
|
|
24
|
+
*/
|
|
25
|
+
zoomSpeed: number;
|
|
26
|
+
/**
|
|
27
|
+
* Multiplier on z-rotation speed.
|
|
28
|
+
* @default 1.0
|
|
29
|
+
*/
|
|
30
|
+
zRotateSpeed: number;
|
|
31
|
+
/**
|
|
32
|
+
* Axis dead zone threshold in the range `[0, 1]`.
|
|
33
|
+
* @default 0.1
|
|
34
|
+
*/
|
|
35
|
+
deadzone: number;
|
|
36
|
+
/**
|
|
37
|
+
* Axis index for **horizontal** arcball rotation.
|
|
38
|
+
* @default 0 - Left stick X
|
|
39
|
+
*/
|
|
40
|
+
axisRotateX: number;
|
|
41
|
+
/**
|
|
42
|
+
* Axis index for **vertical** arcball rotation.
|
|
43
|
+
* @default 1 - Left stick Y
|
|
44
|
+
*/
|
|
45
|
+
axisRotateY: number;
|
|
46
|
+
/**
|
|
47
|
+
* Axis index for **horizontal** panning.
|
|
48
|
+
* @default 2 - Right stick X
|
|
49
|
+
*/
|
|
50
|
+
axisPanX: number;
|
|
51
|
+
/**
|
|
52
|
+
* Axis index for **vertical** panning.
|
|
53
|
+
* @default 3 - Right stick Y
|
|
54
|
+
*/
|
|
55
|
+
axisPanY: number;
|
|
56
|
+
/**
|
|
57
|
+
* Button index for zooming **in** (analog trigger value used for proportional zoom).
|
|
58
|
+
* @default 6 - Left trigger
|
|
59
|
+
*/
|
|
60
|
+
buttonZoomIn: number;
|
|
61
|
+
/**
|
|
62
|
+
* Button index for zooming **out** (analog trigger value used for proportional zoom).
|
|
63
|
+
* @default 7 - Right trigger
|
|
64
|
+
*/
|
|
65
|
+
buttonZoomOut: number;
|
|
66
|
+
/**
|
|
67
|
+
* Button index for rotating counterclockwise around the camera view axis.
|
|
68
|
+
* @default 4 - Left shoulder
|
|
69
|
+
*/
|
|
70
|
+
buttonZRotateLeft: number;
|
|
71
|
+
/**
|
|
72
|
+
* Button index for rotating clockwise around the camera view axis.
|
|
73
|
+
* @default 5 - Right shoulder
|
|
74
|
+
*/
|
|
75
|
+
buttonZRotateRight: number;
|
|
76
|
+
/**
|
|
77
|
+
* Button index for focusing the point at the center of the view.
|
|
78
|
+
* @default 0 - South face button
|
|
79
|
+
*/
|
|
80
|
+
buttonFocus: number;
|
|
81
|
+
};
|
|
82
|
+
/**
|
|
83
|
+
* Adds gamepad support to Three.js `ArcballControls`.
|
|
84
|
+
*
|
|
85
|
+
* Call `update()` inside the render loop to poll gamepad input and apply
|
|
86
|
+
* Arcball transformations. The wrapped `ArcballControls.update()` is only
|
|
87
|
+
* needed after manual camera or target changes, matching Arcball's native API.
|
|
88
|
+
*/
|
|
89
|
+
declare class GamepadArcballControls extends GamepadControls {
|
|
90
|
+
#private;
|
|
91
|
+
/**
|
|
92
|
+
* @param controls - A Three.js `ArcballControls` instance.
|
|
93
|
+
* @param options - Optional overrides for the default behavior.
|
|
94
|
+
* Any property not provided falls back to its default value.
|
|
95
|
+
*/
|
|
96
|
+
constructor(controls: ArcballControls, options?: Partial<GamepadArcballControlsOptions>);
|
|
97
|
+
/**
|
|
98
|
+
* Maps the current gamepad state to `ArcballControls` rotation, pan, zoom,
|
|
99
|
+
* z-rotation, and center focus.
|
|
100
|
+
*
|
|
101
|
+
* @param deltaTime - Seconds since the last frame.
|
|
102
|
+
* @param gamepad - Fresh gamepad snapshot provided by the base class.
|
|
103
|
+
*/
|
|
104
|
+
protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
|
|
105
|
+
}
|
|
106
|
+
//#endregion
|
|
107
|
+
export { GamepadArcballControls, GamepadArcballControlsOptions };
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
|
|
2
|
+
import { GamepadControls } from "./gamepad-controls.js";
|
|
3
|
+
import { Vector2, Vector3 } from "three";
|
|
4
|
+
//#region src/gamepad-arcball-controls.ts
|
|
5
|
+
/**
|
|
6
|
+
* Default options merged in the constructor when no explicit configuration is provided.
|
|
7
|
+
*/
|
|
8
|
+
const DEFAULT_ARCBALL_OPTIONS = {
|
|
9
|
+
rotateSpeed: 1,
|
|
10
|
+
panSpeed: 1,
|
|
11
|
+
zoomSpeed: 1,
|
|
12
|
+
zRotateSpeed: 1,
|
|
13
|
+
deadzone: .1,
|
|
14
|
+
axisRotateX: GAMEPAD_AXIS.LeftX,
|
|
15
|
+
axisRotateY: GAMEPAD_AXIS.LeftY,
|
|
16
|
+
axisPanX: GAMEPAD_AXIS.RightX,
|
|
17
|
+
axisPanY: GAMEPAD_AXIS.RightY,
|
|
18
|
+
buttonZoomIn: GAMEPAD_BUTTON.LeftTrigger,
|
|
19
|
+
buttonZoomOut: GAMEPAD_BUTTON.RightTrigger,
|
|
20
|
+
buttonZRotateLeft: GAMEPAD_BUTTON.LeftShoulder,
|
|
21
|
+
buttonZRotateRight: GAMEPAD_BUTTON.RightShoulder,
|
|
22
|
+
buttonFocus: GAMEPAD_BUTTON.South
|
|
23
|
+
};
|
|
24
|
+
const ZOOM_NOTCHES_PER_SECOND = 8;
|
|
25
|
+
/**
|
|
26
|
+
* Adds gamepad support to Three.js `ArcballControls`.
|
|
27
|
+
*
|
|
28
|
+
* Call `update()` inside the render loop to poll gamepad input and apply
|
|
29
|
+
* Arcball transformations. The wrapped `ArcballControls.update()` is only
|
|
30
|
+
* needed after manual camera or target changes, matching Arcball's native API.
|
|
31
|
+
*/
|
|
32
|
+
var GamepadArcballControls = class extends GamepadControls {
|
|
33
|
+
#controls;
|
|
34
|
+
#options;
|
|
35
|
+
#centerNdc;
|
|
36
|
+
#panStart;
|
|
37
|
+
#panEnd;
|
|
38
|
+
#rotationAxis;
|
|
39
|
+
#cameraForward;
|
|
40
|
+
#cameraRight;
|
|
41
|
+
#previousUp;
|
|
42
|
+
#focusButtonPressed = false;
|
|
43
|
+
#wasInteracting = false;
|
|
44
|
+
/**
|
|
45
|
+
* @param controls - A Three.js `ArcballControls` instance.
|
|
46
|
+
* @param options - Optional overrides for the default behavior.
|
|
47
|
+
* Any property not provided falls back to its default value.
|
|
48
|
+
*/
|
|
49
|
+
constructor(controls, options) {
|
|
50
|
+
super();
|
|
51
|
+
this.#controls = controls;
|
|
52
|
+
this.#options = {
|
|
53
|
+
...DEFAULT_ARCBALL_OPTIONS,
|
|
54
|
+
...options
|
|
55
|
+
};
|
|
56
|
+
this.#centerNdc = new Vector2(0, 0);
|
|
57
|
+
this.#panStart = new Vector3();
|
|
58
|
+
this.#panEnd = new Vector3();
|
|
59
|
+
this.#rotationAxis = new Vector3();
|
|
60
|
+
this.#cameraForward = new Vector3();
|
|
61
|
+
this.#cameraRight = new Vector3();
|
|
62
|
+
this.#previousUp = new Vector3();
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Maps the current gamepad state to `ArcballControls` rotation, pan, zoom,
|
|
66
|
+
* z-rotation, and center focus.
|
|
67
|
+
*
|
|
68
|
+
* @param deltaTime - Seconds since the last frame.
|
|
69
|
+
* @param gamepad - Fresh gamepad snapshot provided by the base class.
|
|
70
|
+
*/
|
|
71
|
+
onUpdate(deltaTime, gamepad) {
|
|
72
|
+
const controls = this.#controls;
|
|
73
|
+
const { rotateSpeed, panSpeed, zoomSpeed, zRotateSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
|
|
74
|
+
const focusPoint = this.#consumeFocusPoint(gamepad, buttonFocus);
|
|
75
|
+
if (!controls.enabled) {
|
|
76
|
+
this.#endInteraction();
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
const rotateX = controls.enableRotate ? this.#applyDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone) : 0;
|
|
80
|
+
const rotateY = controls.enableRotate ? this.#applyDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone) : 0;
|
|
81
|
+
const panX = controls.enablePan ? this.#applyDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone) : 0;
|
|
82
|
+
const panY = controls.enablePan ? this.#applyDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone) : 0;
|
|
83
|
+
const zoom = controls.enableZoom ? this.#getButtonValue(gamepad, buttonZoomIn) - this.#getButtonValue(gamepad, buttonZoomOut) : 0;
|
|
84
|
+
const zRotation = controls.enableRotate ? this.#getButtonValue(gamepad, buttonZRotateLeft) - this.#getButtonValue(gamepad, buttonZRotateRight) : 0;
|
|
85
|
+
const activeInput = rotateX !== 0 || rotateY !== 0 || panX !== 0 || panY !== 0 || Math.abs(zoom) > deadzone || Math.abs(zRotation) > deadzone;
|
|
86
|
+
if (!activeInput && focusPoint === null) {
|
|
87
|
+
this.#endInteraction();
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
if (!this.#wasInteracting) controls.dispatchEvent({ type: "start" });
|
|
91
|
+
let changed = false;
|
|
92
|
+
changed = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) || changed;
|
|
93
|
+
changed = this.#applyPan(deltaTime, panX, panY, panSpeed) || changed;
|
|
94
|
+
changed = this.#applyZoom(deltaTime, zoom, zoomSpeed, deadzone) || changed;
|
|
95
|
+
changed = this.#applyZRotation(deltaTime, zRotation, zRotateSpeed, deadzone) || changed;
|
|
96
|
+
changed = this.#applyFocus(focusPoint) || changed;
|
|
97
|
+
if (changed) {
|
|
98
|
+
controls.update();
|
|
99
|
+
controls.updateMatrixState();
|
|
100
|
+
controls.dispatchEvent({ type: "change" });
|
|
101
|
+
}
|
|
102
|
+
this.#wasInteracting = activeInput;
|
|
103
|
+
if (!activeInput) this.#endInteraction();
|
|
104
|
+
}
|
|
105
|
+
#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) {
|
|
106
|
+
if (rotateX === 0 && rotateY === 0) return false;
|
|
107
|
+
const controls = this.#controls;
|
|
108
|
+
const amount = controls.rotateSpeed * rotateSpeed * deltaTime * Math.PI;
|
|
109
|
+
let changed = false;
|
|
110
|
+
if (rotateX !== 0) {
|
|
111
|
+
this.#rotationAxis.copy(controls.object.up).normalize();
|
|
112
|
+
changed = this.#applyRotationAroundAxis(this.#rotationAxis, rotateX * amount) || changed;
|
|
113
|
+
}
|
|
114
|
+
if (rotateY !== 0) {
|
|
115
|
+
controls.object.getWorldDirection(this.#cameraForward);
|
|
116
|
+
this.#cameraRight.crossVectors(this.#cameraForward, controls.object.up).normalize();
|
|
117
|
+
changed = this.#applyRotationAroundAxis(this.#cameraRight, -rotateY * amount) || changed;
|
|
118
|
+
}
|
|
119
|
+
return changed;
|
|
120
|
+
}
|
|
121
|
+
#applyRotationAroundAxis(axis, angle) {
|
|
122
|
+
if (axis.lengthSq() === 0 || angle === 0) return false;
|
|
123
|
+
const controls = this.#controls;
|
|
124
|
+
controls.updateMatrixState();
|
|
125
|
+
this.#previousUp.copy(controls.object.up);
|
|
126
|
+
const changed = this.#applyTransform(controls.rotate(axis, angle));
|
|
127
|
+
if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(axis, -angle);
|
|
128
|
+
return changed;
|
|
129
|
+
}
|
|
130
|
+
#applyPan(deltaTime, panX, panY, panSpeed) {
|
|
131
|
+
if (panX === 0 && panY === 0) return false;
|
|
132
|
+
const controls = this.#controls;
|
|
133
|
+
const distance = controls._tbRadius * panSpeed * deltaTime;
|
|
134
|
+
controls.updateMatrixState();
|
|
135
|
+
this.#panStart.set(0, 0, 0);
|
|
136
|
+
this.#panEnd.set(panX * distance, panY * distance, 0);
|
|
137
|
+
return this.#applyTransform(controls.pan(this.#panStart, this.#panEnd));
|
|
138
|
+
}
|
|
139
|
+
#applyZoom(deltaTime, zoom, zoomSpeed, deadzone) {
|
|
140
|
+
if (Math.abs(zoom) <= deadzone || this.#controls.scaleFactor <= 0) return false;
|
|
141
|
+
const controls = this.#controls;
|
|
142
|
+
const size = controls.scaleFactor ** (zoom * zoomSpeed * deltaTime * ZOOM_NOTCHES_PER_SECOND);
|
|
143
|
+
if (!Number.isFinite(size) || size <= 0 || size === 1) return false;
|
|
144
|
+
controls.updateMatrixState();
|
|
145
|
+
return this.#applyTransform(controls.scale(size, controls._gizmos.position));
|
|
146
|
+
}
|
|
147
|
+
#applyZRotation(deltaTime, zRotation, zRotateSpeed, deadzone) {
|
|
148
|
+
if (Math.abs(zRotation) <= deadzone) return false;
|
|
149
|
+
const controls = this.#controls;
|
|
150
|
+
const angle = zRotation * zRotateSpeed * deltaTime * Math.PI;
|
|
151
|
+
controls.updateMatrixState();
|
|
152
|
+
controls.object.getWorldDirection(controls._rotationAxis);
|
|
153
|
+
this.#previousUp.copy(controls.object.up);
|
|
154
|
+
const changed = this.#applyTransform(controls.zRotate(controls._gizmos.position, angle));
|
|
155
|
+
if (changed) controls.object.up.copy(this.#previousUp).applyAxisAngle(controls._rotationAxis, angle);
|
|
156
|
+
return changed;
|
|
157
|
+
}
|
|
158
|
+
#applyFocus(point) {
|
|
159
|
+
if (point === null) return false;
|
|
160
|
+
const controls = this.#controls;
|
|
161
|
+
controls.updateMatrixState();
|
|
162
|
+
controls.focus(point, controls.scaleFactor);
|
|
163
|
+
controls.updateMatrixState();
|
|
164
|
+
return true;
|
|
165
|
+
}
|
|
166
|
+
#applyTransform(transformation) {
|
|
167
|
+
if (transformation === void 0) return false;
|
|
168
|
+
this.#controls.applyTransformMatrix(transformation);
|
|
169
|
+
this.#controls.updateMatrixState();
|
|
170
|
+
return true;
|
|
171
|
+
}
|
|
172
|
+
#consumeFocusPoint(gamepad, buttonFocus) {
|
|
173
|
+
const controls = this.#controls;
|
|
174
|
+
const focusPressed = this.#getButtonPressed(gamepad, buttonFocus);
|
|
175
|
+
const shouldFocus = focusPressed && !this.#focusButtonPressed;
|
|
176
|
+
this.#focusButtonPressed = focusPressed;
|
|
177
|
+
if (!shouldFocus || !controls.enabled || !controls.enablePan || !controls.enableFocus || controls.scene === null) return null;
|
|
178
|
+
return controls.unprojectOnObj(this.#centerNdc, controls.object);
|
|
179
|
+
}
|
|
180
|
+
#endInteraction() {
|
|
181
|
+
if (!this.#wasInteracting) return;
|
|
182
|
+
this.#controls.dispatchEvent({ type: "end" });
|
|
183
|
+
this.#wasInteracting = false;
|
|
184
|
+
}
|
|
185
|
+
#getButtonValue(gamepad, button) {
|
|
186
|
+
const gamepadButton = gamepad.buttons[button];
|
|
187
|
+
if (gamepadButton === void 0) return 0;
|
|
188
|
+
if (gamepadButton.value !== 0) return gamepadButton.value;
|
|
189
|
+
return gamepadButton.pressed ? 1 : 0;
|
|
190
|
+
}
|
|
191
|
+
#getButtonPressed(gamepad, button) {
|
|
192
|
+
return gamepad.buttons[button]?.pressed ?? false;
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
|
|
196
|
+
*
|
|
197
|
+
* @param value - Raw axis or trigger value, typically in `[-1, 1]`.
|
|
198
|
+
* @param threshold - Dead zone size; values below this magnitude are zeroed.
|
|
199
|
+
*/
|
|
200
|
+
#applyDeadzone(value, threshold) {
|
|
201
|
+
return Math.abs(value) < threshold ? 0 : value;
|
|
202
|
+
}
|
|
203
|
+
};
|
|
204
|
+
//#endregion
|
|
205
|
+
export { GamepadArcballControls };
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { GamepadControls } from "./gamepad-controls.js";
|
|
2
|
+
import { TrackballControls } from "three/addons/controls/TrackballControls.js";
|
|
3
|
+
|
|
4
|
+
//#region src/gamepad-trackball-controls.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* Configuration for {@link GamepadTrackballControls}.
|
|
7
|
+
*
|
|
8
|
+
* Every property has a sensible default, so you only need to pass the properties you want to override.
|
|
9
|
+
*/
|
|
10
|
+
type GamepadTrackballControlsOptions = {
|
|
11
|
+
/**
|
|
12
|
+
* Multiplier on `TrackballControls.rotateSpeed` for rotation.
|
|
13
|
+
* @default 1.0
|
|
14
|
+
*/
|
|
15
|
+
rotateSpeed: number;
|
|
16
|
+
/**
|
|
17
|
+
* Multiplier on `TrackballControls.panSpeed` for panning.
|
|
18
|
+
* @default 1.0
|
|
19
|
+
*/
|
|
20
|
+
panSpeed: number;
|
|
21
|
+
/**
|
|
22
|
+
* Multiplier on `TrackballControls.zoomSpeed` for zooming.
|
|
23
|
+
* @default 1.0
|
|
24
|
+
*/
|
|
25
|
+
zoomSpeed: number;
|
|
26
|
+
/**
|
|
27
|
+
* Axis dead zone threshold in the range `[0, 1]`.
|
|
28
|
+
* @default 0.1
|
|
29
|
+
*/
|
|
30
|
+
deadzone: number;
|
|
31
|
+
/**
|
|
32
|
+
* Axis index for **horizontal** trackball rotation.
|
|
33
|
+
* @default 0 - Left stick X
|
|
34
|
+
*/
|
|
35
|
+
axisRotateX: number;
|
|
36
|
+
/**
|
|
37
|
+
* Axis index for **vertical** trackball rotation.
|
|
38
|
+
* @default 1 - Left stick Y
|
|
39
|
+
*/
|
|
40
|
+
axisRotateY: number;
|
|
41
|
+
/**
|
|
42
|
+
* Axis index for **horizontal** panning.
|
|
43
|
+
* @default 2 - Right stick X
|
|
44
|
+
*/
|
|
45
|
+
axisPanX: number;
|
|
46
|
+
/**
|
|
47
|
+
* Axis index for **vertical** panning.
|
|
48
|
+
* @default 3 - Right stick Y
|
|
49
|
+
*/
|
|
50
|
+
axisPanY: number;
|
|
51
|
+
/**
|
|
52
|
+
* Button index for zooming **in** (analog trigger value used for proportional zoom).
|
|
53
|
+
* @default 6 - Left trigger
|
|
54
|
+
*/
|
|
55
|
+
buttonZoomIn: number;
|
|
56
|
+
/**
|
|
57
|
+
* Button index for zooming **out** (analog trigger value used for proportional zoom).
|
|
58
|
+
* @default 7 - Right trigger
|
|
59
|
+
*/
|
|
60
|
+
buttonZoomOut: number;
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* Adds gamepad support to Three.js `TrackballControls`.
|
|
64
|
+
*
|
|
65
|
+
* Call `update()` inside the render loop **before** `TrackballControls.update()`.
|
|
66
|
+
* Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
|
|
67
|
+
*/
|
|
68
|
+
declare class GamepadTrackballControls extends GamepadControls {
|
|
69
|
+
#private;
|
|
70
|
+
/**
|
|
71
|
+
* @param controls - A Three.js `TrackballControls` instance.
|
|
72
|
+
* @param options - Optional overrides for the default behavior.
|
|
73
|
+
* Any property not provided falls back to its default value.
|
|
74
|
+
*/
|
|
75
|
+
constructor(controls: TrackballControls, options?: Partial<GamepadTrackballControlsOptions>);
|
|
76
|
+
/**
|
|
77
|
+
* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
|
|
78
|
+
*
|
|
79
|
+
* @param deltaTime - Seconds since the last frame.
|
|
80
|
+
* @param gamepad - Fresh gamepad snapshot provided by the base class.
|
|
81
|
+
*/
|
|
82
|
+
protected onUpdate(deltaTime: number, gamepad: Gamepad): void;
|
|
83
|
+
}
|
|
84
|
+
//#endregion
|
|
85
|
+
export { GamepadTrackballControls, GamepadTrackballControlsOptions };
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
|
|
2
|
+
import { GamepadControls } from "./gamepad-controls.js";
|
|
3
|
+
//#region src/gamepad-trackball-controls.ts
|
|
4
|
+
/**
|
|
5
|
+
* Default options merged in the constructor when no explicit configuration is provided.
|
|
6
|
+
*/
|
|
7
|
+
const DEFAULT_TRACKBALL_OPTIONS = {
|
|
8
|
+
rotateSpeed: 1,
|
|
9
|
+
panSpeed: 1,
|
|
10
|
+
zoomSpeed: 1,
|
|
11
|
+
deadzone: .1,
|
|
12
|
+
axisRotateX: GAMEPAD_AXIS.LeftX,
|
|
13
|
+
axisRotateY: GAMEPAD_AXIS.LeftY,
|
|
14
|
+
axisPanX: GAMEPAD_AXIS.RightX,
|
|
15
|
+
axisPanY: GAMEPAD_AXIS.RightY,
|
|
16
|
+
buttonZoomIn: GAMEPAD_BUTTON.LeftTrigger,
|
|
17
|
+
buttonZoomOut: GAMEPAD_BUTTON.RightTrigger
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Adds gamepad support to Three.js `TrackballControls`.
|
|
21
|
+
*
|
|
22
|
+
* Call `update()` inside the render loop **before** `TrackballControls.update()`.
|
|
23
|
+
* Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
|
|
24
|
+
*/
|
|
25
|
+
var GamepadTrackballControls = class extends GamepadControls {
|
|
26
|
+
#controls;
|
|
27
|
+
#options;
|
|
28
|
+
/**
|
|
29
|
+
* @param controls - A Three.js `TrackballControls` instance.
|
|
30
|
+
* @param options - Optional overrides for the default behavior.
|
|
31
|
+
* Any property not provided falls back to its default value.
|
|
32
|
+
*/
|
|
33
|
+
constructor(controls, options) {
|
|
34
|
+
super();
|
|
35
|
+
this.#controls = controls;
|
|
36
|
+
this.#options = {
|
|
37
|
+
...DEFAULT_TRACKBALL_OPTIONS,
|
|
38
|
+
...options
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
|
|
43
|
+
*
|
|
44
|
+
* @param deltaTime - Seconds since the last frame.
|
|
45
|
+
* @param gamepad - Fresh gamepad snapshot provided by the base class.
|
|
46
|
+
*/
|
|
47
|
+
onUpdate(deltaTime, gamepad) {
|
|
48
|
+
const { rotateSpeed, panSpeed, zoomSpeed, deadzone, axisRotateX, axisRotateY, axisPanX, axisPanY, buttonZoomIn, buttonZoomOut } = this.#options;
|
|
49
|
+
this.#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY);
|
|
50
|
+
this.#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY);
|
|
51
|
+
this.#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut);
|
|
52
|
+
}
|
|
53
|
+
#queueRotation(deltaTime, gamepad, rotateSpeed, deadzone, axisRotateX, axisRotateY) {
|
|
54
|
+
const controls = this.#controls;
|
|
55
|
+
if (controls.noRotate) {
|
|
56
|
+
controls._movePrev.copy(controls._moveCurr);
|
|
57
|
+
controls._lastAngle = 0;
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
const rotX = this.#applyDeadzone(gamepad.axes[axisRotateX] ?? 0, deadzone);
|
|
61
|
+
const rotY = this.#applyDeadzone(gamepad.axes[axisRotateY] ?? 0, deadzone);
|
|
62
|
+
if (rotX === 0 && rotY === 0) return;
|
|
63
|
+
const scale = rotateSpeed * deltaTime * Math.PI;
|
|
64
|
+
controls._moveCurr.x += rotX * scale;
|
|
65
|
+
controls._moveCurr.y += -rotY * scale;
|
|
66
|
+
}
|
|
67
|
+
#queuePan(deltaTime, gamepad, panSpeed, deadzone, axisPanX, axisPanY) {
|
|
68
|
+
const controls = this.#controls;
|
|
69
|
+
if (controls.noPan) {
|
|
70
|
+
controls._panStart.copy(controls._panEnd);
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
const panX = this.#applyDeadzone(gamepad.axes[axisPanX] ?? 0, deadzone);
|
|
74
|
+
const panY = this.#applyDeadzone(gamepad.axes[axisPanY] ?? 0, deadzone);
|
|
75
|
+
if (panX === 0 && panY === 0) return;
|
|
76
|
+
const scale = panSpeed * deltaTime;
|
|
77
|
+
controls._panEnd.x += panX * scale;
|
|
78
|
+
controls._panEnd.y += panY * scale;
|
|
79
|
+
}
|
|
80
|
+
#queueZoom(deltaTime, gamepad, zoomSpeed, deadzone, buttonZoomIn, buttonZoomOut) {
|
|
81
|
+
const controls = this.#controls;
|
|
82
|
+
if (controls.noZoom) {
|
|
83
|
+
controls._zoomStart.copy(controls._zoomEnd);
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const triggerIn = gamepad.buttons[buttonZoomIn]?.value ?? 0;
|
|
87
|
+
const triggerOut = gamepad.buttons[buttonZoomOut]?.value ?? 0;
|
|
88
|
+
if (triggerIn <= deadzone && triggerOut <= deadzone) return;
|
|
89
|
+
controls._zoomEnd.y += (triggerOut - triggerIn) * zoomSpeed * deltaTime;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Returns `value` unchanged, or `0` if below the dead zone `threshold`.
|
|
93
|
+
*
|
|
94
|
+
* @param value - Raw axis or trigger value, typically in `[-1, 1]`.
|
|
95
|
+
* @param threshold - Dead zone size; values below this magnitude are zeroed.
|
|
96
|
+
*/
|
|
97
|
+
#applyDeadzone(value, threshold) {
|
|
98
|
+
return Math.abs(value) < threshold ? 0 : value;
|
|
99
|
+
}
|
|
100
|
+
};
|
|
101
|
+
//#endregion
|
|
102
|
+
export { GamepadTrackballControls };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue } from "./core.js";
|
|
2
2
|
import { GamepadControls, GamepadControlsEventMap } from "./gamepad-controls.js";
|
|
3
|
+
import { GamepadArcballControls, GamepadArcballControlsOptions } from "./gamepad-arcball-controls.js";
|
|
3
4
|
import { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions } from "./gamepad-first-person-controls.js";
|
|
4
5
|
import { GamepadFlyControls, GamepadFlyControlsOptions } from "./gamepad-fly-controls.js";
|
|
5
6
|
import { GamepadOrbitControls, GamepadOrbitControlsOptions } from "./gamepad-orbit-controls.js";
|
|
6
7
|
import { GamepadMapControls } from "./gamepad-map-controls.js";
|
|
7
8
|
import { GamepadPointerLockControls, GamepadPointerLockControlsOptions } from "./gamepad-pointer-lock-controls.js";
|
|
8
|
-
|
|
9
|
+
import { GamepadTrackballControls, GamepadTrackballControlsOptions } from "./gamepad-trackball-controls.js";
|
|
10
|
+
export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadArcballControlsOptions, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, GamepadControls, GamepadControlsEventMap, GamepadFirstPersonControls, GamepadFirstPersonControlsOptions, GamepadFlyControls, GamepadFlyControlsOptions, GamepadMapControls, GamepadOrbitControls, GamepadOrbitControlsOptions, GamepadPointerLockControls, GamepadPointerLockControlsOptions, GamepadTrackballControls, GamepadTrackballControlsOptions };
|
package/dist/index.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { GAMEPAD_AXIS, GAMEPAD_BUTTON } from "./core.js";
|
|
2
2
|
import { GamepadControls } from "./gamepad-controls.js";
|
|
3
|
+
import { GamepadArcballControls } from "./gamepad-arcball-controls.js";
|
|
3
4
|
import { GamepadFirstPersonControls } from "./gamepad-first-person-controls.js";
|
|
4
5
|
import { GamepadFlyControls } from "./gamepad-fly-controls.js";
|
|
5
6
|
import { GamepadOrbitControls } from "./gamepad-orbit-controls.js";
|
|
6
7
|
import { GamepadMapControls } from "./gamepad-map-controls.js";
|
|
7
8
|
import { GamepadPointerLockControls } from "./gamepad-pointer-lock-controls.js";
|
|
8
|
-
|
|
9
|
+
import { GamepadTrackballControls } from "./gamepad-trackball-controls.js";
|
|
10
|
+
export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadArcballControls, GamepadControls, GamepadFirstPersonControls, GamepadFlyControls, GamepadMapControls, GamepadOrbitControls, GamepadPointerLockControls, GamepadTrackballControls };
|
package/package.json
CHANGED