three-base 2.0.172 → 2.0.180

package/FPScontrol.d.ts

@@ -1,5 +1,4 @@
 import { Camera, Clock, EventDispatcher, Quaternion, Ray, Raycaster, Scene, Vector3 } from "three";
-import { Capsule } from "three/examples/jsm/math/Capsule";
 import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
 import type { FPScontrolEventTypeMap } from "./EventMap";
 /** 全局 FPScontrol 实例注册表。
@@ -158,7 +157,7 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     /** 是否允许跳跃（空格触发）。false 时按空格不跳。默认 true */
     jumpEnabled: boolean;
     /** 跳跃初速度（垂直方向，m/s）。
-     *  ⚠️ 2026-09-27 治「跳跃翻墙」：原 15（当时重力 30）→ 顶点 3.75m 远超墙高 2m，跳起后胶囊底越过墙顶
+     *  ⚠️ 2026-09-27 治「跳跃翻墙」：原 15（当时重力 30）→ 顶点 3.75m 远超墙高 2m，跳起后视点越过墙顶
      *  造成水平失明窗口，人带着水平速度飞越墙平面、落地在墙外侧被越推越远（探针实测 z=-187）。
      *  定案 8 ⇒ 顶点 1.07m：仍可跳上 0.8m 高台，且 yBottom 恒低于「墙顶 2.0 − 步高 0.1」，
      *  与主循环竖直门配合后失明窗口彻底消失。**顶点**才是防翻墙的那条线，不是初速度本身。
@@ -284,14 +283,14 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      * 即 R 就是「玩家中心离墙多远开始判定碰撞」的半径。若 R 小于停位需求，人必须**先陷进墙里**
      * 才会被射线检测到，随后每帧被位置修正弹回一点 → 皇上所见「侧撞弹很远」。
      * 探针实测（`tmp/TMP_R_side_effect.mjs`，斜 45° 撞墙角 / 正对单墙同口径）：
-     *   R=0.30 → 停位垂距 **0.2128**（< 胶囊半径 0.35，**明显穿模**）每帧被推 0.040
+     *   R=0.30 → 停位垂距 **0.2128**，射线包络过小，容易贴墙。
      *   R=0.50 → 0.3541（贴到墙面）  每帧 0.036
-     *   R=0.60 → 0.4243（勉强 > 胶囊半径）0.034
+     *   R=0.60 → 0.4243。
      *   R=0.80 → 0.5448 ✓ / R=1.06 → 0.7247 ✓（每帧修正仅 0.002）
-     * ⇒ 取 **0.6**：保证停位垂距 > 玩家胶囊半径(0.35)，不再穿模。
+     * ⇒ 取 **0.6**：为射线包络保留足够的贴墙间距。
      * ⭐ 2026-10-08 皇上旨：下限放宽到 **0.2**、上限收到 **1.0**（编辑框范围 0.2~1.0）。
      *    ⚠️ R<0.6 仍会贴墙穿模（R=0.5 贴到墙面、R=0.3 明显穿模），皇上按需拧；下限放开是给窄通道/贴墙演示留余地。
-     * ⭐ 2026-10-11 A 档复核（tmp→test/fpsCollideFit.test.ts，正对 1m 墙、胶囊半径 0.35）：
+     * ⭐ 2026-10-11 A 档复核（tmp→test/fpsCollideFit.test.ts，正对 1m 墙）：
      *    停位现在**逐位等于 R**（眼停在面前 R 处 ⇒ 身体入墙深度 = 0.35 − R，一条直线）：
      *      R=0.20 → 入墙 **0.1500m**   R=0.30 → **0.0500m**   R=0.35 → **0.0000m**
      *      R=0.50 / 0.60 / 1.00 → **0.0000m**（身体不出面）
@@ -345,12 +344,11 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     private _horizHit;
     private _inputDirVec;
     private _previewRetreat;
-    /** 开启预览那一刻的胶囊两端（关闭时整体还原回去） */
-    private _obsSavedStart;
-    private _obsSavedEnd;
+    /** 开启预览那一刻的玩家视点位置（关闭时还原） */
+    private _obsSavedPosition;
     /** 是否已有可还原的暂存（没进过观察模式就没有，避免构造期赋值把人还原到原点） */
     private _obsHasSave;
-    /** 进观察模式（回弹预览 / 单步）：记下当前胶囊位置，退出时还原 */
+    /** 进观察模式（回弹预览 / 单步）：记下当前视点位置，退出时还原 */
     private _saveObsPos;
     /**
      * 退观察模式：把位置整份还原到进入那一刻，并清掉水平速度。
@@ -380,18 +378,6 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     debugHideSideRays: boolean;
     private _tempEuler;
     MAX_ITERATIONS: number;
-    /**
-     * 一个**物理小帧**里 while 最多走几轮就落地（皇上 2026-10-07 裁决「加一个每小帧轮数上限」）。
-     * 默认 500 = 与 `MAX_ITERATIONS` 同档 ⇒ 现状一字不变；拧小才是他要的「一次只修几格、下一小帧再修」。
-     * ⭐ 为什么拧格长没用（10-07 实测）：常态帧会一直迭代到「8 条射线全部脱开」才落地 ⇒
-     *   **每次落地量 = 这一小帧往墙里挤进多深**，与一格多远无关（格长 0.03→0.01 判级一字未变）。
-     *   一格 = 一轮里每条命中各推的距离 ⇒ 要限制"一次修多少"只能限制**轮数**。
-     * ⚠️ 代价（不许瞒）：出水量 = 轮数 × 每轮票数 × 格长，默认每帧 2 个小帧。拧到 1 轮 + 1cm 格长 ⇒
-     *   一秒最多挤出约 120cm 的量看着够，但高速冲刺顶墙时「这一帧挤进来的」可能比「两小帧推出去的」多
-     *   ⇒ 越陷越深，格长拧到 0.005 那一档体检台 40 号现场就是这么判 **❌穿墙** 的。
-     *   所以默认不动，先让他在线上拧着看手感。
-     */
-    ROUNDS_PER_SUBSTEP: number;
     private _frameIterBudget;
     private _tempQuat;
     private _raycaster;
@@ -407,6 +393,10 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      */
     private _fitNormal;
     private _horizNormal;
+    /** 本子步实际推离过的不同墙面法线。墙角需要同时裁掉两个朝内速度分量，
+     *  不能只用最后一次命中的面，否则两个面会在相邻帧交替抢占速度闸门而抖动。 */
+    private _horizContactNormals;
+    private _horizContactCount;
     private _fitVec;
     private _rhombusAxisX;
     private _rhombusAxisZ;
@@ -503,7 +493,8 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     static markAllCollidersDirty(): void;
     /** 复位玩家到指定世界坐标（默认原点），清空速度；第一人称 demo 的"回到起点"用得到 */
     resetPlayer(position?: Vector3): void;
-    playerCollider: Capsule;
+    /** 玩家视点。所有碰撞射线均以此点为局部原点。 */
+    playerPosition: Vector3;
     clock: Clock;
     prePlayerVelocity: Vector3;
     playerVelocity: Vector3;
@@ -530,7 +521,7 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      *     `depthWrite:true`（three-base/Ground1/Ground1.ts:107）；哪天地板改回
      *     transparent + depthWrite:false，射线线会重新穿地浮出来。
      *   - 回弹方向线（黄→白）= **false**：「回弹向量线保持穿透显示」。
-     *     它是「本帧要看的向量」，起点在胶囊内部、方向常指着墙里，开遮挡会被自己的身子
+     *     它是「本帧要看的向量」，起点在玩家位置、方向常指着墙里，开遮挡会被墙面
      *     或墙面吃掉半截 → 观察目的直接落空，故保持常显在最前。
      */
     private _createDebugLine;

package/FPScontrol.js

@@ -6,11 +6,9 @@
  */
 import { Clock, Euler, EventDispatcher, Group, InstancedMesh, Matrix3, Matrix4, Mesh, Quaternion, Ray, Raycaster, Vector3 } from "three";
 import { MathUtils } from "three";
-// （2026-09-28 皇上旨「完完全全使用 xsh-react-three 的碰撞计算方法」：胶囊兜底整条拆除。
-//   collisionOBB.ts 纯几何模块与其单测保留，但 FPScontrol 不再引用。）
+// 碰撞完全由围绕玩家视点的射线完成；FPScontrol 不使用任何体积碰撞体。
 const { degToRad, clamp } = MathUtils;
 // 「矩形射线法」的水平 far 口径：斜弦画长 = R√2（四弦首尾闭合的唯一解，勿再改回）。
-import { Capsule } from "three/examples/jsm/math/Capsule";
 // 粗辅助线：WebGL 下 `LineBasicMaterial.linewidth` 恒被驱动钳成 1px（Chrome/ANGLE 一律 1px，
 // 调大无效），要真的变粗必须走 `LineSegments2 + LineMaterial`（shader 里按像素铺quad）。
 // 本仓库先例：src/views/home/homeRender.ts:71-73, 344-358。
@@ -212,7 +210,7 @@ export default class FPScontrol extends EventDispatcher {
     /** 是否允许跳跃（空格触发）。false 时按空格不跳。默认 true */
     jumpEnabled = true;
     /** 跳跃初速度（垂直方向，m/s）。
-     *  ⚠️ 2026-09-27 治「跳跃翻墙」：原 15（当时重力 30）→ 顶点 3.75m 远超墙高 2m，跳起后胶囊底越过墙顶
+     *  ⚠️ 2026-09-27 治「跳跃翻墙」：原 15（当时重力 30）→ 顶点 3.75m 远超墙高 2m，跳起后视点越过墙顶
      *  造成水平失明窗口，人带着水平速度飞越墙平面、落地在墙外侧被越推越远（探针实测 z=-187）。
      *  定案 8 ⇒ 顶点 1.07m：仍可跳上 0.8m 高台，且 yBottom 恒低于「墙顶 2.0 − 步高 0.1」，
      *  与主循环竖直门配合后失明窗口彻底消失。**顶点**才是防翻墙的那条线，不是初速度本身。
@@ -260,7 +258,7 @@ export default class FPScontrol extends EventDispatcher {
     //   位置修正沿该面法线一格一格推，每格 = min(RETREAT_SKIN, deficit) ⇒ 大欠距仍走整格，
     //   **收尾那一格按欠距截短** ⇒ 落点正好贴在包络边上（旧写法最后一格也推满 1cm → 过冲 → 来回甩）。
     //   速度只削「往墙里」那一份（v −(v·n)n），切向保留 ⇒ 贴墙能滑，撞墙不再「加速→清零」锯齿。
-    //   ⇒ 停位仍只由 **R** 一个数决定（R=1.06 → 沿法线 0.749~1.06m）；胶囊半径 0.35 ⇒ 身体与墙之间
+    //   ⇒ 停位仍只由 **R** 一个数决定（R=1.06 → 沿法线 0.749~1.06m）；射线包络决定视点与墙之间
     //     还留 0.40~0.71m 空气隙，这是皇上 2026-09-06 终裁布局自带、且亲眼验收过的量，不要当 bug 修。
     /**
      * 单步最大位移（连续碰撞检测用）：每帧位移会被切成若干 ≤ 本值的小步，逐步做碰撞检测。
@@ -273,8 +271,8 @@ export default class FPScontrol extends EventDispatcher {
     MAX_STEP_DISTANCE = 0.1;
     /** 位移细分的最大段数（防止极端速度/长卡顿把一帧切成几百步拖垮帧率） */
     MAX_STEP_COUNT = 32;
-    // 垂直碰撞范围 = 从 playerCollider.end（眼睛）到「该射线所保护的那一面」的距离
-    // = capsule length + radius = (1.0 - 0.35) + 0.35 = 1.0（几何真值；下方两个常量是**口径**，不是几何）
+    // 垂直碰撞范围 = 从玩家视点到「该射线所保护的那一面」的距离
+    // = 视点到脚下射线保护面的距离 1.0（下方两个常量是**口径**，不是几何）
     // 对应 xsh-react-three 中 collideVolume（=3）= 控制器到地面的距离
     // xsh 中 far = collideVolume, 响应 = collideVolume - distance
     // 此处 far = DOWN_RANGE/UP_RANGE + SKIN，响应 = DOWN_RANGE/UP_RANGE − distance
@@ -283,9 +281,9 @@ export default class FPScontrol extends EventDispatcher {
     //   我提醒过这一条常量身兼两职（探测长度 + 站位基准），他追选定案「**直接改站位基准**」，
     //   所以拆成两条各自独立的常量，**不再**共用 VERTICAL_RANGE=1.0：
     //   · DOWN_RANGE = 1.5：下射线 far = 1.5+SKIN，响应 downPen = 1.5 − distance
-    //     → 落地后**眼睛离地 1.5m**。胶囊脚底在眼下 1.0m ⇒ 站定时脚底离地 **0.5m（悬浮）**。
+    //     → 落地后**眼睛离地 1.5m**。
     //   · UP_RANGE  = 0.3：上射线 far = 0.3+SKIN，响应 upPen = 0.3 − distance
-    //     → 头顶到面时**眼睛离顶 0.3m**。胶囊顶在眼下 0.35m ⇒ 真顶到矮面时头顶穿入面内 **0.05m**，
+    //     → 头顶到面时**眼睛离顶 0.3m**，由上射线阻止继续上移。
     //       且 0.3~1.0m 之间的低矮障碍物从此探不到（上射线变短的直接后果）。
     //   ⚠️ 跳跃/重力/台阶吸附的其余口径一字未动，只换这两个基准数。
     //   ⭐ 2026-09-26 皇上旨「能调节的参数都做滚轮输入框」→ 两条改为公共可写（面板「参数旋钮」可拧），
@@ -400,14 +398,14 @@ export default class FPScontrol extends EventDispatcher {
      * 即 R 就是「玩家中心离墙多远开始判定碰撞」的半径。若 R 小于停位需求，人必须**先陷进墙里**
      * 才会被射线检测到，随后每帧被位置修正弹回一点 → 皇上所见「侧撞弹很远」。
      * 探针实测（`tmp/TMP_R_side_effect.mjs`，斜 45° 撞墙角 / 正对单墙同口径）：
-     *   R=0.30 → 停位垂距 **0.2128**（< 胶囊半径 0.35，**明显穿模**）每帧被推 0.040
+     *   R=0.30 → 停位垂距 **0.2128**，射线包络过小，容易贴墙。
      *   R=0.50 → 0.3541（贴到墙面）  每帧 0.036
-     *   R=0.60 → 0.4243（勉强 > 胶囊半径）0.034
+     *   R=0.60 → 0.4243。
      *   R=0.80 → 0.5448 ✓ / R=1.06 → 0.7247 ✓（每帧修正仅 0.002）
-     * ⇒ 取 **0.6**：保证停位垂距 > 玩家胶囊半径(0.35)，不再穿模。
+     * ⇒ 取 **0.6**：为射线包络保留足够的贴墙间距。
      * ⭐ 2026-10-08 皇上旨：下限放宽到 **0.2**、上限收到 **1.0**（编辑框范围 0.2~1.0）。
      *    ⚠️ R<0.6 仍会贴墙穿模（R=0.5 贴到墙面、R=0.3 明显穿模），皇上按需拧；下限放开是给窄通道/贴墙演示留余地。
-     * ⭐ 2026-10-11 A 档复核（tmp→test/fpsCollideFit.test.ts，正对 1m 墙、胶囊半径 0.35）：
+     * ⭐ 2026-10-11 A 档复核（tmp→test/fpsCollideFit.test.ts，正对 1m 墙）：
      *    停位现在**逐位等于 R**（眼停在面前 R 处 ⇒ 身体入墙深度 = 0.35 − R，一条直线）：
      *      R=0.20 → 入墙 **0.1500m**   R=0.30 → **0.0500m**   R=0.35 → **0.0000m**
      *      R=0.50 / 0.60 / 1.00 → **0.0000m**（身体不出面）
@@ -593,19 +591,6 @@ export default class FPScontrol extends EventDispatcher {
             desc: "⭐ 2026-10-11 皇上 A 档改判：每轮**只沿「欠距最大那一面」的法线**推一格，且这一格取 min(本值, 该面欠距) ⇒ 大欠距仍是一格一格往外走（皇上 10-07「1 个单位 1 个单位的修正」），只有**收尾那一格按欠距截短**，落点贴在包络边上（旧写法每条命中射线各推满一格、最后一格也推满 ⇒ 过冲 ⇒ 贴墙来回甩 = 抖动）。" +
                 "⚠️ 上限以下别贪小：0.03/0.02/0.01 体检台判级完全相同，拧到 0.005 才有改善但「跳跃+冲刺+掉帧」那个现场开始穿墙（格长 = 每帧出水量）。迭代推到全部射线脱开为止",
         },
-        {
-            group: "回弹与手感",
-            label: "每小帧轮数上限",
-            key: "ROUNDS_PER_SUBSTEP",
-            min: 1,
-            max: 500,
-            step: 1,
-            digits: 0,
-            unit: "轮",
-            desc: "⭐ 皇上 2026-10-07 裁决加：一个物理小帧里 while 最多走几轮就落地（默认 500 = 与「每帧迭代预算」同档 ⇒ 现状一字不变）。" +
-                "**这颗才是「一次修多少」的真闸门**：10-07 实测每次落地量 = 这一小帧往墙里挤进多深（2/8/10cm 都这么来），跟一格多远无关 ⇒ 要「一次只修几格、下一小帧再修」只能拧这里。" +
-                "⚠️ 拧小的代价：一秒能挤出去的总量变小，高速冲刺顶墙时「挤进来的比推出去的快」⇒ 越陷越深（格长拧到 0.005 那档体检台 40 号现场就判 ❌穿墙，同一个机理）。先拧着看手感，别把默认改小",
-        },
         // ===== 移动与视角 =====
         {
             group: "移动与视角",
@@ -776,7 +761,7 @@ export default class FPScontrol extends EventDispatcher {
     // ⚠️ 只闸水平+竖向的**位置写入**；削速度、playerOnFloor、事件派发全部保留，
     //   否则预览模式下重力会一帧帧攒着把人送到地心并触发掉出世界复位。
     // ⭐⭐ 2026-09-26 皇上七旨「回弹预览开了, 就关不掉」⇒ 本字段改成**带暂存的访问器**：
-    //   开 = 记下当前胶囊位置；关 = **还原**那个位置 + 清掉水平速度。
+    //   开 = 记下当前视点位置；关 = **还原**那个位置 + 清掉水平速度。
     //   病根（实测，墙面板块 x∈[5.0,6.0]、R=1.06）：预览既然不写位置，人就照着自己的
     //   行走速度（speed=6 ⇒ 终端 37.5m/s ⇒ 每帧 0.62m）一路**穿墙走出去**，120 帧后中心
     //   已经在 x=138；这一路上只要停在任何一处「两面墙的票互相抵消」的几何里，位置修正就
@@ -784,15 +769,13 @@ export default class FPScontrol extends EventDispatcher {
     //   deficit 恒为 0.5600、位移 0。看着就是「预览关了位置修正也不回来了」。
     //   ⇒ 预览是**观察**用的，那一段时间里的位移本来就不作数，关掉即回到打开前那一刻。
     _previewRetreat = false;
-    /** 开启预览那一刻的胶囊两端（关闭时整体还原回去） */
-    _obsSavedStart = new Vector3();
-    _obsSavedEnd = new Vector3();
+    /** 开启预览那一刻的玩家视点位置（关闭时还原） */
+    _obsSavedPosition = new Vector3();
     /** 是否已有可还原的暂存（没进过观察模式就没有，避免构造期赋值把人还原到原点） */
     _obsHasSave = false;
-    /** 进观察模式（回弹预览 / 单步）：记下当前胶囊位置，退出时还原 */
+    /** 进观察模式（回弹预览 / 单步）：记下当前视点位置，退出时还原 */
     _saveObsPos() {
-        this._obsSavedStart.copy(this.playerCollider.start);
-        this._obsSavedEnd.copy(this.playerCollider.end);
+        this._obsSavedPosition.copy(this.playerPosition);
         this._obsHasSave = true;
     }
     /**
@@ -803,9 +786,8 @@ export default class FPScontrol extends EventDispatcher {
     _restoreObsPos() {
         if (!this._obsHasSave)
             return;
-        this.playerCollider.start.copy(this._obsSavedStart);
-        this.playerCollider.end.copy(this._obsSavedEnd);
-        this.camera.position.copy(this.playerCollider.end);
+        this.playerPosition.copy(this._obsSavedPosition);
+        this.camera.position.copy(this.playerPosition);
         this.playerVelocity.x = 0;
         this.playerVelocity.z = 0;
         this._obsHasSave = false;
@@ -826,8 +808,7 @@ export default class FPScontrol extends EventDispatcher {
     // xsh 的骨架只有一个 while（`FPSControls.tsx` 的 `computerPosition`）：
     //   ① 在**候选位置**（真实位置 + 已累计的 positionIncremental）上打水平射线
     //   ② 有命中 ⇒ 沿「离开命中点」的方向推**一小格**（它写死 0.03）并续跑下一轮
-    //   ③ 一轮下来没命中 ⇒ goOnComputer=false ⇒ 收工；整圈上限 = MAX_ITERATIONS（皇上 10-03 旨：500）轮，
-    //     单趟 while 另有「本轮数上限」闸门（常态帧 = ROUNDS_PER_SUBSTEP，皇上 10-07 裁决加，默认 500 同档 ⇒ 不变）
+    //   ③ 一轮下来没命中 ⇒ goOnComputer=false ⇒ 收工；整圈上限 = MAX_ITERATIONS（皇上 10-03 旨：500）轮
     //   ④ 循环外**唯一一次** position.add(incremental)
     // ⇒ 旧的「测试法逐级逼近」（六旨：1 → 0.1 → 0.01 三档、武装/判定/接受/撤销、每帧出水量 ≥
     //   进水量那套配套保险丝）**整条删除**。位置仍是一格一格挪出去的（皇上要的一步一步看那个形态不变），
@@ -853,18 +834,6 @@ export default class FPScontrol extends EventDispatcher {
     _tempEuler = new Euler(0, 0, 0, "YXZ");
     // 最大迭代次数（皇上 2026-10-03 旨：「那计算次数改成不超过 500」⇒ 100 → 500）
     MAX_ITERATIONS = 500;
-    /**
-     * 一个**物理小帧**里 while 最多走几轮就落地（皇上 2026-10-07 裁决「加一个每小帧轮数上限」）。
-     * 默认 500 = 与 `MAX_ITERATIONS` 同档 ⇒ 现状一字不变；拧小才是他要的「一次只修几格、下一小帧再修」。
-     * ⭐ 为什么拧格长没用（10-07 实测）：常态帧会一直迭代到「8 条射线全部脱开」才落地 ⇒
-     *   **每次落地量 = 这一小帧往墙里挤进多深**，与一格多远无关（格长 0.03→0.01 判级一字未变）。
-     *   一格 = 一轮里每条命中各推的距离 ⇒ 要限制"一次修多少"只能限制**轮数**。
-     * ⚠️ 代价（不许瞒）：出水量 = 轮数 × 每轮票数 × 格长，默认每帧 2 个小帧。拧到 1 轮 + 1cm 格长 ⇒
-     *   一秒最多挤出约 120cm 的量看着够，但高速冲刺顶墙时「这一帧挤进来的」可能比「两小帧推出去的」多
-     *   ⇒ 越陷越深，格长拧到 0.005 那一档体检台 40 号现场就是这么判 **❌穿墙** 的。
-     *   所以默认不动，先让他在线上拧着看手感。
-     */
-    ROUNDS_PER_SUBSTEP = 500;
     // ⚠️ 每帧碰撞迭代总预算（皇上 2026-09-03：墙角偶尔卡住，要求碰撞计算次数不超过 100；
     // 2026-10-03 同一位皇上把这条上限抬到 500 —— 机制一字未改，只是额度变大）：
     // while 循环原本的上限 100 是「单次 playerCollisions」的，而一个 update() 帧内会调
@@ -892,6 +861,10 @@ export default class FPScontrol extends EventDispatcher {
      */
     _fitNormal = new Vector3();
     _horizNormal = new Vector3();
+    /** 本子步实际推离过的不同墙面法线。墙角需要同时裁掉两个朝内速度分量，
+     *  不能只用最后一次命中的面，否则两个面会在相邻帧交替抢占速度闸门而抖动。 */
+    _horizContactNormals = [new Vector3(), new Vector3(), new Vector3(), new Vector3()];
+    _horizContactCount = 0;
     _fitVec = new Vector3();
     _rhombusAxisX = new Vector3(1, 0, 0);
     _rhombusAxisZ = new Vector3(0, 0, 1);
@@ -1190,14 +1163,12 @@ export default class FPScontrol extends EventDispatcher {
     resetPlayer(position = new Vector3(0, 0, 0)) {
         this.playerVelocity.set(0, 0, 0);
         this.prePlayerVelocity.set(0, 0, 0);
-        this.playerCollider.start.set(position.x, position.y + 0.35, position.z);
-        this.playerCollider.end.set(position.x, position.y + 1, position.z);
-        this.playerCollider.radius = 0.35;
-        this.camera.position.copy(this.playerCollider.end);
-        // ⭐ 复位 = 换现场 ⇒ 把相机/胶囊位置基准挪到新位置。
+        this.playerPosition.set(position.x, position.y + 1, position.z);
+        this.camera.position.copy(this.playerPosition);
+        // ⭐ 复位 = 换现场 ⇒ 把相机/视点位置基准挪到新位置。
     }
-    // 玩家胶囊碰撞体
-    playerCollider = new Capsule(new Vector3(0, 0.35, 0), new Vector3(0, 1, 0), 0.35);
+    /** 玩家视点。所有碰撞射线均以此点为局部原点。 */
+    playerPosition = new Vector3(0, 1, 0);
     // 时钟对象
     clock = new Clock();
     prePlayerVelocity = new Vector3();
@@ -1242,7 +1213,7 @@ export default class FPScontrol extends EventDispatcher {
      *     `depthWrite:true`（three-base/Ground1/Ground1.ts:107）；哪天地板改回
      *     transparent + depthWrite:false，射线线会重新穿地浮出来。
      *   - 回弹方向线（黄→白）= **false**：「回弹向量线保持穿透显示」。
-     *     它是「本帧要看的向量」，起点在胶囊内部、方向常指着墙里，开遮挡会被自己的身子
+     *     它是「本帧要看的向量」，起点在玩家位置、方向常指着墙里，开遮挡会被墙面
      *     或墙面吃掉半截 → 观察目的直接落空，故保持常显在最前。
      */
     _createDebugLine(depthTest) {
@@ -1312,7 +1283,7 @@ export default class FPScontrol extends EventDispatcher {
         this._debugRayGroup = null;
     }
     init(canvas) {
-        this.playerCollider.end.set(0, 1, 0);
+        this.playerPosition.set(0, 1, 0);
         document.addEventListener("keydown", this.keydown);
         document.addEventListener("keyup", this.keyup);
         canvas.addEventListener("pointerdown", this.mousedown);
@@ -1460,7 +1431,7 @@ export default class FPScontrol extends EventDispatcher {
             this.playerCollisions(s === stepCount - 1);
         }
         // 设置相机位置（第一人称默认值）
-        this.camera.position.copy(this.playerCollider.end);
+        this.camera.position.copy(this.playerPosition);
         // 第三人称：偏移相机位置 + 朝向第一人称坐标
         if (this.thirdPerson) {
             const cosPitch = Math.cos(this._thirdPersonAngleX);
@@ -1475,7 +1446,7 @@ export default class FPScontrol extends EventDispatcher {
                 Math.cos(this._thirdPersonAngleY) *
                     cosPitch *
                     this.thirdPersonDistance;
-            this.camera.lookAt(this.playerCollider.end);
+            this.camera.lookAt(this.playerPosition);
         }
         // dev 调试模式：在相机本地坐标系叠加偏移（向后上方）
         if (this.dev && !this.thirdPerson) {
@@ -1494,7 +1465,7 @@ export default class FPScontrol extends EventDispatcher {
     //   xsh: direction prop → _localRayDirs（归一化）
     //   xsh: raycaster.far = getDirection().length() → HORIZONTAL_FAR / downFar / upFar
     //   xsh: Group3D rotation={x:-euler.x} → yawQuat（pitch 补偿）
-    //   xsh: getIntersetResult(positionIncremental) → worldPos = playerCollider.end + positionIncremental
+    //   xsh: getIntersetResult(positionIncremental) → worldPos = playerPosition + positionIncremental
     //
     // 现行 10 条布局逐条表 = 上方「★ 矩形射线法 ★」权威规格块（唯一数据源，不在这里重复一遍）。
     /** 输出一条碰撞日志（唯一出口 = 浏览器控制台；皇上：「日志就是浏览器的控制台」） */
@@ -1530,18 +1501,16 @@ export default class FPScontrol extends EventDispatcher {
         //     · 竖向保留 faceUp / 天花板三道闸守卫（「掉出世界」血案修复）。
         //     · ⭐ 2026-10-11 A 档：**只沿「欠距最大那一面」的法线**推，且最后一格按欠距截短
         //       （xsh 是每条命中各推一整格 ⇒ 4 条命中同一面墙一轮推 4cm，退出时必过冲）。
-        //   原 deficit / 票面合成(finalDir) / 逐格推离 / 白推保险丝 / 胶囊兜底机器整条拆除。
+        //   原 deficit / 票面合成(finalDir) / 逐格推离 / 白推保险丝等旧分支已拆除。
         //   ⚠️ 措辞校正（10-11）：上面这句里「deficit」那半已随 A 档**回归**（`_horizFitDeficit()`：
         //   沿命中面法线的菱形可达距离 R·max(|n·x̂|,|n·ẑ|) 减当前垂距）；
-        //   仍拆除的是「票面合成 finalDir / 白推保险丝 / 胶囊兜底」三件 —— 别照旧文案把它们捡回来。
+        //   仍拆除的是「票面合成 finalDir / 白推保险丝」两件 —— 别照旧文案把它们捡回来。
         const positionIncremental = this._tempVec4.set(0, 0, 0);
         this._refreshInputDir(); // 台账 ix/iz 列还要用（与碰撞计算无关）
         const recordDebug = (this.dev || this.thirdPerson) && isFinalStep;
         let debugRecorded = !recordDebug;
         this._horizHit = false;
-        // ⭐ 皇上 2026-10-07 裁决「加一个每小帧轮数上限」：这一趟 while 最多走几轮就落地。
-        //   常态帧用旋钮 ROUNDS_PER_SUBSTEP（默认 500 与 MAX_ITERATIONS 同档 ⇒ 现状完全不变）。
-        const roundCap = this.ROUNDS_PER_SUBSTEP;
+        this._horizContactCount = 0;
         const downRange = this.DOWN_RANGE;
         const upRange = this.UP_RANGE;
         let i = 0;
@@ -1556,7 +1525,7 @@ export default class FPScontrol extends EventDispatcher {
             // ⭐ 2026-10-02 模拟修正：真实 collider 此刻**还没被本步位移推过**，
             //   所以锚点 = 真实位置 + 本步位移 =「这一步走完会站在哪儿」的**模拟位置**
             //   （数值上与旧写法「先 translate 再取 end」完全相同 ⇒ 几何、方向、测试基线都不变）。
-            const basePos = this._tempVec3.copy(this.playerCollider.end).add(this._subStep);
+            const basePos = this._tempVec3.copy(this.playerPosition).add(this._subStep);
             // xsh: 射线原点 = 控制器位置 + positionIncremental（getIntersetResult(incremental) 语义）
             const worldPos = this._candPos.copy(basePos).add(positionIncremental);
             // xsh: Group3D rotation={x:-euler.x} 补偿 pitch → 只跟随 yaw
@@ -1615,18 +1584,21 @@ export default class FPScontrol extends EventDispatcher {
                 }
             }
             if (bestDeficit > 1e-6) {
-                if (i > roundCap) {
-                    // ⭐ **轮次上限**用完 ⇒ 这一轮起水平一格都不再推。
-                    //   常态帧 = 皇上 10-07 点头新加的 ROUNDS_PER_SUBSTEP（默认 500 ⇒ 与旧行为同形）。
-                    //   ⚠️ 只拦水平：竖向（踩地/顶头）仍照常，否则人会往地心沉（皇上 09-25 冻结口径）。
+                // 大欠距逐格推离，直到所有水平射线都脱离碰撞面。
+                positionIncremental.addScaledVector(this._horizNormal, Math.min(this.RETREAT_SKIN, bestDeficit));
+                // 一面墙在多轮迭代里会重复命中；只保留方向不同的接触面。
+                let known = false;
+                for (let ni = 0; ni < this._horizContactCount; ni++) {
+                    if (this._horizContactNormals[ni].dot(this._horizNormal) > 0.999) {
+                        known = true;
+                        break;
+                    }
                 }
-                else {
-                    // ⭐ 皇上 10-07 旨「每执行一次，偏移量是多少」⇒ 一格一行、带累计的形态保留：
-                    //   大欠距仍是一格一格往外走，只有收尾那一格按欠距截短。
-                    positionIncremental.addScaledVector(this._horizNormal, Math.min(this.RETREAT_SKIN, bestDeficit));
-                    goOnComputer = true;
-                    this._horizHit = true;
+                if (!known && this._horizContactCount < this._horizContactNormals.length) {
+                    this._horizContactNormals[this._horizContactCount++].copy(this._horizNormal);
                 }
+                goOnComputer = true;
+                this._horizHit = true;
             }
             // ========== 向下射线（索引 0 = upTodwomRay）==========
             const downRay = this._rays[0];
@@ -1739,7 +1711,7 @@ export default class FPScontrol extends EventDispatcher {
                     //   第 11 帧眼落到板底之下 0.0135，上射线打到**板底（法线朝下）**，旧口径
                     //   `positionIncremental.y -= upPen` 一帧把人往下砸 **0.9865m** → 眼落到 −2.0，
                     //   从此两条竖射线彻底够不着 → 自由落体到 **−13.161547** → 撞上 camera.y≤−10 的
-                    //   掉出世界复位（`this.playerCollider.end.set(0, 1, 10)`）→ 「陷进地面很长一段
+                    //   掉出世界复位（玩家视点重置到 (0, 1, 10)）→ 「陷进地面很长一段
                     //   距离然后凭空回到原点」。这就是皇上看到的现象。
                     //   新口径：**绝不往下顶**，一步顶到「脚底刚好落在这块面之上」（眼高 = 面 y +
                     //   downRange + SKIN）。顶完眼只比板底高一个 SKIN → 下一轮迭代下射线立刻
@@ -1833,7 +1805,7 @@ export default class FPScontrol extends EventDispatcher {
         //     位移永远照走（previewRetreat 只关「修正」那份，不关位移）。
         this._appliedMove.set(this._subStep.x + corrX, this._subStep.y + corrY, this._subStep.z + corrZ);
         if (this._appliedMove.lengthSq() > 0) {
-            this.playerCollider.translate(this._appliedMove);
+            this.playerPosition.add(this._appliedMove);
         }
         // 本步已消费：归零，面板那两颗直接调 playerCollisions 的按钮不会重复走一步
         this._subStep.set(0, 0, 0);
@@ -1849,9 +1821,15 @@ export default class FPScontrol extends EventDispatcher {
         //   ⚠️ 方向与推离用的是**同一个** `_horizNormal`（水平半区那轮算好、就地复用），绝不另算一遍。
         //   ⚠️ 竖向 y 一字不动（重力/跳跃照旧）；观察模式（回弹预览）不改速度，口径与 10-07 一致。
         if (this._horizHit && !this.previewRetreat) {
-            const into = this.playerVelocity.dot(this._horizNormal);
-            if (into < 0) {
-                this.playerVelocity.addScaledVector(this._horizNormal, -into);
+            // 墙角中两个约束面不一定在同一轮成为“欠距最大面”。依次投影两轮，
+            // 让每个面都得到 v·n >= 0，同时保留不受任何墙面约束的切向速度。
+            for (let pass = 0; pass < 2; pass++) {
+                for (let ni = 0; ni < this._horizContactCount; ni++) {
+                    const normal = this._horizContactNormals[ni];
+                    const into = this.playerVelocity.dot(normal);
+                    if (into < 0)
+                        this.playerVelocity.addScaledVector(normal, -into);
+                }
             }
         }
         // ⭐ 十旨：一帧一条的抖动台账。**只由子步循环的最后一步（isFinalStep）记** ——
@@ -1877,10 +1855,8 @@ export default class FPScontrol extends EventDispatcher {
     // 越界传送
     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.playerPosition.set(0, 1, 10);
+            this.camera.position.copy(this.playerPosition);
         }
     };
     // 更新