three-player-controller 0.3.5 → 0.3.7

package/README.md

@@ -148,7 +148,7 @@ export function playerController(): {
     setGravity: (gravity: number) => void;
     setJumpHeight: (jumpHeight: number) => void;
     setPlayerSpeed: (playerSpeed: number) => void;
-    setPlayerFlySpeed: (playerFlySpeed: number) => void;
+    setflySpeed: (flySpeed: number) => void;
     setMinCamDistance: (minCamDistance: number) => void;
     setMaxCamDistance: (maxCamDistance: number) => void;
     setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
@@ -180,7 +180,7 @@ export function playerController(): {
 | `setGravity(v)` | 设置重力（传入基准值，内部自动乘以 scale） |
 | `setJumpHeight(v)` | 设置跳跃高度（传入基准值，内部自动乘以 scale） |
 | `setPlayerSpeed(v)` | 设置移动速度（传入基准值，内部自动乘以 scale） |
-| `setPlayerFlySpeed(v)` | 设置飞行速度（传入基准值，内部自动乘以 scale） |
+| `setflySpeed(v)` | 设置飞行速度（传入基准值，内部自动乘以 scale） |
 | `setMinCamDistance(v)` | 设置第三人称最小相机距离 |
 | `setMaxCamDistance(v)` | 设置第三人称最大相机距离 |
 | `setThirdMouseMode(v)` | 设置第三人称鼠标模式（0~3） |
@@ -251,7 +251,7 @@ type PlayerControllerOptions = {
         gravity?: number;
         jumpHeight?: number;
         speed?: number;
-        playerFlySpeed?: number;
+        flySpeed?: number;
         rotateY?: number;
         headObjName?: string;
         flyEnabled?: boolean;
@@ -270,32 +270,41 @@ type PlayerControllerOptions = {
 
 ### 关键字段说明
 
-| 字段 | 类型 | 默认 / 说明 |
-|------|-----:|------------|
-| `scene` | `THREE.Scene` | three.js 场景（必填） |
-| `camera` | `THREE.PerspectiveCamera` | three.js 相机（必填） |
-| `controls` | `OrbitControls` | 外部相机控制器（必填） |
-| `playerModel.url` | `string` | 人物模型路径 GLB/GLTF（必填） |
-| `playerModel.scale` | `number` | 人物模型缩放（必填） |
-| `playerModel.idleAnim` / `walkAnim` / `runAnim` / `jumpAnim` | `string` | 动画名，需与模型内动画名一致（必填） |
-| `playerModel.leftWalkAnim` / `rightWalkAnim` / `backwardAnim` | `string` | 左走/右走/后退动画，不填则复用 `walkAnim` |
-| `playerModel.flyAnim` / `flyIdleAnim` | `string` | 飞行/飞行待机动画，不填则复用 `idleAnim` |
-| `playerModel.enterCarAnim` / `exitCarAnim` | `string` | 上车/下车动画（使用车辆功能时必填） |
-| `playerModel.rotateY` | `number` | 模型绕 Y 轴额外旋转偏移，默认 `0` |
-| `playerModel.headObjName` | `string` | 头部节点名称，用于第一人称相机绑定 |
-| `playerModel.speed` | `number` | 移动速度基准值，默认 `300` |
-| `playerModel.gravity` | `number` | 重力加速度基准值，默认 `-2400` |
-| `playerModel.jumpHeight` | `number` | 跳跃高度基准值，默认 `600` |
-| `playerModel.playerFlySpeed` | `number` | 飞行速度基准值，默认 `2100` |
-| `playerModel.flyEnabled` | `boolean` | 是否允许飞行，默认 `true` |
-| `initPos` | `THREE.Vector3` | 初始位置，默认 `(0,0,0)` |
-| `mouseSensity` | `number` | 鼠标灵敏度，默认 `5` |
-| `minCamDistance` / `maxCamDistance` | `number` | 第三人称相机距离限制，默认 `100` / `440` |
-| `colliderMeshUrl` | `string` | 自定义碰撞体模型路径，默认使用场景中所有网格 |
-| `isShowMobileControls` | `boolean` | 移动端是否自动显示虚拟摇杆，默认 `true` |
-| `thirdMouseMode` | `0\|1\|2\|3` | 第三人称鼠标模式，默认 `1`（见下表） |
-| `enableZoom` | `boolean` | 第三人称是否允许滚轮缩放，默认 `false` |
-| `enableOverShoulderView` | `boolean` | 是否开启过肩视角偏移，默认 `false` |
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|------|-----:|:----:|:----:|------|
+| `scene` | `THREE.Scene` | 是 | — | three.js 场景 |
+| `camera` | `THREE.PerspectiveCamera` | 是 | — | three.js 相机 |
+| `controls` | `OrbitControls` | 是 | — | 外部相机控制器 |
+| `playerModel.url` | `string` | 是 | — | 人物模型路径（GLB/GLTF） |
+| `playerModel.scale` | `number` | 是 | — | 人物模型缩放 |
+| `playerModel.idleAnim` | `string` | 是 | — | Idle 动画名，需与模型内动画名一致 |
+| `playerModel.walkAnim` | `string` | 是 | — | Walk 动画名，需与模型内动画名一致 |
+| `playerModel.runAnim` | `string` | 是 | — | Run 动画名，需与模型内动画名一致 |
+| `playerModel.jumpAnim` | `string` | 是 | — | Jump 动画名，需与模型内动画名一致 |
+| `playerModel.leftWalkAnim` | `string` | 否 | `walkAnim` | 左走动画名，不填则复用 `walkAnim` |
+| `playerModel.rightWalkAnim` | `string` | 否 | `walkAnim` | 右走动画名，不填则复用 `walkAnim` |
+| `playerModel.backwardAnim` | `string` | 否 | `walkAnim` | 后退动画名，不填则复用 `walkAnim` |
+| `playerModel.flyAnim` | `string` | 否 | `idleAnim` | 飞行动画名，不填则复用 `idleAnim` |
+| `playerModel.flyIdleAnim` | `string` | 否 | `idleAnim` | 飞行待机动画名，不填则复用 `idleAnim` |
+| `playerModel.enterCarAnim` | `string` | 否 | — | 上车动画名（使用车辆功能时必填） |
+| `playerModel.exitCarAnim` | `string` | 否 | — | 下车动画名（使用车辆功能时必填） |
+| `playerModel.rotateY` | `number` | 否 | `0` | 模型绕 Y 轴的额外旋转偏移 |
+| `playerModel.headObjName` | `string` | 否 | — | 头部节点名称，用于第一人称相机绑定 |
+| `playerModel.speed` | `number` | 否 | `300` | 移动速度基准值 |
+| `playerModel.gravity` | `number` | 否 | `-2400` | 重力加速度基准值 |
+| `playerModel.jumpHeight` | `number` | 否 | `600` | 跳跃高度基准值 |
+| `playerModel.flySpeed` | `number` | 否 | `2100` | 飞行速度基准值 |
+| `playerModel.flyEnabled` | `boolean` | 否 | `true` | 是否允许飞行模式 |
+| `initPos` | `THREE.Vector3` | 否 | `(0,0,0)` | 初始位置 |
+| `mouseSensity` | `number` | 否 | `5` | 鼠标灵敏度 |
+| `minCamDistance` | `number` | 否 | `100` | 第三人称最小相机距离 |
+| `maxCamDistance` | `number` | 否 | `440` | 第三人称最大相机距离 |
+| `colliderMeshUrl` | `string` | 否 | — | 自定义碰撞体模型路径，默认使用场景中所有网格 |
+| `isShowMobileControls` | `boolean` | 否 | `true` | 移动端是否自动显示虚拟摇杆 |
+| `thirdMouseMode` | `0\|1\|2\|3` | 否 | `1` | 第三人称鼠标模式（见下表） |
+| `enableZoom` | `boolean` | 否 | `false` | 第三人称是否允许滚轮缩放 |
+| `enableOverShoulderView` | `boolean` | 否 | `false` | 是否开启过肩视角偏移 |
+| `capsuleRadiusRatio` | `number` | 否 | `1.0` | 玩家胶囊碰撞体的半径系数，值越大碰撞范围越宽 |
 
 **thirdMouseMode 说明：**
 

package/dist/index.d.mts

@@ -81,10 +81,11 @@ type PlayerControllerOptions = {
         gravity?: number;
         jumpHeight?: number;
         speed?: number;
-        playerFlySpeed?: number;
+        flySpeed?: number;
         rotateY?: number;
         headObjName?: string;
         flyEnabled?: boolean;
+        capsuleRadiusRatio?: number;
     };
     initPos?: THREE.Vector3;
     mouseSensity?: number;

package/dist/index.d.ts

@@ -81,10 +81,11 @@ type PlayerControllerOptions = {
         gravity?: number;
         jumpHeight?: number;
         speed?: number;
-        playerFlySpeed?: number;
+        flySpeed?: number;
         rotateY?: number;
         headObjName?: string;
         flyEnabled?: boolean;
+        capsuleRadiusRatio?: number;
     };
     initPos?: THREE.Vector3;
     mouseSensity?: number;

package/dist/index.js

@@ -337,8 +337,9 @@ var PlayerController = class {
     this.enableOverShoulderView = false;
     this.isChangeControllerTransitionTimer = null;
     // ==================== 玩家基本属性 ====================
-    this.playerRadius = 45;
-    this.playerHeight = 180;
+    this.playerCapsuleRadius = 45;
+    this.playerCapsuleRadiusRatio = 1;
+    this.playerCapsuleHeight = 180;
     // 玩家参考身高
     this.isFirstPerson = false;
     this.boundingBoxMinY = 0;
@@ -368,7 +369,7 @@ var PlayerController = class {
     // 全局车辆共享参数
     this.vehicleParams = {
       debug: {
-        showPhysicsBox: true
+        showPhysicsBox: false
       },
       chassis: {
         linearDamping: 0.5,
@@ -714,7 +715,7 @@ var PlayerController = class {
     this.gravity = (opts.playerModel.gravity ?? -2400) * s;
     this.jumpHeight = (opts.playerModel.jumpHeight ?? 600) * s;
     this.playerSpeed = (opts.playerModel.speed ?? 300) * s;
-    this.playerFlySpeed = (opts.playerModel.playerFlySpeed ?? 2100) * s;
+    this.playerFlySpeed = (opts.playerModel.flySpeed ?? 2100) * s;
     this.curPlayerSpeed = this.playerSpeed;
     this.playerModel.rotateY = opts.playerModel.rotateY ?? 0;
     this.playerFlyEnabled = opts.playerModel.flyEnabled ?? true;
@@ -725,6 +726,7 @@ var PlayerController = class {
     this.orginMaxCamDistance = this.maxCamDistance;
     this.thirdMouseMode = opts.thirdMouseMode ?? 1;
     this.enableZoom = opts.enableZoom ?? false;
+    this.playerCapsuleRadiusRatio = opts.playerModel.capsuleRadiusRatio ?? 1;
     const isMobileDevice = () => navigator.maxTouchPoints && navigator.maxTouchPoints > 0 || "ontouchstart" in window || /Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
     this.isShowMobileControls = (opts.isShowMobileControls ?? true) && isMobileDevice();
     if (this.isShowMobileControls) {
@@ -805,11 +807,10 @@ var PlayerController = class {
       );
       this.person = gltf.scene;
       const { size } = this.getBbox(this.person);
-      const ratio = this.playerHeight / size.y;
-      const power = Math.round(Math.log10(ratio));
-      const modelScale = Math.pow(10, power);
-      this.playerRadius = Number(Math.min(size.x, size.z).toFixed(0)) * modelScale;
-      this.playerHeight = Number(size.y.toFixed(0)) * modelScale;
+      const ratio = this.playerCapsuleHeight / size.y;
+      const modelScale = ratio;
+      this.playerCapsuleRadius = Number(Math.min(size.x, size.z).toFixed(0)) * modelScale * this.playerCapsuleRadiusRatio;
+      this.playerCapsuleHeight = Number(size.y.toFixed(0)) * modelScale;
       const scale = this.playerModel.scale;
       const material = new THREE3.MeshStandardMaterial({
         color: new THREE3.Color(1, 0, 0),
@@ -820,8 +821,8 @@ var PlayerController = class {
         wireframe: true,
         depthWrite: false
       });
-      const r = this.playerRadius * scale;
-      const h = this.playerHeight * scale;
+      const r = this.playerCapsuleRadius * scale;
+      const h = this.playerCapsuleHeight * scale;
       this.player = new THREE3.Mesh(
         new import_RoundedBoxGeometry.RoundedBoxGeometry(r * 2, h, r * 2, 1, 75),
         material
@@ -1009,8 +1010,7 @@ var PlayerController = class {
       const vehicleModel = await this.loader.loadAsync(opts.url);
       const { size: originalSize } = this.getBbox(vehicleModel.scene);
       const ratio = this.vehicleLength / Math.max(originalSize.x, originalSize.y, originalSize.z);
-      const power = Math.round(Math.log10(ratio));
-      const modelScale = Math.pow(10, power);
+      const modelScale = ratio;
       const vehicleMixer = new THREE3.AnimationMixer(vehicleModel.scene);
       const animations = vehicleModel.animations ?? [];
       const vehicleActions = /* @__PURE__ */ new Map();
@@ -2166,9 +2166,9 @@ var PlayerController = class {
     );
     if (intersects.length > 0) {
       playerDistanceFromGround = this.player.position.y - intersects[0].point.y;
-      const maxH = this.playerHeight * this.playerModel.scale * 0.9;
-      const h = this.playerHeight * this.playerModel.scale * 0.75;
-      const minH = this.playerHeight * this.playerModel.scale * 0.7;
+      const maxH = this.playerCapsuleHeight * this.playerModel.scale * 0.9;
+      const h = this.playerCapsuleHeight * this.playerModel.scale * 0.75;
+      const minH = this.playerCapsuleHeight * this.playerModel.scale * 0.7;
       if (!this.isFlying) {
         if (playerDistanceFromGround >= maxH) {
           this.playerVelocity.y += delta * this.gravity;
@@ -2316,7 +2316,7 @@ var PlayerController = class {
     }
     if (!this.isFirstPerson) {
       const lookTarget = this.player.position.clone();
-      lookTarget.y += this.playerHeight / 8 * this.playerModel.scale;
+      lookTarget.y += this.playerCapsuleHeight / 8 * this.playerModel.scale;
       this.camera.position.sub(this.controls.target);
       this.controls.target.copy(lookTarget);
       this.camera.position.add(lookTarget);