three-player-controller 0.3.4 → 0.3.6
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 +215 -81
- package/dist/index.d.mts +25 -4
- package/dist/index.d.ts +25 -4
- package/dist/index.js +1024 -5330
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +844 -196
- package/dist/index.mjs.map +1 -1
- package/package.json +18 -9
- package/dist/rapier.es-XQHNYU2P.mjs +0 -4966
- package/dist/rapier.es-XQHNYU2P.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -4,21 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
[![NPM Package][npm]][npm-url]
|
|
6
6
|
|
|
7
|
-
轻量的第三人称 / 第一人称玩家控制器，开箱即用，基于 three.js 和 three-mesh-bvh 实现人物胶囊体碰撞、BVH
|
|
8
|
-
|
|
9
|
-
# 安装
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
npm install three-player-controller
|
|
13
|
-
```
|
|
7
|
+
轻量的第三人称 / 第一人称玩家控制器，开箱即用，基于 three.js 和 three-mesh-bvh 实现人物胶囊体碰撞、BVH 碰撞检测、人物动画、第一/三人称切换与相机避障，利用 three-mesh-bvh 优化碰撞检测性能，大场景下高性能运行。
|
|
14
8
|
|
|
15
9
|
# 示例
|
|
16
10
|
|
|
17
|
-
- [
|
|
18
|
-
|
|
19
|
-
- [3dtiles 场景](https://hh-hang.github.io/three-player-controller/3dtilesScene.html)
|
|
20
|
-
|
|
21
|
-
- [3dtiles 自定义](https://hh-hang.github.io/three-player-controller/3dtilesCustomize.html)
|
|
11
|
+
- [示例](https://hh-hang.github.io/three-player-controller/index.html)
|
|
22
12
|
|
|
23
13
|
### 普通控制
|
|
24
14
|
|
|
@@ -28,10 +18,49 @@ npm install three-player-controller
|
|
|
28
18
|
|
|
29
19
|
|
|
30
20
|
|
|
21
|
+
### 车辆控制
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
31
25
|
### 移动端控制演示
|
|
32
26
|
|
|
33
27
|
|
|
34
28
|
|
|
29
|
+
# 安装
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install three-player-controller three three-mesh-bvh
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 可选依赖
|
|
36
|
+
|
|
37
|
+
如果需要使用**车辆控制**，请安装 Rapier：
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @dimforge/rapier3d-compat
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
如果需要使用**移动端控制**，请安装 nipplejs：
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install nipplejs
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
# 本地运行示例
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# 克隆仓库
|
|
53
|
+
git clone https://github.com/hh-hang/three-player-controller.git
|
|
54
|
+
|
|
55
|
+
# 安装依赖
|
|
56
|
+
npm install
|
|
57
|
+
|
|
58
|
+
# 运行开发服务器
|
|
59
|
+
npm run dev
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
在浏览器访问 `http://localhost:5173/three-player-controller/` 查看示例。
|
|
63
|
+
|
|
35
64
|
# 使用
|
|
36
65
|
|
|
37
66
|
```js
|
|
@@ -41,19 +70,39 @@ import { playerController } from "three-player-controller";
|
|
|
41
70
|
const player = playerController();
|
|
42
71
|
|
|
43
72
|
// 初始化玩家控制器
|
|
44
|
-
player.init({
|
|
73
|
+
await player.init({
|
|
45
74
|
scene, // three.js 场景
|
|
46
75
|
camera, // three.js 相机
|
|
47
76
|
controls, // three.js 控制器
|
|
48
77
|
playerModel: {
|
|
49
78
|
url: "./glb/person.glb", // 模型路径
|
|
50
|
-
scale: 0.001,
|
|
51
|
-
idleAnim: "
|
|
52
|
-
walkAnim: "
|
|
53
|
-
runAnim: "
|
|
54
|
-
jumpAnim: "
|
|
79
|
+
scale: 0.001, // 模型缩放
|
|
80
|
+
idleAnim: "idle", // Idle 动画名
|
|
81
|
+
walkAnim: "walk", // Walk 动画名
|
|
82
|
+
runAnim: "run", // Run 动画名
|
|
83
|
+
jumpAnim: "jump", // Jump 动画名
|
|
55
84
|
},
|
|
56
|
-
initPos:
|
|
85
|
+
initPos: new THREE.Vector3(0, 0, 0), // 初始位置
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
// 加入车辆控制
|
|
89
|
+
await player.loadVehicleModel({
|
|
90
|
+
url: "./glb/bugatti.glb",
|
|
91
|
+
scale: 0.1,
|
|
92
|
+
position: new Vector3(22, 3.69, 14.5),
|
|
93
|
+
wheelsNames: [
|
|
94
|
+
"Wheel_LF", // 前左
|
|
95
|
+
"Wheel_RF", // 前右
|
|
96
|
+
"Wheel_LR", // 后左
|
|
97
|
+
"Wheel_RR", // 后右
|
|
98
|
+
],
|
|
99
|
+
animations: {
|
|
100
|
+
openDoorAnim: "openDoorLF",
|
|
101
|
+
},
|
|
102
|
+
boardingPoint: new Vector3(0.5, 0, 1.8),
|
|
103
|
+
seatOffset: new Vector3(0, 0.6, 0),
|
|
104
|
+
chassisRatio: 0.15,
|
|
105
|
+
suspensionRestLengthRatio: 0.2,
|
|
57
106
|
});
|
|
58
107
|
|
|
59
108
|
// 渲染循环调用
|
|
@@ -68,41 +117,77 @@ player.update();
|
|
|
68
117
|
|
|
69
118
|
```ts
|
|
70
119
|
export function playerController(): {
|
|
120
|
+
// 初始化
|
|
71
121
|
init: (opts: PlayerControllerOptions, callback?: () => void) => void;
|
|
72
|
-
|
|
122
|
+
// 加载车辆模型
|
|
123
|
+
loadVehicleModel: (params: VehicleOptions) => void;
|
|
124
|
+
// 切换人物模型
|
|
125
|
+
switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => void;
|
|
126
|
+
// 切换第一/第三人称
|
|
73
127
|
changeView: () => void;
|
|
128
|
+
// 复位玩家位置
|
|
74
129
|
reset: (pos?: THREE.Vector3) => void;
|
|
130
|
+
// 每帧调用
|
|
75
131
|
update: (dt?: number) => void;
|
|
132
|
+
// 销毁控制器
|
|
76
133
|
destroy: () => void;
|
|
77
|
-
|
|
134
|
+
// 外部输入控制
|
|
135
|
+
setInput: (input: PlayerInput) => void;
|
|
136
|
+
// 获取人物当前位置
|
|
137
|
+
getPosition: () => THREE.Vector3;
|
|
138
|
+
// 获取屏幕中心射线与场景的交点
|
|
139
|
+
getCenterScreenRaycastHit: () => THREE.Intersection | undefined;
|
|
140
|
+
// 获取人物模型
|
|
78
141
|
getPerson: () => THREE.Object3D | null;
|
|
142
|
+
// 获取当前驾驶的车辆实例
|
|
79
143
|
getActiveVehicle: () => VehicleInstance | null;
|
|
144
|
+
// 获取所有车辆实例
|
|
80
145
|
getAllVehicles: () => VehicleInstance[];
|
|
146
|
+
// 动态参数调整
|
|
147
|
+
setMouseSensitivity: (mouseSensity: number) => void;
|
|
148
|
+
setGravity: (gravity: number) => void;
|
|
149
|
+
setJumpHeight: (jumpHeight: number) => void;
|
|
150
|
+
setPlayerSpeed: (playerSpeed: number) => void;
|
|
151
|
+
setPlayerFlySpeed: (playerFlySpeed: number) => void;
|
|
152
|
+
setMinCamDistance: (minCamDistance: number) => void;
|
|
153
|
+
setMaxCamDistance: (maxCamDistance: number) => void;
|
|
154
|
+
setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
|
|
155
|
+
setEnableZoom: (enableZoom: boolean) => void;
|
|
156
|
+
setOverShoulderView: (enable: boolean) => void;
|
|
157
|
+
setPlayerScale: (scale: number) => void;
|
|
158
|
+
setDebug: (debug: boolean) => void;
|
|
81
159
|
};
|
|
82
160
|
```
|
|
83
161
|
|
|
84
162
|
### 方法说明
|
|
85
163
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
164
|
+
| 方法 | 说明 |
|
|
165
|
+
|------|------|
|
|
166
|
+
| `init(opts, callback?)` | 初始化控制器，`callback` 在资源加载完成后调用 |
|
|
167
|
+
| `loadVehicleModel(params)` | 加载并初始化一辆车辆，可多次调用加载多辆 |
|
|
168
|
+
| `switchPlayerModel(model)` | 运行时切换人物模型，保留当前位置与朝向 |
|
|
169
|
+
| `changeView()` | 在第一/第三人称间切换 |
|
|
170
|
+
| `reset(pos?)` | 复位玩家到指定位置（默认初始位置） |
|
|
171
|
+
| `update(dt?)` | 每帧调用，驱动物理与动画 |
|
|
172
|
+
| `destroy()` | 销毁控制器，释放所有资源 |
|
|
173
|
+
| `setInput(input)` | 外部传入输入状态，适用于自定义按键或手柄接入 |
|
|
174
|
+
| `getPosition()` | 获取人物当前世界坐标 |
|
|
175
|
+
| `getCenterScreenRaycastHit()` | 获取屏幕中心射线与碰撞体的交点，可用于瞄准/交互检测 |
|
|
176
|
+
| `getPerson()` | 获取人物模型对象 |
|
|
177
|
+
| `getActiveVehicle()` | 获取当前正在驾驶的车辆实例 |
|
|
178
|
+
| `getAllVehicles()` | 获取所有已加载的车辆实例数组 |
|
|
179
|
+
| `setMouseSensitivity(v)` | 设置鼠标灵敏度 |
|
|
180
|
+
| `setGravity(v)` | 设置重力（传入基准值，内部自动乘以 scale） |
|
|
181
|
+
| `setJumpHeight(v)` | 设置跳跃高度（传入基准值，内部自动乘以 scale） |
|
|
182
|
+
| `setPlayerSpeed(v)` | 设置移动速度（传入基准值，内部自动乘以 scale） |
|
|
183
|
+
| `setPlayerFlySpeed(v)` | 设置飞行速度（传入基准值，内部自动乘以 scale） |
|
|
184
|
+
| `setMinCamDistance(v)` | 设置第三人称最小相机距离 |
|
|
185
|
+
| `setMaxCamDistance(v)` | 设置第三人称最大相机距离 |
|
|
186
|
+
| `setThirdMouseMode(v)` | 设置第三人称鼠标模式（0~3） |
|
|
187
|
+
| `setEnableZoom(v)` | 设置第三人称是否允许滚轮缩放 |
|
|
188
|
+
| `setOverShoulderView(v)` | 开启/关闭过肩视角偏移 |
|
|
189
|
+
| `setPlayerScale(scale)` | 动态设置人物缩放，同步更新碰撞体与所有相关物理参数 |
|
|
190
|
+
| `setDebug(v)` | 开启/关闭碰撞体调试显示 |
|
|
106
191
|
|
|
107
192
|
---
|
|
108
193
|
|
|
@@ -111,16 +196,32 @@ export function playerController(): {
|
|
|
111
196
|
### 全局事件开关
|
|
112
197
|
|
|
113
198
|
```ts
|
|
114
|
-
export function onAllEvent(): void;
|
|
199
|
+
export function onAllEvent(): void; // 打开所有输入事件
|
|
115
200
|
export function offAllEvent(): void; // 关闭所有输入事件
|
|
116
201
|
```
|
|
117
202
|
|
|
118
|
-
### 说明
|
|
119
|
-
|
|
120
203
|
- `onAllEvent()`：确保控制器存在并打开输入监听。
|
|
121
|
-
- `offAllEvent()
|
|
204
|
+
- `offAllEvent()`：关闭输入监听，用于显示 UI 或暂停时禁止玩家输入。
|
|
205
|
+
|
|
206
|
+
默认处理包括：WASD 移动、奔跑、跳跃、鼠标视角等。
|
|
207
|
+
|
|
208
|
+
### setInput 外部输入
|
|
209
|
+
|
|
210
|
+
可通过 `setInput` 接管输入，适用于自定义按键映射或手柄：
|
|
122
211
|
|
|
123
|
-
|
|
212
|
+
```ts
|
|
213
|
+
player.setInput({
|
|
214
|
+
moveX: 1 | 0 | -1, // 横向移动：1 右，-1 左，0 停
|
|
215
|
+
moveY: 1 | 0 | -1, // 纵向移动：1 前，-1 后，0 停
|
|
216
|
+
lookDeltaX: number, // 视角横向偏移量
|
|
217
|
+
lookDeltaY: number, // 视角纵向偏移量
|
|
218
|
+
jump: boolean, // 跳跃
|
|
219
|
+
shift: boolean, // 奔跑
|
|
220
|
+
toggleView: boolean, // 切换第一/第三人称
|
|
221
|
+
toggleFly: boolean, // 切换飞行模式
|
|
222
|
+
toggleVehicle: boolean, // 上车/下车
|
|
223
|
+
});
|
|
224
|
+
```
|
|
124
225
|
|
|
125
226
|
---
|
|
126
227
|
|
|
@@ -135,6 +236,7 @@ type PlayerControllerOptions = {
|
|
|
135
236
|
controls: OrbitControls;
|
|
136
237
|
playerModel: {
|
|
137
238
|
url: string;
|
|
239
|
+
scale: number;
|
|
138
240
|
idleAnim: string;
|
|
139
241
|
walkAnim: string;
|
|
140
242
|
runAnim: string;
|
|
@@ -144,10 +246,15 @@ type PlayerControllerOptions = {
|
|
|
144
246
|
backwardAnim?: string;
|
|
145
247
|
flyAnim?: string;
|
|
146
248
|
flyIdleAnim?: string;
|
|
147
|
-
|
|
249
|
+
enterCarAnim?: string;
|
|
250
|
+
exitCarAnim?: string;
|
|
148
251
|
gravity?: number;
|
|
149
252
|
jumpHeight?: number;
|
|
150
253
|
speed?: number;
|
|
254
|
+
playerFlySpeed?: number;
|
|
255
|
+
rotateY?: number;
|
|
256
|
+
headObjName?: string;
|
|
257
|
+
flyEnabled?: boolean;
|
|
151
258
|
};
|
|
152
259
|
initPos?: THREE.Vector3;
|
|
153
260
|
mouseSensity?: number;
|
|
@@ -155,41 +262,64 @@ type PlayerControllerOptions = {
|
|
|
155
262
|
maxCamDistance?: number;
|
|
156
263
|
colliderMeshUrl?: string;
|
|
157
264
|
isShowMobileControls?: boolean;
|
|
158
|
-
thirdMouseMode?:
|
|
265
|
+
thirdMouseMode?: 0 | 1 | 2 | 3;
|
|
159
266
|
enableZoom?: boolean;
|
|
267
|
+
enableOverShoulderView?: boolean;
|
|
160
268
|
};
|
|
161
269
|
```
|
|
162
270
|
|
|
163
271
|
### 关键字段说明
|
|
164
272
|
|
|
165
|
-
| 字段
|
|
166
|
-
|
|
167
|
-
| `scene`
|
|
168
|
-
| `camera`
|
|
169
|
-
| `controls`
|
|
170
|
-
| `playerModel.url`
|
|
171
|
-
| `playerModel.scale`
|
|
172
|
-
| `playerModel.idleAnim`
|
|
173
|
-
| `playerModel.
|
|
174
|
-
| `playerModel.
|
|
175
|
-
| `playerModel.
|
|
176
|
-
| `playerModel.
|
|
177
|
-
| `playerModel.
|
|
178
|
-
| `playerModel.
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
273
|
+
| 字段 | 类型 | 必填 | 默认 | 说明 |
|
|
274
|
+
|------|-----:|:----:|:----:|------|
|
|
275
|
+
| `scene` | `THREE.Scene` | 是 | — | three.js 场景 |
|
|
276
|
+
| `camera` | `THREE.PerspectiveCamera` | 是 | — | three.js 相机 |
|
|
277
|
+
| `controls` | `OrbitControls` | 是 | — | 外部相机控制器 |
|
|
278
|
+
| `playerModel.url` | `string` | 是 | — | 人物模型路径（GLB/GLTF） |
|
|
279
|
+
| `playerModel.scale` | `number` | 是 | — | 人物模型缩放 |
|
|
280
|
+
| `playerModel.idleAnim` | `string` | 是 | — | Idle 动画名，需与模型内动画名一致 |
|
|
281
|
+
| `playerModel.walkAnim` | `string` | 是 | — | Walk 动画名，需与模型内动画名一致 |
|
|
282
|
+
| `playerModel.runAnim` | `string` | 是 | — | Run 动画名，需与模型内动画名一致 |
|
|
283
|
+
| `playerModel.jumpAnim` | `string` | 是 | — | Jump 动画名，需与模型内动画名一致 |
|
|
284
|
+
| `playerModel.leftWalkAnim` | `string` | 否 | `walkAnim` | 左走动画名，不填则复用 `walkAnim` |
|
|
285
|
+
| `playerModel.rightWalkAnim` | `string` | 否 | `walkAnim` | 右走动画名，不填则复用 `walkAnim` |
|
|
286
|
+
| `playerModel.backwardAnim` | `string` | 否 | `walkAnim` | 后退动画名，不填则复用 `walkAnim` |
|
|
287
|
+
| `playerModel.flyAnim` | `string` | 否 | `idleAnim` | 飞行动画名，不填则复用 `idleAnim` |
|
|
288
|
+
| `playerModel.flyIdleAnim` | `string` | 否 | `idleAnim` | 飞行待机动画名，不填则复用 `idleAnim` |
|
|
289
|
+
| `playerModel.enterCarAnim` | `string` | 否 | — | 上车动画名（使用车辆功能时必填） |
|
|
290
|
+
| `playerModel.exitCarAnim` | `string` | 否 | — | 下车动画名（使用车辆功能时必填） |
|
|
291
|
+
| `playerModel.rotateY` | `number` | 否 | `0` | 模型绕 Y 轴的额外旋转偏移 |
|
|
292
|
+
| `playerModel.headObjName` | `string` | 否 | — | 头部节点名称，用于第一人称相机绑定 |
|
|
293
|
+
| `playerModel.speed` | `number` | 否 | `300` | 移动速度基准值 |
|
|
294
|
+
| `playerModel.gravity` | `number` | 否 | `-2400` | 重力加速度基准值 |
|
|
295
|
+
| `playerModel.jumpHeight` | `number` | 否 | `600` | 跳跃高度基准值 |
|
|
296
|
+
| `playerModel.playerFlySpeed` | `number` | 否 | `2100` | 飞行速度基准值 |
|
|
297
|
+
| `playerModel.flyEnabled` | `boolean` | 否 | `true` | 是否允许飞行模式 |
|
|
298
|
+
| `initPos` | `THREE.Vector3` | 否 | `(0,0,0)` | 初始位置 |
|
|
299
|
+
| `mouseSensity` | `number` | 否 | `5` | 鼠标灵敏度 |
|
|
300
|
+
| `minCamDistance` | `number` | 否 | `100` | 第三人称最小相机距离 |
|
|
301
|
+
| `maxCamDistance` | `number` | 否 | `440` | 第三人称最大相机距离 |
|
|
302
|
+
| `colliderMeshUrl` | `string` | 否 | — | 自定义碰撞体模型路径，默认使用场景中所有网格 |
|
|
303
|
+
| `isShowMobileControls` | `boolean` | 否 | `true` | 移动端是否自动显示虚拟摇杆 |
|
|
304
|
+
| `thirdMouseMode` | `0\|1\|2\|3` | 否 | `1` | 第三人称鼠标模式（见下表） |
|
|
305
|
+
| `enableZoom` | `boolean` | 否 | `false` | 第三人称是否允许滚轮缩放 |
|
|
306
|
+
| `enableOverShoulderView` | `boolean` | 否 | `false` | 是否开启过肩视角偏移 |
|
|
307
|
+
|
|
308
|
+
**thirdMouseMode 说明：**
|
|
309
|
+
|
|
310
|
+
| 值 | 行为 |
|
|
311
|
+
|----|------|
|
|
312
|
+
| `0` | 隐藏鼠标，鼠标同时控制朝向和视角 |
|
|
313
|
+
| `1` | 隐藏鼠标，鼠标仅控制视角（默认） |
|
|
314
|
+
| `2` | 显示鼠标，拖拽控制朝向和视角 |
|
|
315
|
+
| `3` | 显示鼠标，拖拽仅控制视角 |
|
|
186
316
|
|
|
187
317
|
---
|
|
188
318
|
|
|
189
319
|
### 车辆类型定义
|
|
190
320
|
|
|
191
321
|
```ts
|
|
192
|
-
type
|
|
322
|
+
type VehicleOptions = {
|
|
193
323
|
url: string;
|
|
194
324
|
position: THREE.Vector3;
|
|
195
325
|
wheelsNames: string[];
|
|
@@ -201,22 +331,26 @@ type vehicleOptions = {
|
|
|
201
331
|
seatOffset?: THREE.Vector3;
|
|
202
332
|
chassisRatio?: number;
|
|
203
333
|
suspensionRestLengthRatio?: number;
|
|
334
|
+
followVehicleDirection?: boolean;
|
|
335
|
+
speedMultiplier?: number;
|
|
204
336
|
};
|
|
205
337
|
```
|
|
206
338
|
|
|
207
339
|
### 关键字段说明
|
|
208
340
|
|
|
209
|
-
| 字段
|
|
210
|
-
|
|
211
|
-
| `url`
|
|
212
|
-
| `position`
|
|
213
|
-
| `wheelsNames`
|
|
214
|
-
| `scale`
|
|
215
|
-
| `animations.openDoorAnim`
|
|
216
|
-
| `boardingPoint`
|
|
217
|
-
| `seatOffset`
|
|
218
|
-
| `chassisRatio`
|
|
219
|
-
| `suspensionRestLengthRatio` |
|
|
341
|
+
| 字段 | 类型 | 必填 | 默认 | 说明 |
|
|
342
|
+
|------|-----:|:----:|:----:|------|
|
|
343
|
+
| `url` | `string` | 是 | — | 车辆模型路径（GLB/GLTF） |
|
|
344
|
+
| `position` | `THREE.Vector3` | 是 | — | 车辆初始世界坐标 |
|
|
345
|
+
| `wheelsNames` | `string[]` | 是 | — | 车轮节点名称数组，顺序为前左、前右、后左、后右 |
|
|
346
|
+
| `scale` | `number` | 否 | `1` | 模型缩放系数 |
|
|
347
|
+
| `animations.openDoorAnim` | `string` | 否 | — | 车门打开动画片段名称 |
|
|
348
|
+
| `boardingPoint` | `THREE.Vector3` | 是 | — | 上车点局部坐标（相对车辆模型坐标系） |
|
|
349
|
+
| `seatOffset` | `THREE.Vector3` | 否 | `(0,0,0)` | 座位偏移，用于微调人物坐入后的位置 |
|
|
350
|
+
| `chassisRatio` | `number` | 否 | `0.2` | 底盘高度相对于轮胎直径的比例（影响模型位置） |
|
|
351
|
+
| `suspensionRestLengthRatio` | `number` | 否 | `0.2` | 悬架弹簧静止长度相对于轮胎直径的比例（影响碰撞底盘高度） |
|
|
352
|
+
| `followVehicleDirection` | `boolean` | 否 | `true` | 行驶时相机是否跟随车辆速度方向自动转向车辆正后方 |
|
|
353
|
+
| `speedMultiplier` | `number` | 否 | `1` | 车辆速度倍率，用于调节不同车辆的速度差异 |
|
|
220
354
|
|
|
221
355
|
---
|
|
222
356
|
|
package/dist/index.d.mts
CHANGED
|
@@ -81,8 +81,10 @@ type PlayerControllerOptions = {
|
|
|
81
81
|
gravity?: number;
|
|
82
82
|
jumpHeight?: number;
|
|
83
83
|
speed?: number;
|
|
84
|
+
playerFlySpeed?: number;
|
|
84
85
|
rotateY?: number;
|
|
85
86
|
headObjName?: string;
|
|
87
|
+
flyEnabled?: boolean;
|
|
86
88
|
};
|
|
87
89
|
initPos?: THREE.Vector3;
|
|
88
90
|
mouseSensity?: number;
|
|
@@ -92,8 +94,9 @@ type PlayerControllerOptions = {
|
|
|
92
94
|
isShowMobileControls?: boolean;
|
|
93
95
|
thirdMouseMode?: 0 | 1 | 2 | 3;
|
|
94
96
|
enableZoom?: boolean;
|
|
97
|
+
enableOverShoulderView?: boolean;
|
|
95
98
|
};
|
|
96
|
-
type
|
|
99
|
+
type VehicleOptions = {
|
|
97
100
|
url: string;
|
|
98
101
|
position: THREE.Vector3;
|
|
99
102
|
wheelsNames: string[];
|
|
@@ -105,6 +108,8 @@ type vehicleOptions = {
|
|
|
105
108
|
seatOffset?: THREE.Vector3;
|
|
106
109
|
chassisRatio?: number;
|
|
107
110
|
suspensionRestLengthRatio?: number;
|
|
111
|
+
followVehicleDirection?: boolean;
|
|
112
|
+
speedMultiplier?: number;
|
|
108
113
|
};
|
|
109
114
|
type VehicleInstance = {
|
|
110
115
|
vehicleGroup: THREE.Group;
|
|
@@ -127,21 +132,37 @@ type VehicleInstance = {
|
|
|
127
132
|
w: number;
|
|
128
133
|
h: number;
|
|
129
134
|
};
|
|
135
|
+
speedMultiplier: number;
|
|
130
136
|
};
|
|
131
137
|
declare function playerController(): {
|
|
132
138
|
init: (opts: PlayerControllerOptions, callback?: () => void) => Promise<void>;
|
|
133
|
-
loadVehicleModel: (params:
|
|
139
|
+
loadVehicleModel: (params: VehicleOptions) => Promise<void>;
|
|
134
140
|
changeView: () => void;
|
|
135
141
|
reset: (pos?: THREE.Vector3) => void;
|
|
136
142
|
update: (dt?: number) => Promise<void>;
|
|
137
143
|
destroy: () => void;
|
|
138
144
|
setInput: (i: any) => void;
|
|
139
|
-
|
|
145
|
+
getPosition: () => THREE.Vector3;
|
|
146
|
+
getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>;
|
|
140
147
|
getPerson: () => THREE.Object3D<THREE.Object3DEventMap>;
|
|
141
148
|
getActiveVehicle: () => VehicleInstance;
|
|
142
149
|
getAllVehicles: () => VehicleInstance[];
|
|
150
|
+
switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => Promise<void>;
|
|
151
|
+
setMouseSensitivity: (mouseSensity: number) => void;
|
|
152
|
+
setGravity: (gravity: number) => void;
|
|
153
|
+
setJumpHeight: (jumpHeight: number) => void;
|
|
154
|
+
setPlayerSpeed: (playerSpeed: number) => void;
|
|
155
|
+
setPlayerFlySpeed: (playerFlySpeed: number) => void;
|
|
156
|
+
setMinCamDistance: (minCamDistance: number) => void;
|
|
157
|
+
setMaxCamDistance: (maxCamDistance: number) => void;
|
|
158
|
+
setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
|
|
159
|
+
setEnableZoom: (enableZoom: boolean) => void;
|
|
160
|
+
setDebug: (debug: boolean) => void;
|
|
161
|
+
setOverShoulderView: (enable: boolean) => void;
|
|
162
|
+
setPlayerScale: (scale: number) => void;
|
|
143
163
|
};
|
|
164
|
+
type playerController = ReturnType<typeof playerController>;
|
|
144
165
|
declare function onAllEvent(): void;
|
|
145
166
|
declare function offAllEvent(): void;
|
|
146
167
|
|
|
147
|
-
export { type PlayerControllerOptions, type VehicleInstance, offAllEvent, onAllEvent, playerController
|
|
168
|
+
export { type PlayerControllerOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };
|
package/dist/index.d.ts
CHANGED
|
@@ -81,8 +81,10 @@ type PlayerControllerOptions = {
|
|
|
81
81
|
gravity?: number;
|
|
82
82
|
jumpHeight?: number;
|
|
83
83
|
speed?: number;
|
|
84
|
+
playerFlySpeed?: number;
|
|
84
85
|
rotateY?: number;
|
|
85
86
|
headObjName?: string;
|
|
87
|
+
flyEnabled?: boolean;
|
|
86
88
|
};
|
|
87
89
|
initPos?: THREE.Vector3;
|
|
88
90
|
mouseSensity?: number;
|
|
@@ -92,8 +94,9 @@ type PlayerControllerOptions = {
|
|
|
92
94
|
isShowMobileControls?: boolean;
|
|
93
95
|
thirdMouseMode?: 0 | 1 | 2 | 3;
|
|
94
96
|
enableZoom?: boolean;
|
|
97
|
+
enableOverShoulderView?: boolean;
|
|
95
98
|
};
|
|
96
|
-
type
|
|
99
|
+
type VehicleOptions = {
|
|
97
100
|
url: string;
|
|
98
101
|
position: THREE.Vector3;
|
|
99
102
|
wheelsNames: string[];
|
|
@@ -105,6 +108,8 @@ type vehicleOptions = {
|
|
|
105
108
|
seatOffset?: THREE.Vector3;
|
|
106
109
|
chassisRatio?: number;
|
|
107
110
|
suspensionRestLengthRatio?: number;
|
|
111
|
+
followVehicleDirection?: boolean;
|
|
112
|
+
speedMultiplier?: number;
|
|
108
113
|
};
|
|
109
114
|
type VehicleInstance = {
|
|
110
115
|
vehicleGroup: THREE.Group;
|
|
@@ -127,21 +132,37 @@ type VehicleInstance = {
|
|
|
127
132
|
w: number;
|
|
128
133
|
h: number;
|
|
129
134
|
};
|
|
135
|
+
speedMultiplier: number;
|
|
130
136
|
};
|
|
131
137
|
declare function playerController(): {
|
|
132
138
|
init: (opts: PlayerControllerOptions, callback?: () => void) => Promise<void>;
|
|
133
|
-
loadVehicleModel: (params:
|
|
139
|
+
loadVehicleModel: (params: VehicleOptions) => Promise<void>;
|
|
134
140
|
changeView: () => void;
|
|
135
141
|
reset: (pos?: THREE.Vector3) => void;
|
|
136
142
|
update: (dt?: number) => Promise<void>;
|
|
137
143
|
destroy: () => void;
|
|
138
144
|
setInput: (i: any) => void;
|
|
139
|
-
|
|
145
|
+
getPosition: () => THREE.Vector3;
|
|
146
|
+
getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>;
|
|
140
147
|
getPerson: () => THREE.Object3D<THREE.Object3DEventMap>;
|
|
141
148
|
getActiveVehicle: () => VehicleInstance;
|
|
142
149
|
getAllVehicles: () => VehicleInstance[];
|
|
150
|
+
switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => Promise<void>;
|
|
151
|
+
setMouseSensitivity: (mouseSensity: number) => void;
|
|
152
|
+
setGravity: (gravity: number) => void;
|
|
153
|
+
setJumpHeight: (jumpHeight: number) => void;
|
|
154
|
+
setPlayerSpeed: (playerSpeed: number) => void;
|
|
155
|
+
setPlayerFlySpeed: (playerFlySpeed: number) => void;
|
|
156
|
+
setMinCamDistance: (minCamDistance: number) => void;
|
|
157
|
+
setMaxCamDistance: (maxCamDistance: number) => void;
|
|
158
|
+
setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
|
|
159
|
+
setEnableZoom: (enableZoom: boolean) => void;
|
|
160
|
+
setDebug: (debug: boolean) => void;
|
|
161
|
+
setOverShoulderView: (enable: boolean) => void;
|
|
162
|
+
setPlayerScale: (scale: number) => void;
|
|
143
163
|
};
|
|
164
|
+
type playerController = ReturnType<typeof playerController>;
|
|
144
165
|
declare function onAllEvent(): void;
|
|
145
166
|
declare function offAllEvent(): void;
|
|
146
167
|
|
|
147
|
-
export { type PlayerControllerOptions, type VehicleInstance, offAllEvent, onAllEvent, playerController
|
|
168
|
+
export { type PlayerControllerOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };
|