three-base 2.0.169 → 2.0.172

package/FPScontrol.ts

@@ -305,17 +305,19 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     //     far = R√2。菱形几何一个数没变（R=1.06 → 外接框 2.12×2.12、斜弦 45°、首尾闭合），
     //     只是不再经过「局部单位」这道换算。竖向的 2cm 探测余量见 `VERTICAL_SKIN`。
     //
-    // 【停位口径（现行唯一，皇上 2026-09-27 十五旨）】射线在 far 内命中 = 碰撞；
-    //   「还差多远才脱开」= 菱形沿墙法线的可达距离 reach = R·max(|n·右|, |n·前|) ∈ [R/√2, R]
-    //   减去当前垂距 = deficit，取全轮最大者当读数；位置修正沿回弹方向**一格一格推**（每格
-    //   RETREAT_SKIN），推到最大穿透 ≤ 阈值 / 全脱开为止 —— 停位带与旧的解析解同宽。
+    // 【停位口径（现行唯一，皇上 2026-10-11 A 档改判 = 「解析贴合 + 只削法向速度」）】
+    //   射线在 far 内命中 = 碰撞；「还差多远才脱开」= 菱形沿墙法线的可达距离
+    //   reach = R·max(|n·右|, |n·前|) ∈ [R/√2, R] 减去当前垂距 = deficit，取全轮**最大**者当读数；
+    //   位置修正沿该面法线一格一格推，每格 = min(RETREAT_SKIN, deficit) ⇒ 大欠距仍走整格，
+    //   **收尾那一格按欠距截短** ⇒ 落点正好贴在包络边上（旧写法最后一格也推满 1cm → 过冲 → 来回甩）。
+    //   速度只削「往墙里」那一份（v −(v·n)n），切向保留 ⇒ 贴墙能滑，撞墙不再「加速→清零」锯齿。
     //   ⇒ 停位仍只由 **R** 一个数决定（R=1.06 → 沿法线 0.749~1.06m）；胶囊半径 0.35 ⇒ 身体与墙之间
     //     还留 0.40~0.71m 空气隙，这是皇上 2026-09-06 终裁布局自带、且亲眼验收过的量，不要当 bug 修。
     /**
      * 单步最大位移（连续碰撞检测用）：每帧位移会被切成若干 ≤ 本值的小步，逐步做碰撞检测。
      * ⚠️ 必须明显小于水平包络的可达距离（R=1.06 时沿法线 0.749~1.06m），否则掉帧时一步就跨过墙体。
      * ⚠️ 本值同时决定「单次碰撞需要修正多深」——子步越小，玩家每次陷进墙里越浅，
-     *    迭代要走的格数就越少（一格恒 RETREAT_SKIN，总位移 ≈ 该子步的穿透深度），
+     *    迭代要走的格数就越少（一格 ≤ RETREAT_SKIN，总位移 ≈ 该子步的穿透深度），
      *    不会出现「一下子回弹很多」。
      *    0.25 → 0.1：单次最大穿透从 0.25 降到 0.1，回弹量同比变小（子步数相应上调）。
      */
@@ -456,6 +458,12 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      * ⇒ 取 **0.6**：保证停位垂距 > 玩家胶囊半径(0.35)，不再穿模。
      * ⭐ 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）：
+     *    停位现在**逐位等于 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**（身体不出面）
+     *    ⇒ 抖不抖与 R 无关（A 档后全档抖动 0.0000m）；R<0.35 只剩「身体陷进墙多少」这一件事，
+     *      皇上 10-11 定「旋钮不动，只把数字写明」⇒ 要真焊死得改这里的下限，别在推离公式里偷偷加夹取。
      */
     public static readonly MIN_HORIZONTAL_RAY_RADIUS: number = 0.2;
     /** 水平射线半径 R 的安全上限（⭐ 2026-10-08 皇上旨收到 1.0：再大包络远大于停位需求、回弹精度已够，白烧射程） */
@@ -518,7 +526,8 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
             digits: 2,
             unit: "m",
             frozen: true,
-            desc: "菱形半对角线 R，外接框边长 = 2R（= 离墙多远开始判定碰撞的半径）。越大包络越大、回弹方向越准；R<0.6 仍会贴墙穿模（R=0.5 贴墙面、R=0.3 明显穿模），已放宽到 0.2~1.0 供按需拧",
+            desc: "菱形半对角线 R，外接框边长 = 2R（= 离墙多远开始判定碰撞的半径）。越大包络越大、回弹方向越准；R<0.6 仍会贴墙穿模（R=0.5 贴墙面、R=0.3 明显穿模），已放宽到 0.2~1.0 供按需拧。" +
+                "⭐ 2026-10-11 A 档实测：停位逐位等于 R ⇒ 身体入墙深度 = 0.35 − R（R=0.2 → 0.15m、R=0.3 → 0.05m、R≥0.35 → 0m）；抖动与 R 无关（全档 0.0000m），旋钮范围按皇上旨不动",
             get: (fps) => fps.CHORD_RHOMBUS_R,
             set: (fps, v) => fps.setHorizontalRayRadius(v),
         },
@@ -635,7 +644,7 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
             step: 0.005,
             digits: 3,
             unit: "m",
-            desc: "⭐ 2026-09-28 皇上旨「完完全全用 xsh-react-three 的碰撞法」：每条命中射线每轮沿「命中点→中心」方向推的一小格（xsh 源码里写死 0.03；**皇上 10-07 旨「应该 1 个单位 1 个单位的修正」⇒ 默认改 0.01 = 一格 1cm**）。" +
+            desc: "⭐ 2026-10-11 皇上 A 档改判：每轮**只沿「欠距最大那一面」的法线**推一格，且这一格取 min(本值, 该面欠距) ⇒ 大欠距仍是一格一格往外走（皇上 10-07「1 个单位 1 个单位的修正」），只有**收尾那一格按欠距截短**，落点贴在包络边上（旧写法每条命中射线各推满一格、最后一格也推满 ⇒ 过冲 ⇒ 贴墙来回甩 = 抖动）。" +
                 "⚠️ 上限以下别贪小：0.03/0.02/0.01 体检台判级完全相同，拧到 0.005 才有改善但「跳跃+冲刺+掉帧」那个现场开始穿墙（格长 = 每帧出水量）。迭代推到全部射线脱开为止",
         },
         {
@@ -814,11 +823,6 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     // 缓存本帧的按键输入单位方向（水平）。initPlayerInputDir() 每物理步刷新一次；
     // 零向量表示「本帧没按方向键」→ 最终方向退化为纯反弹方向。
     private _inputDirVec: Vector3 = new Vector3();
-    /**
-     * 本帧**进碰撞之前**的水平速率（米/秒）。皇上八旨要求「移动向量的长度保持不变」，
-     * 而碰撞会把 `playerVelocity.x/z` 清零，所以必须在 updatePlayer 入口先记一份。
-     */
-    private _preCollideHorizSpeed: number = 0;
     // ========== 回弹预览（皇上 2026-09-25 旨：「加个开关可以关闭碰撞修正位置的计算，方便观察回弹向量」）==========
     // 打开后：**不写位置**（见 playerCollisions 末尾唯一的 translate 闸门），但方向/推离量照常算、
     // 黄→白方向线照常画 → 肉眼核对「算出来的方向对不对」而不被人推开。
@@ -926,10 +930,20 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     private _probeRaycaster: Raycaster = new Raycaster();
     // 临时向量（复用避免 GC）
     private _tempVec3: Vector3 = new Vector3();
-    // xsh 移植（2026-09-28）：候选位置（= 控制器位置 + positionIncremental，射线原点锚）
-    //   与推离向量专用临时量（复用避免 GC）
+    // xsh 移植（2026-09-28）：候选位置（= 控制器位置 + positionIncremental，射线原点锚）临时量
     private _candPos: Vector3 = new Vector3();
-    private _corrVec: Vector3 = new Vector3();
+    /**
+     * ⭐ 2026-10-11 A 档（解析贴合）专用临时量，全部复用避免 GC：
+     *  · `_fitNormal` = 助手里「本轮这条命中面」指向玩家一侧的单位水平法线；
+     *  · `_horizNormal` = 本轮**欠距最大**那面的法线（推离方向 + 速度闸门共用一个方向，绝不各算一遍）；
+     *  · `_fitVec` = (候选中心 − 命中点) 临时量；
+     *  · `_rhombusAxisX/_rhombusAxisZ` = 本帧菱形两条对角轴的世界方向（随 yaw 转，恒水平）。
+     */
+    private _fitNormal: Vector3 = new Vector3();
+    private _horizNormal: Vector3 = new Vector3();
+    private _fitVec: Vector3 = new Vector3();
+    private _rhombusAxisX: Vector3 = new Vector3(1, 0, 0);
+    private _rhombusAxisZ: Vector3 = new Vector3(0, 0, 1);
     private _tempVec4: Vector3 = new Vector3();
     // 位移细分用的临时向量（与 playerCollisions 内的 _tempVec4 分开，避免被覆盖）
     private _tempVec5: Vector3 = new Vector3();
@@ -1119,6 +1133,40 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
         if (!this._transformFaceNormalWorld(interset, n)) return null;
         return n.normalize().y;
     }
+    /**
+     * ⭐⭐ 2026-10-11 皇上改判 A 档「解析贴合」：一条水平命中射线**沿本面法线还差多少才脱开**。
+     *   同时把该面的单位水平法线（指向玩家所在的一侧）写进 `this._fitNormal` 供调用方取用。
+     *
+     * 为什么要它：旧写法每轮对每条命中射线**整格**推 `RETREAT_SKIN`（1cm），而退出判据是「8 条射线
+     *   全部脱开」⇒ 落点必然**过冲最多一格**（实测弹回 1.05cm），下一帧再从过冲处走回来 =
+     *   皇上所见「顶进去又弹回来一直抖」（无头复现：抖峰峰 0.0193m，60fps 下 34 次往复/40 帧，
+     *   与 R / 墙厚 / 入射角 / 帧率全无关）。按欠距推到「刚好脱开」就不再有过冲。
+     *
+     * 判据（恒等式，不是拍的）：碰撞包络是顶点在 ±R·x̂、±R·ẑ 的**菱形**，它沿方向 n 的支持距离
+     *   req = R·max(|n·x̂|, |n·ẑ|) ∈ [R/√2, R]。候选中心沿 n 到命中面的垂距为 perp（在实体内为负），
+     *   那么「还差 deficit = req − perp」推满就正好贴在包络边上。
+     *
+     * 法线取向：**与射线行进方向相反**的一侧（three 对 FrontSide 只回正面命中，所以常态天然满足；
+     *   DoubleSide 拿到背面时按此翻号）。⚠️ 不能按「指向中心」翻号——中心已经陷进 1m 厚墙板时，
+     *   那样翻会把人往墙体更深处推（旧写法正是靠两侧票互相抵消才卡在板正中）。
+     *
+     * @returns deficit（米，≤0 = 已经脱开）。退化场景返回 0：
+     *   · 拿不到面法线（无 face / 零向量）
+     *   · 命中面近乎水平（法线压平后是零向量，如贴着地面/台面掠射）⇒ 不该把它当墙侧推
+     */
+    private _horizFitDeficit(worldPos: Vector3, rayDir: Vector3, interset: Intersection): number {
+        const n = this._fitNormal;
+        if (!this._transformFaceNormalWorld(interset, n)) return 0;
+        n.y = 0; // 本布局水平射线在 y=−0.7/−0.75（皇上 09-26 五旨），推离必须纯水平（同旧「偏差①」）
+        if (n.lengthSq() < 1e-8) return 0;
+        n.normalize();
+        // 指向「射线来的那一侧」= 逆着射线行进方向，即离开实体的方向
+        if (n.dot(rayDir) > 0) n.negate();
+        const perp = n.dot(this._fitVec.copy(worldPos).sub(interset.point));
+        const ax = Math.abs(n.dot(this._rhombusAxisX));
+        const az = Math.abs(n.dot(this._rhombusAxisZ));
+        return this.CHORD_RHOMBUS_R * Math.max(ax, az) - perp;
+    }
     /**
      * 脚下深探：往下问 VOID_PROBE_DOWN 这么长一段，有没有地面（2026-09-25，穿地板自救用）。
      * @returns true = 下方有地面 → 只是正常腾空/下落，不是穿模
@@ -1397,11 +1445,10 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     controls = (deltaTime: number): void => {
         const speedDelta = deltaTime * (this.playerOnFloor ? 25 : 8) * this.speed;
         // ⭐ 2026-09-26 皇上旨「碰撞就是按射线拾取算的，不用搞太复杂」：
-        //   旧的「接触法线缓存 + 加速度保速投影」整块删除 —— 撞墙的手感由位置侧负责
-        //   （命中即 playerVelocity.x/z = 0，再走迭代推格修正位置，皇上 2026-09-25 定案）。
-        //   ⭐ 2026-09-26 皇上八旨给这条加了个尾巴：位置修正判完之后，若本帧算出了方向且没和
-        //   输入方向对消，水平速度会整条换成 normalize(输入 + 回弹) × 碰撞前速率（贴墙不再走不动），
-        //   见 playerCollisions 末尾那段。清零本身照旧。
+        //   旧的「接触法线缓存 + 加速度保速投影」整块删除 —— 这里**只管往输入方向加速**，
+        //   撞墙的手感全部由 playerCollisions 负责：位置侧「解析贴合」（欠距最大那面推格、
+        //   最后一格截短），速度侧「只削往墙里那一份」（⚠️ 2026-10-11 A 档改判，此处不再是
+        //   playerVelocity.x/z 整条清零 ⇒ 贴墙能沿墙滑行，见 playerCollisions 末尾那段）。
         const accel = this._accelVec.set(0, 0, 0);
         if (this.keyStates["KeyW"]) {
             accel.addScaledVector(this.getForwardVector(), speedDelta);
@@ -1442,9 +1489,6 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
             damping *= 0.1;
         }
         this.playerVelocity.addScaledVector(this.playerVelocity, damping);
-        // ⭐ 2026-09-26 皇上八旨「位置修正结束后…移动向量的长度保持不变」：本帧**进碰撞前**的
-        //   水平速率快照。碰撞会把速度清零，子步跑完再想要「原来的长度」就没有了，必须在入口取。
-        this._preCollideHorizSpeed = Math.hypot(this.playerVelocity.x, this.playerVelocity.z);
         // 位移细分（连续碰撞）：把本帧位移切成若干 ≤ MAX_STEP_DISTANCE 的小步，逐步推进并检测。
         // 不细分的话，掉帧（deltaTime 被 clamp 到 0.05）时单步位移可达 25×0.025 ≈ 0.6，
         // 远大于射线的检测余量（沿法线最小 reach R/√2 = 0.749 − 子步 0.1）→ 直接跨过墙体（穿墙）。
@@ -1512,11 +1556,15 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
         //   ⇒ 本方法整体 = xsh `FPSControls.tsx → computerPosition()` 的忠实移植，骨架只有：
         //     ① while 循环（皇上 09-03 定「一帧合计不超过 100」，10-03 旨改到 500；骨架与 xsh 的 i<100 同形）；
         //     ② 每轮在「候选位置」（真实位置 + positionIncremental）上打 8 条水平斜弦射线，
-        //        每条命中 ⇒ 沿「控制器中心 − 命中点」方向推一小格（xsh 源码写死 0.03；皇上 10-07 旨
-        //        「应该 1 个单位 1 个单位的修正」⇒ 本项默认改成 RETREAT_SKIN = 0.01，一格 1cm）
-        //        累加进 positionIncremental，并 goOnComputer=true 续命下一轮（xsh 各票天然抵消）；
+        //        ⭐ 2026-10-11 皇上 A 档改判：每条命中算「沿本面法线还差多少才脱开」(deficit)，
+        //        **只取欠距最大的那一面**，沿它的法线推 min(RETREAT_SKIN, deficit) ——
+        //        一格一格的外形保留（皇上 10-07 旨「应该 1 个单位 1 个单位的修正」⇒ RETREAT_SKIN=0.01），
+        //        但收尾那一格按欠距截短 ⇒ 落点贴包络边，不再整格过冲（旧 xsh 各票各推一整格 ⇒ 必过冲）；
+        //        累加进 positionIncremental，并 goOnComputer=true 续命下一轮；
         //     ③ 下射线命中 ⇒ 竖直速度清零 + y 钉到「命中面之上 DOWN_RANGE」（xsh: cv − distance）；
-        //        上射线命中 ⇒ 竖直速度清零 + 修正（含三道闸天花板的血案守卫）；
+        //        上射线命中 ⇒ 竖直速度清零 + 修正（含三道闸天花板的血案守卫）
+        //        —— ⭐ 10-11 修好少括号的 bug 后，上射线**每轮都测**（旧代码被关进「下射线命中」分支里
+        //        ⇒ 腾空时跳起来顶不到天花板）；
         //     ④ 某一轮全部射线脱开 ⇒ 收工；循环外唯一一次 translate 落地（血案护栏不变）。
         //   ⭐⭐ 2026-10-02 皇上旨「模拟修正，不是真实修正，把最终结果算好了再应用到真实的第一人称
         //     控制器上面」⇒ 那个 translate 落的是**「本步位移 + 允许的修正」一次到位**：
@@ -1529,7 +1577,12 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
         //       本布局射线在 y=−0.7/−0.75（皇上 09-26 五旨），不压平会把 y 混进推离；
         //     · 水平射线 8 条（皇上 09-06/09-14 亲加的 6-9 共线反向组），xsh 原版 4 条；
         //     · 竖向保留 faceUp / 天花板三道闸守卫（「掉出世界」血案修复）。
+        //     · ⭐ 2026-10-11 A 档：**只沿「欠距最大那一面」的法线**推，且最后一格按欠距截短
+        //       （xsh 是每条命中各推一整格 ⇒ 4 条命中同一面墙一轮推 4cm，退出时必过冲）。
         //   原 deficit / 票面合成(finalDir) / 逐格推离 / 白推保险丝 / 胶囊兜底机器整条拆除。
+        //   ⚠️ 措辞校正（10-11）：上面这句里「deficit」那半已随 A 档**回归**（`_horizFitDeficit()`：
+        //   沿命中面法线的菱形可达距离 R·max(|n·x̂|,|n·ẑ|) 减当前垂距）；
+        //   仍拆除的是「票面合成 finalDir / 白推保险丝 / 胶囊兜底」三件 —— 别照旧文案把它们捡回来。
         const positionIncremental = this._tempVec4.set(0, 0, 0);
         this._refreshInputDir(); // 台账 ix/iz 列还要用（与碰撞计算无关）
         const recordDebug = (this.dev || this.thirdPerson) && isFinalStep;
@@ -1561,12 +1614,21 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
             for (const ray of this._rays) {
                 ray.updateWorld(yawQuat, worldPos);
             }
+            // ⭐ 2026-10-11 A 档：菱形两条对角轴的世界方向（只随 yaw，恒水平）——贴合量 req 要用它
+            this._rhombusAxisX.set(1, 0, 0).applyQuaternion(yawQuat);
+            this._rhombusAxisZ.set(0, 0, 1).applyQuaternion(yawQuat);
             const horizontalFar = this.HORIZONTAL_FAR; // = R√2（xsh: far = direction.length()）
             const downFar = downRange + this.VERTICAL_SKIN;
             const upFar = upRange + this.VERTICAL_SKIN;
             const devVisualFarD = downRange;
             const devVisualFarU = upRange;
-            // ========== 水平半区（xsh 原样：每条命中射线各推一小格）==========
+            // ========== 水平半区（⭐ 2026-10-11 皇上改判 A 档 = 解析贴合，替代「每条命中各推一整格」）==========
+            // 每轮：所有命中射线各算「沿本面法线还差多少才脱开」(deficit)，**只取欠距最大的那一面**，
+            // 沿它的法线推 `min(RETREAT_SKIN, deficit)` —— 一格 1cm 的上限照旧（皇上 10-07「1 个单位
+            // 1 个单位的修正」），但**最后一格只推欠距本身**，落点贴在包络边上，不再整格过冲。
+            //   · 为什么不再各票相加：4 条命中同一面墙时旧写法一轮推 4cm，退出时必然过头；
+            //   · 为什么只取最大：墙角两面墙各欠 3cm 时，先脱开深的那面，下一轮再补另一面（≤2~3 轮）。
+            let bestDeficit = 0;
             for (let ri = 2; ri < this._rays.length; ri++) {
                 const ray = this._rays[ri];
                 ray.far = horizontalFar;
@@ -1595,24 +1657,23 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
                         interset = intersets[j];
                     }
                 }
-                // ⭐ xsh 原文：vector3Temp = worldPos − interset.point; setLength(0.03);
-                //   positionIncremental.add(vector3Temp); goOnComputer = true;
-                //   ⚠️ 锚点 = basePos（xsh 的 getWorldPosition，循环内不含增量）。
-                const corr = this._corrVec.copy(basePos).sub(interset.point);
-                corr.y = 0; // 偏差①：本布局射线在 y=−0.7/−0.75，不压平会把 y 混进推离（xsh 射线在 y=0 天然水平）
-                if (corr.lengthSq() > 1e-12) {
-                    if (i > roundCap) {
-                        // ⭐ **轮次上限**用完 ⇒ 这一轮起水平一格都不再推。
-                        //   常态帧 = 皇上 10-07 点头新加的 ROUNDS_PER_SUBSTEP（默认 500 ⇒ 与旧行为同形）。
-                        //   ⚠️ 只拦水平：竖向（踩地/顶头）仍照常，否则人会往地心沉（皇上 09-25 冻结口径）。
-                    } else {
-                        corr.setLength(this.RETREAT_SKIN);
-                        positionIncremental.add(corr);
-                        goOnComputer = true;
-                        this._horizHit = true;
-                        // 方向线/台账的「修正方向」快照 = 最后一次命中的推离方向
-                        // ⭐ 皇上 10-07 旨「每执行一次，偏移量是多少」⇒ 按钮那一次：一格一行，带累计
-                    }
+                const deficit = this._horizFitDeficit(worldPos, ray.direction, interset);
+                if (deficit > bestDeficit) {
+                    bestDeficit = deficit;
+                    this._horizNormal.copy(this._fitNormal); // 与推离方向同一个数，绝不分两处算
+                }
+            }
+            if (bestDeficit > 1e-6) {
+                if (i > roundCap) {
+                    // ⭐ **轮次上限**用完 ⇒ 这一轮起水平一格都不再推。
+                    //   常态帧 = 皇上 10-07 点头新加的 ROUNDS_PER_SUBSTEP（默认 500 ⇒ 与旧行为同形）。
+                    //   ⚠️ 只拦水平：竖向（踩地/顶头）仍照常，否则人会往地心沉（皇上 09-25 冻结口径）。
+                } else {
+                    // ⭐ 皇上 10-07 旨「每执行一次，偏移量是多少」⇒ 一格一行、带累计的形态保留：
+                    //   大欠距仍是一格一格往外走，只有收尾那一格按欠距截短。
+                    positionIncremental.addScaledVector(this._horizNormal, Math.min(this.RETREAT_SKIN, bestDeficit));
+                    goOnComputer = true;
+                    this._horizHit = true;
                 }
             }
             // ========== 向下射线（索引 0 = upTodwomRay）==========
@@ -1675,6 +1736,13 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
                 //     **不能**沿用旧探针的 `!debugRecorded`：`debugRecorded = !recordDebug`，而 `recordDebug`
                 //     跟着面板「碰撞射线」(dev) 走 → dev 关着时恒 true → 整段被跳过，
                 //     这正是皇上「在控制台里根本看不到下射线数值」的原因。
+            // ⭐ 2026-10-11 皇上旨「少括号的 bug 一起修」：这个 `}` 是 `if (downIntersets.length > 0)` 的
+            //   闭合括号，历史上被吃掉了 ⇒ 下面整段「向上射线」被关进「下射线命中」分支里。
+            //   症状：腾空时脚下射线打不到地面 → 上射线**一次都不测** → 跳起来顶不到天花板（穿板顶）。
+            //   顺带的第二个坑：while 的闭合括号跟着后移到「应用推离」注释之后（原 1843 行那个 `}`），
+            //   于是「更新调试射线」那段也在每轮迭代里跑一遍 —— 删掉那个多余括号后它回到循环外，
+            //   正好对上它自己的标签「dev 模式的**最后一步**」，且每帧只做一次。
+            }
             // ========== 向上射线（索引 1 = dwomToUpRay）==========
             const upRay = this._rays[1];
             upRay.far = upFar;
@@ -1786,7 +1854,6 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
         //   ⚠️ 只跳「写位置」，不跳「记账」：`playerVelocity.y = 0`、`playerOnFloor = true`
         //     与削速度/方向票全部保留 → 观察时不会一帧帧攒重力陷到地心，也不会触发
         //     camera.y ≤ −10 的掉出世界复位。
-        }
         // ⭐⭐ 2026-10-02 皇上旨（原话）：「在修正位置的时候，我希望的是**模拟修正**，而不是**真实的
         //   修正**，在模拟修正中把最终结果计算好了，再应用到真实的第一人称控制器上面」。
         //   ⇒ 上面那个 while 全在**模拟位置**（真实位置 + 本步位移 `_subStep`）上跑；真实 collider
@@ -1824,15 +1891,22 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
         // 本步已消费：归零，面板那两颗直接调 playerCollisions 的按钮不会重复走一步
         this._subStep.set(0, 0, 0);
 
-        // ⭐⭐ 2026-10-07 皇上旨「撞到墙后，加速度置为 0」：
-        //   抖动根因 = 撞墙后位置被推回包络边，但 playerVelocity 的水平分量（朝墙的冲量）一直保留，
-        //   下一帧 controls() 又叠加输入加速度 → 再次朝墙冲 → 再次被推回 → 来回甩 = 肉眼抖动。
-        //   ⇒ 本子步水平命中（_horizHit）即把 playerVelocity.x/z 清零：人贴墙即停，
-        //     不再被惯性反复往墙里拽、被推离反复弹回。（观察模式：单步/回弹预览不改速度，
-        //     免得不落地的观察帧把速度抹掉、干扰手感判断；竖向 y 一字不动——重力/跳跃照旧。）
+        // ⭐⭐ 2026-10-11 皇上旨「撞墙会进入墙体然后反弹回来，一直抖动」→ A 档改判：
+        //   **只削掉「往墙里」那一份速度**（沿命中面法线的负分量），切向分量原样保留。
+        //   旧口径（2026-10-07「撞到墙后，加速度置为 0」）是 x/z 双双归零，两处毛病：
+        //     ① 斜着撞墙 = 连「沿墙滑行」那份一起抹掉 → 手感像被墙吸停，且人是沿坐标轴方向被清，
+        //        不是沿墙法线；速度被清零的方向与实际推离方向不共线 → 推离与加速度交替占上风；
+        //     ② 全清 ⇒ 每帧「输入重新加速 → 立刻清零」的锯齿，正是他看到的抖动的另一半来源
+        //        （实测峰峰 0.0193m、60fps 下约 17 次/秒翻向）。
+        //   新口径：`into = v·n`（n = 本轮欠距最大那面的**外法线**，指向玩家一侧），只在 into<0
+        //   （= 正在往墙里冲）时减掉 `into·n` 那份 ⇒ 撞后 v·n = 0（非穿透），切向 v−(v·n)n 完整保留。
+        //   ⚠️ 方向与推离用的是**同一个** `_horizNormal`（水平半区那轮算好、就地复用），绝不另算一遍。
+        //   ⚠️ 竖向 y 一字不动（重力/跳跃照旧）；观察模式（回弹预览）不改速度，口径与 10-07 一致。
         if (this._horizHit && !this.previewRetreat) {
-            this.playerVelocity.x = 0;
-            this.playerVelocity.z = 0;
+            const into = this.playerVelocity.dot(this._horizNormal);
+            if (into < 0) {
+                this.playerVelocity.addScaledVector(this._horizNormal, -into);
+            }
         }
         // ⭐ 十旨：一帧一条的抖动台账。**只由子步循环的最后一步（isFinalStep）记** ——
         //   中间小步是碰撞细分的过渡状态，记了就变成「一帧好几条」，翻向/跳变的口径全乱。

package/Ground1/Ground1.js

@@ -21,8 +21,10 @@
  *
  *   ⚠️ 改动红线（这几条被别处依赖，**不许顺手改**）：
  *   - `userData.fpsCollision = true`：FPScontrol 把地板当碰撞体（见 FPScontrol.ts 地面处理段）。
- *   - `userData.aoFloor = true`：ssao_pass / debugExcludedShader 的「地板类半透明」特例按此标记走
- *     （默认不写进可见深度图；物体落在地板上仍有接触 AO）。
+ *   - ⚠️ 2026-10-11 皇上旨「物体的深度都要进深度图」⇒ 原第三条红线 `userData.aoFloor = true`
+ *     （把地板从可见深度图里排除的那条例外）**整条拆除**：它的前提是地板半透明可透视，与本文件
+ *     ② 的「不透明改造」自相矛盾。地板现在按普通实心面写进深度图，被它挡住的描边/辉光/覆盖色/
+ *     磨砂会被裁掉。见 three-base/pass/ssao_pass.ts 文件头。
  *   - ShaderMaterial 必须含 logdepthbuf chunk；linear 输出必须 `#include <colorspace_fragment>`；
  *     否则末端 sRGB 编码会二次编码 → 发白。
  */
@@ -36,10 +38,8 @@ export default class Ground1 extends Mesh {
         super();
         // 标记为自己参与 FPS 碰撞检测
         this.userData.fpsCollision = true;
-        // 标记为"地板类半透明"：参与世界空间 AO（物体落在它上需要接触 AO），
-        // 但透过它看到的物体（如从下方透视）仍照常显示描边/辉光、且不被它的接触 AO 乘黑。
-        // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
-        this.userData.aoFloor = true;
+        // ⚠️ 这里原来还有 `this.userData.aoFloor = true;`（把本地板从可见深度图里排除的特例标记），
+        // 2026-10-11 皇上旨「物体的深度都要进深度图」⇒ 连同 ssao_pass 的特例分支一起整条删除。
     }
     renderOrder = -1;
     geometry = (() => {

package/Ground1/Ground1.ts

@@ -21,8 +21,10 @@
  *
  *   ⚠️ 改动红线（这几条被别处依赖，**不许顺手改**）：
  *   - `userData.fpsCollision = true`：FPScontrol 把地板当碰撞体（见 FPScontrol.ts 地面处理段）。
- *   - `userData.aoFloor = true`：ssao_pass / debugExcludedShader 的「地板类半透明」特例按此标记走
- *     （默认不写进可见深度图；物体落在地板上仍有接触 AO）。
+ *   - ⚠️ 2026-10-11 皇上旨「物体的深度都要进深度图」⇒ 原第三条红线 `userData.aoFloor = true`
+ *     （把地板从可见深度图里排除的那条例外）**整条拆除**：它的前提是地板半透明可透视，与本文件
+ *     ② 的「不透明改造」自相矛盾。地板现在按普通实心面写进深度图，被它挡住的描边/辉光/覆盖色/
+ *     磨砂会被裁掉。见 three-base/pass/ssao_pass.ts 文件头。
  *   - ShaderMaterial 必须含 logdepthbuf chunk；linear 输出必须 `#include <colorspace_fragment>`；
  *     否则末端 sRGB 编码会二次编码 → 发白。
  */
@@ -37,10 +39,8 @@ export default class Ground1 extends Mesh {
         super();
         // 标记为自己参与 FPS 碰撞检测
         this.userData.fpsCollision = true;
-        // 标记为"地板类半透明"：参与世界空间 AO（物体落在它上需要接触 AO），
-        // 但透过它看到的物体（如从下方透视）仍照常显示描边/辉光、且不被它的接触 AO 乘黑。
-        // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
-        this.userData.aoFloor = true;
+        // ⚠️ 这里原来还有 `this.userData.aoFloor = true;`（把本地板从可见深度图里排除的特例标记），
+        // 2026-10-11 皇上旨「物体的深度都要进深度图」⇒ 连同 ssao_pass 的特例分支一起整条删除。
     }
     renderOrder: number = -1;
     geometry: PlaneGeometry = (() => {

package/MktMesh/MktMesh.d.ts

@@ -72,9 +72,13 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  · 只读 XZ ⇒ 与名册历代那把「水平距离」尺同一把（09-28 旨），高度差不进尺子。
      *  · `null` ⇒ 回落 `camera.position`（老口径）：发布页那一路没有控制器引用，不注入就一切照旧。
      *  · 存的是**引用**（OrbitControls 原地改它那个 Vector3）⇒ 消费方设一次即可，不必每帧重设。
-     *  · ⚠️ 全景点矩阵本就是**世界矩阵**，锚点也取世界坐标；⛔ 别再乘一遍 `matrixWorld`（同 `updateTexture` 里那句提醒）。
+     *  · 注入的是**世界坐标**；`updateTexture` 里先 `worldToLocal` 换算到本网格局部空间再比距离
+     *    （全景矩阵与着色器取图的 `vProjPos` 都在局部空间，见那里的 2026-10-11 丙旨说明）。
+     *    ⛔ 反过来去给全景矩阵乘 `matrixWorld` 是错的：那会让 JS 侧的尺子和 shader 里的取图各走一路。
      */
     private _rosterCenter;
+    /** 锚点换算到局部空间的落点（每帧复用同一只临时量，避免分配） */
+    private _rosterAnchorLocal;
     /**
      * ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：库侧不再自养「按全景序号取整槽、齐活才写」那一路，
      *    改成与编辑态**同一份换绑策略**（`./panoSlotBind`）+ 同一口径的三张表：

package/MktMesh/MktMesh.js

@@ -118,9 +118,13 @@ export default class MktMesh extends Mesh {
      *  · 只读 XZ ⇒ 与名册历代那把「水平距离」尺同一把（09-28 旨），高度差不进尺子。
      *  · `null` ⇒ 回落 `camera.position`（老口径）：发布页那一路没有控制器引用，不注入就一切照旧。
      *  · 存的是**引用**（OrbitControls 原地改它那个 Vector3）⇒ 消费方设一次即可，不必每帧重设。
-     *  · ⚠️ 全景点矩阵本就是**世界矩阵**，锚点也取世界坐标；⛔ 别再乘一遍 `matrixWorld`（同 `updateTexture` 里那句提醒）。
+     *  · 注入的是**世界坐标**；`updateTexture` 里先 `worldToLocal` 换算到本网格局部空间再比距离
+     *    （全景矩阵与着色器取图的 `vProjPos` 都在局部空间，见那里的 2026-10-11 丙旨说明）。
+     *    ⛔ 反过来去给全景矩阵乘 `matrixWorld` 是错的：那会让 JS 侧的尺子和 shader 里的取图各走一路。
      */
     _rosterCenter = null;
+    /** 锚点换算到局部空间的落点（每帧复用同一只临时量，避免分配） */
+    _rosterAnchorLocal = new Vector3();
     /**
      * ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：库侧不再自养「按全景序号取整槽、齐活才写」那一路，
      *    改成与编辑态**同一份换绑策略**（`./panoSlotBind`）+ 同一口径的三张表：
@@ -691,15 +695,21 @@ export default class MktMesh extends Mesh {
             this.activeIndex = -1;
             return;
         }
-        const ref = this._rosterCenter ?? camera.position;
+        // ⭐ 皇上旨 2026-10-11 丙：尺子的两端必须落在**同一个空间**。注入的锚点是世界坐标，而下面那把尺子量的
+        //    全景位置记在本网格的**局部（制图）空间** —— 依据是着色器自己：`vProjPos = uProjInvMatrix·modelMatrix·pos`
+        //    = M⁻¹·M·pos = 局部（`uProjInvMatrix` 正是 `syncProjInvMatrix` 里那句 `matrixWorld` 求逆），片元再拿
+        //    `dir = vProjPos - tm[3].xyz` 取图 ⇒ 全景矩阵只可能和 `vProjPos` 同空间，即局部。
+        //    所以换算放在**锚点这一端**（`worldToLocal`），⛔ 不去给全景矩阵乘 `matrixWorld`：那是把 JS 的尺子
+        //    和 shader 的取图拆成两路。网格无变换时这一步是恒等 ⇒ 老项目逐字不变；有旋转时（消费方给 mkt 加了
+        //    `rotation.y`）原来会把「往世界的某一头走」量成「往局部的另一头走」，人走到位了名册还不动。
+        const ref = this._rosterAnchorLocal.copy(this._rosterCenter ?? camera.position);
+        this.worldToLocal(ref);
         const dists = [];
         for (let i = 0; i < n; i++) {
             const e = this.textures[i].matrix.elements;
             this._tmpV3.set(e[12], e[13], e[14]);
-            // ⚠️ 全景点矩阵**本身就是世界矩阵**（见上方 textures 字段注释），位置已在世界空间，
-            //    可直接与锚点的世界坐标比距离 —— 这里**绝不能再乘 matrixWorld**：那是双重变换，
-            //    MktMesh 一有整体变换就会算错「离锚点最近的是哪张」（选错全景）。
-            //    （2026-09-19 曾误以为它记在模型空间而多乘了一次，趁 MktDevMesh 对齐时一并纠正。）
+            // ⚠️ 全景点矩阵记在本网格的局部空间（与 `wallPoints` 同一空间，见上面丙旨那段着色器推导），
+            //    所以拿来直接和**已换算到局部**的 `ref` 比距离；⛔ 这里绝不乘 `matrixWorld`（双重变换 = 选错全景）。
             // ⭐ 09-28 09:33 旨：挑图与编辑器取图同一把「**水平距离**」尺（XZ 平面，不含高度差）。
             // const d = this._tmpV3.distanceTo(camera.position);   // 旧原理：三维直线距离——全景点同高（y 恒 1.6）时与本式排序等价，注释保留备查
             // ⭐ 10-07 第二十一道旨：尺子的另一端从相机位置换成 `ref`（控制器中心点；未注入时它就是相机位置）。

package/MktMesh/MktMesh.ts

@@ -141,9 +141,13 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  · 只读 XZ ⇒ 与名册历代那把「水平距离」尺同一把（09-28 旨），高度差不进尺子。
      *  · `null` ⇒ 回落 `camera.position`（老口径）：发布页那一路没有控制器引用，不注入就一切照旧。
      *  · 存的是**引用**（OrbitControls 原地改它那个 Vector3）⇒ 消费方设一次即可，不必每帧重设。
-     *  · ⚠️ 全景点矩阵本就是**世界矩阵**，锚点也取世界坐标；⛔ 别再乘一遍 `matrixWorld`（同 `updateTexture` 里那句提醒）。
+     *  · 注入的是**世界坐标**；`updateTexture` 里先 `worldToLocal` 换算到本网格局部空间再比距离
+     *    （全景矩阵与着色器取图的 `vProjPos` 都在局部空间，见那里的 2026-10-11 丙旨说明）。
+     *    ⛔ 反过来去给全景矩阵乘 `matrixWorld` 是错的：那会让 JS 侧的尺子和 shader 里的取图各走一路。
      */
     private _rosterCenter: Vector3 | null = null;
+    /** 锚点换算到局部空间的落点（每帧复用同一只临时量，避免分配） */
+    private _rosterAnchorLocal: Vector3 = new Vector3();
     /**
      * ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：库侧不再自养「按全景序号取整槽、齐活才写」那一路，
      *    改成与编辑态**同一份换绑策略**（`./panoSlotBind`）+ 同一口径的三张表：
@@ -716,15 +720,21 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             this.activeIndex = -1;
             return;
         }
-        const ref = this._rosterCenter ?? camera.position;
+        // ⭐ 皇上旨 2026-10-11 丙：尺子的两端必须落在**同一个空间**。注入的锚点是世界坐标，而下面那把尺子量的
+        //    全景位置记在本网格的**局部（制图）空间** —— 依据是着色器自己：`vProjPos = uProjInvMatrix·modelMatrix·pos`
+        //    = M⁻¹·M·pos = 局部（`uProjInvMatrix` 正是 `syncProjInvMatrix` 里那句 `matrixWorld` 求逆），片元再拿
+        //    `dir = vProjPos - tm[3].xyz` 取图 ⇒ 全景矩阵只可能和 `vProjPos` 同空间，即局部。
+        //    所以换算放在**锚点这一端**（`worldToLocal`），⛔ 不去给全景矩阵乘 `matrixWorld`：那是把 JS 的尺子
+        //    和 shader 的取图拆成两路。网格无变换时这一步是恒等 ⇒ 老项目逐字不变；有旋转时（消费方给 mkt 加了
+        //    `rotation.y`）原来会把「往世界的某一头走」量成「往局部的另一头走」，人走到位了名册还不动。
+        const ref = this._rosterAnchorLocal.copy(this._rosterCenter ?? camera.position);
+        this.worldToLocal(ref);
         const dists: { t: MktTextureInfo; d: number }[] = [];
         for (let i = 0; i < n; i++) {
             const e = this.textures[i].matrix.elements;
             this._tmpV3.set(e[12], e[13], e[14]);
-            // ⚠️ 全景点矩阵**本身就是世界矩阵**（见上方 textures 字段注释），位置已在世界空间，
-            //    可直接与锚点的世界坐标比距离 —— 这里**绝不能再乘 matrixWorld**：那是双重变换，
-            //    MktMesh 一有整体变换就会算错「离锚点最近的是哪张」（选错全景）。
-            //    （2026-09-19 曾误以为它记在模型空间而多乘了一次，趁 MktDevMesh 对齐时一并纠正。）
+            // ⚠️ 全景点矩阵记在本网格的局部空间（与 `wallPoints` 同一空间，见上面丙旨那段着色器推导），
+            //    所以拿来直接和**已换算到局部**的 `ref` 比距离；⛔ 这里绝不乘 `matrixWorld`（双重变换 = 选错全景）。
             // ⭐ 09-28 09:33 旨：挑图与编辑器取图同一把「**水平距离**」尺（XZ 平面，不含高度差）。
             // const d = this._tmpV3.distanceTo(camera.position);   // 旧原理：三维直线距离——全景点同高（y 恒 1.6）时与本式排序等价，注释保留备查
             // ⭐ 10-07 第二十一道旨：尺子的另一端从相机位置换成 `ref`（控制器中心点；未注入时它就是相机位置）。

package/MktMesh/types.d.ts

@@ -1,6 +1,10 @@
 import type { Matrix4 } from "three";
 /**
- * 单个纹理的运行时信息：url + 世界矩阵（位置 + 旋转，缩放忽略）。
+ * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
+ * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
+ * 着色器里 `vProjPos = uProjInvMatrix·modelMatrix·position` 恰好把顶点拉回局部，片元再拿
+ * `vProjPos - 矩阵位置` 求投影方向，两端必须同空间纹理才贴得住（网格整体旋转/平移时尤其要紧，
+ * 名册挑图那把尺子也因此先把世界锚点 `worldToLocal` 再比距离，见 `MktMesh.updateTexture`）。
  * 纹理矩阵的「位置」即墨卡托投影的中心点（shader 里以它为原点求方向向量）。
  */
 export interface MktTextureInfo {

package/MktMesh/types.ts

@@ -8,7 +8,11 @@
 import type { Matrix4 } from "three";
 
 /**
- * 单个纹理的运行时信息：url + 世界矩阵（位置 + 旋转，缩放忽略）。
+ * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
+ * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
+ * 着色器里 `vProjPos = uProjInvMatrix·modelMatrix·position` 恰好把顶点拉回局部，片元再拿
+ * `vProjPos - 矩阵位置` 求投影方向，两端必须同空间纹理才贴得住（网格整体旋转/平移时尤其要紧，
+ * 名册挑图那把尺子也因此先把世界锚点 `worldToLocal` 再比距离，见 `MktMesh.updateTexture`）。
  * 纹理矩阵的「位置」即墨卡托投影的中心点（shader 里以它为原点求方向向量）。
  */
 export interface MktTextureInfo {

package/ThreeBase.d.ts

@@ -90,8 +90,8 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入）。用于确认深度管线本身是否工作。
      *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
      *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
      *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
@@ -99,15 +99,6 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
      * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
      */
     debugDepthPreview: DebugDepthMode;
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor(): boolean;
-    set baseDepthIncludeFloor(v: boolean);
     normalRenderTarget: WebGLRenderTarget<Texture>;
     screenRenderTarget: WebGLRenderTarget<Texture>;
     screenCopyShader: import("three").ShaderMaterial;