three-base 2.0.130 → 2.0.137

package/FPScontrol.js

@@ -1,232 +1,617 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-05-04 23:01:36
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-11-07 21:57:39
- */
-import { Clock, EventDispatcher, Vector3, } from "three";
-import { Capsule } from "three/examples/jsm/math/Capsule";
-import { Octree } from "three/examples/jsm/math/Octree";
-import { clamp, degToRad } from "three/src/math/MathUtils";
-/**
- * 第一人称控制器
- *
- * @export
- * @class FPScontrol
- * @extends {EventDispatcher}
- */
-export default class FPScontrol extends EventDispatcher {
-    canvas;
-    constructor(camera, canvas) {
-        super();
-        // 相机对象
-        this.camera = camera;
-        this.camera.rotation.order = "YXZ";
-        this.canvas = canvas;
-        this.init(canvas);
-    }
-    // 是否启用
-    enable = false;
-    GRAVITY = 30; // 重力
-    STEPS_PER_FRAME = 5; // 每帧碰撞计算的次数
-    speed = 1; // 速度
-    camera;
-    // 移动时是否保持惯性 由外部来配置
-    inertia = true;
-    // 八叉树数组
-    octreeMap = new Map();
-    octree = (() => {
-        const octree = new Octree();
-        octree.getCapsuleTriangles = (capsule, triangles) => {
-            const octrees = Array.from(this.octreeMap.values());
-            for (let octree of octrees) {
-                for (let i = 0; i < octree.subTrees.length; i++) {
-                    const subTree = octree.subTrees[i];
-                    if (!capsule.intersectsBox(subTree.box))
-                        continue;
-                    if (subTree.triangles.length > 0) {
-                        for (let j = 0; j < subTree.triangles.length; j++) {
-                            if (triangles.indexOf(subTree.triangles[j]) === -1)
-                                triangles.push(subTree.triangles[j]);
-                        }
-                    }
-                    else {
-                        subTree.getCapsuleTriangles(capsule, triangles);
-                    }
-                }
-            }
-            return triangles;
-        };
-        return octree;
-    })();
-    addOctree(obj) {
-        const octree = new Octree();
-        octree.fromGraphNode(obj);
-        this.octreeMap.set(obj.id, octree);
-        return octree;
-    }
-    // 用户自己的碰撞体积
-    playerCollider = new Capsule(new Vector3(0, 0.35, 0), new Vector3(0, 1, 0), 0.35);
-    // 时钟对象
-    clock = new Clock();
-    prePlayerVelocity = new Vector3();
-    playerVelocity = new Vector3();
-    // 起跳中
-    jumping = false;
-    playerDirection = new Vector3();
-    prePlayerOnFloor = false;
-    playerOnFloor = false;
-    mouseTime = 0;
-    isMousedown = false;
-    keyStates = {};
-    init(canvas) {
-        this.playerCollider.end.set(0, 1, 0);
-        document.addEventListener("keydown", this.keydown);
-        document.addEventListener("keyup", this.keyup);
-        canvas.addEventListener("pointerdown", this.mousedown);
-        document.addEventListener("pointerup", this.mouseup);
-        document.body.addEventListener("pointermove", this.mousemove);
-        this.enable = true;
-    }
-    keydown = (event) => {
-        this.keyStates[event.code] = true;
-    };
-    keyup = (event) => {
-        this.keyStates[event.code] = false;
-    };
-    mousedown = () => {
-        this.isMousedown = true;
-        this.mouseTime = performance.now();
-    };
-    mouseup = () => {
-        this.isMousedown = false;
-    };
-    mousemove = (event) => {
-        if (this.enable && this.isMousedown) {
-            this.camera.rotation.y -= event.movementX / 500;
-            this.camera.rotation.x -= event.movementY / 500;
-        }
-    };
-    // 获取前进的向量
-    getForwardVector = () => {
-        this.camera.getWorldDirection(this.playerDirection);
-        this.playerDirection.y = 0;
-        this.playerDirection.normalize();
-        return this.playerDirection;
-    };
-    // 获取 后退的向量
-    getSideVector = () => {
-        this.camera.getWorldDirection(this.playerDirection);
-        this.playerDirection.y = 0;
-        this.playerDirection.normalize();
-        this.playerDirection.cross(this.camera.up);
-        return this.playerDirection;
-    };
-    // 玩家移动控制器
-    controls = (deltaTime) => {
-        const speedDelta = deltaTime * (this.playerOnFloor ? 25 : 8) * this.speed;
-        // const speedDelta = this.speed;
-        if (this.keyStates["KeyW"]) {
-            this.playerVelocity.add(this.getForwardVector().multiplyScalar(speedDelta));
-        }
-        if (this.keyStates["KeyS"]) {
-            this.playerVelocity.add(this.getForwardVector().multiplyScalar(-speedDelta));
-        }
-        if (this.keyStates["KeyA"]) {
-            this.playerVelocity.add(this.getSideVector().multiplyScalar(-speedDelta));
-        }
-        if (this.keyStates["KeyD"]) {
-            this.playerVelocity.add(this.getSideVector().multiplyScalar(speedDelta));
-        }
-        if (this.playerOnFloor &&
-            !this.keyStates["KeyW"] &&
-            !this.keyStates["KeyS"] &&
-            !this.keyStates["KeyA"] &&
-            !this.keyStates["KeyD"]) {
-            if (!this.inertia) {
-                // 关闭惯性时就大幅增加动能的衰减
-                this.playerVelocity.x *= 0.85;
-                this.playerVelocity.z *= 0.85;
-            }
-        }
-        if (this.playerOnFloor) {
-            if (this.keyStates["Space"]) {
-                this.playerVelocity.y = 15;
-                this.jumping = true;
-                this.dispatchEvent({ type: "jump_start" });
-            }
-        }
-    };
-    // 更新玩家的位置
-    updatePlayer = (deltaTime) => {
-        let damping = Math.exp(-4 * deltaTime) - 1;
-        if (!this.playerOnFloor) {
-            this.playerVelocity.y -= this.GRAVITY * deltaTime;
-            damping *= 0.1;
-        }
-        this.playerVelocity.addScaledVector(this.playerVelocity, damping);
-        const deltaPosition = this.playerVelocity.clone().multiplyScalar(deltaTime);
-        this.playerCollider.translate(deltaPosition);
-        this.playerCollisions();
-        this.camera.position.copy(this.playerCollider.end);
-        this.camera.rotation.x = clamp(this.camera.rotation.x, degToRad(-89), degToRad(89));
-    };
-    // 玩家的碰撞检测
-    playerCollisions() {
-        this.playerOnFloor = false;
-        // 遍历 八叉树 做碰撞检测
-        const result = this.octree.capsuleIntersect(this.playerCollider);
-        if (result) {
-            this.playerOnFloor = result.normal.y > 0;
-            if (!this.playerOnFloor) {
-                this.playerVelocity.addScaledVector(result.normal, -result.normal.dot(this.playerVelocity));
-            }
-            const { x: preX, y: preY, z: preZ } = this.prePlayerVelocity;
-            const { x, y, z } = this.playerVelocity;
-            if (Math.abs(preX + preZ) < 0.1 && Math.abs(x + z) > 0.1) {
-                this.dispatchEvent({ type: "move_start" });
-            }
-            else if (Math.abs(preX + preZ) > 0.1 && Math.abs(x + z) < 0.1) {
-                this.dispatchEvent({ type: "move_end" });
-            }
-            this.prePlayerVelocity.copy(this.playerVelocity);
-            this.playerCollider.translate(result.normal.multiplyScalar(result.depth));
-        }
-        if (this.jumping && !this.prePlayerOnFloor && this.playerOnFloor) {
-            // 分发落地事件
-            this.jumping = false;
-            this.dispatchEvent({ type: "jump_end" });
-        }
-        this.prePlayerOnFloor = this.playerOnFloor;
-    }
-    // 更新控制器的位置
-    teleportPlayerIfOob = () => {
-        if (this.camera.position.y <= -10) {
-            this.playerCollider.start.set(0, 0.35, 0);
-            this.playerCollider.end.set(0, 1, 10);
-            this.playerCollider.radius = 0.35;
-            this.camera.position.copy(this.playerCollider.end);
-            //   this.camera.position.set(0, 3, 0);
-        }
-    };
-    // 更新
-    update() {
-        if (this.enable) {
-            const deltaTime = Math.min(0.05, this.clock.getDelta()) / this.STEPS_PER_FRAME;
-            for (let i = 0; i < this.STEPS_PER_FRAME; i++) {
-                this.controls(deltaTime);
-                this.updatePlayer(deltaTime);
-                this.teleportPlayerIfOob();
-            }
-        }
-    }
-    // 销毁事件
-    disposer() {
-        this.enable = false;
-        document.removeEventListener("keydown", this.keydown);
-        document.removeEventListener("keyup", this.keyup);
-        this.canvas.removeEventListener("pointerdown", this.mousedown);
-        document.removeEventListener("pointerup", this.mouseup);
-        document.body.removeEventListener("pointermove", this.mousemove);
-    }
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-05-04 23:01:36
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-11-07 21:57:39
+ */
+import { BufferGeometry, Clock, EventDispatcher, Euler, Float32BufferAttribute, Group, Line, LineBasicMaterial, Mesh, InstancedMesh, Quaternion, Raycaster, Vector3, } from "three";
+import { Capsule } from "three/examples/jsm/math/Capsule";
+import { clamp, degToRad } from "three/src/math/MathUtils";
+import { acceleratedRaycast, computeBoundsTree } from "three-mesh-bvh";
+// 确保 three-mesh-bvh 补丁已应用（含 InstancedMesh）
+if (Mesh.prototype.raycast !== acceleratedRaycast) {
+    Mesh.prototype.raycast = acceleratedRaycast;
+}
+if (InstancedMesh.prototype.raycast !== acceleratedRaycast) {
+    InstancedMesh.prototype.raycast = acceleratedRaycast;
+}
+/** 第一/三人称控制器（6 射线 + 迭代推离，userData.fpsCollision 标记碰撞体） */
+export default class FPScontrol extends EventDispatcher {
+    canvas;
+    /**
+     * @param camera 相机
+     * @param canvas canvas 元素
+     * @param scene 场景，用于射线碰撞检测（会递归检测所有子对象）
+     */
+    constructor(camera, canvas, scene) {
+        super();
+        this.camera = camera;
+        this.camera.rotation.order = "YXZ";
+        this.canvas = canvas;
+        this.scene = scene;
+        this.init(canvas);
+    }
+    // 是否启用
+    enable = false;
+    GRAVITY = 30; // 重力
+    STEPS_PER_FRAME = 2; // 每帧碰撞计算的次数
+    speed = 1; // 速度
+    camera;
+    // 移动时是否保持惯性 由外部来配置
+    inertia = true;
+    // 场景引用（用于射线检测）
+    scene;
+    // ========== dev / 第三人称 ==========
+    // 开发模式：打开后显示射线可视化
+    dev = false;
+    // 调试模式相机偏移（本地坐标系，Y=上，Z=后）
+    devCameraOffset = new Vector3(0, 2.5, 12.5);
+    // 第三人称模式
+    thirdPerson = false;
+    // 第三人称参数：相机与第一人称位置的距离和高度偏移
+    thirdPersonDistance = 5;
+    thirdPersonHeight = 2;
+    // 第三人称轨道角
+    _thirdPersonAngleY = 0;
+    _thirdPersonAngleX = 0.5;
+    // 模式切换检测
+    _prevThirdPerson = false;
+    // ========== 射线碰撞检测 ==========
+    // 碰撞体积（对应 xsh-react-three 的 collideVolume，默认 3，此处缩放为 0.5）
+    // 用于水平射线的起点偏移和 far 值
+    COLLIDE_VOLUME = 0.5;
+    // 垂直碰撞范围 = 从 playerCollider.end（眼睛）到脚底的距离
+    // = capsule length + radius = (1.0 - 0.35) + 0.35 = 1.0
+    // 对应 xsh-react-three 中 collideVolume（=3）= 控制器到地面的距离
+    // xsh 中 far = collideVolume, 响应 = collideVolume - distance
+    // 此处 far = VERTICAL_RANGE, 响应 = VERTICAL_RANGE - distance
+    VERTICAL_RANGE = 1.0;
+    // 推离步长（每次迭代推离的距离，与 xsh-react-three 一致：0.03）
+    PUSH_DISTANCE = 0.03;
+    // 最大迭代次数（与 xsh-react-three 一致：100）
+    MAX_ITERATIONS = 100;
+    // 临时四元数（复用避免 GC）
+    _tempQuat = new Quaternion();
+    // 射线检测器
+    _raycaster = new Raycaster();
+    // 临时向量（复用避免 GC）
+    _tempVec = new Vector3();
+    _tempVec2 = new Vector3();
+    _tempVec3 = new Vector3();
+    _tempVec4 = new Vector3();
+    // ========== 射线定义（完全参考 xsh-react-three FPSControls.tsx 的 render 方法）==========
+    // 射线定义在局部空间，通过 Group3D(rotation={x: -euler.x}) 补偿 pitch
+    // 即射线只跟随 yaw 旋转，不跟随 pitch 俯仰
+    //
+    // xsh-react-three 原始布局（collideVolume=cv）：
+    //   rightToForwardRay: position={x:cv, y:0, z:0},  direction={x:-cv, y:0, z:-cv}
+    //   leftToForwardRay:  position={x:-cv, y:0, z:0}, direction={x:cv, y:0, z:-cv}
+    //   leftToBackRay:     position={x:-cv, y:0, z:0}, direction={x:cv, y:0, z:cv}
+    //   rightToBackRay:    position={x:cv, y:0, z:0},  direction={x:-cv, y:0, z:cv}
+    //   upTodwomRay:       position={x:0, y:0, z:0},   direction={y:-cv}
+    //   dwomToUpRay:       position={x:0, y:0, z:0},   direction={y:cv}
+    //
+    // 局部空间射线起点（索引 0-5）
+    _localRayOrigins = [
+        new Vector3(0, 0, 0), // 0: upTodwomRay（下射线）
+        new Vector3(0, 0, 0), // 1: dwomToUpRay（上射线）
+        new Vector3(1, 0, 0), // 2: rightToForwardRay 起点（右侧）
+        new Vector3(-1, 0, 0), // 3: leftToForwardRay 起点（左侧）
+        new Vector3(-1, 0, 0), // 4: leftToBackRay 起点（左侧）
+        new Vector3(1, 0, 0), // 5: rightToBackRay 起点（右侧）
+    ];
+    // 局部空间射线方向（对应 direction prop，归一化前为 {x:±cv, y:0, z:±cv}）
+    // 归一化后与 xsh 的 clampLength(0,1) 效果一致
+    _localRayDirs = [
+        new Vector3(0, -1, 0), // 0: 下射线方向
+        new Vector3(0, 1, 0), // 1: 上射线方向
+        new Vector3(-1, 0, -1).normalize(), // 2: rightToForward → 指向 -X -Z（左前方）
+        new Vector3(1, 0, -1).normalize(), // 3: leftToForward → 指向 +X -Z（右前方）
+        new Vector3(1, 0, 1).normalize(), // 4: leftToBack → 指向 +X +Z（右后方）
+        new Vector3(-1, 0, 1).normalize(), // 5: rightToBack → 指向 -X +Z（左后方）
+    ];
+    // 世界空间射线起点（复用避免 GC）
+    _worldRayOrigins = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
+    // 世界空间射线方向（复用避免 GC）
+    _worldRayDirs = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
+    // userData.fpsCollision === true 的碰撞体列表
+    _colliders = [];
+    // 缓存标记：场景变化时才重建碰撞体列表
+    _collidersDirty = true;
+    _colliderSceneVersion = 0;
+    // 收集 fpsCollision 物体 + 首次构建 BVH
+    _getColliders() {
+        if (!this._collidersDirty)
+            return;
+        this._colliders.length = 0;
+        this.scene.traverseVisible((obj) => {
+            if (obj.isMesh && obj.userData?.fpsCollision) {
+                const geo = obj.geometry;
+                if (geo && !geo.boundsTree && geo.attributes.position?.count > 0) {
+                    computeBoundsTree.apply(geo);
+                }
+                this._colliders.push(obj);
+            }
+        });
+        this._collidersDirty = false;
+    }
+    // 标记碰撞体列表需要重建（外部在添加/删除碰撞体时调用）
+    markCollidersDirty() {
+        this._collidersDirty = true;
+    }
+    // 玩家胶囊碰撞体
+    playerCollider = new Capsule(new Vector3(0, 0.35, 0), new Vector3(0, 1, 0), 0.35);
+    // 时钟对象
+    clock = new Clock();
+    prePlayerVelocity = new Vector3();
+    playerVelocity = new Vector3();
+    // 起跳中
+    jumping = false;
+    playerDirection = new Vector3();
+    prePlayerOnFloor = false;
+    playerOnFloor = false;
+    mouseTime = 0;
+    isMousedown = false;
+    keyStates = {};
+    // ========== 射线可视化 ==========
+    _debugRayGroup = null;
+    // 6 条调试线段：0-3 水平射线，4 向下射线，5 向上射线
+    _debugLines = [];
+    // 懒初始化调试射线组
+    _initDebugLines() {
+        if (this._debugRayGroup)
+            return;
+        this._debugRayGroup = new Group();
+        this._debugRayGroup.name = "FPSControl_DebugRays";
+        for (let i = 0; i < 6; i++) {
+            const geo = new BufferGeometry();
+            geo.setAttribute("position", new Float32BufferAttribute(new Float32Array(6), 3));
+            geo.setAttribute("color", new Float32BufferAttribute(new Float32Array(6), 3));
+            const mat = new LineBasicMaterial({
+                vertexColors: true,
+                linewidth: 1,
+            });
+            const line = new Line(geo, mat);
+            // 让调试线段不被射线检测命中
+            line.raycast = () => { };
+            line.frustumCulled = false;
+            this._debugLines.push(line);
+            this._debugRayGroup.add(line);
+        }
+        this.scene.add(this._debugRayGroup);
+    }
+    // 更新调试线段位置 + 颜色
+    _updateDebugLine(index, origin, farPoint, hit) {
+        const line = this._debugLines[index];
+        const pos = line.geometry.attributes.position.array;
+        const col = line.geometry.attributes.color.array;
+        // 位置：起点 → 终点
+        pos[0] = origin.x;
+        pos[1] = origin.y;
+        pos[2] = origin.z;
+        pos[3] = farPoint.x;
+        pos[4] = farPoint.y;
+        pos[5] = farPoint.z;
+        // 颜色渐变：起点（近端）绿色/红色 → 终点白色
+        const r = hit ? 1.0 : 0.0;
+        const g = hit ? 0.0 : 1.0;
+        col[0] = r;
+        col[1] = g;
+        col[2] = 0.0; // 起点
+        col[3] = 1.0;
+        col[4] = 1.0;
+        col[5] = 1.0; // 终点白色
+        line.geometry.attributes.position.needsUpdate = true;
+        line.geometry.attributes.color.needsUpdate = true;
+    }
+    // 销毁调试射线
+    _disposeDebugLines() {
+        if (!this._debugRayGroup)
+            return;
+        for (const line of this._debugLines) {
+            line.geometry.dispose();
+            line.material.dispose();
+        }
+        this._debugLines = [];
+        this.scene.remove(this._debugRayGroup);
+        this._debugRayGroup = null;
+    }
+    init(canvas) {
+        this.playerCollider.end.set(0, 1, 0);
+        document.addEventListener("keydown", this.keydown);
+        document.addEventListener("keyup", this.keyup);
+        canvas.addEventListener("pointerdown", this.mousedown);
+        document.addEventListener("pointerup", this.mouseup);
+        document.body.addEventListener("pointermove", this.mousemove);
+        this.enable = true;
+    }
+    keydown = (event) => {
+        this.keyStates[event.code] = true;
+    };
+    keyup = (event) => {
+        this.keyStates[event.code] = false;
+    };
+    mousedown = () => {
+        this.isMousedown = true;
+        this.mouseTime = performance.now();
+    };
+    mouseup = () => {
+        this.isMousedown = false;
+    };
+    mousemove = (event) => {
+        if (this.enable && this.isMousedown) {
+            if (this.thirdPerson) {
+                // 第三人称：旋转轨道角
+                this._thirdPersonAngleY -= event.movementX / 500;
+                this._thirdPersonAngleX -= event.movementY / 500;
+                this._thirdPersonAngleX = clamp(this._thirdPersonAngleX, degToRad(-89), degToRad(89));
+            }
+            else {
+                // 第一人称：直接旋转相机
+                this.camera.rotation.y -= event.movementX / 500;
+                this.camera.rotation.x -= event.movementY / 500;
+            }
+        }
+    };
+    // 获取前进的向量
+    getForwardVector = () => {
+        if (this.thirdPerson) {
+            // 第三人称：前进 = 轨道偏航方向
+            this.playerDirection.set(Math.sin(this._thirdPersonAngleY), 0, Math.cos(this._thirdPersonAngleY));
+            return this.playerDirection;
+        }
+        this.camera.getWorldDirection(this.playerDirection);
+        this.playerDirection.y = 0;
+        this.playerDirection.normalize();
+        return this.playerDirection;
+    };
+    // 获取侧向向量
+    getSideVector = () => {
+        if (this.thirdPerson) {
+            // 第三人称：侧向 = 轨道偏航 ±90°
+            this.playerDirection.set(Math.sin(this._thirdPersonAngleY + Math.PI / 2), 0, Math.cos(this._thirdPersonAngleY + Math.PI / 2));
+            return this.playerDirection;
+        }
+        this.camera.getWorldDirection(this.playerDirection);
+        this.playerDirection.y = 0;
+        this.playerDirection.normalize();
+        this.playerDirection.cross(this.camera.up);
+        return this.playerDirection;
+    };
+    // 玩家移动控制器
+    controls = (deltaTime) => {
+        const speedDelta = deltaTime * (this.playerOnFloor ? 25 : 8) * this.speed;
+        if (this.keyStates["KeyW"]) {
+            this.playerVelocity.add(this.getForwardVector().multiplyScalar(speedDelta));
+        }
+        if (this.keyStates["KeyS"]) {
+            this.playerVelocity.add(this.getForwardVector().multiplyScalar(-speedDelta));
+        }
+        if (this.keyStates["KeyA"]) {
+            this.playerVelocity.add(this.getSideVector().multiplyScalar(-speedDelta));
+        }
+        if (this.keyStates["KeyD"]) {
+            this.playerVelocity.add(this.getSideVector().multiplyScalar(speedDelta));
+        }
+        if (this.playerOnFloor &&
+            !this.keyStates["KeyW"] &&
+            !this.keyStates["KeyS"] &&
+            !this.keyStates["KeyA"] &&
+            !this.keyStates["KeyD"]) {
+            if (!this.inertia) {
+                this.playerVelocity.x *= 0.85;
+                this.playerVelocity.z *= 0.85;
+            }
+        }
+        if (this.playerOnFloor) {
+            if (this.keyStates["Space"]) {
+                this.playerVelocity.y = 15;
+                this.jumping = true;
+                this.dispatchEvent({ type: "jump_start" });
+            }
+        }
+    };
+    // 更新玩家的位置
+    updatePlayer = (deltaTime) => {
+        let damping = Math.exp(-4 * deltaTime) - 1;
+        if (!this.playerOnFloor) {
+            this.playerVelocity.y -= this.GRAVITY * deltaTime;
+            damping *= 0.1;
+        }
+        this.playerVelocity.addScaledVector(this.playerVelocity, damping);
+        const deltaPosition = this.playerVelocity.clone().multiplyScalar(deltaTime);
+        this.playerCollider.translate(deltaPosition);
+        this.playerCollisions();
+        // 设置相机位置（第一人称默认值）
+        this.camera.position.copy(this.playerCollider.end);
+        // 第三人称：偏移相机位置 + 朝向第一人称坐标
+        if (this.thirdPerson) {
+            const cosPitch = Math.cos(this._thirdPersonAngleX);
+            this.camera.position.x +=
+                Math.sin(this._thirdPersonAngleY) *
+                    cosPitch *
+                    this.thirdPersonDistance;
+            this.camera.position.y +=
+                Math.sin(this._thirdPersonAngleX) * this.thirdPersonDistance +
+                    this.thirdPersonHeight;
+            this.camera.position.z +=
+                Math.cos(this._thirdPersonAngleY) *
+                    cosPitch *
+                    this.thirdPersonDistance;
+            this.camera.lookAt(this.playerCollider.end);
+        }
+        // dev 调试模式：在相机本地坐标系叠加偏移（向后上方）
+        if (this.dev && !this.thirdPerson) {
+            const offset = this.devCameraOffset.clone().applyQuaternion(this.camera.quaternion);
+            this.camera.position.add(offset);
+        }
+        this.camera.rotation.x = clamp(this.camera.rotation.x, degToRad(-89), degToRad(89));
+    };
+    // 碰撞检测（完全参考 xsh-react-three FPSControls.tsx 的 computerPosition 方法）
+    //
+    // 射线布局对比（xsh-react-three 的 Raycaster 组件 → 本地实现）：
+    //   xsh: position prop → _localRayOrigins × collideVolume
+    //   xsh: direction prop → _localRayDirs（归一化后 = clampLength(0,1)）
+    //   xsh: raycaster.far = getDirection().length() → horizontalFar / verticalFar
+    //   xsh: Group3D rotation={x:-euler.x} → yawQuat（pitch 补偿）
+    //   xsh: getIntersetResult(positionIncremental) → worldPos = playerCollider.end + positionIncremental
+    //
+    // 6条射线完整数据（cv = collideVolume, vr = VERTICAL_RANGE）：
+    //   0 upTodwomRay:    origin=(0,0,0)×cv+worldPos, dir=(0,-1,0)×yaw, far=vr, 响应=vr-distance
+    //   1 dwomToUpRay:    origin=(0,0,0)×cv+worldPos, dir=(0,1,0)×yaw,  far=vr, 响应=faceNormal×0.01
+    //   2 rightToForward: origin=(cv,0,0)×yaw+worldPos, dir=(-1,0,-1).norm×yaw, far=cv√2
+    //   3 leftToForward:  origin=(-cv,0,0)×yaw+worldPos, dir=(1,0,-1).norm×yaw,  far=cv√2
+    //   4 leftToBack:     origin=(-cv,0,0)×yaw+worldPos, dir=(1,0,1).norm×yaw,   far=cv√2
+    //   5 rightToBack:    origin=(cv,0,0)×yaw+worldPos, dir=(-1,0,1).norm×yaw,   far=cv√2
+    playerCollisions() {
+        this.playerOnFloor = false;
+        this._getColliders();
+        const positionIncremental = this._tempVec4.set(0, 0, 0);
+        const collideVolume = this.COLLIDE_VOLUME;
+        const verticalRange = this.VERTICAL_RANGE;
+        let i = 0;
+        let goOnComputer = true;
+        // 调试数据：按射线索引存储（0=下, 1=上, 2-5=水平），只在第一次迭代记录
+        const devRayData = this.dev ? new Array(6).fill(null) : null;
+        let debugRecorded = !this.dev;
+        while (goOnComputer && i < 100) {
+            goOnComputer = false;
+            i++;
+            // 与 xsh: object3d.getWorldPosition() + positionIncremental 对应
+            const worldPos = this._tempVec3
+                .copy(this.playerCollider.end)
+                .add(positionIncremental);
+            // 与 xsh: Group3D rotation={x:-euler.x} 补偿 pitch → 只跟随 yaw
+            const yawQuat = this._tempQuat.setFromEuler(new Euler(0, this.camera.rotation.y, 0, "YXZ"));
+            // 将局部射线原点和方向转换为世界空间
+            for (let ri = 0; ri < 6; ri++) {
+                this._worldRayOrigins[ri]
+                    .copy(this._localRayOrigins[ri])
+                    .multiplyScalar(collideVolume)
+                    .applyQuaternion(yawQuat)
+                    .add(worldPos);
+                this._worldRayDirs[ri]
+                    .copy(this._localRayDirs[ri])
+                    .applyQuaternion(yawQuat)
+                    .normalize();
+            }
+            // far 值
+            const horizontalFar = collideVolume * Math.SQRT2;
+            const downFar = verticalRange;
+            const upFar = verticalRange;
+            // ========== 4 条水平射线（索引 2-5）==========
+            for (const ri of [2, 3, 4, 5]) {
+                this._raycaster.set(this._worldRayOrigins[ri], this._worldRayDirs[ri]);
+                this._raycaster.far = horizontalFar;
+                const intersets = this._raycaster.intersectObjects(this._colliders, false);
+                // 调试：第一次迭代记录射线数据
+                if (!debugRecorded) {
+                    const hasHit = intersets.length > 0;
+                    let closestDist = Infinity;
+                    let intersetPoint = null;
+                    if (hasHit) {
+                        for (const int of intersets) {
+                            const d = int.point.distanceTo(worldPos);
+                            if (d < closestDist) {
+                                closestDist = d;
+                                intersetPoint = int.point;
+                            }
+                        }
+                    }
+                    devRayData[ri] = {
+                        origin: this._worldRayOrigins[ri].clone(),
+                        farPoint: hasHit
+                            ? intersetPoint.clone()
+                            : this._worldRayOrigins[ri].clone().addScaledVector(this._worldRayDirs[ri], horizontalFar),
+                        hit: hasHit,
+                    };
+                }
+                if (intersets.length > 0) {
+                    let interset = intersets[0];
+                    if (intersets.length > 1) {
+                        for (let j = 1; j < intersets.length; j++) {
+                            if (intersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                                interset = intersets[j];
+                            }
+                        }
+                    }
+                    // 与 xsh: object3d.getWorldPosition().sub(interset.point).setLength(0.03) 一致
+                    this._tempVec
+                        .copy(worldPos)
+                        .sub(interset.point)
+                        .setLength(0.03);
+                    positionIncremental.add(this._tempVec);
+                    goOnComputer = true;
+                }
+            }
+            // ========== 向下射线（索引 0 = upTodwomRay）==========
+            this._raycaster.set(this._worldRayOrigins[0], this._worldRayDirs[0]);
+            this._raycaster.far = downFar;
+            let downIntersets = this._raycaster.intersectObjects(this._colliders, false);
+            // 调试：记录向下射线
+            if (!debugRecorded) {
+                const hasHit = downIntersets.length > 0;
+                let intersetPoint = null;
+                if (hasHit) {
+                    let closestDist = Infinity;
+                    for (const int of downIntersets) {
+                        const d = int.point.distanceTo(worldPos);
+                        if (d < closestDist) {
+                            closestDist = d;
+                            intersetPoint = int.point;
+                        }
+                    }
+                }
+                devRayData[0] = {
+                    origin: this._worldRayOrigins[0].clone(),
+                    farPoint: hasHit
+                        ? intersetPoint.clone()
+                        : this._worldRayOrigins[0].clone().addScaledVector(this._worldRayDirs[0], downFar),
+                    hit: hasHit,
+                };
+            }
+            if (downIntersets.length > 0) {
+                let interset = downIntersets[0];
+                if (downIntersets.length > 1) {
+                    for (let j = 1; j < downIntersets.length; j++) {
+                        if (downIntersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                            interset = downIntersets[j];
+                        }
+                    }
+                }
+                this.playerVelocity.y = 0;
+                positionIncremental.y += verticalRange - interset.distance;
+                this.playerOnFloor = true;
+                goOnComputer = true;
+            }
+            // ========== 向上射线（索引 1 = dwomToUpRay）==========
+            this._raycaster.set(this._worldRayOrigins[1], this._worldRayDirs[1]);
+            this._raycaster.far = upFar;
+            let upIntersets = this._raycaster.intersectObjects(this._colliders, false);
+            // 调试：记录向上射线
+            if (!debugRecorded) {
+                const hasHit = upIntersets.length > 0;
+                let intersetPoint = null;
+                if (hasHit) {
+                    let closestDist = Infinity;
+                    for (const int of upIntersets) {
+                        const d = int.point.distanceTo(worldPos);
+                        if (d < closestDist) {
+                            closestDist = d;
+                            intersetPoint = int.point;
+                        }
+                    }
+                }
+                devRayData[1] = {
+                    origin: this._worldRayOrigins[1].clone(),
+                    farPoint: hasHit
+                        ? intersetPoint.clone()
+                        : this._worldRayOrigins[1].clone().addScaledVector(this._worldRayDirs[1], upFar),
+                    hit: hasHit,
+                };
+                debugRecorded = true;
+            }
+            if (upIntersets.length > 0) {
+                let interset = upIntersets[0];
+                if (upIntersets.length > 1) {
+                    for (let j = 1; j < upIntersets.length; j++) {
+                        if (upIntersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                            interset = upIntersets[j];
+                        }
+                    }
+                }
+                this.playerVelocity.y = 0;
+                // 与 xsh: face.worldNormal.setLength(0.01) 一致
+                if (interset.face) {
+                    const faceNormal = interset.face.normal.clone();
+                    const worldQuat = new Quaternion();
+                    interset.object.getWorldQuaternion(worldQuat);
+                    faceNormal.applyQuaternion(worldQuat).setLength(0.01);
+                    positionIncremental.add(faceNormal);
+                }
+                else {
+                    positionIncremental.y -= 0.01;
+                }
+                goOnComputer = true;
+            }
+        }
+        // ========== 更新调试射线（dev 模式）==========
+        if (this.dev && devRayData) {
+            this._initDebugLines();
+            for (let di = 0; di < 6; di++) {
+                const data = devRayData[di];
+                if (data) {
+                    this._updateDebugLine(di, data.origin, data.farPoint, data.hit);
+                }
+            }
+        }
+        // 应用推离
+        if (positionIncremental.lengthSq() > 0) {
+            this.playerCollider.translate(positionIncremental);
+        }
+        // 事件分发
+        if (this.jumping && !this.prePlayerOnFloor && this.playerOnFloor) {
+            this.jumping = false;
+            this.dispatchEvent({ type: "jump_end" });
+        }
+        const { x: preX, z: preZ } = this.prePlayerVelocity;
+        const { x, z } = this.playerVelocity;
+        if (Math.abs(preX + preZ) < 0.1 && Math.abs(x + z) > 0.1) {
+            this.dispatchEvent({ type: "move_start" });
+        }
+        else if (Math.abs(preX + preZ) > 0.1 && Math.abs(x + z) < 0.1) {
+            this.dispatchEvent({ type: "move_end" });
+        }
+        this.prePlayerVelocity.copy(this.playerVelocity);
+        this.prePlayerOnFloor = this.playerOnFloor;
+    }
+    // 越界传送
+    teleportPlayerIfOob = () => {
+        if (this.camera.position.y <= -10) {
+            this.playerCollider.start.set(0, 0.35, 0);
+            this.playerCollider.end.set(0, 1, 10);
+            this.playerCollider.radius = 0.35;
+            this.camera.position.copy(this.playerCollider.end);
+        }
+    };
+    // 更新
+    update() {
+        if (this.enable) {
+            // 第三人称模式切换时同步角度
+            if (this.thirdPerson && !this._prevThirdPerson) {
+                // 从第一人称切换到第三人称：复制相机旋转角
+                this._thirdPersonAngleY = this.camera.rotation.y;
+                this._thirdPersonAngleX = this.camera.rotation.x;
+            }
+            else if (!this.thirdPerson && this._prevThirdPerson) {
+                // 从第三人称切换回第一人称：还原相机旋转角
+                this.camera.rotation.y = this._thirdPersonAngleY;
+                this.camera.rotation.x = this._thirdPersonAngleX;
+            }
+            this._prevThirdPerson = this.thirdPerson;
+            const deltaTime = Math.min(0.05, this.clock.getDelta()) / this.STEPS_PER_FRAME;
+            for (let i = 0; i < this.STEPS_PER_FRAME; i++) {
+                this.controls(deltaTime);
+                this.updatePlayer(deltaTime);
+                this.teleportPlayerIfOob();
+            }
+        }
+        // dev 模式关闭时隐藏调试射线
+        if (!this.dev && this._debugRayGroup && this._debugRayGroup.visible) {
+            this._debugRayGroup.visible = false;
+        }
+        else if (this.dev && this._debugRayGroup && !this._debugRayGroup.visible) {
+            this._debugRayGroup.visible = true;
+        }
+    }
+    // 销毁事件
+    disposer() {
+        this.enable = false;
+        document.removeEventListener("keydown", this.keydown);
+        document.removeEventListener("keyup", this.keyup);
+        this.canvas.removeEventListener("pointerdown", this.mousedown);
+        document.removeEventListener("pointerup", this.mouseup);
+        document.body.removeEventListener("pointermove", this.mousemove);
+        this._disposeDebugLines();
+    }
+}