three-player-controller 0.2.51 → 0.3.0

package/dist/index.mjs

@@ -20,27 +20,28 @@ THREE.Mesh.prototype.raycast = acceleratedRaycast;
 var controllerInstance = null;
 var clock = new THREE.Clock();
 var PlayerController = class {
-  // 射线检测时只返回第一个碰撞
   constructor() {
+    // ==================== 基本配置与参数 ====================
     this.loader = new GLTFLoader();
     // 0: 隐藏鼠标控制朝向及视角，1: 隐藏鼠标仅控制视角，2: 显示鼠标拖拽控制朝向及视角, 3: 显示鼠标拖拽仅控制视角
+    // ==================== 玩家基本属性 ====================
     this.playerRadius = 45;
     this.playerHeight = 180;
     this.isFirstPerson = false;
     this.boundingBoxMinY = 0;
-    // 测试参数
+    // ==================== 测试参数 ====================
     this.displayPlayer = false;
     this.displayCollider = false;
     this.displayVisualizer = false;
-    // 场景对象
+    // ==================== 场景对象 ====================
     this.collider = null;
     this.visualizer = null;
     this.person = null;
-    // 状态开关
+    // ==================== 状态开关 ====================
     this.playerIsOnGround = false;
     this.isupdate = true;
     this.isFlying = false;
-    // 输入状态
+    // ==================== 输入状态 ====================
     this.fwdPressed = false;
     this.bkdPressed = false;
     this.lftPressed = false;
@@ -48,10 +49,9 @@ var PlayerController = class {
     this.spacePressed = false;
     this.ctPressed = false;
     this.shiftPressed = false;
-    // 移动端输入
+    // ==================== 移动端输入 ====================
     this.prevJoyState = { dirX: 0, dirY: 0, shift: false };
     this.nippleModule = null;
-    // 移动控制相关
     this.joystickManager = null;
     this.joystickZoneEl = null;
     this.lookAreaEl = null;
@@ -62,29 +62,28 @@ var PlayerController = class {
     this.isLookDown = false;
     this.lastTouchX = 0;
     this.lastTouchY = 0;
-    // 第三人称
+    // ==================== 第三人称相机参数 ====================
     this._camCollisionLerp = 0.18;
     // 平滑系数
     this._camEpsilon = 0.35;
-    // 摄像机与障碍物之间的安全距离（米）
+    // 摄像机与障碍物之间的安全距离
     this._minCamDistance = 1;
     // 摄像机最小距离
     this._maxCamDistance = 4.4;
     // 摄像机最大距离
     this.orginMaxCamDistance = 4.4;
-    // 物理/运动
+    // ==================== 物理/运动 ====================
     this.playerVelocity = new THREE.Vector3();
     // 玩家速度向量
     this.upVector = new THREE.Vector3(0, 1, 0);
-    //  临时复用向量/矩阵
+    // ==================== 临时复用向量/矩阵 ====================
     this.tempVector = new THREE.Vector3();
     this.tempVector2 = new THREE.Vector3();
     this.tempBox = new THREE.Box3();
     this.tempMat = new THREE.Matrix4();
     this.tempSegment = new THREE.Line3();
-    // 检测动画定时
     this.recheckAnimTimer = null;
-    //  复用向量：用于相机朝向 / 移动
+    // ==================== 相机朝向/移动复用向量 ====================
     this.camDir = new THREE.Vector3();
     this.moveDir = new THREE.Vector3();
     this.targetQuat = new THREE.Quaternion();
@@ -95,13 +94,65 @@ var PlayerController = class {
     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));
     this._raycasterPersonToCam = new THREE.Raycaster(new THREE.Vector3(), new THREE.Vector3());
-    // 键盘按下事件
+    /**
+     * 根据按键设置人物动画
+     */
+    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");
+          return;
+        }
+        if (this.fwdPressed) {
+          this.playPersonAnimationByName(this.shiftPressed ? "running" : "walking");
+          return;
+        }
+        if (!this.isFirstPerson && (this.lftPressed || this.rgtPressed || this.bkdPressed)) {
+          this.playPersonAnimationByName(this.shiftPressed ? "running" : "walking");
+          return;
+        }
+        if (this.lftPressed) {
+          this.playPersonAnimationByName("left_walking");
+          return;
+        }
+        if (this.rgtPressed) {
+          this.playPersonAnimationByName("right_walking");
+          return;
+        }
+        if (this.bkdPressed) {
+          this.playPersonAnimationByName("walking_backward");
+          return;
+        }
+      }
+      if (this.recheckAnimTimer !== null) {
+        clearTimeout(this.recheckAnimTimer);
+      }
+      this.recheckAnimTimer = setTimeout(() => {
+        this.setAnimationByPressed();
+        this.recheckAnimTimer = null;
+      }, 200);
+    };
+    // ==================== 事件处理 ====================
+    /**
+     * 键盘按下事件
+     */
     this._boundOnKeydown = async (e) => {
-      if (e.ctrlKey && (e.code === "KeyW" || e.code === "KeyA" || e.code === "KeyS" || e.code === "KeyD")) {
+      if (e.ctrlKey && ["KeyW", "KeyA", "KeyS", "KeyD"].includes(e.code)) {
         e.preventDefault();
       }
       switch (e.code) {
@@ -124,11 +175,7 @@ var PlayerController = class {
         case "ShiftLeft":
           this.shiftPressed = true;
           this.setAnimationByPressed();
-          this.controls.mouseButtons = {
-            LEFT: 2,
-            MIDDLE: 1,
-            RIGHT: 0
-          };
+          this.controls.mouseButtons = { LEFT: 2, MIDDLE: 1, RIGHT: 0 };
           break;
         case "Space":
           this.spacePressed = true;
@@ -148,11 +195,15 @@ var PlayerController = class {
         case "KeyF":
           this.isFlying = !this.isFlying;
           this.setAnimationByPressed();
-          if (!this.isFlying && !this.playerIsOnGround) this.playPersonAnimationByName("jumping");
+          if (!this.isFlying && !this.playerIsOnGround) {
+            this.playPersonAnimationByName("jumping");
+          }
           break;
       }
     };
-    // 键盘抬起事件
+    /**
+     * 键盘抬起事件
+     */
     this._boundOnKeyup = (e) => {
       switch (e.code) {
         case "KeyW":
@@ -174,11 +225,7 @@ var PlayerController = class {
         case "ShiftLeft":
           this.shiftPressed = false;
           this.setAnimationByPressed();
-          this.controls.mouseButtons = {
-            LEFT: 0,
-            MIDDLE: 1,
-            RIGHT: 2
-          };
+          this.controls.mouseButtons = { LEFT: 0, MIDDLE: 1, RIGHT: 2 };
           break;
         case "Space":
           this.spacePressed = false;
@@ -188,127 +235,85 @@ var PlayerController = class {
           break;
       }
     };
-    // 根据按键设置人物动画
-    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");
-          return;
-        }
-        if (this.fwdPressed) {
-          if (this.shiftPressed) {
-            this.playPersonAnimationByName("running");
-          } else {
-            this.playPersonAnimationByName("walking");
-          }
-          return;
-        }
-        if (!this.isFirstPerson && (this.lftPressed || this.rgtPressed || this.bkdPressed)) {
-          if (this.shiftPressed) {
-            this.playPersonAnimationByName("running");
-          } else {
-            this.playPersonAnimationByName("walking");
-          }
-          return;
-        }
-        if (this.lftPressed) {
-          this.playPersonAnimationByName("left_walking");
-          return;
-        }
-        if (this.rgtPressed) {
-          this.playPersonAnimationByName("right_walking");
-          return;
-        }
-        if (this.bkdPressed) {
-          this.playPersonAnimationByName("walking_backward");
-          return;
-        }
-      }
-      if (this.recheckAnimTimer !== null) {
-        clearTimeout(this.recheckAnimTimer);
-      }
-      this.recheckAnimTimer = setTimeout(() => {
-        this.setAnimationByPressed();
-        this.recheckAnimTimer = null;
-      }, 200);
-    };
-    // 鼠标移动事件
+    /**
+     * 鼠标移动事件
+     */
     this._mouseMove = (e) => {
       if (document.pointerLockElement !== document.body) return;
       this.setToward(e.movementX, e.movementY, 1e-4);
     };
+    /**
+     * 鼠标点击事件
+     */
     this._mouseClick = (e) => {
       this.setPointerLock();
     };
+    // ==================== 移动端控制 ====================
+    /**
+     * 指针按下事件
+     */
     this.onPointerDown = (e) => {
       if (e.pointerType !== "touch") return;
       this.isLookDown = true;
       this.lookPointerId = e.pointerId;
       this.lastTouchX = e.clientX;
       this.lastTouchY = e.clientY;
-      this.lookAreaEl?.setPointerCapture && this.lookAreaEl.setPointerCapture(e.pointerId);
+      this.lookAreaEl?.setPointerCapture?.(e.pointerId);
       e.preventDefault();
     };
+    /**
+     * 指针移动事件
+     */
     this.onPointerMove = (e) => {
       if (!this.isLookDown || e.pointerId !== this.lookPointerId) return;
       const dx = e.clientX - this.lastTouchX;
       const dy = e.clientY - this.lastTouchY;
       this.lastTouchX = e.clientX;
       this.lastTouchY = e.clientY;
-      this.setInput({
-        lookDeltaX: dx,
-        lookDeltaY: dy
-      });
+      this.setInput({ lookDeltaX: dx, lookDeltaY: dy });
       e.preventDefault();
     };
+    /**
+     * 指针抬起事件
+     */
     this.onPointerUp = (e) => {
       if (e.pointerId !== this.lookPointerId) return;
       this.isLookDown = false;
       this.lookPointerId = null;
-      this.lookAreaEl?.releasePointerCapture && this.lookAreaEl.releasePointerCapture(e.pointerId);
+      this.lookAreaEl?.releasePointerCapture?.(e.pointerId);
     };
     this._raycaster.firstHitOnly = true;
     this._raycasterPersonToCam.firstHitOnly = true;
   }
-  // 初始化
+  // ==================== 初始化相关方法 ====================
+  /**
+   * 初始化控制器
+   */
   async init(opts, callback) {
     this.scene = opts.scene;
     this.camera = opts.camera;
     this.camera.rotation.order = "YXZ";
     this.controls = opts.controls;
     this.playerModel = opts.playerModel;
-    this.initPos = opts.initPos ? opts.initPos : new THREE.Vector3(0, 0, 0);
-    this.intDirection = opts.intDirection ? opts.intDirection : new THREE.Vector3(0, 0, -1);
-    this.mouseSensity = opts.mouseSensity ? opts.mouseSensity : 5;
+    this.initPos = opts.initPos ?? new THREE.Vector3(0, 0, 0);
+    this.mouseSensity = opts.mouseSensity ?? 5;
     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 : 800 * s;
-    this.originPlayerSpeed = opts.playerModel.speed ? opts.playerModel.speed * s : 400 * s;
+    this.gravity = (opts.playerModel.gravity ?? -2400) * s;
+    this.jumpHeight = (opts.playerModel.jumpHeight ?? 800) * s;
+    this.originPlayerSpeed = (opts.playerModel.speed ?? 400) * s;
     this.playerSpeed = this.originPlayerSpeed;
-    this.playerModel.rotateY = opts.playerModel.rotateY ? opts.playerModel.rotateY : 0;
+    this.playerModel.rotateY = opts.playerModel.rotateY ?? 0;
     this._camCollisionLerp = 0.18;
     this._camEpsilon = 35 * s;
-    this._minCamDistance = opts.minCamDistance ? opts.minCamDistance * s : 100 * s;
-    this._maxCamDistance = opts.maxCamDistance ? opts.maxCamDistance * s : 440 * s;
+    this._minCamDistance = (opts.minCamDistance ?? 100) * s;
+    this._maxCamDistance = (opts.maxCamDistance ?? 440) * s;
     this.orginMaxCamDistance = this._maxCamDistance;
     this.thirdMouseMode = opts.thirdMouseMode ?? 1;
-    function isMobileDevice() {
-      return navigator.maxTouchPoints && navigator.maxTouchPoints > 0 || "ontouchstart" in window || /Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
-    }
+    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) {
-      this.initMobileControls();
+      await this.initMobileControls();
     }
     await this.createBVH(opts.colliderMeshUrl);
     this.createPlayer();
@@ -321,73 +326,19 @@ var PlayerController = class {
     this.setControls();
     if (callback) callback();
   }
-  // 第一/三视角切换
-  changeView() {
-    this.isFirstPerson = !this.isFirstPerson;
-    if (this.isFirstPerson) {
-      this.player.attach(this.camera);
-      this.camera.position.set(0, 40 * this.playerModel.scale, 30 * this.playerModel.scale);
-      this.camera.rotation.set(0, Math.PI, 0);
-      this.setPointerLock();
-    } else {
-      this.scene.attach(this.camera);
-      const worldPos = this.player.position.clone();
-      const dir = new THREE.Vector3(0, 0, -1).applyQuaternion(this.player.quaternion);
-      const angle = Math.atan2(dir.z, dir.x);
-      const offset = new THREE.Vector3(Math.cos(angle) * 400 * this.playerModel.scale, 200 * this.playerModel.scale, Math.sin(angle) * 400 * this.playerModel.scale);
-      this.camera.position.copy(worldPos).add(offset);
-      this.controls.target.copy(worldPos);
-      this.setPointerLock();
-    }
-  }
-  setPointerLock() {
-    if ((this.thirdMouseMode == 0 || this.thirdMouseMode == 1) && !this.isFirstPerson || this.isFirstPerson) document.body.requestPointerLock();
-  }
-  // 摄像机/控制器设置
-  setCameraPos() {
-    if (this.isFirstPerson) {
-      this.camera.position.set(0, 40 * this.playerModel.scale, 30 * this.playerModel.scale);
-    } else {
-      const worldPos = this.player.position.clone();
-      const dir = new THREE.Vector3(0, 0, -1).applyQuaternion(this.player.quaternion);
-      const angle = Math.atan2(dir.z, dir.x);
-      const offset = new THREE.Vector3(Math.cos(angle) * 400 * this.playerModel.scale, -100 * this.playerModel.scale, Math.sin(angle) * 400 * this.playerModel.scale);
-      this.camera.position.copy(worldPos).add(offset);
-    }
-    this.camera.updateProjectionMatrix();
-  }
-  // 设置控制器
-  setControls() {
-    if (this.thirdMouseMode == 0 || this.thirdMouseMode == 1) {
-      this.controls.enabled = false;
-    } else {
-      this.controls.enabled = true;
-    }
-    this.controls.rotateSpeed = this.mouseSensity * 0.05;
-    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;
-    this.controls.rotateSpeed = 1;
-    this.controls.enableZoom = true;
-    this.controls.mouseButtons = {
-      LEFT: 0,
-      MIDDLE: 1,
-      RIGHT: 2
-    };
-  }
-  // 初始化加载器
+  /**
+   * 初始化加载器
+   */
   async initLoader() {
     const dracoLoader = new DRACOLoader();
     dracoLoader.setDecoderPath("https://unpkg.com/three@0.180.0/examples/jsm/libs/draco/gltf/");
     dracoLoader.setDecoderConfig({ type: "js" });
     this.loader.setDRACOLoader(dracoLoader);
   }
-  // 人物与动画加载
+  // ==================== 玩家模型相关方法 ====================
+  /**
+   * 加载玩家模型与动画
+   */
   async loadPersonGLB() {
     try {
       const gltf = await this.loader.loadAsync(this.playerModel.url);
@@ -407,8 +358,7 @@ var PlayerController = class {
       this.personMixer = new THREE.AnimationMixer(this.person);
       const animations = gltf.animations ?? [];
       this.personActions = /* @__PURE__ */ new Map();
-      const findClip = (name) => animations.find((a) => a.name === name);
-      const regs = [
+      const animationMappings = [
         [this.playerModel.idleAnim, "idle"],
         [this.playerModel.walkAnim, "walking"],
         [this.playerModel.leftWalkAnim || this.playerModel.walkAnim, "left_walking"],
@@ -419,11 +369,12 @@ var PlayerController = class {
         [this.playerModel.flyIdleAnim || this.playerModel.idleAnim, "flyidle"],
         [this.playerModel.flyAnim || this.playerModel.idleAnim, "flying"]
       ];
-      for (const [key, clipName] of regs) {
-        const clip = findClip(key);
+      const findClip = (name) => animations.find((a) => a.name === name);
+      for (const [clipName, actionName] of animationMappings) {
+        const clip = findClip(clipName);
         if (!clip) continue;
         const action = this.personMixer.clipAction(clip);
-        if (clipName === "jumping") {
+        if (actionName === "jumping") {
           action.setLoop(THREE.LoopOnce, 1);
           action.clampWhenFinished = true;
           action.setEffectiveTimeScale(1.2);
@@ -434,7 +385,7 @@ var PlayerController = class {
         }
         action.enabled = true;
         action.setEffectiveWeight(0);
-        this.personActions.set(clipName, action);
+        this.personActions.set(actionName, action);
       }
       this.idleAction = this.personActions.get("idle");
       this.walkAction = this.personActions.get("walking");
@@ -452,8 +403,7 @@ var PlayerController = class {
         const finishedAction = ev.action;
         if (finishedAction === this.jumpAction) {
           if (this.fwdPressed) {
-            if (this.shiftPressed) this.playPersonAnimationByName("running");
-            else this.playPersonAnimationByName("walking");
+            this.playPersonAnimationByName(this.shiftPressed ? "running" : "walking");
             return;
           }
           if (this.bkdPressed) {
@@ -468,15 +418,16 @@ var PlayerController = class {
         }
       });
     } catch (error) {
+      console.error("\u52A0\u8F7D\u73A9\u5BB6\u6A21\u578B\u5931\u8D25:", error);
     }
   }
-  // 平滑切换人物动画
+  /**
+   * 平滑切换人物动画
+   */
   playPersonAnimationByName(name, fade = 0.18) {
-    if (!this.personActions) return;
-    if (this.ctPressed) return;
+    if (!this.personActions || this.ctPressed) return;
     const next = this.personActions.get(name);
-    if (!next) return;
-    if (this.actionState === next) return;
+    if (!next || this.actionState === next) return;
     const prev = this.actionState;
     next.reset();
     next.setEffectiveWeight(1);
@@ -487,46 +438,254 @@ var PlayerController = class {
     } else {
       next.fadeIn(fade);
     }
-    this.actionState = next;
-  }
-  // 创建玩家胶囊体
-  createPlayer() {
-    const material = new THREE.MeshStandardMaterial({
-      color: new THREE.Color(1, 0, 0),
-      shadowSide: THREE.DoubleSide,
-      depthTest: false
-    });
-    material.transparent = true;
-    material.opacity = this.displayPlayer ? 0.5 : 0;
-    material.wireframe = true;
-    material.depthWrite = false;
-    const r = this.playerRadius * this.playerModel.scale;
-    const h = this.playerHeight * this.playerModel.scale;
-    this.player = new THREE.Mesh(new RoundedBoxGeometry(r * 2, h, r * 2, 1, 75), material);
-    this.player.geometry.translate(0, -h * 0.25, 0);
-    this.player.capsuleInfo = {
-      radius: r,
-      segment: new THREE.Line3(new THREE.Vector3(), new THREE.Vector3(0, -h * 0.5, 0))
-    };
-    this.player.name = "capsule";
-    this.scene.add(this.player);
-    this.reset();
-    this.player.rotateY(this.playerModel.rotateY ?? 0);
+    this.actionState = next;
+  }
+  /**
+   * 创建玩家胶囊体
+   */
+  createPlayer() {
+    const material = new THREE.MeshStandardMaterial({
+      color: new THREE.Color(1, 0, 0),
+      shadowSide: THREE.DoubleSide,
+      depthTest: false,
+      transparent: true,
+      opacity: this.displayPlayer ? 0.5 : 0,
+      wireframe: true,
+      depthWrite: false
+    });
+    const r = this.playerRadius * this.playerModel.scale;
+    const h = this.playerHeight * this.playerModel.scale;
+    this.player = new THREE.Mesh(new RoundedBoxGeometry(r * 2, h, r * 2, 1, 75), material);
+    this.player.geometry.translate(0, -h * 0.25, 0);
+    this.player.capsuleInfo = {
+      radius: r,
+      segment: new THREE.Line3(new THREE.Vector3(), new THREE.Vector3(0, -h * 0.5, 0))
+    };
+    this.player.name = "capsule";
+    this.scene.add(this.player);
+    this.reset();
+    this.player.rotateY(this.playerModel.rotateY ?? 0);
+  }
+  // ==================== 相机与视角控制 ====================
+  /**
+   * 第一/三人称视角切换
+   */
+  changeView() {
+    this.isFirstPerson = !this.isFirstPerson;
+    if (this.isFirstPerson) {
+      this.player.attach(this.camera);
+      this.camera.position.set(0, 40 * this.playerModel.scale, 30 * this.playerModel.scale);
+      this.camera.rotation.set(0, Math.PI, 0);
+    } else {
+      this.scene.attach(this.camera);
+      const worldPos = this.player.position.clone();
+      const dir = new THREE.Vector3(0, 0, -1).applyQuaternion(this.player.quaternion);
+      const angle = Math.atan2(dir.z, dir.x);
+      const offset = new THREE.Vector3(Math.cos(angle) * 400 * this.playerModel.scale, 200 * this.playerModel.scale, Math.sin(angle) * 400 * this.playerModel.scale);
+      this.camera.position.copy(worldPos).add(offset);
+      this.controls.target.copy(worldPos);
+    }
+    this.setPointerLock();
+  }
+  /**
+   * 设置指针锁定
+   */
+  setPointerLock() {
+    if ((this.thirdMouseMode === 0 || this.thirdMouseMode === 1) && !this.isFirstPerson || this.isFirstPerson) {
+      document.body.requestPointerLock();
+    }
+  }
+  /**
+   * 设置摄像机初始位置
+   */
+  setCameraPos() {
+    if (this.isFirstPerson) {
+      this.camera.position.set(0, 40 * this.playerModel.scale, 30 * this.playerModel.scale);
+    } else {
+      const worldPos = this.player.position.clone();
+      const dir = new THREE.Vector3(0, 0, -1).applyQuaternion(this.player.quaternion);
+      const angle = Math.atan2(dir.z, dir.x);
+      const offset = new THREE.Vector3(Math.cos(angle) * 400 * this.playerModel.scale, -100 * this.playerModel.scale, Math.sin(angle) * 400 * this.playerModel.scale);
+      this.camera.position.copy(worldPos).add(offset);
+    }
+    this.camera.updateProjectionMatrix();
+  }
+  /**
+   * 设置控制器
+   */
+  setControls() {
+    this.controls.enabled = !(this.thirdMouseMode === 0 || this.thirdMouseMode === 1);
+    this.controls.rotateSpeed = this.mouseSensity * 0.05;
+    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;
+    this.controls.rotateSpeed = 1;
+    this.controls.enableZoom = true;
+    this.controls.mouseButtons = { LEFT: 0, MIDDLE: 1, RIGHT: 2 };
+  }
+  /**
+   * 设置朝向
+   */
+  setToward(dx, dy, speed) {
+    if (this.isFirstPerson) {
+      const yaw = -dx * speed * this.mouseSensity;
+      const pitch = -dy * speed * this.mouseSensity;
+      this.player.rotateY(yaw);
+      this.camera.rotation.x = THREE.MathUtils.clamp(this.camera.rotation.x + pitch, -1.1, 1.4);
+    } else {
+      const sensitivity = this.mouseSensity;
+      const deltaX = -dx * speed * sensitivity;
+      const deltaY = -dy * speed * sensitivity;
+      const target = this.player.position.clone();
+      const distance = this.camera.position.distanceTo(target);
+      const currentPosition = this.camera.position.clone().sub(target);
+      let theta = Math.atan2(currentPosition.x, currentPosition.z);
+      let phi = Math.acos(currentPosition.y / distance);
+      theta += deltaX;
+      phi += deltaY;
+      phi = Math.max(0.1, Math.min(Math.PI - 0.1, phi));
+      const newX = distance * Math.sin(phi) * Math.sin(theta);
+      const newY = distance * Math.cos(phi);
+      const newZ = distance * Math.sin(phi) * Math.cos(theta);
+      this.camera.position.set(target.x + newX, target.y + newY, target.z + newZ);
+      this.camera.lookAt(target);
+    }
+  }
+  // ==================== 物理与碰撞检测 ====================
+  /**
+   * BVH碰撞体构建
+   */
+  async createBVH(meshUrl = "") {
+    await this.initLoader();
+    const ensureAttributesMinimal = (geom) => {
+      if (!geom.attributes.position) return null;
+      if (!geom.attributes.normal) geom.computeVertexNormals();
+      if (!geom.attributes.uv) {
+        const count = geom.attributes.position.count;
+        const dummyUV = new Float32Array(count * 2);
+        geom.setAttribute("uv", new THREE.BufferAttribute(dummyUV, 2));
+      }
+      return geom;
+    };
+    const collected = [];
+    if (meshUrl === "") {
+      if (this.collider) {
+        this.scene.remove(this.collider);
+        this.collider = null;
+      }
+      this.scene.traverse((c) => {
+        const mesh = c;
+        if (mesh?.isMesh && mesh.geometry && c.name !== "capsule") {
+          try {
+            let geom = mesh.geometry.clone();
+            geom.applyMatrix4(mesh.matrixWorld);
+            if (geom.index) geom = geom.toNonIndexed();
+            const safe = ensureAttributesMinimal(geom);
+            if (safe) collected.push(safe);
+          } catch (e) {
+            console.warn("\u5904\u7406\u7F51\u683C\u65F6\u51FA\u9519\uFF1A", mesh, e);
+          }
+        }
+      });
+      if (!collected.length) return;
+      const attrMap = /* @__PURE__ */ new Map();
+      const attrConflict = /* @__PURE__ */ new Set();
+      for (const g of collected) {
+        for (const name of Object.keys(g.attributes)) {
+          const attr = g.attributes[name];
+          const ctor = attr.array.constructor;
+          const itemSize = attr.itemSize;
+          if (!attrMap.has(name)) {
+            attrMap.set(name, { itemSize, arrayCtor: ctor, examples: 1 });
+          } else {
+            const m = attrMap.get(name);
+            if (m.itemSize !== itemSize || m.arrayCtor !== ctor) {
+              attrConflict.add(name);
+            } else {
+              m.examples++;
+            }
+          }
+        }
+      }
+      if (attrConflict.size) {
+        for (const g of collected) {
+          for (const name of Array.from(attrConflict)) {
+            if (g.attributes[name]) g.deleteAttribute(name);
+          }
+        }
+        for (const name of attrConflict) attrMap.delete(name);
+      }
+      const attrNames = Array.from(attrMap.keys());
+      for (const g of collected) {
+        const count = g.attributes.position.count;
+        for (const name of attrNames) {
+          if (!g.attributes[name]) {
+            const meta = attrMap.get(name);
+            const len = count * meta.itemSize;
+            const array = new meta.arrayCtor(len);
+            g.setAttribute(name, new THREE.BufferAttribute(array, meta.itemSize));
+          }
+        }
+      }
+    } else {
+      const gltf = await this.loader.loadAsync(meshUrl);
+      const mesh = gltf.scene.children[0];
+      mesh.name = "BVH\u52A0\u8F7D\u6A21\u578B";
+      let geom = mesh.geometry.clone();
+      geom.applyMatrix4(mesh.matrixWorld);
+      if (geom.index) geom = geom.toNonIndexed();
+      const safe = ensureAttributesMinimal(geom);
+      if (safe) collected.push(safe);
+    }
+    const merged = BufferGeometryUtils.mergeGeometries(collected, false);
+    if (!merged) {
+      console.error("\u5408\u5E76\u51E0\u4F55\u5931\u8D25");
+      return;
+    }
+    merged.boundsTree = new MeshBVH(merged, { maxDepth: 100 });
+    this.collider = new THREE.Mesh(
+      merged,
+      new THREE.MeshBasicMaterial({
+        opacity: 0.5,
+        transparent: true,
+        wireframe: true
+      })
+    );
+    if (this.displayCollider) this.scene.add(this.collider);
+    if (this.displayVisualizer) {
+      if (this.visualizer) this.scene.remove(this.visualizer);
+      this.visualizer = new MeshBVHHelper(this.collider, this.visualizeDepth);
+      this.scene.add(this.visualizer);
+    }
+    this.boundingBoxMinY = this.collider.geometry.boundingBox.min.y;
   }
-  // 获取法线与Y轴的夹角
+  /**
+   * 获取法线与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;
     const normalMagnitude = Math.sqrt(normal.x * normal.x + normal.y * normal.y + normal.z * normal.z);
-    const yAxisMagnitude = 1;
-    const cosTheta = dotProduct / (normalMagnitude * yAxisMagnitude);
+    const cosTheta = dotProduct / normalMagnitude;
     return Math.acos(cosTheta);
   }
-  // 每帧更新
+  // ==================== 循环更新 ====================
+  /**
+   * 每帧更新
+   */
   async update(delta = clock.getDelta()) {
     if (!this.isupdate || !this.player || !this.collider) return;
     delta = Math.min(delta, 1 / 30);
-    if (!this.isFlying) this.player.position.addScaledVector(this.playerVelocity, delta);
+    if (!this.isFlying) {
+      this.player.position.addScaledVector(this.playerVelocity, delta);
+    }
     this.updateMixers(delta);
     this.camera.getWorldDirection(this.camDir);
     let angle = Math.atan2(this.camDir.z, this.camDir.x) + Math.PI / 2;
@@ -537,14 +696,9 @@ var PlayerController = class {
     if (this.lftPressed) this.moveDir.add(this.DIR_LFT);
     if (this.rgtPressed) this.moveDir.add(this.DIR_RGT);
     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);
-      }
+      if (this.fwdPressed) this.moveDir.y = this.camDir.y;
+      else this.moveDir.y = 0;
+      if (this.spacePressed) this.moveDir.add(this.DIR_UP);
     }
     if (this.isFlying && this.fwdPressed) {
       this.playerSpeed = this.shiftPressed ? this.originPlayerSpeed * 12 : this.originPlayerSpeed * 7;
@@ -564,8 +718,7 @@ 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 (this.isFlying) {
-      } else {
+      if (!this.isFlying) {
         if (playerDistanceFromGround > maxH) {
           this.playerVelocity.y += delta * this.gravity;
           this.player.position.addScaledVector(this.playerVelocity, delta);
@@ -628,7 +781,7 @@ var PlayerController = class {
       this.moveDir.normalize();
       this.moveDir.negate();
       let lookTarget;
-      if (this.thirdMouseMode == 0 || this.thirdMouseMode == 2) {
+      if (this.thirdMouseMode === 0 || this.thirdMouseMode === 2) {
         if (this.moveDir.lengthSq() > 0) {
           lookTarget = this.player.position.clone().add(this.moveDir);
         } else {
@@ -639,7 +792,7 @@ var PlayerController = class {
         const alpha = Math.min(1, this.rotationSpeed * delta);
         this.player.quaternion.slerp(this.targetQuat, alpha);
       }
-      if ((this.thirdMouseMode == 1 || this.thirdMouseMode == 3) && this.moveDir.lengthSq() > 0) {
+      if ((this.thirdMouseMode === 1 || this.thirdMouseMode === 3) && this.moveDir.lengthSq() > 0) {
         lookTarget = this.player.position.clone().add(this.moveDir);
         this.targetMat.lookAt(this.player.position, lookTarget, this.player.up);
         this.targetQuat.setFromRotationMatrix(this.targetMat);
@@ -703,206 +856,39 @@ var PlayerController = class {
       }
     }
   }
-  // 重置
+  /**
+   * 更新模型动画
+   */
+  updateMixers(delta) {
+    if (this.personMixer) this.personMixer.update(delta);
+  }
+  /**
+   * 重置玩家位置
+   */
   reset(position) {
     if (!this.player) return;
     this.playerVelocity.set(0, 0, 0);
-    this.player.position.copy(position ? position : this.initPos);
-  }
-  // 销毁
-  destroy() {
-    this.offAllEvent();
-    if (this.player) {
-      this.player.remove(this.camera);
-      this.scene.remove(this.player);
-    }
-    this.player = null;
-    if (this.person) {
-      this.scene.remove(this.person);
-      this.person = null;
-    }
-    this.resetControls();
-    if (this.visualizer) {
-      this.scene.remove(this.visualizer);
-      this.visualizer = null;
-    }
-    if (this.collider) {
-      this.scene.remove(this.collider);
-      this.collider = null;
-    }
-    this.destroyMobileControls();
-    controllerInstance = null;
-  }
-  // 事件绑定
-  onAllEvent() {
-    this.isupdate = true;
-    this.setPointerLock();
-    window.addEventListener("keydown", this._boundOnKeydown);
-    window.addEventListener("keyup", this._boundOnKeyup);
-    window.addEventListener("mousemove", this._mouseMove);
-    window.addEventListener("click", this._mouseClick);
-  }
-  // 事件解绑
-  offAllEvent() {
-    this.isupdate = false;
-    document.exitPointerLock();
-    window.removeEventListener("keydown", this._boundOnKeydown);
-    window.removeEventListener("keyup", this._boundOnKeyup);
-    window.removeEventListener("mousemove", this._mouseMove);
-    window.removeEventListener("click", this._mouseClick);
+    this.player.position.copy(position ?? this.initPos);
   }
+  /**
+   * 获取玩家位置
+   */
   getPosition() {
     return this.player.position;
   }
-  // 更新模型动画
-  updateMixers(delta) {
-    if (this.personMixer) this.personMixer.update(delta);
-  }
-  // BVH构建
-  async createBVH(meshUrl = "") {
-    await this.initLoader();
-    const ensureAttributesMinimal = (geom) => {
-      if (!geom.attributes.position) {
-        return null;
-      }
-      if (!geom.attributes.normal) geom.computeVertexNormals();
-      if (!geom.attributes.uv) {
-        const count = geom.attributes.position.count;
-        const dummyUV = new Float32Array(count * 2);
-        geom.setAttribute("uv", new THREE.BufferAttribute(dummyUV, 2));
-      }
-      return geom;
-    };
-    const collected = [];
-    if (meshUrl == "") {
-      if (this.collider) {
-        this.scene.remove(this.collider);
-        this.collider = null;
-      }
-      this.scene.traverse((c) => {
-        const mesh = c;
-        if (mesh?.isMesh && mesh.geometry && c.name !== "capsule") {
-          try {
-            let geom = mesh.geometry.clone();
-            geom.applyMatrix4(mesh.matrixWorld);
-            if (geom.index) geom = geom.toNonIndexed();
-            const safe = ensureAttributesMinimal(geom);
-            if (safe) collected.push(safe);
-          } catch (e) {
-            console.warn("\u5904\u7406\u7F51\u683C\u65F6\u51FA\u9519\uFF1A", mesh, e);
-          }
-        }
-      });
-      if (!collected.length) {
-        return;
-      }
-      const attrMap = /* @__PURE__ */ new Map();
-      const attrConflict = /* @__PURE__ */ new Set();
-      for (const g of collected) {
-        for (const name of Object.keys(g.attributes)) {
-          const attr = g.attributes[name];
-          const ctor = attr.array.constructor;
-          const itemSize = attr.itemSize;
-          if (!attrMap.has(name)) {
-            attrMap.set(name, { itemSize, arrayCtor: ctor, examples: 1 });
-          } else {
-            const m = attrMap.get(name);
-            if (m.itemSize !== itemSize || m.arrayCtor !== ctor) attrConflict.add(name);
-            else m.examples++;
-          }
-        }
-      }
-      if (attrConflict.size) {
-        for (const g of collected) {
-          for (const name of Array.from(attrConflict)) {
-            if (g.attributes[name]) g.deleteAttribute(name);
-          }
-        }
-        for (const name of attrConflict) attrMap.delete(name);
-      }
-      const attrNames = Array.from(attrMap.keys());
-      for (const g of collected) {
-        const count = g.attributes.position.count;
-        for (const name of attrNames) {
-          if (!g.attributes[name]) {
-            const meta = attrMap.get(name);
-            const len = count * meta.itemSize;
-            const array = new meta.arrayCtor(len);
-            g.setAttribute(name, new THREE.BufferAttribute(array, meta.itemSize));
-          }
-        }
-      }
-    } else {
-      const gltf = await this.loader.loadAsync(meshUrl, (xhr) => {
-      });
-      const mesh = gltf.scene.children[0];
-      mesh.name = "BVH\u52A0\u8F7D\u6A21\u578B";
-      let geom = mesh.geometry.clone();
-      geom.applyMatrix4(mesh.matrixWorld);
-      if (geom.index) geom = geom.toNonIndexed();
-      const safe = ensureAttributesMinimal(geom);
-      if (safe) collected.push(safe);
-    }
-    const merged = BufferGeometryUtils.mergeGeometries(collected, false);
-    if (!merged) {
-      console.error("\u5408\u5E76\u51E0\u4F55\u5931\u8D25");
-      return;
-    }
-    merged.boundsTree = new MeshBVH(merged, {
-      maxDepth: 100
-    });
-    this.collider = new THREE.Mesh(
-      merged,
-      new THREE.MeshBasicMaterial({
-        opacity: 0.5,
-        transparent: true,
-        wireframe: true
-      })
-    );
-    if (this.displayCollider) this.scene.add(this.collider);
-    if (this.displayVisualizer) {
-      if (this.visualizer) this.scene.remove(this.visualizer);
-      this.visualizer = new MeshBVHHelper(this.collider, this.visualizeDepth);
-      this.scene.add(this.visualizer);
-    }
-    this.boundingBoxMinY = this.collider.geometry.boundingBox.min.y;
-  }
-  // 设置朝向
-  setToward(dx, dy, speed) {
-    if (this.isFirstPerson) {
-      const yaw = -dx * speed * this.mouseSensity;
-      const pitch = -dy * speed * this.mouseSensity;
-      this.player.rotateY(yaw);
-      this.camera.rotation.x = THREE.MathUtils.clamp(this.camera.rotation.x + pitch, -1.1, 1.4);
-    } else {
-      const sensitivity = this.mouseSensity;
-      const deltaX = -dx * speed * sensitivity;
-      const deltaY = -dy * speed * sensitivity;
-      const target = this.player.position.clone();
-      const distance = this.camera.position.distanceTo(target);
-      const currentPosition = this.camera.position.clone().sub(target);
-      let theta = Math.atan2(currentPosition.x, currentPosition.z);
-      let phi = Math.acos(currentPosition.y / distance);
-      theta += deltaX;
-      phi += deltaY;
-      phi = Math.max(0.1, Math.min(Math.PI - 0.1, phi));
-      const newX = distance * Math.sin(phi) * Math.sin(theta);
-      const newY = distance * Math.cos(phi);
-      const newZ = distance * Math.sin(phi) * Math.cos(theta);
-      this.camera.position.set(target.x + newX, target.y + newY, target.z + newZ);
-      this.camera.lookAt(target);
-    }
-  }
-  // 设置输入
+  // ==================== 输入处理 ====================
+  /**
+   * 设置输入
+   */
   setInput(input) {
     if (typeof input.moveX === "number") {
-      this.lftPressed = input.moveX == -1;
-      this.rgtPressed = input.moveX == 1;
+      this.lftPressed = input.moveX === -1;
+      this.rgtPressed = input.moveX === 1;
       this.setAnimationByPressed();
     }
     if (typeof input.moveY === "number") {
-      this.fwdPressed = input.moveY == 1;
-      this.bkdPressed = input.moveY == -1;
+      this.fwdPressed = input.moveY === 1;
+      this.bkdPressed = input.moveY === -1;
       this.setAnimationByPressed();
     }
     if (typeof input.lookDeltaX === "number" && typeof input.lookDeltaY === "number") {
@@ -928,10 +914,36 @@ var PlayerController = class {
     if (input.toggleFly) {
       this.isFlying = !this.isFlying;
       this.setAnimationByPressed();
-      if (!this.isFlying && !this.playerIsOnGround) this.playPersonAnimationByName("jumping");
+      if (!this.isFlying && !this.playerIsOnGround) {
+        this.playPersonAnimationByName("jumping");
+      }
     }
   }
-  // 初始化移动端摇杆控制
+  /**
+   * 事件绑定
+   */
+  onAllEvent() {
+    this.isupdate = true;
+    this.setPointerLock();
+    window.addEventListener("keydown", this._boundOnKeydown);
+    window.addEventListener("keyup", this._boundOnKeyup);
+    window.addEventListener("mousemove", this._mouseMove);
+    window.addEventListener("click", this._mouseClick);
+  }
+  /**
+   * 事件解绑
+   */
+  offAllEvent() {
+    this.isupdate = false;
+    document.exitPointerLock();
+    window.removeEventListener("keydown", this._boundOnKeydown);
+    window.removeEventListener("keyup", this._boundOnKeyup);
+    window.removeEventListener("mousemove", this._mouseMove);
+    window.removeEventListener("click", this._mouseClick);
+  }
+  /**
+   * 初始化移动端摇杆控制
+   */
   async initMobileControls() {
     this.controls.maxPolarAngle = Math.PI * (300 / 360);
     this.controls.touches = { ONE: null, TWO: null };
@@ -955,13 +967,9 @@ var PlayerController = class {
     });
     container.appendChild(this.joystickZoneEl);
     ["touchstart", "touchmove", "touchend", "touchcancel"].forEach((evtName) => {
-      this.joystickZoneEl?.addEventListener(
-        evtName,
-        (e) => {
-          e.preventDefault();
-        },
-        { passive: false }
-      );
+      this.joystickZoneEl?.addEventListener(evtName, (e) => e.preventDefault(), {
+        passive: false
+      });
     });
     this.joystickManager = nipple.create({
       zone: this.joystickZoneEl,
@@ -1013,26 +1021,14 @@ var PlayerController = class {
     });
     container.appendChild(this.lookAreaEl);
     ["touchstart", "touchmove", "touchend", "touchcancel"].forEach((evtName) => {
-      this.lookAreaEl?.addEventListener(
-        evtName,
-        (e) => {
-          e.preventDefault();
-        },
-        { passive: false }
-      );
-    });
-    this.lookAreaEl.addEventListener("pointerdown", this.onPointerDown, {
-      passive: false
-    });
-    this.lookAreaEl.addEventListener("pointermove", this.onPointerMove, {
-      passive: false
-    });
-    this.lookAreaEl.addEventListener("pointerup", this.onPointerUp, {
-      passive: false
-    });
-    this.lookAreaEl.addEventListener("pointercancel", this.onPointerUp, {
-      passive: false
+      this.lookAreaEl?.addEventListener(evtName, (e) => e.preventDefault(), {
+        passive: false
+      });
     });
+    this.lookAreaEl.addEventListener("pointerdown", this.onPointerDown, { passive: false });
+    this.lookAreaEl.addEventListener("pointermove", this.onPointerMove, { passive: false });
+    this.lookAreaEl.addEventListener("pointerup", this.onPointerUp, { passive: false });
+    this.lookAreaEl.addEventListener("pointercancel", this.onPointerUp, { passive: false });
     const createBtn = (rightPx, bottomPx, bgUrl) => {
       const btn = document.createElement("button");
       const styles = {
@@ -1064,13 +1060,7 @@ var PlayerController = class {
       Object.assign(btn.style, styles);
       container.appendChild(btn);
       ["touchstart", "touchend", "touchcancel"].forEach((evtName) => {
-        btn.addEventListener(
-          evtName,
-          (e) => {
-            e.preventDefault();
-          },
-          { passive: false }
-        );
+        btn.addEventListener(evtName, (e) => e.preventDefault(), { passive: false });
       });
       return btn;
     };
@@ -1118,7 +1108,9 @@ var PlayerController = class {
       { passive: false }
     );
   }
-  // 销毁移动端摇杆控制
+  /**
+   * 销毁移动端摇杆控制
+   */
   destroyMobileControls() {
     try {
       if (this.joystickManager && this.joystickManager.destroy) {
@@ -1153,6 +1145,33 @@ var PlayerController = class {
       console.warn("\u9500\u6BC1\u79FB\u52A8\u7AEF\u6447\u6746\u63A7\u5236\u65F6\u51FA\u9519\uFF1A", e);
     }
   }
+  // ==================== 销毁 ====================
+  /**
+   * 销毁人物控制器
+   */
+  destroy() {
+    this.offAllEvent();
+    if (this.player) {
+      this.player.remove(this.camera);
+      this.scene.remove(this.player);
+    }
+    this.player = null;
+    if (this.person) {
+      this.scene.remove(this.person);
+      this.person = null;
+    }
+    this.resetControls();
+    if (this.visualizer) {
+      this.scene.remove(this.visualizer);
+      this.visualizer = null;
+    }
+    if (this.collider) {
+      this.scene.remove(this.collider);
+      this.collider = null;
+    }
+    this.destroyMobileControls();
+    controllerInstance = null;
+  }
 };
 function playerController() {
   if (!controllerInstance) controllerInstance = new PlayerController();