three-base 2.0.169 → 2.0.175

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」，
      *  与主循环竖直门配合后失明窗口彻底消失。**顶点**才是防翻墙的那条线，不是初速度本身。
@@ -183,7 +182,7 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      * 单步最大位移（连续碰撞检测用）：每帧位移会被切成若干 ≤ 本值的小步，逐步做碰撞检测。
      * ⚠️ 必须明显小于水平包络的可达距离（R=1.06 时沿法线 0.749~1.06m），否则掉帧时一步就跨过墙体。
      * ⚠️ 本值同时决定「单次碰撞需要修正多深」——子步越小，玩家每次陷进墙里越浅，
-     *    迭代要走的格数就越少（一格恒 RETREAT_SKIN，总位移 ≈ 该子步的穿透深度），
+     *    迭代要走的格数就越少（一格 ≤ RETREAT_SKIN，总位移 ≈ 该子步的穿透深度），
      *    不会出现「一下子回弹很多」。
      *    0.25 → 0.1：单次最大穿透从 0.25 降到 0.1，回弹量同比变小（子步数相应上调）。
      */
@@ -284,13 +283,19 @@ 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 墙）：
+     *    停位现在**逐位等于 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 定「旋钮不动，只把数字写明」⇒ 要真焊死得改这里的下限，别在推离公式里偷偷加夹取。
      */
     static readonly MIN_HORIZONTAL_RAY_RADIUS: number;
     /** 水平射线半径 R 的安全上限（⭐ 2026-10-08 皇上旨收到 1.0：再大包络远大于停位需求、回弹精度已够，白烧射程） */
@@ -338,18 +343,12 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      */
     private _horizHit;
     private _inputDirVec;
-    /**
-     * 本帧**进碰撞之前**的水平速率（米/秒）。皇上八旨要求「移动向量的长度保持不变」，
-     * 而碰撞会把 `playerVelocity.x/z` 清零，所以必须在 updatePlayer 入口先记一份。
-     */
-    private _preCollideHorizSpeed;
     private _previewRetreat;
-    /** 开启预览那一刻的胶囊两端（关闭时整体还原回去） */
-    private _obsSavedStart;
-    private _obsSavedEnd;
+    /** 开启预览那一刻的玩家视点位置（关闭时还原） */
+    private _obsSavedPosition;
     /** 是否已有可还原的暂存（没进过观察模式就没有，避免构造期赋值把人还原到原点） */
     private _obsHasSave;
-    /** 进观察模式（回弹预览 / 单步）：记下当前胶囊位置，退出时还原 */
+    /** 进观察模式（回弹预览 / 单步）：记下当前视点位置，退出时还原 */
     private _saveObsPos;
     /**
      * 退观察模式：把位置整份还原到进入那一刻，并清掉水平速度。
@@ -379,25 +378,28 @@ 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;
     private _probeRaycaster;
     private _tempVec3;
     private _candPos;
-    private _corrVec;
+    /**
+     * ⭐ 2026-10-11 A 档（解析贴合）专用临时量，全部复用避免 GC：
+     *  · `_fitNormal` = 助手里「本轮这条命中面」指向玩家一侧的单位水平法线；
+     *  · `_horizNormal` = 本轮**欠距最大**那面的法线（推离方向 + 速度闸门共用一个方向，绝不各算一遍）；
+     *  · `_fitVec` = (候选中心 − 命中点) 临时量；
+     *  · `_rhombusAxisX/_rhombusAxisZ` = 本帧菱形两条对角轴的世界方向（随 yaw 转，恒水平）。
+     */
+    private _fitNormal;
+    private _horizNormal;
+    /** 本子步实际推离过的不同墙面法线。墙角需要同时裁掉两个朝内速度分量，
+     *  不能只用最后一次命中的面，否则两个面会在相邻帧交替抢占速度闸门而抖动。 */
+    private _horizContactNormals;
+    private _horizContactCount;
+    private _fitVec;
+    private _rhombusAxisX;
+    private _rhombusAxisZ;
     private _tempVec4;
     private _tempVec5;
     /**
@@ -447,6 +449,28 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      * @returns null = 拿不到法线（无 face 或零向量）→ 调用方按「维持旧行为」处理
      */
     private _faceNormalWorldY;
+    /**
+     * ⭐⭐ 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;
     /**
      * 脚下深探：往下问 VOID_PROBE_DOWN 这么长一段，有没有地面（2026-09-25，穿地板自救用）。
      * @returns true = 下方有地面 → 只是正常腾空/下落，不是穿模
@@ -469,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;
@@ -496,7 +521,7 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
      *     `depthWrite:true`（three-base/Ground1/Ground1.ts:107）；哪天地板改回
      *     transparent + depthWrite:false，射线线会重新穿地浮出来。
      *   - 回弹方向线（黄→白）= **false**：「回弹向量线保持穿透显示」。
-     *     它是「本帧要看的向量」，起点在胶囊内部、方向常指着墙里，开遮挡会被自己的身子
+     *     它是「本帧要看的向量」，起点在玩家位置、方向常指着墙里，开遮挡会被墙面
      *     或墙面吃掉半截 → 观察目的直接落空，故保持常显在最前。
      */
     private _createDebugLine;