three-player-controller 0.1.7 → 0.1.9

package/README.md

@@ -1,50 +1,57 @@
 # three-player-controller
 
-A lightweight third-person / first-person player controller, ready to use out of the box, based on three.js and three-mesh-bvh. It implements capsule-based character collision, BVH collision detection, character animations, first/third-person switching, and camera obstacle avoidance. This repository contains the library source code and example demos.
+轻量的第三人称 / 第一人称玩家控制器，开箱即用，基于 three.js 和 three-mesh-bvh 实现人物胶囊体碰撞、BVH 碰撞检测、人物动画、第一/三人称切换与相机避障。此仓库包含库源码、example 演示。
 
-# Installation
+# 安装
 
 npm install three-player-controller
 
-# Demo
+# 示例
 
 [Player Controller](https://hh-hang.github.io/three-player-controller/)
 
-### Controls
+### 控制
 
-![Controls](https://github.com/hh-hang/three-player-controller/blob/master/example/public/gif/1.gif)
+![控制演示](https://github.com/hh-hang/three-player-controller/blob/master/example/public/gif/1.gif)
 
-### Third-person camera obstacle avoidance
+### 飞行
 
-![Third-person camera obstacle avoidance](https://github.com/hh-hang/three-player-controller/blob/master/example/public/gif/2.gif)
+![飞行](https://github.com/hh-hang/three-player-controller/blob/master/example/public/gif/3.gif)
 
-# Usage
+### 3DTiles 漫游
+
+![3DTiles 漫游](https://github.com/hh-hang/three-player-controller/blob/master/example/public/gif/4.gif)
+
+
+# 使用
 
 ```js
 import * as THREE from "three";
 import { playerController } from "three-player-controller";
 
-// Initialize the player controller
+const player = playerController();
+
+// 初始化玩家控制器
 player.init({
-  scene, // three.js scene
-  camera, // three.js camera
-  controls, // three.js controls
+  scene, // three.js 场景
+  camera, // three.js 相机
+  controls, // three.js 控制器
   playerModel: {
-    url: "./glb/person.glb", // model path
-    scale: 0.001, // model scale
-    idleAnim: "Idle_2", // idle animation name
-    walkAnim: "Walking_11", // walk animation name
-    runAnim: "Running_9", // run animation name
-    jumpAnim: "Jump_3", // jump animation name
+    url: "./glb/person.glb", // 模型路径
+    scale: 0.001, // 模型缩放
+    idleAnim: "Idle_2", // 默认 Idle 动画名字
+    walkAnim: "Walking_11", // 默认 Walk 动画名字
+    runAnim: "Running_9", // 默认 Run 动画名字
+    jumpAnim: "Jump_3", // 默认 Jump 动画名字
   },
-  initPos: pos, // initial position
+  initPos: pos, // 初始位置
 });
 
-// Call in the render loop
+// 渲染循环调用
 player.update();
 ```
 
-# Thanks
+# 感谢
 
 [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh)
 

package/dist/index.d.mts

@@ -15,14 +15,17 @@ declare function playerController(): {
             leftWalkAnim?: string;
             rightWalkAnim?: string;
             backwardAnim?: string;
+            flyAnim?: string;
+            flyIdleAnim?: string;
             scale: number;
             gravity?: number;
             jumpHeight?: number;
-            highJumpHeight?: number;
             speed?: number;
         };
         initPos?: THREE.Vector3;
         mouseSensity?: number;
+        minCamDistance?: number;
+        maxCamDistance?: number;
     }, callback?: () => void) => Promise<void>;
     changeView: () => void;
     createBVH: (url?: string) => Promise<void>;

package/dist/index.d.ts

@@ -15,14 +15,17 @@ declare function playerController(): {
             leftWalkAnim?: string;
             rightWalkAnim?: string;
             backwardAnim?: string;
+            flyAnim?: string;
+            flyIdleAnim?: string;
             scale: number;
             gravity?: number;
             jumpHeight?: number;
-            highJumpHeight?: number;
             speed?: number;
         };
         initPos?: THREE.Vector3;
         mouseSensity?: number;
+        minCamDistance?: number;
+        maxCamDistance?: number;
     }, callback?: () => void) => Promise<void>;
     changeView: () => void;
     createBVH: (url?: string) => Promise<void>;

package/dist/index.js

@@ -63,6 +63,7 @@ var PlayerController = class {
     //  状态开关
     this.playerIsOnGround = false;
     this.isupdate = true;
+    this.isFlying = false;
     //  输入状态
     this.fwdPressed = false;
     this.bkdPressed = false;
@@ -71,8 +72,6 @@ var PlayerController = class {
     this.spacePressed = false;
     this.ctPressed = false;
     this.shiftPressed = false;
-    this.sustainSpacePressed = false;
-    this.spaceLongPressTimer = null;
     // 第三人称
     this._camCollisionLerp = 0.18;
     // 平滑系数
@@ -82,6 +81,7 @@ var PlayerController = class {
     // 摄像机最小距离
     this._maxCamDistance = 4.4;
     // 摄像机最大距离
+    this.orginMaxCamDistance = 4.4;
     //  物理/运动
     this.playerVelocity = new THREE.Vector3();
     // 玩家速度向量
@@ -102,6 +102,7 @@ var PlayerController = class {
     this.DIR_BKD = new THREE.Vector3(0, 0, 1);
     this.DIR_LFT = new THREE.Vector3(-1, 0, 0);
     this.DIR_RGT = new THREE.Vector3(1, 0, 0);
+    this.DIR_UP = new THREE.Vector3(0, 1, 0);
     this._personToCam = new THREE.Vector3();
     this._originTmp = new THREE.Vector3();
     this._raycaster = new THREE.Raycaster(new THREE.Vector3(), new THREE.Vector3(0, -1, 0));
@@ -133,12 +134,11 @@ var PlayerController = class {
           this.setAnimationByPressed();
           break;
         case "Space":
-          if (!this.spacePressed) this.spacePressed = true;
-          if (!this.spaceLongPressTimer) {
-            this.spaceLongPressTimer = setTimeout(() => {
-              this.sustainSpacePressed = true;
-            }, 2e3);
-          }
+          this.spacePressed = true;
+          if (!this.playerIsOnGround || this.isFlying) return;
+          this.playPersonAnimationByName("jumping");
+          this.playerVelocity.y = this.jumpHeight;
+          this.playerIsOnGround = false;
           break;
         case "ControlLeft":
           this.ctPressed = true;
@@ -146,6 +146,15 @@ var PlayerController = class {
         case "KeyV":
           this.changeView();
           break;
+        case "KeyF":
+          this.isFlying = !this.isFlying;
+          this._maxCamDistance = this.isFlying ? this.orginMaxCamDistance * 2 : this.orginMaxCamDistance;
+          if (!this.isFlying && !this.playerIsOnGround) {
+            this.playPersonAnimationByName("jumping");
+          } else {
+            this.setAnimationByPressed();
+          }
+          break;
       }
     };
     // 键盘抬起事件
@@ -172,12 +181,7 @@ var PlayerController = class {
           this.setAnimationByPressed();
           break;
         case "Space":
-          if (this.spaceLongPressTimer) {
-            clearTimeout(this.spaceLongPressTimer);
-            this.spaceLongPressTimer = null;
-          }
           this.spacePressed = false;
-          this.sustainSpacePressed = false;
           break;
         case "ControlLeft":
           this.ctPressed = false;
@@ -186,6 +190,16 @@ var PlayerController = class {
     };
     // 根据按键设置人物动画
     this.setAnimationByPressed = () => {
+      this._maxCamDistance = this.orginMaxCamDistance;
+      if (this.isFlying) {
+        if (!this.fwdPressed) {
+          this.playPersonAnimationByName("flyidle");
+          return;
+        }
+        this.playPersonAnimationByName("flying");
+        this._maxCamDistance = this.orginMaxCamDistance * 2;
+        return;
+      }
       if (this.playerIsOnGround) {
         if (!this.fwdPressed && !this.bkdPressed && !this.lftPressed && !this.rgtPressed) {
           this.playPersonAnimationByName("idle");
@@ -265,13 +279,13 @@ var PlayerController = class {
     const s = this.playerModel.scale;
     this.visualizeDepth = 0 * s;
     this.gravity = opts.playerModel.gravity ? opts.playerModel.gravity * s : -2400 * s;
-    this.jumpHeight = opts.playerModel.jumpHeight ? opts.playerModel.jumpHeight * s : 300 * s;
-    this.highJumpHeight = opts.playerModel.highJumpHeight ? opts.playerModel.highJumpHeight * s : 1e3 * s;
+    this.jumpHeight = opts.playerModel.jumpHeight ? opts.playerModel.jumpHeight * s : 800 * s;
     this.playerSpeed = opts.playerModel.speed ? opts.playerModel.speed * s : 400 * s;
     this._camCollisionLerp = 0.18;
     this._camEpsilon = 35 * s;
-    this._minCamDistance = 100 * s;
-    this._maxCamDistance = 440 * s;
+    this._minCamDistance = opts.minCamDistance ? opts.minCamDistance * s : 100 * s;
+    this._maxCamDistance = opts.maxCamDistance ? opts.maxCamDistance * s : 440 * s;
+    this.orginMaxCamDistance = this._maxCamDistance;
     await this.createBVH();
     this.createPlayer();
     await this.loadPersonGLB();
@@ -318,10 +332,11 @@ var PlayerController = class {
   // 设置控制器
   setControls() {
     this.controls.enabled = false;
-    this.controls.maxPolarAngle = Math.PI * (230 / 360);
+    this.controls.maxPolarAngle = Math.PI * (300 / 360);
   }
   // 重置控制器
   resetControls() {
+    if (!this.controls) return;
     this.controls.enabled = true;
     this.controls.enablePan = true;
     this.controls.maxPolarAngle = Math.PI / 2;
@@ -352,6 +367,7 @@ var PlayerController = class {
       this.person.traverse((child) => {
         if (child.isMesh) {
           child.castShadow = true;
+          child.receiveShadow = true;
         }
       });
       this.player.add(this.person);
@@ -367,7 +383,9 @@ var PlayerController = class {
         [this.playerModel.rightWalkAnim || this.playerModel.walkAnim, "right_walking"],
         [this.playerModel.backwardAnim || this.playerModel.walkAnim, "walking_backward"],
         [this.playerModel.jumpAnim, "jumping"],
-        [this.playerModel.runAnim, "running"]
+        [this.playerModel.runAnim, "running"],
+        [this.playerModel.flyIdleAnim || this.playerModel.idleAnim, "flyidle"],
+        [this.playerModel.flyAnim || this.playerModel.idleAnim, "flying"]
       ];
       for (const [key, clipName] of regs) {
         const clip = findClip(key);
@@ -393,6 +411,8 @@ var PlayerController = class {
       this.backwardAction = this.personActions.get("walking_backward");
       this.jumpAction = this.personActions.get("jumping");
       this.runAction = this.personActions.get("running");
+      this.flyidleAction = this.personActions.get("flyidle");
+      this.flyAction = this.personActions.get("flying");
       this.idleAction.setEffectiveWeight(1);
       this.idleAction.play();
       this.actionState = this.idleAction;
@@ -460,6 +480,7 @@ var PlayerController = class {
     this.scene.add(this.player);
     this.reset();
   }
+  // 获取法线与Y轴的夹角
   getAngleWithYAxis(normal) {
     const yAxis = { x: 0, y: 1, z: 0 };
     const dotProduct = normal.x * yAxis.x + normal.y * yAxis.y + normal.z * yAxis.z;
@@ -470,10 +491,10 @@ var PlayerController = class {
   }
   // 每帧更新
   async update(delta = clock.getDelta()) {
-    if (!this.isupdate || !this.player) return;
+    if (!this.isupdate || !this.player || !this.collider) return;
     delta = Math.min(delta, 1 / 30);
+    if (!this.isFlying) this.player.position.addScaledVector(this.playerVelocity, delta);
     this.updateMixers(delta);
-    if (!this.collider) return;
     this.camera.getWorldDirection(this.camDir);
     let angle = Math.atan2(this.camDir.z, this.camDir.x) + Math.PI / 2;
     angle = 2 * Math.PI - angle;
@@ -482,31 +503,23 @@ var PlayerController = class {
     if (this.bkdPressed) this.moveDir.add(this.DIR_BKD);
     if (this.lftPressed) this.moveDir.add(this.DIR_LFT);
     if (this.rgtPressed) this.moveDir.add(this.DIR_RGT);
-    if (this.spacePressed && this.playerIsOnGround) {
-      this.playPersonAnimationByName("jumping");
-      setTimeout(() => {
-        this.playerVelocity.y = this.jumpHeight;
-        this.playerIsOnGround = false;
-        this.spacePressed = false;
-        this.player.position.addScaledVector(this.playerVelocity, delta);
-        this.player.updateMatrixWorld();
-      }, 200);
-    }
-    if (this.sustainSpacePressed && this.playerIsOnGround) {
-      this.playPersonAnimationByName("jumping");
-      setTimeout(() => {
-        this.playerVelocity.y = this.highJumpHeight;
-        this.playerIsOnGround = false;
-        this.spacePressed = false;
-        this.player.position.addScaledVector(this.playerVelocity, delta);
-        this.player.updateMatrixWorld();
-      }, 200);
+    if (this.isFlying) {
+      if (this.fwdPressed) {
+        this.moveDir.y = this.camDir.y;
+      } else {
+        this.moveDir.y = 0;
+      }
+      if (this.spacePressed) {
+        this.moveDir.add(this.DIR_UP);
+      }
     }
-    this.playerSpeed = this.shiftPressed ? 900 * this.playerModel.scale : 400 * this.playerModel.scale;
-    if (this.moveDir.lengthSq() > 1e-6) {
-      this.moveDir.normalize().applyAxisAngle(this.upVector, angle);
-      this.player.position.addScaledVector(this.moveDir, this.playerSpeed * delta);
+    if (this.isFlying && this.fwdPressed) {
+      this.playerSpeed = this.shiftPressed ? 4e3 * this.playerModel.scale : 3e3 * this.playerModel.scale;
+    } else {
+      this.playerSpeed = this.shiftPressed ? 900 * this.playerModel.scale : 400 * this.playerModel.scale;
     }
+    this.moveDir.normalize().applyAxisAngle(this.upVector, angle);
+    this.player.position.addScaledVector(this.moveDir, this.playerSpeed * delta);
     let playerDistanceFromGround = Infinity;
     this._originTmp.set(this.player.position.x, this.player.position.y, this.player.position.z);
     this._raycaster.ray.origin.copy(this._originTmp);
@@ -518,26 +531,30 @@ var PlayerController = class {
       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;
-      if (playerDistanceFromGround > maxH) {
-        this.playerVelocity.y += delta * this.gravity;
-        this.player.position.addScaledVector(this.playerVelocity, delta);
-        this.playerIsOnGround = false;
-      } else if (playerDistanceFromGround > h && playerDistanceFromGround < maxH) {
-        if (angle2 >= 0 && angle2 < 5) {
-          this.player.position.y = intersects[0].point.y + h;
+      console.log(angle2, playerDistanceFromGround, maxH, h, minH);
+      if (this.isFlying) {
+      } else {
+        if (playerDistanceFromGround > maxH) {
+          this.playerVelocity.y += delta * this.gravity;
+          this.player.position.addScaledVector(this.playerVelocity, delta);
+          this.playerIsOnGround = false;
+        } else if (playerDistanceFromGround > h && playerDistanceFromGround < maxH) {
+          if (angle2 >= 0 && angle2 < 5) {
+            this.playerVelocity.y += delta * this.gravity;
+            this.player.position.addScaledVector(this.playerVelocity, delta);
+            this.playerIsOnGround = true;
+          } else {
+            this.playerVelocity.set(0, 0, 0);
+            this.playerIsOnGround = true;
+          }
+        } else if (playerDistanceFromGround > minH && playerDistanceFromGround < h) {
           this.playerVelocity.set(0, 0, 0);
           this.playerIsOnGround = true;
-        } else {
+        } else if (playerDistanceFromGround < minH) {
           this.playerVelocity.set(0, 0, 0);
+          this.player.position.set(this.player.position.x, intersects[0].point.y + h, this.player.position.z);
           this.playerIsOnGround = true;
         }
-      } else if (playerDistanceFromGround > minH && playerDistanceFromGround < h) {
-        this.playerVelocity.set(0, 0, 0);
-        this.playerIsOnGround = true;
-      } else if (playerDistanceFromGround < minH) {
-        this.playerVelocity.set(0, 0, 0);
-        this.player.position.set(this.player.position.x, intersects[0].point.y + h, this.player.position.z);
-        this.playerIsOnGround = true;
       }
     }
     this.player.updateMatrixWorld();
@@ -569,13 +586,10 @@ var PlayerController = class {
     });
     const newPosition = this.tempVector.copy(this.tempSegment.start).applyMatrix4(this.collider.matrixWorld);
     const deltaVector = this.tempVector2.subVectors(newPosition, this.player.position);
-    const len = deltaVector.length();
-    const offset = Math.max(0, len - 1e-5);
-    if (offset > 0 && len > 0) {
-      const n = deltaVector.multiplyScalar(1 / len);
-      this.player.position.addScaledVector(n, offset);
-    }
-    if (!this.isFirstPerson && this.moveDir.lengthSq() > 0) {
+    const offset = Math.max(0, deltaVector.length() - 1e-5);
+    deltaVector.normalize().multiplyScalar(offset);
+    this.player.position.add(deltaVector);
+    if (!this.isFirstPerson && this.moveDir.lengthSq() > 0 && !this.isFlying) {
       this.camDir.y = 0;
       this.camDir.normalize();
       this.camDir.negate();
@@ -587,6 +601,18 @@ var PlayerController = class {
       const alpha = Math.min(1, this.rotationSpeed * delta);
       this.player.quaternion.slerp(this.targetQuat, alpha);
     }
+    if (this.isFlying) {
+      this.camDir.y = 0;
+      this.camDir.normalize();
+      this.camDir.negate();
+      this.moveDir.normalize();
+      this.moveDir.negate();
+      const lookTarget = this.player.position.clone().add(this.fwdPressed ? this.moveDir : this.camDir);
+      this.targetMat.lookAt(this.player.position, lookTarget, this.player.up);
+      this.targetQuat.setFromRotationMatrix(this.targetMat);
+      const alpha = Math.min(1, this.rotationSpeed * delta);
+      this.player.quaternion.slerp(this.targetQuat, alpha);
+    }
     if (!this.isFirstPerson) {
       const lookTarget = this.player.position.clone();
       lookTarget.y += 30 * this.playerModel.scale;
@@ -607,18 +633,15 @@ var PlayerController = class {
         const targetCamPos = origin.clone().add(direction.clone().multiplyScalar(safeDist));
         this.camera.position.lerp(targetCamPos, this._camCollisionLerp);
       } else {
-        const dis = this.player.position.distanceTo(this.camera.position);
         this._raycasterPersonToCam.far = this._maxCamDistance;
         const intersectsMaxDis = this._raycasterPersonToCam.intersectObject(this.collider, false);
-        if (dis < this._maxCamDistance) {
-          let safeDist = this._maxCamDistance;
-          if (intersectsMaxDis.length) {
-            const hitMax = intersectsMaxDis[0];
-            safeDist = hitMax.distance - this._camEpsilon;
-          }
-          const targetCamPos = origin.clone().add(direction.clone().multiplyScalar(safeDist));
-          this.camera.position.lerp(targetCamPos, this._camCollisionLerp);
+        let safeDist = this._maxCamDistance;
+        if (intersectsMaxDis.length) {
+          const hitMax = intersectsMaxDis[0];
+          safeDist = hitMax.distance - this._camEpsilon;
         }
+        const targetCamPos = origin.clone().add(direction.clone().multiplyScalar(safeDist));
+        this.camera.position.lerp(targetCamPos, this._camCollisionLerp);
       }
     }
     if (this.player.position.y < this.boundingBoxMinY - 1) {
@@ -684,7 +707,6 @@ var PlayerController = class {
   // 更新模型动画
   updateMixers(delta) {
     if (this.personMixer) this.personMixer.update(delta);
-    if (this.droneMixer) this.droneMixer.update(delta);
   }
   // BVH构建
   async createBVH(meshUrl = "") {