three-base 2.0.129 → 2.0.134

package/FPScontrol.js

@@ -1,232 +1,505 @@
-/*
- * @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, Float32BufferAttribute, Group, Line, LineBasicMaterial, Mesh, InstancedMesh, 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 = 5; // 每帧碰撞计算的次数
+    speed = 1; // 速度
+    camera;
+    // 移动时是否保持惯性 由外部来配置
+    inertia = true;
+    // 场景引用（用于射线检测）
+    scene;
+    // ========== dev / 第三人称 ==========
+    // 开发模式：打开后显示射线可视化
+    dev = false;
+    // 第三人称模式
+    thirdPerson = false;
+    // 第三人称参数：相机与第一人称位置的距离和高度偏移
+    thirdPersonDistance = 5;
+    thirdPersonHeight = 2;
+    // 第三人称轨道角
+    _thirdPersonAngleY = 0;
+    _thirdPersonAngleX = 0.5;
+    // 模式切换检测
+    _prevThirdPerson = false;
+    // ========== 射线碰撞检测 ==========
+    // 碰撞体积（胶囊体半径）
+    COLLIDE_VOLUME = 0.5;
+    // 推离步长（每次迭代推离的距离）
+    PUSH_DISTANCE = 0.03;
+    // 最大迭代次数
+    MAX_ITERATIONS = 100;
+    // 射线检测器
+    _raycaster = new Raycaster();
+    // 临时向量（复用避免 GC）
+    _tempVec = new Vector3();
+    _tempVec2 = new Vector3();
+    _tempVec3 = new Vector3();
+    _tempVec4 = new Vector3();
+    // 水平射线方向（4 个 45° 斜向）
+    HORIZONTAL_RAY_DIRECTIONS = [
+        new Vector3(-1, 0, -1).normalize(), // 右→前
+        new Vector3(1, 0, -1).normalize(), // 左→前
+        new Vector3(1, 0, 1).normalize(), // 左→后
+        new Vector3(-1, 0, 1).normalize(), // 右→后
+    ];
+    // 垂直射线方向
+    VERTICAL_DOWN = new Vector3(0, -1, 0); // 上→下
+    VERTICAL_UP = new Vector3(0, 1, 0); // 下→上
+    // userData.fpsCollision === true 的碰撞体列表
+    _colliders = [];
+    // 收集 fpsCollision 物体 + 首次构建 BVH（参照 ThreeMouse dispatchEvent）
+    _getColliders() {
+        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);
+            }
+        });
+    }
+    // 玩家胶囊碰撞体
+    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);
+        }
+        this.camera.rotation.x = clamp(this.camera.rotation.x, degToRad(-89), degToRad(89));
+    };
+    // 碰撞检测：6 射线迭代推离（水平 4 + 垂直 2）
+    playerCollisions() {
+        this.playerOnFloor = false;
+        // 收集 fpsCollision 物体
+        this._getColliders();
+        // 累积位移增量（用于迭代推离）
+        const positionIncremental = this._tempVec4.set(0, 0, 0);
+        // dev 模式：记录射线数据
+        const devRayData = this.dev ? [] : null;
+        let iterationCount = 0;
+        let hasCollision = true;
+        // ========== 迭代推离 ==========
+        while (hasCollision && iterationCount < this.MAX_ITERATIONS) {
+            hasCollision = false;
+            iterationCount++;
+            // 最后 2 次迭代记录调试数据
+            const recordDebug = this.dev && iterationCount >= this.MAX_ITERATIONS - 2;
+            // 获取胶囊体中心的世界位置
+            const centerPos = this._tempVec3
+                .addVectors(this.playerCollider.start, this.playerCollider.end)
+                .multiplyScalar(0.5);
+            // ========== 水平射线（4 根 45°）==========
+            for (let ri = 0; ri < this.HORIZONTAL_RAY_DIRECTIONS.length; ri++) {
+                const rayDir = this.HORIZONTAL_RAY_DIRECTIONS[ri];
+                // 起点：胶囊体中心向射线方向偏移 COLLIDE_VOLUME
+                const rayOrigin = this._tempVec2
+                    .copy(centerPos)
+                    .addScaledVector(rayDir, -this.COLLIDE_VOLUME);
+                this._raycaster.set(rayOrigin, rayDir.clone());
+                this._raycaster.far = this.COLLIDE_VOLUME * 2;
+                const hits = this._raycaster.intersectObjects(this._colliders, false);
+                if (recordDebug) {
+                    // 记录调试射线数据
+                    const farPoint = new Vector3().copy(rayOrigin).addScaledVector(rayDir, this.COLLIDE_VOLUME * 2);
+                    const hasHit = hits.length > 0 && hits[0].distance < this.COLLIDE_VOLUME * 2;
+                    devRayData.push({
+                        origin: rayOrigin.clone(),
+                        farPoint: hasHit ? hits[0].point.clone() : farPoint,
+                        hit: hasHit,
+                    });
+                }
+                if (hits.length > 0) {
+                    const hit = hits[0];
+                    // 推离向量：交点 → 当前位置，长度 PUSH_DISTANCE
+                    const pushVector = this._tempVec
+                        .copy(centerPos)
+                        .sub(hit.point)
+                        .setLength(this.PUSH_DISTANCE);
+                    // 累加推离量到位移增量
+                    positionIncremental.add(pushVector);
+                    // 继续循环，因为推离后可能还会碰撞
+                    hasCollision = true;
+                }
+            }
+            // 重置 far（垂直射线各自设 far）
+            this._raycaster.far = Infinity;
+            // 垂直射线
+            // 向下 → 地面检测
+            const downRayOrigin = centerPos.clone();
+            this._raycaster.set(downRayOrigin, this.VERTICAL_DOWN.clone());
+            this._raycaster.far = this.COLLIDE_VOLUME + 0.5; // 适当延长检测距离
+            const downHits = this._raycaster.intersectObjects(this._colliders, false);
+            if (downHits.length > 0) {
+                const hit = downHits[0];
+                // 脚下 COLLIDE_VOLUME 内 = 站在地面
+                if (hit.distance < this.COLLIDE_VOLUME + 0.1) {
+                    this.playerOnFloor = true;
+                    // 如果正在下落，归零垂直速度
+                    if (this.playerVelocity.y < 0) {
+                        this.playerVelocity.y = 0;
+                    }
+                    // 上移站位
+                    const adjustY = this.COLLIDE_VOLUME + 0.1 - hit.distance;
+                    if (adjustY > 0) {
+                        positionIncremental.y += adjustY;
+                    }
+                }
+                else if (hit.distance < this.COLLIDE_VOLUME + 0.3) {
+                    // 接近地面缓冲
+                    this.playerOnFloor = true;
+                    if (this.playerVelocity.y < 0) {
+                        this.playerVelocity.y = 0;
+                    }
+                }
+                hasCollision = true;
+            }
+            if (recordDebug) {
+                // 向下射线调试数据
+                const downFar = new Vector3().copy(downRayOrigin).addScaledVector(this.VERTICAL_DOWN, this.COLLIDE_VOLUME + 0.5);
+                const downHit = downHits.length > 0;
+                devRayData.push({
+                    origin: downRayOrigin.clone(),
+                    farPoint: downHit ? downHits[0].point.clone() : downFar,
+                    hit: downHit,
+                });
+            }
+            // 向上 → 头顶碰撞
+            const upRayOrigin = centerPos.clone();
+            this._raycaster.set(upRayOrigin, this.VERTICAL_UP.clone());
+            this._raycaster.far = this.COLLIDE_VOLUME + 0.2;
+            const upHits = this._raycaster.intersectObjects(this._colliders, false);
+            if (upHits.length > 0) {
+                const hit = upHits[0];
+                // 头顶碰撞：归零向上速度 + 下移
+                if (hit.distance < this.COLLIDE_VOLUME + 0.2) {
+                    // 归零向上的速度
+                    if (this.playerVelocity.y > 0) {
+                        this.playerVelocity.y = 0;
+                    }
+                    // 计算需要下移的距离
+                    const adjustY = this.COLLIDE_VOLUME + 0.2 - hit.distance;
+                    if (adjustY > 0) {
+                        positionIncremental.y -= Math.min(adjustY, 0.01); // 限制每次调整量
+                    }
+                    hasCollision = true;
+                }
+            }
+            if (recordDebug) {
+                // 向上射线调试数据
+                const upFar = new Vector3().copy(upRayOrigin).addScaledVector(this.VERTICAL_UP, this.COLLIDE_VOLUME + 0.2);
+                const upHit = upHits.length > 0;
+                devRayData.push({
+                    origin: upRayOrigin.clone(),
+                    farPoint: upHit ? upHits[0].point.clone() : upFar,
+                    hit: upHit,
+                });
+            }
+        }
+        // ========== 更新调试射线（dev 模式）==========
+        if (this.dev && devRayData) {
+            this._initDebugLines();
+            for (let i = 0; i < devRayData.length && i < 6; i++) {
+                const data = devRayData[i];
+                // 跳过未收集到的（可能迭代次数不够）
+                this._updateDebugLine(i, 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();
+    }
+}