three-base 2.0.137 → 2.0.145

package/FPScontrol.js

@@ -4,18 +4,159 @@
  * @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 { 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 不再引用。）
+const { degToRad, clamp } = MathUtils;
+// 「矩形射线法」的水平 far 口径：斜弦画长 = R√2（四弦首尾闭合的唯一解，勿再改回）。
 import { Capsule } from "three/examples/jsm/math/Capsule";
-import { clamp, degToRad } from "three/src/math/MathUtils";
+// 粗辅助线：WebGL 下 `LineBasicMaterial.linewidth` 恒被驱动钳成 1px（Chrome/ANGLE 一律 1px，
+// 调大无效），要真的变粗必须走 `LineSegments2 + LineMaterial`（shader 里按像素铺quad）。
+// 本仓库先例：src/views/home/homeRender.ts:71-73, 344-358。
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/examples/jsm/lines/LineSegmentsGeometry.js";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
 import { acceleratedRaycast, computeBoundsTree } from "three-mesh-bvh";
-// 确保 three-mesh-bvh 补丁已应用（含 InstancedMesh）
+//  确保 three-mesh-bvh 补丁已应用到普通 Mesh 的射线拾取（BVH 加速）。
+//  ⚠️ 绝不给 InstancedMesh.prototype.raycast 打该补丁：three-mesh-bvh 的
+//  acceleratedRaycast 没有 per-instance 遍历逻辑，对无 boundsTree 的几何会退化成
+//  原生 Mesh.prototype.raycast（只检测几何体一次、不遍历实例），导致 InstancedMesh
+//  的实例完全拾取不到（如 three-base 实例化网格示例的 hover/click 事件失效）。
+//  InstancedMesh 必须保留 three 原生 raycast（逐实例检测并返回 instanceId）。
 if (Mesh.prototype.raycast !== acceleratedRaycast) {
     Mesh.prototype.raycast = acceleratedRaycast;
 }
-if (InstancedMesh.prototype.raycast !== acceleratedRaycast) {
-    InstancedMesh.prototype.raycast = acceleratedRaycast;
+/** 全局 FPScontrol 实例注册表。
+ *  InstancedBatch 在「异步创建碰撞体 InstancedMesh」后，通过本表通知所有已创建的 FPScontrol
+ *  重新收集碰撞体，确保晚于控制器初始化的实例化碰撞体也能被碰撞射线命中（否则会出现"墙建出来了却穿过去"的时序 bug）。 */
+export const fpsControlRegistry = new Set();
+/**
+ * 往「只含 1 段」的 LineSegments2 里写端点与顶点色。
+ * `LineSegmentsGeometry` 用交错的实例属性存段：instanceStart/instanceEnd 共用一条
+ * `instanceStart.array`（长度 6 = 起点 xyz + 终点 xyz），颜色同理。
+ * 每帧只写数组 + 置 needsUpdate，绝不调 `setPositions()`（那会重建缓冲、60fps 下白扔 GC）。
+ */
+function writeDebugSegment(line, ax, ay, az, bx, by, bz, c0, c1, c2, c3, c4, c5) {
+    const attrs = line.geometry.attributes;
+    const pos = attrs.instanceStart.array;
+    pos[0] = ax;
+    pos[1] = ay;
+    pos[2] = az;
+    pos[3] = bx;
+    pos[4] = by;
+    pos[5] = bz;
+    const col = attrs.instanceColorStart.array;
+    col[0] = c0;
+    col[1] = c1;
+    col[2] = c2;
+    col[3] = c3;
+    col[4] = c4;
+    col[5] = c5;
+    attrs.instanceStart.needsUpdate = true;
+    attrs.instanceColorStart.needsUpdate = true;
+}
+/**
+ * 单条碰撞射线 + 其专属辅助线的封装（皇上 2026-09-06 旨：每一条射线都必须拥有一个
+ * 一一对应、且由射线自身数据驱动的辅助线，杜绝「调试线索引与射线索引错位 / 漂移」）。
+ * 继承 THREE.Ray（天然持有 worldOrigin=this.origin、worldDir=this.direction），
+ * 额外携带：局部定义(localOrigin/localDir)、本帧碰撞 far、专属 debugLine、本帧命中/响应态。
+ *
+ * ⭐ 2026-09-21 皇上旨「就在 FPScontrol.ts 加 export」：对外导出以便复用。
+ *   本类**零业务耦合**（只依赖 three 的 Ray / Vector3 / LineSegments2），拿到别处可直接独立使用，
+ *   四步走：`new FpsRay(localOrigin, localDir, debugLine?, isSideRay?)`
+ *          → `updateWorld(yawQuat, worldPos)`（每帧世界化）
+ *          → `applyToRaycaster(raycaster)`（注入碰撞检测）
+ *          → `recordHit(hitPointOrNull, visualFar)`（冻结本帧命中态 + 辅助线起终点）
+ *          → `syncDebugLine()`（写入几何 + 三态配色：红=命中 / 青=探测余量 / 白末端）。
+ *   `debugLine` 由调用方自备：一条**只有 1 段**的 `LineSegments2`（几何由
+ *     `LineSegmentsGeometry.setPositions/setColors` 各给 6 个 float = 起点+终点；
+ *     材质照抄 FPScontrol._createDebugLine：LineMaterial + vertexColors + linewidth(px) +
+ *     depthTest（射线线 true=正常遮挡 / 向量线 false=保持穿透）+ depthWrite:false +
+ *     transparent:true + toneMapped:false + renderOrder:9999）。
+ *   不传 debugLine 也可纯当「带局部定义与命中态的 Ray」用，syncDebugLine 会自动跳过。
+ *
+ * ⚠️ 副作用提醒（皇上已悉，定案保留）：从本模块 import 会执行文件顶层的 three-mesh-bvh 原型补丁
+ *   （`Mesh.prototype.raycast = acceleratedRaycast`）。若哪天只要这个类、不想要该全局补丁，
+ *   需把 FpsRay 搬到独立文件（如 three-base/FpsRay.ts）。
+ */
+export class FpsRay extends Ray {
+    /** 局部定义（随布局冻结，单位就是**世界米**；世界空间 = 跟随 yaw 旋转 + 加玩家位置） */
+    localOrigin;
+    localDir;
+    /** 本帧碰撞 far（由 FPScontrol 按射线类型注入：水平=horizontalFar，下=downFar，上=upFar） */
+    far = 0;
+    /** 专属辅助线（与射线一一对应；懒初始化，未开调试时为 null） */
+    debugLine = null;
+    /** ⭐ 是否为「侧向射线」（±X 直射线，原 6/7）。用于调试线绘制默认隐藏开关（debugHideSideRays）。
+     *   当前「矩形射线法」10 条布局**无侧向射线**，全部 false；若日后加回 ±X 侧向直射线，给那条置 true。
+     *   反向水平斜弦 6-9 不是侧向（是 2-5 的反方向探测），保持 false → 调试线可见（皇上要「看到区别」）。 */
+    isSideRay = false;
+    /** 本帧调试态：是否命中 / 是否真触发碰撞响应（供三态配色） */
+    hit = false;
+    responded = false;
+    /**
+     * 本条线的辅助线是否参与正常深度遮挡（= debugLine 材质的 depthTest）。
+     * 2026-09-25 皇上旨「射线辅助线应该是正常的遮挡状态」→ 10 条射线线全为 true；
+     * 两条回弹向量线按同日定案保持穿透显示（它们不挂在 FpsRay 上）。
+     * 挂在同一 Line 上的 `renderOrder:9999` 不再代表「盖住一切」，故把真值记在这里供核对/回归断言。
+     */
+    depthTestEnabled = false;
+    /** 辅助线起点（命中记录时按本帧 world origin 冻结，避免迭代间 worldPos 漂移） */
+    debugOrigin = new Vector3();
+    /** 辅助线终点：恒 = origin+direction*visualFar 画满（命中点不参与绘制，命中态看颜色） */
+    debugFarPoint = new Vector3();
+    constructor(localOrigin, localDir, debugLine = null, isSideRay = false) {
+        super(localOrigin.clone(), localDir.clone().normalize());
+        this.localOrigin = localOrigin.clone();
+        this.localDir = localDir.clone().normalize();
+        this.debugLine = debugLine;
+        this.isSideRay = isSideRay;
+    }
+    /** 每帧：把局部定义转为世界空间（局部已是米，只需跟随 yaw 旋转 + 加玩家位置） */
+    updateWorld(yawQuat, worldPos) {
+        this.origin.copy(this.localOrigin).applyQuaternion(yawQuat).add(worldPos);
+        this.direction.copy(this.localDir).applyQuaternion(yawQuat).normalize();
+    }
+    /** 把本射线注入射线器（碰撞用） */
+    applyToRaycaster(raycaster) {
+        raycaster.set(this.origin, this.direction);
+        raycaster.far = this.far;
+    }
+    /**
+     * 记录本帧命中态 + 冻结辅助线起终点。
+     * ⚠️ 辅助线**恒按 visualFar 画满**：命中点不参与绘制。
+     *   2026-09-25 皇上两次旨意（先是「下射线一落地就从 1.5 缩到 1.0，看着像射线变短了」，
+     *   后是「拾取到物体后辅助线都变短了」）定案：**长度不再兼职表达命中**，
+     *   命中态只由颜色指示（红 = 命中 / 亮青 = 未命中）。附带好处：菱形包络恒闭合。
+     *   ⚠️ 想让线收在命中点是回退这条口径，动之前先问过皇上。
+     */
+    recordHit(intersetPoint, visualFar) {
+        this.hit = intersetPoint !== null;
+        // 冻结辅助线起点 = 当前 world origin（首轮迭代记录，避免被后续迭代的 worldPos 推离带偏）
+        this.debugOrigin.copy(this.origin);
+        this.debugFarPoint.copy(this.origin).addScaledVector(this.direction, visualFar);
+    }
+    /** 把 debugOrigin→debugFarPoint 写入专属辅助线几何 + 三态配色（红=命中 / 青=探测余量 / 白末端） */
+    syncDebugLine() {
+        const line = this.debugLine;
+        if (!line)
+            return;
+        // ⚠️ 配色与旧 _updateDebugLine 完全一致：命中=红(1,0,0) / 未命中=亮青(0,1,1) / 末端白
+        const r = this.hit ? 1.0 : 0.0;
+        const g = this.hit ? 0.0 : 1.0;
+        const b = this.hit ? 0.0 : 1.0;
+        writeDebugSegment(line, this.debugOrigin.x, this.debugOrigin.y, this.debugOrigin.z, this.debugFarPoint.x, this.debugFarPoint.y, this.debugFarPoint.z, r, g, b, 1.0, 1.0, 1.0);
+    }
 }
-/** 第一/三人称控制器（6 射线 + 迭代推离，userData.fpsCollision 标记碰撞体） */
+/** 第一/三人称控制器（「矩形射线法」10 条射线：4 斜弦 + 0/1 竖向 + 6-9 反向斜弦 + 迭代推离，
+ *  userData.fpsCollision 标记碰撞体）。详见下方 `_localRayOrigins` 上方的「★矩形射线法★」权威规格块。
+ *  ⭐ 射线布局 = 矩形射线法 / Rectangle-Ray Method（皇上 2026-09-06 命名，唯一数据源 = _localRayOrigins/_localRayDirs）：
+ *    0/1 竖向（下/上）+ 2-5 斜弦（菱形，R=1.06，四弦闭合）+ 6-9 反向斜弦（2-5 的反方向、起点 xy 重合、
+ *    比 2-5 再低 0.05m —— 皇上 2026-09-26 五旨定案：HORIZ_FWD_RAY_Y = −0.7m、HORIZ_REVERSE_RAY_Y = −0.75m，
+ *    即离地 0.8m / 0.75m；此前 0 / −0.5 / −0.7 各版均已作废），
+ *    用于反向探测玩家身后墙）。6/7 ±X 侧向与 8-13 共线延长线已于 2026-09-06 精简删除。
+ *    以后说「矩形射线法」即可按规格块精确还原（含冻结常量表 / 10 条逐条表 / 局部→世界变换 / 关键不变量）。 */
 export default class FPScontrol extends EventDispatcher {
     canvas;
     /**
@@ -30,20 +171,47 @@ export default class FPScontrol extends EventDispatcher {
         this.canvas = canvas;
         this.scene = scene;
         this.init(canvas);
+        // 注册到全局表，供 InstancedBatch 异步创建碰撞体后通知重建碰撞列表
+        fpsControlRegistry.add(this);
     }
     // 是否启用
     enable = false;
-    GRAVITY = 30; // 重力
+    /**
+     * 重力加速度。⭐ 皇上 2026-10-03 旨「重力 固定 10m/s 不需要编辑」⇒ 30 → **10**，
+     * 并且从面板旋钮表（PARAM_SPECS）与 meta 右侧表单整条删除，从此不是可调参数。
+     * ⚠️ 跳跃顶点 = jumpSpeed²/(2×GRAVITY)，滞空时间 = 2×jumpSpeed/GRAVITY ⇒ 重力降到 1/3
+     *   等于同一初速度跳得高 3 倍、在空里多待 3 倍（jumpSpeed 的默认值要跟这一点连着看）。
+     */
+    GRAVITY = 10; // 重力（皇上定案：固定 10，不做编辑项 ⇒ readonly，写它编译就报错）
     STEPS_PER_FRAME = 2; // 每帧碰撞计算的次数
     speed = 1; // 速度
     camera;
     // 移动时是否保持惯性 由外部来配置
     inertia = true;
+    // ⭐ 2026-09-06 皇上：跳跃 / 移动惯性 运行时可调（演示面板参数控制）
+    /** 是否允许跳跃（空格触发）。false 时按空格不跳。默认 true */
+    jumpEnabled = true;
+    /** 跳跃初速度（垂直方向，m/s）。
+     *  ⚠️ 2026-09-27 治「跳跃翻墙」：原 15（当时重力 30）→ 顶点 3.75m 远超墙高 2m，跳起后胶囊底越过墙顶
+     *  造成水平失明窗口，人带着水平速度飞越墙平面、落地在墙外侧被越推越远（探针实测 z=-187）。
+     *  定案 8 ⇒ 顶点 1.07m：仍可跳上 0.8m 高台，且 yBottom 恒低于「墙顶 2.0 − 步高 0.1」，
+     *  与主循环竖直门配合后失明窗口彻底消失。**顶点**才是防翻墙的那条线，不是初速度本身。
+     *  ⭐ 2026-10-03 皇上旨「重力固定 10」⇒ 顶点 = jumpSpeed²/20，原 8 会把顶点抬到 3.2m（>墙顶 2m）
+     *  = 09-27 那个翻墙窗口原地复活，所以按「**实测跳跃弧线不变**」倒推出 **5**（5²/20 = 1.25m 理论值，
+     *  实测脚底最高 1.57m 与 8@重力30 同一档；离散积分每帧扣 0.167 + 腾空阻尼，比理论值少约 0.15m）。
+     *  代价：同一顶点高度下滞空时间 0.53s → 1.0s（重力变 1/3 的直接后果，也就是皇上要的手感）。
+     *  调大此值会重新打开翻墙窗口。 */
+    jumpSpeed = 5;
+    /** 惯性关闭（inertia=false）时，每帧水平速度保留率（×0.85 旧值）。越小停得越快。默认 0.85 */
+    inertiaDamp = 0.85;
     // 场景引用（用于射线检测）
     scene;
     // ========== dev / 第三人称 ==========
     // 开发模式：打开后显示射线可视化
     dev = false;
+    // ⚠️ 2026-09-25 退役：原 `debugDownRayProbe` + `_downProbeTick` 独立探针（另一套 console.log）。
+    //   皇上旨「我说的日志就是浏览器的控制台，而不是你来开发一个控制台」→ 下射线数值已并进【碰撞日志】
+    //   的【下射线】段，开关与节流计数随之整条删除。
     // 调试模式相机偏移（本地坐标系，Y=上，Z=后）
     devCameraOffset = new Vector3(0, 2.5, 12.5);
     // 第三人称模式
@@ -57,80 +225,842 @@ export default class FPScontrol extends EventDispatcher {
     // 模式切换检测
     _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
+    //
+    // ⭐⭐ 2026-09-26 皇上旨「把『碰撞包络』『贴墙余量』这些可以去掉的参数都去掉，不要那么复杂」
+    //   → 旧的 `COLLIDE_VOLUME`(cv=0.5) 整条删除。它在最后一次简化（回退搜索改解析推离）之后
+    //     已经**不再决定任何停位**，只剩三件壳：① 斜弦起点写 R/cv、6-9 高度写「局部 × cv」
+    //     （= 一套没人看的中间单位）；② far 的分母；③ 面板上两个看着像旋钮、拧了其实只换尺子的格子。
+    //   ⇒ 现在**全部直接用世界米**：斜弦起点 (±R,0,0)、6-9 起点 (0, 皇上拧的米数, ±R)、
+    //     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），推到最大穿透 ≤ 阈值 / 全脱开为止 —— 停位带与旧的解析解同宽。
+    //   ⇒ 停位仍只由 **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，总位移 ≈ 该子步的穿透深度），
+     *    不会出现「一下子回弹很多」。
+     *    0.25 → 0.1：单次最大穿透从 0.25 降到 0.1，回弹量同比变小（子步数相应上调）。
+     */
+    MAX_STEP_DISTANCE = 0.1;
+    /** 位移细分的最大段数（防止极端速度/长卡顿把一帧切成几百步拖垮帧率） */
+    MAX_STEP_COUNT = 32;
+    // 垂直碰撞范围 = 从 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;
+    // 此处 far = DOWN_RANGE/UP_RANGE + SKIN，响应 = DOWN_RANGE/UP_RANGE − distance
+    //
+    // ⭐⭐ 2026-09-25 皇上旨「把下射线的长度改成 1.5，上射线的长度改成 0.3」→
+    //   我提醒过这一条常量身兼两职（探测长度 + 站位基准），他追选定案「**直接改站位基准**」，
+    //   所以拆成两条各自独立的常量，**不再**共用 VERTICAL_RANGE=1.0：
+    //   · DOWN_RANGE = 1.5：下射线 far = 1.5+SKIN，响应 downPen = 1.5 − distance
+    //     → 落地后**眼睛离地 1.5m**。胶囊脚底在眼下 1.0m ⇒ 站定时脚底离地 **0.5m（悬浮）**。
+    //   · UP_RANGE  = 0.3：上射线 far = 0.3+SKIN，响应 upPen = 0.3 − distance
+    //     → 头顶到面时**眼睛离顶 0.3m**。胶囊顶在眼下 0.35m ⇒ 真顶到矮面时头顶穿入面内 **0.05m**，
+    //       且 0.3~1.0m 之间的低矮障碍物从此探不到（上射线变短的直接后果）。
+    //   ⚠️ 跳跃/重力/台阶吸附的其余口径一字未动，只换这两个基准数。
+    //   ⭐ 2026-09-26 皇上旨「能调节的参数都做滚轮输入框」→ 两条改为公共可写（面板「参数旋钮」可拧），
+    //   但 1.5 / 0.3 仍是皇上定下的**基线**：改公共性 ≠ 改基线，默认值一字未动。
+    DOWN_RANGE = 1.5;
+    UP_RANGE = 0.3;
+    /**
+     * 「脚下到底还有没有地面」的深探长度（2026-09-25，仅用于穿地板自救的判据）。
+     *   竖向两条射线只够得着 下 (DOWN_RANGE+SKIN)=1.52m / 上 (UP_RANGE+SKIN)=0.32m，
+     *   正常跳跃顶点 ≈ jumpSpeed²/(2·GRAVITY) = 5²/20 = 1.25m（实测脚底最高 ≈ 1.5m）
+     *   → 腾空时脚下射线天然全瞎。
+     *   若此时头顶又撞到东西，就分不清
+     *   「跳起来顶到天花板」（该往下压）和「穿过地板掉进无底洞」（该顶出来）。
+     *   判据：往下再问 VOID_PROBE_DOWN 一段，问得到地面 = 正常腾空/下落，问不到 = 已经穿模。
+     *   取 8m ≈ 2 跳多一点；比它更深的地面在 demo 里不存在。
+     */
+    VOID_PROBE_DOWN = 8.0;
+    /**
+     * 竖向两条射线的探测余量（2cm）。⚠️ 它**不是**水平参数：水平侧的「离墙多远」全由 R 决定
+     *   （见上方停位口径），这里只是给「脚底离地 1.5m / 眼离顶 0.3m」两条基准各留一点富余，
+     *   避免落地那一帧量到的距离恰好等于基准 → 判据在阈值上抖动。
+     * 2026-09-26 皇上旨「把贴墙余量这类可以去掉的参数都去掉」→ 名字里「贴墙」的语义已不存在
+     *   （水平不再读它），面板格子一并删除，改私有；数值 0.02 一字未动（竖向已冻结）。
+     */
+    VERTICAL_SKIN = 0.02;
+    /**
+     * ⭐ 皇上 2026-09-06 定案：射线围成的**菱形**（旋转 45° 的正方形）**半对角线 R = 1.06 m**
+     *   → 外接框 **2.12 × 2.12 m**（皇上原话「横向你也改成 2.12m」+「要正方形不要 X 形状」）。
+     *
+     *   ⭐⭐ 菱形的几何约束：**起点外扩量 a 就是半对角线 R，画长 L = R√2**。
+     *       起点 (±a,0,0) + 方向朝内 45° + 长 L → 末端 (a − L/√2, 0, ∓L/√2)
+     *       要末端正好落在顶点 (0,0,∓R) 使四弦**首尾闭合**：a = L/√2 = R。
+     *       ⇒ 起点一旦挪回**玩家中心**（a=0），四弦就从同一点发散 → 变成**X 形状**（皇上否决）。
+     *       ⇒ 要菱形多大，起点就得外扩多少；两者是同一个数。
+     *
+     *   ⚠️ 臣曾误判：以为起点外扩越大，命中点切向偏移越大、回弹方向越歪。
+     *      **实测相反**：R=0.5(旧) 平均偏离 17.89°、R=0(中心) 7.88°、**R=1.06 只有 4.20°**（最准）。
+     *
+     * ⛔⛔ **2026-09-06 19:32 皇上终裁：布局冻结** —— 原话「终于对了，这个布局千万不要改了」。
+     *    当日 21:56 再旨删掉 6/7 两条 ±X 侧向射线；2026-09-25 晚否决「均匀放射 N=12」方案、
+     *    令回退矩形布局（「我最开始用射线组合的矩形，就是最好的方案」）。
+     *    **已验收通过，不得再动**（含 R 本身与射线条数）。皇上未发话前，任何调整——
+     *    哪怕只是「再调大一点」「再精简一条」——都必须**先请旨**。
+     *    （几何上要改大小只动 `CHORD_RHOMBUS_R` 一个数，far = R√2 自动跟着闭合。）
+     *    ⭐ 2026-10-08 皇上旨（明确发话，覆盖本段冻结）：默认 R 改 **0.5**、可调范围放宽到 **[0.2, 1.0]**，
+     *       见下方 `CHORD_RHOMBUS_R` 默认值、`MIN/MAX_HORIZONTAL_RAY_RADIUS` 与 `PARAM_SPECS` 编辑框。
+     */
+    /** 菱形半对角线 R（水平射线半径，单位=世界米）。
+     *  ⭐ 2026-10-08 皇上旨：默认 **0.5**（覆盖 09-06 终裁的 1.06）；运行时可写公共字段，
+     *     走 setHorizontalRayRadius(r) 调整，clamp 到 [0.2, 1.0]（见 MIN/MAX_HORIZONTAL_RAY_RADIUS）。 */
+    CHORD_RHOMBUS_R = 0.5;
+    /**
+     * 6-9 这组「共线反向」射线的起点高度（**世界米**，相对控制器中心；负 = 低于中心）。
+     *
+     * ⭐ 2026-09-26 皇上五道旨（当日反复，全部记录在此，别再拿任意一版当定案）：
+     *   ①「平行的射线往下移动一点」⇒ 与 2-5 重合（0）；②「2 组不要重合，要整体下移」⇒ −0.5；
+     *   ③「平行射线高度 改成 −0.7」⇒ −0.7；④「按面板打印的那份日志参数设初始默认值」⇒ 回 −0.5；
+     *   ⑤**定案：两组 = −0.7（2-5）与 −0.75（6-9）**⇒ 本值 **−0.75m**。
+     *   站定时眼在脚底以上 1.5m ⇒ 2-5 离地 0.8m、6-9 离地 0.75m，两组只差 5cm（皇上旨「不用间隔的太宽」）。
+     *   ⚠️ 副作用（皇上已知）：两组都从「与眼同高」降到胸口/腰，矮桌、栏杆、地毯边、
+     *   低台阶沿都会变成「撞得上的墙」；1.5m 以上只靠 0/1 竖向射线与顶部判定。
+     *   ⚠️ 本字段有**两处**消费：`_localRayOrigins` 初值 + `setHorizontalRayRadius()`（面板「水平射线框」
+     *   滑动条每次拖动都重写 6-9 起点）。只改初值 = 拖一下滑动条就被悄悄改回去，所以两处必须同源。
+     *   旧字段存的是「局部单位」（× cv 才是米），2026-09-26 随 cv 一并废除换算，本字段从此就是米数。
+     */
+    HORIZ_REVERSE_RAY_Y = -0.75;
+    /**
+     * 2-5 这组斜弦的起点高度（**世界米**，相对控制器中心；负 = 低于中心）。
+     *
+     * ⭐ 2026-09-26 皇上问「平行线的高度怎么只有一组可以调」—— 因为这一组此前**没有字段**，
+     *   y=0 直接内联在 `_localRayOrigins[2..5]` 与 `setHorizontalRayRadius()` 两处 = 死值。
+     *   现在补成字段 + 旋钮，与 6-9 对称。
+     *   ⚠️ 同样有**两处**消费（初值 + `setHorizontalRayRadius()`），只改一处就是死旋钮。
+     *   ⭐ 定案见下方 6-9 那条「五道旨」：本值 **−0.7m**（离地 0.8m）。
+     *   ⚠️ 这一改**动了 09-06 终裁布局里「2-5 与眼同高」那条**（皇上 09-26 五旨点名要 −0.7）；
+     *   菱形闭合（R / far=R√2 / 停位距离）与此无关，一字未动。
+     */
+    HORIZ_FWD_RAY_Y = -0.7;
+    /**
+     * ⭐ 2026-09-26 皇上旨「2 组平行射线不用间隔的太宽了，你把能调节的参数都做成滚轮输入框」→
+     *   6-9 那组的高度从此由皇上自己在面板「参数旋钮」里拧，不再由臣定档位。
+     *   参数就是**世界米**（相对控制器中心，负 = 低于中心），字段存什么面板就显示什么。
+     *   ⚠️ 写入口必须**两处同时写**（`_localRayOrigins[6..9]` + `_rays[6..9].localOrigin`），
+     *   少一处 = 拖一下「水平射线框」滑动条就把高度悄悄改回去的死旋钮（皇上多次踩过）。
+     * @param worldY 世界米 y 偏移（相对控制器中心）
+     */
+    setHorizReverseRayY(worldY) {
+        this.HORIZ_REVERSE_RAY_Y = worldY;
+        const r = this.CHORD_RHOMBUS_R;
+        for (let i = 0; i < 4; i++) {
+            const zSign = i < 2 ? -1 : 1; // 6/7 在菱形 −R 顶点，8/9 在 +R 顶点（与 setHorizontalRayRadius 同式）
+            this._localRayOrigins[6 + i].set(0, worldY, zSign * r);
+            this._rays[6 + i].localOrigin.set(0, worldY, zSign * r);
+        }
+    }
+    /**
+     * ⭐ 2026-09-26 皇上旨「平行线的高度怎么只有一组可以调」→ 2-5 那组也做成可拧的，两处写入口同源。
+     * @param worldY 世界米 y 偏移（相对控制器中心）；皇上 09-26 五旨定案默认 −0.75（2-5 是 −0.7）
+     */
+    setHorizFwdRayY(worldY) {
+        this.HORIZ_FWD_RAY_Y = worldY;
+        const signs = [1, -1, -1, 1]; // 与 _localRayOrigins[2..5] 对应（右/左/左/右顶点）
+        for (let i = 0; i < 4; i++) {
+            const x = signs[i] * this.CHORD_RHOMBUS_R;
+            this._localRayOrigins[2 + i].set(x, worldY, 0);
+            this._rays[2 + i].localOrigin.set(x, worldY, 0);
+        }
+    }
+    /**
+     * 水平射线半径 R 的安全下限（⭐ 2026-09-22 补，皇上滑动条可调后暴露）。
+     * **几何事实**：斜弦沿法线的可达距离 = **R**（far = R√2、斜弦 45° → R√2·cos45° = R），
+     * 即 R 就是「玩家中心离墙多远开始判定碰撞」的半径。若 R 小于停位需求，人必须**先陷进墙里**
+     * 才会被射线检测到，随后每帧被位置修正弹回一点 → 皇上所见「侧撞弹很远」。
+     * 探针实测（`tmp/TMP_R_side_effect.mjs`，斜 45° 撞墙角 / 正对单墙同口径）：
+     *   R=0.30 → 停位垂距 **0.2128**（< 胶囊半径 0.35，**明显穿模**）每帧被推 0.040
+     *   R=0.50 → 0.3541（贴到墙面）  每帧 0.036
+     *   R=0.60 → 0.4243（勉强 > 胶囊半径）0.034
+     *   R=0.80 → 0.5448 ✓ / R=1.06 → 0.7247 ✓（每帧修正仅 0.002）
+     * ⇒ 取 **0.6**：保证停位垂距 > 玩家胶囊半径(0.35)，不再穿模。
+     * ⭐ 2026-10-08 皇上旨：下限放宽到 **0.2**、上限收到 **1.0**（编辑框范围 0.2~1.0）。
+     *    ⚠️ R<0.6 仍会贴墙穿模（R=0.5 贴到墙面、R=0.3 明显穿模），皇上按需拧；下限放开是给窄通道/贴墙演示留余地。
+     */
+    static MIN_HORIZONTAL_RAY_RADIUS = 0.2;
+    /** 水平射线半径 R 的安全上限（⭐ 2026-10-08 皇上旨收到 1.0：再大包络远大于停位需求、回弹精度已够，白烧射程） */
+    static MAX_HORIZONTAL_RAY_RADIUS = 1.0;
+    /** 水平射线（斜弦）的 far = R√2 —— 四弦首尾闭合的几何解，随 R 一个数走。 */
+    get HORIZONTAL_FAR() {
+        return this.CHORD_RHOMBUS_R * Math.SQRT2;
+    }
+    /**
+     * 运行时设置水平射线（菱形）半对角线半径 R（单位：世界米）。
+     * 改变后 4 条斜弦起点 x = ±R、4 条反向弦起点 z = ±R **原地更新**
+     *   （同时更新碰撞检测用的 `_localRayOrigins` 与调试线用的 `_rays[i].localOrigin`，两处保持一致）。
+     * ⚠️ R 越大碰撞包络越大、回弹越准（R=1.06 约 4.20°）；R 越小包络越小、贴墙余量越小、回弹偏离越大（R=0.5 旧值约 17.89°）。
+     *   整束水平射线的大小只由此一个数决定（far = R√2 自动跟随，菱形闭合不破）。
+     */
+    setHorizontalRayRadius(r) {
+        // ⭐ 2026-09-22：clamp 到安全区间 —— 越界值会让碰撞包络小于停位需求（贴墙穿模 + 每帧弹回），
+        //   见 MIN_HORIZONTAL_RAY_RADIUS 注释里的实测表。Demo 滑动条 / meta 表单的 min 同取此下限。
+        const clamped = Math.min(FPScontrol.MAX_HORIZONTAL_RAY_RADIUS, Math.max(FPScontrol.MIN_HORIZONTAL_RAY_RADIUS, r));
+        this.CHORD_RHOMBUS_R = clamped;
+        const signs = [1, -1, -1, 1]; // 与 _localRayOrigins[2..5] 对应的 x 符号（右/左/左/右顶点）
+        for (let i = 0; i < 4; i++) {
+            const x = signs[i] * clamped;
+            // 2-5 斜弦：起点 y = HORIZ_FWD_RAY_Y
+            this._localRayOrigins[2 + i].set(x, this.HORIZ_FWD_RAY_Y, 0); // 碰撞检测用（主循环与停位公式都读此数组）
+            this._rays[2 + i].localOrigin.set(x, this.HORIZ_FWD_RAY_Y, 0); // 调试线用（每帧 updateWorld 读 localOrigin）
+            // ⭐ 6-9 共线反向射线（皇上 2026-09-14 改）：起点 = 2-5 终点（菱形内侧顶点），
+            //   6/7 对应 2/3（终点 z=-R）→ local z=-k；8/9 对应 4/5（终点 z=+R）→ local z=+k；
+            //   x=0、y = HORIZ_REVERSE_RAY_Y（皇上 2026-09-26 五旨定案 −0.75，比 2-5 的 −0.7 再低 5cm；
+            //   中途的 −0.5 / −0.7 与旧值 0.2（世界 0.1m）、「归零重合」各版均已作废）。
+            //   与 2-5 共线、方向取反 → 同一直线双向探测。
+            //   ⚠️ 这里重写的是**滑动条路径**：漏改就会让「拖一下 R 就把高度改回去」= 死旋钮。
+            const zSign = i < 2 ? -1 : 1;
+            this._localRayOrigins[6 + i].set(0, this.HORIZ_REVERSE_RAY_Y, zSign * clamped);
+            this._rays[6 + i].localOrigin.set(0, this.HORIZ_REVERSE_RAY_Y, zSign * clamped);
+        }
+    }
+    /**
+     * ⭐⭐ 2026-09-26 皇上旨「2 组平行射线不用间隔的太宽了，你把能调节的参数都给我做的滚轮输入的输入框，
+     *   然后一键打印，把参数打印到控制台」—— 全部可调旋钮的**唯一数据源**。
+     *
+     * 面板「参数旋钮」分组按本表逐行生成滚轮输入框；「打印参数（全量·控制台）」按本表逐行出行；
+     * `setParamValue()` 按本表夹范围并走各自的 `set`（该走 setter 的一个都不能漏，否则又是死旋钮）。
+     *
+     * ⚠️ 表里 `frozen: true` 的行 = 皇上已下旨定死基线（布局冻结 09-06、竖向 09-25、撞墙清零 09-25），
+     *   做成输入框只是让皇上自己能拧，**不代表臣可以改默认值**；默认值一律保持基线原样。
+     */
+    static PARAM_SPECS = [
+        // ===== 射线几何（拧了立刻反映到辅助线上）=====
+        {
+            group: "射线几何",
+            label: "水平射线框 R",
+            key: "CHORD_RHOMBUS_R",
+            min: FPScontrol.MIN_HORIZONTAL_RAY_RADIUS,
+            max: FPScontrol.MAX_HORIZONTAL_RAY_RADIUS,
+            step: 0.01,
+            digits: 2,
+            unit: "m",
+            frozen: true,
+            desc: "菱形半对角线 R，外接框边长 = 2R（= 离墙多远开始判定碰撞的半径）。越大包络越大、回弹方向越准；R<0.6 仍会贴墙穿模（R=0.5 贴墙面、R=0.3 明显穿模），已放宽到 0.2~1.0 供按需拧",
+            get: (fps) => fps.CHORD_RHOMBUS_R,
+            set: (fps, v) => fps.setHorizontalRayRadius(v),
+        },
+        {
+            group: "射线几何",
+            label: "平行射线高度·2-5",
+            key: "HORIZ_FWD_RAY_Y",
+            min: -2.0,
+            max: 2.0,
+            step: 0.05,
+            digits: 2,
+            unit: "m",
+            desc: "2-5 这组（前方/斜弦）射线的起点高度，相对控制器中心、世界米。皇上 09-26 五旨定案 −0.7 = 离地 0.8m（胸/腰之间，不再与眼同高）。与「平行射线高度」那一行相加/相减才是两组的高差。拧它 = 改 2-5 探的是胸口还是腰，矮障碍/高墙的归属会跟着变",
+            set: (fps, v) => fps.setHorizFwdRayY(v),
+        },
+        {
+            group: "射线几何",
+            label: "平行射线高度",
+            key: "HORIZ_REVERSE_RAY_Y",
+            min: -2.0,
+            max: 2.0,
+            step: 0.05,
+            digits: 2,
+            unit: "m",
+            desc: "6-9 那组「平行/共线反向」射线的起点高度，相对控制器中心、世界米。与 2-5 的间隔 = |本值 − 平行射线高度·2-5|；皇上 09-26 五旨定案 −0.75 = 比 2-5（−0.7）再低 5cm、离地 0.75m（「2 组平行射线不用间隔的太宽了」）。越低越先探到身后腰下的矮障碍（矮桌/栏杆/地毯边）",
+            set: (fps, v) => fps.setHorizReverseRayY(v),
+        },
+        {
+            group: "射线几何",
+            label: "下射线长度",
+            key: "DOWN_RANGE",
+            min: 0.5,
+            max: 3,
+            step: 0.05,
+            digits: 2,
+            unit: "m",
+            frozen: true,
+            desc: "落地后眼睛离地的高度（站位基准）。1.5 ⇒ 脚底悬浮 0.5m；改小人会往下沉，改大悬浮更高。⚠️ 皇上 2026-09-25 定案基线，改水平碰撞不许牵连它",
+        },
+        {
+            group: "射线几何",
+            label: "上射线长度",
+            key: "UP_RANGE",
+            min: 0,
+            max: 2,
+            step: 0.05,
+            digits: 2,
+            unit: "m",
+            frozen: true,
+            desc: "头顶到面时「眼睛离顶」的距离。0.3 ⇒ 真顶到矮面时头顶陷入面内 0.05m，且 0.3~1.0m 之间的低矮障碍探不到",
+        },
+        {
+            group: "射线几何",
+            label: "穿地板自救探深",
+            key: "VOID_PROBE_DOWN",
+            min: 2,
+            max: 20,
+            step: 0.5,
+            digits: 1,
+            unit: "m",
+            desc: "腾空时再往下问一段，问不到地面 = 已穿模 → 把人顶回来。比它更深的地面在场景里不存在",
+        },
+        // ===== 回弹与手感（步进 / 预算 / 两条对消阈值）=====
+        {
+            group: "回弹与手感",
+            label: "单步最大位移",
+            key: "MAX_STEP_DISTANCE",
+            min: 0.02,
+            max: 0.4,
+            step: 0.01,
+            digits: 2,
+            unit: "m",
+            desc: "连续碰撞检测把每帧位移切成的最大段长。越小单次穿透越浅、回弹越不「一下子弹很远」，但子步更费。⚠️ 必须明显小于水平包络可达距离 R(默认 1.06)，超过掉帧时会一步跨过墙",
+        },
+        {
+            group: "回弹与手感",
+            label: "一帧最多切几步",
+            key: "MAX_STEP_COUNT",
+            min: 4,
+            max: 64,
+            step: 1,
+            digits: 0,
+            unit: "步",
+            desc: "位移细分的段数上限（防止极端速度/长卡顿把一帧切成几百步拖垮帧率）",
+        },
+        {
+            group: "回弹与手感",
+            label: "每帧碰撞计算次数",
+            key: "STEPS_PER_FRAME",
+            min: 1,
+            max: 4,
+            step: 1,
+            digits: 0,
+            unit: "次",
+            desc: "一帧里跑几遍碰撞+回弹循环。1 最省，4 最贴手但每帧多付三倍查询",
+        },
+        {
+            group: "回弹与手感",
+            label: "每帧迭代预算",
+            key: "MAX_ITERATIONS",
+            min: 10,
+            max: 1000,
+            step: 10,
+            digits: 0,
+            unit: "次",
+            desc: "一帧内全部子步共享的迭代上限（预算烧完即停，宁可贴墙也不空转）。皇上 2026-10-03 旨：不超过 500",
+        },
+        {
+            group: "回弹与手感",
+            label: "单次推离",
+            key: "RETREAT_SKIN",
+            min: 0.005,
+            max: 0.2,
+            step: 0.005,
+            digits: 3,
+            unit: "m",
+            desc: "⭐ 2026-09-28 皇上旨「完完全全用 xsh-react-three 的碰撞法」：每条命中射线每轮沿「命中点→中心」方向推的一小格（xsh 源码里写死 0.03；**皇上 10-07 旨「应该 1 个单位 1 个单位的修正」⇒ 默认改 0.01 = 一格 1cm**）。" +
+                "⚠️ 上限以下别贪小：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: "移动与视角",
+            label: "移动速度",
+            key: "speed",
+            min: 0.2,
+            max: 3,
+            step: 0.05,
+            digits: 2,
+            desc: "第一人称移动速度倍率（面板与右侧表单同一个字段）",
+        },
+        {
+            group: "移动与视角",
+            label: "跳跃初速度",
+            key: "jumpSpeed",
+            min: 1,
+            max: 8,
+            step: 0.2,
+            digits: 1,
+            unit: "m/s",
+            desc: "起跳垂直初速度。⚠️ 重力按皇上 10-03 旨固定为 10（已从旋钮表删除，不可编辑）⇒ 顶点 = 初速度²/20、滞空 = 2×初速度/10。当前 5 ⇒ 顶点 1.25m（实测脚底最高与旧 8@重力30 同一档）。上限锁 8：8 ⇒ 顶点 3.2m 越过墙顶 2m，会重开 09-27 治好的「跳跃翻墙 ⇒ 穿墙」窗口",
+        },
+        {
+            group: "移动与视角",
+            label: "惯性阻尼",
+            key: "inertiaDamp",
+            min: 0.5,
+            max: 0.99,
+            step: 0.01,
+            digits: 2,
+            desc: "「移动惯性」关掉时每帧水平速度保留率，越小松键停得越快",
+        },
+        {
+            group: "移动与视角",
+            label: "第三人称距离",
+            key: "thirdPersonDistance",
+            min: 1,
+            max: 15,
+            step: 0.1,
+            digits: 1,
+            unit: "m",
+            desc: "第三人称相机在玩家身后多远",
+        },
+        {
+            group: "移动与视角",
+            label: "第三人称高度",
+            key: "thirdPersonHeight",
+            min: 0,
+            max: 10,
+            step: 0.1,
+            digits: 1,
+            unit: "m",
+            desc: "第三人称相机高出玩家多少",
+        },
+        {
+            group: "辅助线与预览",
+            label: "辅助线粗细",
+            key: "debugLineWidth",
+            min: 1,
+            max: 8,
+            step: 0.5,
+            digits: 1,
+            unit: "px",
+            desc: "射线辅助线像素宽（只有 LineSegments2 才吃这个值，LineBasicMaterial 会被驱动钳成 1px）",
+        },
+    ];
+    /** 读某个旋钮的当前值（表里没有该 key 时返回 NaN，面板/打印据此跳过，不会崩） */
+    getParamValue(key) {
+        const spec = FPScontrol.PARAM_SPECS.find((s) => s.key === key);
+        if (!spec) {
+            return NaN;
+        }
+        // 旋钮一律按「字段名」存取：表 = 唯一数据源，面板和打印读的是同一个数
+        return spec.get ? spec.get(this) : Number(this[spec.key]);
+    }
+    /**
+     * 写某个旋钮：先夹到 [min,max]，再走该旋钮自己的 `set`（缺省 = 直接写字段）。
+     * @returns 真正落进去的值（夹过之后的），面板拿它回显，避免显示的和实际的两张皮
+     */
+    setParamValue(key, v) {
+        const spec = FPScontrol.PARAM_SPECS.find((s) => s.key === key);
+        if (!spec || !Number.isFinite(v)) {
+            return this.getParamValue(key);
+        }
+        const clamped = Math.min(spec.max, Math.max(spec.min, v));
+        if (spec.set) {
+            spec.set(this, clamped);
+        }
+        else {
+            this[key] = clamped;
+        }
+        return clamped;
+    }
+    // ⚠️ 2026-09-06 21:56 皇上撤旨删除 6/7 侧向射线（±X 直墙改由场景保证/接受穿墙）→ SIDE_FAR_K 一并移除。
+    // ⚠️⚠️ 2026-09-25 皇上旨「向下的射线有陷入地板」→ 原 `DEBUG_RAY_VISUAL_LEN = 1.5` **作废并删除**。
+    //   病根：辅助线起点在脚底上方竖向基准处，却画一个更长的定值 → 线头扎进地板以下，
+    //   而上图那段根本不是射线（射线真实只探到 far）。当年 1.5 是为了让竖线不比斜弦短
+    //   （构图齐平），皇上今日定案改为「**每条线画到自己的真实长度**」：
+    //     · 下 0 → DOWN_RANGE = 1.5，上 1 → UP_RANGE = 0.3（同日再旨拆开的两条基准；
+    //       站定时下射线 distance 恰为 1.5 → 线头正好落在地板面上，不会埋进地板）
+    //     · 水平 2-9 → 画到碰撞 far = horizontalFar = R√2 ≈ 1.4991
+    //   哪日要恢复「竖线比射线长」的观感，得重新请旨，别顺手塞回一个定值。
+    /**
+     * 辅助线粗细（**像素**）。2026-09-25 皇上旨「辅助线能调粗一点」+ 定案 2px。
+     * ⚠️ 这个旋钮只有在 `LineMaterial`（LineSegments2）上才活着：`LineBasicMaterial.linewidth`
+     *   被 WebGL 驱动一律钳成 1px，改大完全无效果。像素宽依赖 `resolution` = 画布 CSS 尺寸，
+     *   已在 _createDebugLine / _syncDebugLineResolution 里跟上。
+     */
+    debugLineWidth = 2;
+    // 按键加速度累加临时量（先整块累加再一次进速度，见 controls()）
+    _accelVec = new Vector3();
+    /**
+     * 本次调用在**模拟位置**上算出的水平弹出总量（= xsh while 收敛所需的推离长度）。
+     * ⭐ 2026-10-02 模拟修正后它不再等于「真实位置陷了多深」—— 真实位置不再先被写进墙里，
+     *   它是「这一步要是真走进去、需要弹多少才干净」的模拟读数。
+     */
+    // 本迭代是否有水平射线命中（用于循环外统一回弹）
+    // ⭐ 2026-09-21 旨「射线命中 = 碰撞 = 立刻做位置修正」：命中即置位，不再要求真穿透。
+    //    安全由**推离量本身**保证：deficit=0（只是贴着）→ dist=0 → 一格都不推，
+    //    不会「没穿透也放行」而一帧推 1.15 穿墙。
+    _horizHit = false;
+    // 缓存本帧的按键输入单位方向（水平）。initPlayerInputDir() 每物理步刷新一次；
+    // 零向量表示「本帧没按方向键」→ 最终方向退化为纯反弹方向。
+    _inputDirVec = new Vector3();
+    /**
+     * 本帧**进碰撞之前**的水平速率（米/秒）。皇上八旨要求「移动向量的长度保持不变」，
+     * 而碰撞会把 `playerVelocity.x/z` 清零，所以必须在 updatePlayer 入口先记一份。
+     */
+    _preCollideHorizSpeed = 0;
+    // ========== 回弹预览（皇上 2026-09-25 旨：「加个开关可以关闭碰撞修正位置的计算，方便观察回弹向量」）==========
+    // 打开后：**不写位置**（见 playerCollisions 末尾唯一的 translate 闸门），但方向/推离量照常算、
+    // 黄→白方向线照常画 → 肉眼核对「算出来的方向对不对」而不被人推开。
+    // ⚠️ 只闸水平+竖向的**位置写入**；削速度、playerOnFloor、事件派发全部保留，
+    //   否则预览模式下重力会一帧帧攒着把人送到地心并触发掉出世界复位。
+    // ⭐⭐ 2026-09-26 皇上七旨「回弹预览开了, 就关不掉」⇒ 本字段改成**带暂存的访问器**：
+    //   开 = 记下当前胶囊位置；关 = **还原**那个位置 + 清掉水平速度。
+    //   病根（实测，墙面板块 x∈[5.0,6.0]、R=1.06）：预览既然不写位置，人就照着自己的
+    //   行走速度（speed=6 ⇒ 终端 37.5m/s ⇒ 每帧 0.62m）一路**穿墙走出去**，120 帧后中心
+    //   已经在 x=138；这一路上只要停在任何一处「两面墙的票互相抵消」的几何里，位置修正就
+    //   再也算不出方向 —— 现场实录：人停在墙板正中 x=5.5，连跑 120 帧每帧都命中、
+    //   deficit 恒为 0.5600、位移 0。看着就是「预览关了位置修正也不回来了」。
+    //   ⇒ 预览是**观察**用的，那一段时间里的位移本来就不作数，关掉即回到打开前那一刻。
+    _previewRetreat = false;
+    /** 开启预览那一刻的胶囊两端（关闭时整体还原回去） */
+    _obsSavedStart = new Vector3();
+    _obsSavedEnd = new Vector3();
+    /** 是否已有可还原的暂存（没进过观察模式就没有，避免构造期赋值把人还原到原点） */
+    _obsHasSave = false;
+    /** 进观察模式（回弹预览 / 单步）：记下当前胶囊位置，退出时还原 */
+    _saveObsPos() {
+        this._obsSavedStart.copy(this.playerCollider.start);
+        this._obsSavedEnd.copy(this.playerCollider.end);
+        this._obsHasSave = true;
+    }
+    /**
+     * 退观察模式：把位置整份还原到进入那一刻，并清掉水平速度。
+     * ⚠️ 只清 x/z（竖向已冻结）：观察模式刻意不削速度 ⇒ 人攒着一身的行走终端速度
+     *   （speed=6 ⇒ 37.5m/s ⇒ 每帧 0.62m），还原位置后若不清掉，下一帧又是一个大跨步再次穿墙。
+     */
+    _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.playerVelocity.x = 0;
+        this.playerVelocity.z = 0;
+        this._obsHasSave = false;
+    }
+    get previewRetreat() {
+        return this._previewRetreat;
+    }
+    set previewRetreat(on) {
+        if (on === this._previewRetreat)
+            return;
+        if (on)
+            this._saveObsPos();
+        else
+            this._restoreObsPos();
+        this._previewRetreat = on;
+    }
+    // ========== 水平位置修正 = 迭代推离（皇上 2026-09-27 十五旨：除反弹方向外**完全照 xsh-react-three**）==========
+    // xsh 的骨架只有一个 while（`FPSControls.tsx` 的 `computerPosition`）：
+    //   ① 在**候选位置**（真实位置 + 已累计的 positionIncremental）上打水平射线
+    //   ② 有命中 ⇒ 沿「离开命中点」的方向推**一小格**（它写死 0.03）并续跑下一轮
+    //   ③ 一轮下来没命中 ⇒ goOnComputer=false ⇒ 收工；整圈上限 = MAX_ITERATIONS（皇上 10-03 旨：500）轮，
+    //     单趟 while 另有「本轮数上限」闸门（常态帧 = ROUNDS_PER_SUBSTEP，皇上 10-07 裁决加，默认 500 同档 ⇒ 不变）
+    //   ④ 循环外**唯一一次** position.add(incremental)
+    // ⇒ 旧的「测试法逐级逼近」（六旨：1 → 0.1 → 0.01 三档、武装/判定/接受/撤销、每帧出水量 ≥
+    //   进水量那套配套保险丝）**整条删除**。位置仍是一格一格挪出去的（皇上要的一步一步看那个形态不变），
+    //   只是格长固定成一档 = 下面这个 RETREAT_SKIN。
+    /**
+     * 每轮迭代沿回弹方向推出去的**固定格长**（米）。
+     * ⭐ 皇上 2026-10-07 旨「这个修正距离一看就不正常，应该 1 个单位 1 个单位的修正」⇒ 默认从 xsh
+     *   源码 `setLength(0.03)` 那个写死的数**改成 0.01**（一次一格 = 1cm）。
+     *   ⚠️ 别往下拧太多：体检台 34 现场实测 0.03 / 0.02 / 0.01 判级完全相同（❌0·⚠️20·✅14），
+     *   拧到 0.005 才有 6 个 ⚠️ 转 ✅，但同一趟「跳跃 + 冲刺 + 掉帧」现场判 **❌穿墙**
+     *   —— 格长就是每帧的出水量，格子越小一帧 500 轮预算能挤出去的总量越小，高速顶墙时抵不过往里挤的位移。
+     */
+    RETREAT_SKIN = 0.01;
+    /**
+     * dev 视图里是否**隐藏**纯 ±X 射线（6/7 侧向，默认 true = 不画）。
+     * ⚠️ 皇上 2026-09-03：这几条从玩家中心左右各伸出，连起来是一根**横贯视野中央**的线，
+     *   是全场最扎眼的一根（原话「中间的横着的那根线不要」）。
+     * ⚠️⚠️ **只是不画，碰撞射线照常发射**——左右方向的探测全靠 6/7（2026-09-06 起延长线已删），
+     *   真删掉侧向墙就要等玩家中心陷进去才被挡住（老 bug 立刻回来）。
+     *   想恢复显示（例如排查侧向碰撞）：本字段置 false。
+     */
+    debugHideSideRays = true;
+    _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() 帧内会调
+    // STEPS_PER_FRAME(2) × 位移细分(≤32) ≈ 最多 64 次——墙角处若每次都跑满，理论上限
+    // 6400 迭代 × 8 射线 ≈ 5 万次射线求交/帧，这才是「墙角偶尔卡住」的真凶（循环个数多，
+    // 不是单个循环跑太多）。改为整帧共享预算：一帧内全部子步合计最多迭代 MAX_ITERATIONS(500)
+    // 次；每个子步仍保证至少 1 次迭代（推离不能整次跳过，否则穿墙）。
+    _frameIterBudget = 500;
     // 临时四元数（复用避免 GC）
     _tempQuat = new Quaternion();
     // 射线检测器
     _raycaster = new Raycaster();
+    // 脚下深探（_floorBelow，穿地板自救）专用检测器（**不可**复用 _raycaster：调用方正在同一实例上逐射线取命中）
+    _probeRaycaster = new Raycaster();
     // 临时向量（复用避免 GC）
-    _tempVec = new Vector3();
-    _tempVec2 = new Vector3();
     _tempVec3 = new Vector3();
+    // xsh 移植（2026-09-28）：候选位置（= 控制器位置 + positionIncremental，射线原点锚）
+    //   与推离向量专用临时量（复用避免 GC）
+    _candPos = new Vector3();
+    _corrVec = new Vector3();
     _tempVec4 = new Vector3();
-    // ========== 射线定义（完全参考 xsh-react-three FPSControls.tsx 的 render 方法）==========
-    // 射线定义在局部空间，通过 Group3D(rotation={x: -euler.x}) 补偿 pitch
-    // 即射线只跟随 yaw 旋转，不跟随 pitch 俯仰
+    // 位移细分用的临时向量（与 playerCollisions 内的 _tempVec4 分开，避免被覆盖）
+    _tempVec5 = new Vector3();
+    /**
+     * ⭐⭐ 2026-10-02 皇上旨「在修正位置的时候，我希望的是**模拟修正**，而不是**真实的修正**，
+     *   在模拟修正中把最终结果计算好了，再应用到真实的第一人称控制器上面」。
+     * 本小步（位移细分的一份）**尚未写进真实位置**的位移：playerCollisions 先在
+     *   「真实位置 + 本位移」的**模拟位置**上跑 xsh 的 while，算出干净落点后，
+     *   才由那唯一一次 translate 落到真实控制器上（见 playerCollisions 末尾）。
+     *   ⇒ 真实位置不再「先走进墙里 0.04m，再被弹出来 0.06m」= 一个渲染帧两趟来回甩 = 超级抖。
+     * 消费掉（落地）后归零，所以面板那颗直接调 playerCollisions 的按钮不会重复走一步。
+     */
+    _subStep = new Vector3();
+    /** 模拟算完之后本小步真正写进真实位置的那一份（本步位移 + 最终修正）= 唯一一次 translate */
+    _appliedMove = new Vector3();
+    _wallQuat = new Quaternion();
+    // 消速度专用：把面法线从实例局部空间变换到世界空间时，需要算上 instanceMatrix 的旋转/缩放（逆转置）
+    _wallMat3 = new Matrix3();
+    _wallMatrix4 = new Matrix4();
+    // 竖向射线判「命中面朝上还是朝下」用的世界法线（见 _faceNormalWorldY）
+    _vertNormal = new Vector3();
+    // ========== 射线布局（唯一数据源 = 下方 `_localRayOrigins` / `_localRayDirs`） ==========
+    // 射线定义在局部空间，只跟随 yaw 旋转、不跟随 pitch 俯仰（对应 Group3D(rotation={x:-euler.x}) 补偿）。
+    // ⚠️ 局部坐标的单位**就是世界米**（2026-09-26 起）。此前要先 × COLLIDE_VOLUME 换算成米，
+    //    那个参数连同面板格子一并删除；R / 6-9 高度 / far 的**物理数值一个没变**。
     //
-    // 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}
+    // 布局沿革（勿凭记忆重建，逐条清单见下方「★ 矩形射线法 ★」规格块与 CHORD_RHOMBUS_R 的终裁注释）：
+    //   · 源自 xsh-react-three 的 6 条（4 斜弦 + 上下竖向）；斜弦起点外扩到 ±R → 四弦首尾闭合成**菱形**。
+    //   · 曾扩到 14 条（±X 侧向 + 共线延长线）去补 reach，2026-09-06 皇上终裁精简为 8 条水平 + 2 条竖向。
+    //   · 「均匀放射 N=12」方案皇上当场否决并令回退：「我最开始用射线组合的矩形，就是最好的方案」。
+    //   · 防穿墙的判据只有一个：**沿法线 reach > MAX_STEP_DISTANCE**（现行最小 R/√2 = 0.749 > 0.1，富余 7 倍）。
+    //     停位不需要 reach 探得到 —— 那是命中之后由解析推离顶出来的。
+    //   · 反例（只针对均匀放射，不是本布局的问题）：起点外扩到**包络圆周**上，玩家陷墙时起点已越过墙面
+    //     → 朝外射永远打不到墙 → 深穿透失明。本布局斜弦起点在 z=0 中心平面、反向弦落在菱形顶点，天生没这个坑。
     //
-    // 局部空间射线起点（索引 0-5）
+    // ════════════════════════════════════════════════════════════════════════════
+    // ★ 矩形射线法 / Rectangle-Ray Method（皇上 2026-09-06 命名 · 权威布局规格）
+    // ═════════════════════════════════════════════════════════════════════════════
+    // ⚠️ 以后若碰撞布局被改坏，只说「矩形射线法」→ AI 按本块精确还原（不要凭记忆重建）。
+    //   本块是唯一数据源：改动射线只改下方 `_localRayOrigins` / `_localRayDirs`（务必等长），
+    //   `this._rays`（FpsRay[]）与每条专属调试线自动跟随，不可能错位。
+    //
+    // 一、冻结常量（逐字还原值；单位一律**世界米**）
+    //   CHORD_RHOMBUS_R      = 1.06   菱形半对角线 R（水平射线半径）
+    //   水平 far             = R√2 ≈ 1.4991（getter HORIZONTAL_FAR，随 R 自动重算 → 菱形闭合不破）
+    //   HORIZ_FWD_RAY_Y      = −0.7   2-5 起点高度（相对控制器中心；皇上 09-26 五旨定案，离地 0.8m）
+    //   HORIZ_REVERSE_RAY_Y  = −0.75  6-9 起点高度（比 2-5 再低 5cm，离地 0.75m；「不用间隔太宽」）
+    //   DOWN_RANGE = 1.5 / UP_RANGE = 0.3；竖向 far 各再 + VERTICAL_SKIN(0.02) 探测余量
+    //   辅助线绘制长度        竖向 = DOWN_RANGE(1.5)/UP_RANGE(0.3)、水平 = 本条 far
+    //                         （= 射线自身长度，皇上 2026-09-25 定案；原 DEBUG_RAY_VISUAL_LEN=1.5 已作废删除）
+    //   GRAVITY = 10（皇上 2026-10-03 旨：固定 10、不做编辑项；原 30）
+    //   jumpSpeed = 5（按「实测跳跃弧线不变」随重力倒推：5²/20 = 1.25m；历史 15 → 8 → 5）
+    //   inertia = true   inertiaDamp = 0.85
+    //   ⚠️ 2026-09-26 已删除：`COLLIDE_VOLUME`、水平侧的 `COLLIDE_SKIN`、`HORIZONTAL_FAR_K`。
+    //      它们只服务于「局部单位 × cv 才是米」这套中间换算，删掉后几何数值一字未动。
+    //
+    // 二、10 条射线逐条表（localOrigin 单位=米，运行时只跟随 yaw + 加玩家位置）
+    //   idx  origin(米)              dir(单位向量)            far          角色
+    //   0    (0,0,0)                (0,-1,0)             downFar(=DOWN_RANGE+SKIN)  竖向·下（踩地）
+    //   1    (0,0,0)                (0,+1,0)             upFar(=UP_RANGE+SKIN)       竖向·上（顶头）
+    //   2    (R, −0.7, 0)           (-1,0,-1)→归一       R√2  斜弦·右顶点→左前
+    //   3    (-R,−0.7, 0)           (+1,0,-1)→归一       R√2  斜弦·左顶点→右前
+    //   4    (-R,−0.7, 0)           (+1,0,+1)→归一       R√2  斜弦·左顶点→右后
+    //   5    (R, −0.7, 0)           (-1,0,+1)→归一       R√2  斜弦·右顶点→左后
+    //   6    (0, −0.75, −R)         (+1,0,+1)→归一       R√2  共线反向·2（=2 终点→起点）
+    //   7    (0, −0.75, −R)         (-1,0,+1)→归一       R√2  共线反向·3（=3 终点→起点）
+    //   8    (0, −0.75, +R)         (-1,0,-1)→归一       R√2  共线反向·4（=4 终点→起点）
+    //   9    (0, −0.75, +R)         (+1,0,-1)→归一       R√2  共线反向·5（=5 终点→起点）
+    //   ⭐ 6-9 = 2-5 的**共线反向**射线（皇上 2026-09-14 改：原「起点重合朝外分叉」被否，改为真·重合）：
+    //      起点 = 2-5 各自的**终点**（菱形内侧顶点 (0,0,∓R)），方向与 2-5 严格取反，
+    //      → 与 2-5 **共线、同一直线、但再低 5cm**（y = HORIZ_FWD_RAY_Y = −0.7 / HORIZ_REVERSE_RAY_Y = −0.75，
+    //        皇上 2026-09-26 五旨「两组 = −0.7 和 −0.75」⇒ 站定时离地 0.8m / 0.75m）。
+    //        历史上 y 曾取世界 0.1m（2026-09-14，肉眼区分）→ 09-26 归零重合 → −0.5 → 三旨 −0.7 → 四旨回 −0.5 → 五旨 −0.7/−0.75。
+    //        用于「同一直线双向探测」玩家两侧墙。R = CHORD_RHOMBUS_R = 1.06。
+    //
+    // 三、局部→世界变换（FpsRay.updateWorld，每帧）
+    //   worldOrigin    = localOrigin · yawQuat + playerWorldPos
+    //   worldDirection = localDir · yawQuat（归一化）
+    //
+    // 四、关键不变量（还原后必须仍满足，否则布局被破坏）
+    //   · 菱形闭合：四斜弦末端落在 (0,0,±R)，外接框 2.12×2.12；far 恒 = R√2
+    //   · 沿法线 reach = R·max(|n·右|, |n·前|) ∈ [R/√2, R] = 0.749~1.06 > MAX_STEP_DISTANCE(0.1) → 不穿墙
+    //   · 回弹方向口径：normalize(Σ_i normalize(控制器中心−碰撞点_i))（水平、等权）
+    //   · 6-9 反向射线 isSideRay = false（可见，不与已删除的 6/7 侧向历史混淆）
+    // ═════════════════════════════════════════════════════════════════════════════
+    // ⭐ 射线定义即唯一数据源：下方 `this._rays`（FpsRay[]）由本数组 map 生成，
+    //   每条 FpsRay 自带 world 空间 origin/direction（每帧 updateWorld）与专属 debugLine，
+    //   增减射线只需改本数组（与 _localRayDirs 务必等长），`this._rays` 自动跟随、调试线一一对应。
     _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 起点（右侧）
+        // ⭐ 2026-09-06 皇上旨「横向你也改成 2.12m」「不是正方形，是 X 形状」：
+        //   斜弦起点 = **±CHORD_RHOMBUS_R(1.06) 米**（局部就是米，不再 ×cv 换算）。
+        //   四条弦首尾相接，围成外接框 **2.12×2.12 的菱形**。
+        //   ⚠️ 臣曾把起点挪回玩家中心 (0,0,0) —— 四弦变成从**同一点**发散的 **X**，被皇上否决。
+        //      **菱形的半对角线 R 就是起点外扩量**，要够大就必须外扩，不能回中心。
+        //   ✅ 实测（tmp/fps_rhombus_shape_ab.mjs）：八方位停位一致、speed 20 不穿墙、薄墙 0.1m 不穿、
+        //      夹缝正常；**回弹方向平均偏离 4.20°**（比中心的 7.88° 更准）。
+        new Vector3(this.CHORD_RHOMBUS_R, this.HORIZ_FWD_RAY_Y, 0), // 2: 斜弦起点（菱形右顶点）
+        new Vector3(-this.CHORD_RHOMBUS_R, this.HORIZ_FWD_RAY_Y, 0), // 3: 斜弦起点（菱形左顶点）
+        new Vector3(-this.CHORD_RHOMBUS_R, this.HORIZ_FWD_RAY_Y, 0), // 4: 斜弦起点（菱形左顶点）
+        new Vector3(this.CHORD_RHOMBUS_R, this.HORIZ_FWD_RAY_Y, 0), // 5: 斜弦起点（菱形右顶点）
+        // ⭐ 矩形射线法·反向探测（皇上 2026-09-06 加）：6-9 = 2-5 的反方向射线，
+        //   方向取反 → 探测玩家身后的墙。自动参与碰撞检测（主循环 ri=2..length）且可见（isSideRay=false）。
+        // ⭐ 共线反向（皇上 2026-09-14 改）：6-9 起点 = 2-5 终点（菱形内侧顶点），方向取反 → 与 2-5 共线。
+        //   2026-09-26 皇上旨「平行的射线往下移动一点」→ 先归零与 2-5 同高；同日再旨「2 组射线不要重合在一起了,
+        //   要整体下移」⇒ −0.5；三旨「改成 −0.7」；四旨「按面板日志定初始值」⇒ 回 −0.5；
+        //   五旨（定案）「两组 = −0.7 和 −0.75」⇒ y = HORIZ_FWD_RAY_Y −0.7 / HORIZ_REVERSE_RAY_Y −0.75（四条一起降）。
+        new Vector3(0, this.HORIZ_REVERSE_RAY_Y, -this.CHORD_RHOMBUS_R), // 6: 共线反向·2（终点(0,0,-R)→右顶点）
+        new Vector3(0, this.HORIZ_REVERSE_RAY_Y, -this.CHORD_RHOMBUS_R), // 7: 共线反向·3（终点(0,0,-R)→左顶点）
+        new Vector3(0, this.HORIZ_REVERSE_RAY_Y, this.CHORD_RHOMBUS_R), // 8: 共线反向·4（终点(0,0,+R)→左顶点）
+        new Vector3(0, this.HORIZ_REVERSE_RAY_Y, this.CHORD_RHOMBUS_R), // 9: 共线反向·5（终点(0,0,+R)→右顶点）
     ];
-    // 局部空间射线方向（对应 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（左后方）
+        new Vector3(-1, 0, -1).normalize(), // 2: 右顶点→左前
+        new Vector3(1, 0, -1).normalize(), // 3: 左顶点→右前
+        new Vector3(1, 0, 1).normalize(), // 4: 左顶点→右后
+        new Vector3(-1, 0, 1).normalize(), // 5: 右顶点→左后
+        // ⭐ 矩形射线法·共线反向（皇上 2026-09-14 改）：6-9 = 2-5 严格取反，起点改为 2-5 终点（菱形内侧顶点），与 2-5 共线同一直线（见 _localRayOrigins）
+        new Vector3(1, 0, 1).normalize(), // 6: 反向·2（右顶点→右后）
+        new Vector3(-1, 0, 1).normalize(), // 7: 反向·3（左顶点→左后）
+        new Vector3(-1, 0, -1).normalize(), // 8: 反向·4（左顶点→左前）
+        new Vector3(1, 0, -1).normalize(), // 9: 反向·5（右顶点→右前）
     ];
-    // 世界空间射线起点（复用避免 GC）
-    _worldRayOrigins = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
-    // 世界空间射线方向（复用避免 GC）
-    _worldRayDirs = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
+    // ⭐ 每条射线一个 FpsRay 封装：局部定义 + 每帧 world 空间 + 本帧 far + 专属辅助线。
+    //   world 空间 origin/direction 由 FpsRay.updateWorld 每帧重算（不再单独维护 _worldRayOrigins/_worldRayDirs），
+    //   辅助线由 FpsRay.debugLine 一对一持有 → 杜绝「调试线索引与射线索引错位 / 漂移」。
+    _rays = this._localRayOrigins.map((origin, i) => new FpsRay(origin, this._localRayDirs[i]));
     // userData.fpsCollision === true 的碰撞体列表
     _colliders = [];
     // 缓存标记：场景变化时才重建碰撞体列表
     _collidersDirty = true;
     _colliderSceneVersion = 0;
+    /**
+     * 把命中面的法线变换到**世界空间**（含 InstancedMesh 的实例旋转/缩放；
+     * 非均匀缩放下必须用 3×3 逆转置，不能直接 applyMatrix3）。
+     * ⚠️ 原样返回：不抹平 y、不归一化、不翻向 —— 都由调用方按需处理。
+     * ⚠️ 只用 _wallQuat/_wallMatrix4/_wallMat3 这三个专用临时量，可安全嵌套调用其它射线流程。
+     * @returns false = 无 face 或法线是零向量（调用方须自行兜底）
+     */
+    _transformFaceNormalWorld(interset, outN) {
+        if (!interset.face)
+            return false;
+        outN.copy(interset.face.normal);
+        // 1) object 自身世界旋转（InstancedMesh 整体；对普通 Mesh 就是它自己的旋转）
+        interset.object.getWorldQuaternion(this._wallQuat);
+        outN.applyQuaternion(this._wallQuat);
+        // 2) 若是 InstancedMesh，再叠加上该实例的旋转/缩放
+        const obj = interset.object;
+        if (obj.isInstancedMesh && interset.instanceId !== undefined) {
+            const mesh = interset.object;
+            mesh.getMatrixAt(interset.instanceId, this._wallMatrix4);
+            const e = this._wallMatrix4.elements;
+            // instanceMatrix 是列主序 4×4，左上 3×3 转成行主序 Matrix3
+            this._wallMat3.set(e[0], e[4], e[8], e[1], e[5], e[9], e[2], e[6], e[10]);
+            this._wallMat3.invert().transpose(); // 逆转置 = 正确法线变换
+            outN.applyMatrix3(this._wallMat3);
+        }
+        return outN.lengthSq() > 1e-12;
+    }
+    /**
+     * ⭐ 2026-09-27 射线为主方案恢复（与 HEAD 旧射线口径一字不差，内部复用 _transformFaceNormalWorld）：
+     *   解析一个射线命中点的「墙法线」与「沿法线的垂距」。
+     * @param worldPos 玩家中心（本子步候选位置）
+     * @param interset 射线命中点
+     * @param pushDir 输出「命中点→玩家」的水平推离向量（未归一化；退化时被换成 fallbackDir）
+     * @param outN 输出「指向玩家一侧」的单位水平墙面法线（退化时同样有效）
+     * @param fallbackDir 射线反方向（已水平归一化），退化（命中点≈玩家中心）时兜底推离方向
+     * @returns 垂距 perpDist（≥0）。退化时返回 0（视为最深穿透），并置 _perpDegenerate
+     */
+    /**
+     * 竖向（上/下）射线专用：取命中面**世界法线的 y 分量**（已归一化）。
+     *   > 0 = 朝上的面（可行走顶面，如 Ground1 地板、箱体顶面）
+     *   < 0 = 朝下的面（天花板 / 箱体底面）
+     * @returns null = 拿不到法线（无 face 或零向量）→ 调用方按「维持旧行为」处理
+     */
+    _faceNormalWorldY(interset) {
+        const n = this._vertNormal;
+        if (!this._transformFaceNormalWorld(interset, n))
+            return null;
+        return n.normalize().y;
+    }
+    /**
+     * 脚下深探：往下问 VOID_PROBE_DOWN 这么长一段，有没有地面（2026-09-25，穿地板自救用）。
+     * @returns true = 下方有地面 → 只是正常腾空/下落，不是穿模
+     */
+    _floorBelow(worldPos) {
+        this._probeRaycaster.ray.origin.copy(worldPos);
+        this._probeRaycaster.ray.direction.set(0, -1, 0);
+        this._probeRaycaster.far = this.VOID_PROBE_DOWN;
+        return this._probeRaycaster.intersectObjects(this._colliders, false).length > 0;
+    }
+    /**
+     * ⭐⭐ 刷新本帧的**按键输入方向**（水平单位向量）—— 皇上 2026-09-21 旨：
+     *   「移动方向」取**按键输入方向**（WASD 相对相机），用于与回弹方向相加。
+     * 算法与 `controls()` 里的加速度合成**同源**（同用 getForwardVector / getSideVector），
+     *   保证「输入方向」与「实际加速方向」严格一致（不会因两处各写一遍而漂移）。
+     * ⚠️ 与 `controls()` 的区别：这里**只要方向**，不乘 speedDelta、不进速度 ——
+     *   取的是「玩家意图往哪走」这个纯方向。
+     * 无按键 / 前后或左右互相抵消 → 零向量（调用方据此退化为纯回弹方向）。
+     * 每物理步调用一次（在 `playerCollisions` 入口）。
+     */
+    _refreshInputDir() {
+        this._inputDirVec.set(0, 0, 0);
+        if (this.keyStates["KeyW"])
+            this._inputDirVec.add(this.getForwardVector());
+        if (this.keyStates["KeyS"])
+            this._inputDirVec.sub(this.getForwardVector());
+        if (this.keyStates["KeyA"])
+            this._inputDirVec.sub(this.getSideVector());
+        if (this.keyStates["KeyD"])
+            this._inputDirVec.add(this.getSideVector());
+        // 只取水平分量：回弹方向恒在水平面内，混入 y 会让两者相加后偏离水平面
+        this._inputDirVec.y = 0;
+        if (this._inputDirVec.lengthSq() > 1e-8)
+            this._inputDirVec.normalize();
+        else
+            this._inputDirVec.set(0, 0, 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;
+        this.scene.traverseVisible((child) => {
+            if (child instanceof Mesh && child.userData?.fpsCollision) {
+                const geo = child.geometry;
                 if (geo && !geo.boundsTree && geo.attributes.position?.count > 0) {
                     computeBoundsTree.apply(geo);
                 }
-                this._colliders.push(obj);
+                // ⚠️ InstancedMesh 的包围球必须强制重算：three 只在 boundingSphere === null 时才计算，
+                // 而它首次被计算时 count 往往还是 0（模板异步加载），算出的是「空球」radius = -1，
+                // 之后实例数量/矩阵变化都不会刷新 → raycast 的包围球剔除永远失败 → 碰撞与点击全部失效。
+                if (child instanceof InstancedMesh) {
+                    child.boundingSphere = null;
+                }
+                this._colliders.push(child);
             }
         });
         this._collidersDirty = false;
@@ -139,6 +1069,22 @@ export default class FPScontrol extends EventDispatcher {
     markCollidersDirty() {
         this._collidersDirty = true;
     }
+    /** 通知所有已创建的 FPScontrol 重新收集碰撞体（InstancedBatch 异步创建碰撞 InstancedMesh 后调用） */
+    static markAllCollidersDirty() {
+        for (const c of fpsControlRegistry) {
+            c.markCollidersDirty();
+        }
+    }
+    /** 复位玩家到指定世界坐标（默认原点），清空速度；第一人称 demo 的"回到起点"用得到 */
+    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);
+        // ⭐ 复位 = 换现场 ⇒ 把相机/胶囊位置基准挪到新位置。
+    }
     // 玩家胶囊碰撞体
     playerCollider = new Capsule(new Vector3(0, 0.35, 0), new Vector3(0, 1, 0), 0.35);
     // 时钟对象
@@ -154,65 +1100,103 @@ export default class FPScontrol extends EventDispatcher {
     isMousedown = false;
     keyStates = {};
     // ========== 射线可视化 ==========
+    // ⭐ 每条射线（this._rays[i]）自带一条专属辅助线 ray.debugLine；
     _debugRayGroup = null;
-    // 6 条调试线段：0-3 水平射线，4 向下射线，5 向上射线
-    _debugLines = [];
-    // 懒初始化调试射线组
+    /** 全部调试线的材质（含 10 条射线线），只为统一同步 `resolution`（粗细按像素算，必须知道画布尺寸） */
+    _debugLineMats = [];
+    // 懒初始化调试射线组（每条 FpsRay 一条专属线）
     _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._rays 一一对应，杜绝索引错位）
+        //    射线线 = 开深度测试（正常遮挡，皇上 2026-09-25）
+        for (const ray of this._rays) {
+            const line = this._createDebugLine(true);
+            ray.debugLine = line;
+            // 材质真值抄到射线上（线对象上没有这个概念，断言/核对只看材质要 cast）
+            ray.depthTestEnabled = line.material.depthTest === true;
             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;
-    }
-    // 销毁调试射线
+    /**
+     * 创建一条标准调试线（几何/材质统一，debugLine 复用）；不被射线检测命中。
+     * @param depthTest 是否参与正常深度遮挡 —— **两种口径按皇上 2026-09-25 逐条定案**：
+     *   - 射线辅助线（10 条）= **true**：「射线辅助线 / 下射线的辅助线应该是正常的遮挡状态」。
+     *     旧值 false + renderOrder:9999 是当年为治 2026-09-03「贴地辅助线被地面挡掉看不见」而定，
+     *     代价是穿透一切浮在最前 —— 下射线画满 1.5 后埋进地里那半截被直接画在地板之上，
+     *     就是皇上所见「像没开深度测试」。能挡住它们的前提：地面 Ground1 已是不透明且
+     *     `depthWrite:true`（three-base/Ground1/Ground1.ts:107）；哪天地板改回
+     *     transparent + depthWrite:false，射线线会重新穿地浮出来。
+     *   - 回弹方向线（黄→白）= **false**：「回弹向量线保持穿透显示」。
+     *     它是「本帧要看的向量」，起点在胶囊内部、方向常指着墙里，开遮挡会被自己的身子
+     *     或墙面吃掉半截 → 观察目的直接落空，故保持常显在最前。
+     */
+    _createDebugLine(depthTest) {
+        // 一条线 = 一段（2 端点）。LineSegmentsGeometry 用实例属性存段，先塞 6 个 0 占位，
+        // 之后每帧只改数组（见 writeDebugSegment），不重复建缓冲。
+        const geo = new LineSegmentsGeometry();
+        geo.setPositions(new Float32Array(6));
+        geo.setColors(new Float32Array(6));
+        const mat = new LineMaterial({
+            vertexColors: true,
+            // ⭐ 2026-09-25 皇上旨「辅助线调粗一点」+ 定案 2px：`linewidth` 在 LineMaterial 里
+            //   是**真的像素宽**（shader 铺 quad），不像 LineBasicMaterial 被驱动钳成 1px。
+            linewidth: this.debugLineWidth,
+            depthTest,
+            // 关深度写入：调试线只可见、不参与后续深度/后处理重建，避免被当背景
+            depthWrite: false,
+            // 进透明队列：renderOrder 9999 让它排在场景几何之后画（亮色也不被 alpha 混合削淡）
+            transparent: true,
+            // 后处理链下不走色调映射，避免亮色被压暗
+            toneMapped: false,
+        });
+        // resolution 必须等于画布 CSS 尺寸，否则像素宽会按 1×1 折算 = 粗到糊满屏幕。
+        // 尺寸变化由 _syncDebugLineResolution() 每帧跟上。
+        mat.resolution.set(this._canvasCssWidth(), this._canvasCssHeight());
+        this._debugLineMats.push(mat);
+        const line = new LineSegments2(geo, mat);
+        // 让调试线段不被射线检测命中
+        line.raycast = () => { };
+        line.frustumCulled = false;
+        // 同队列内的绘制先后。⚠️ 它不再等于「盖住一切」——是否被挡住由上面的 depthTest 说话。
+        line.renderOrder = 9999;
+        return line;
+    }
+    /** 画布 CSS 宽（LineMaterial 的像素宽按它折算；DOM 缺席时兜 1，绝不喂 NaN/0） */
+    _canvasCssWidth() {
+        return this.canvas?.clientWidth || 1;
+    }
+    /** 画布 CSS 高，口径同 _canvasCssWidth */
+    _canvasCssHeight() {
+        return this.canvas?.clientHeight || 1;
+    }
+    /** 把画布当前尺寸同步进所有调试线材质（resize / 改粗细都要走一次） */
+    _syncDebugLineResolution() {
+        const w = this._canvasCssWidth();
+        const h = this._canvasCssHeight();
+        for (const mat of this._debugLineMats) {
+            if (mat.resolution.x !== w || mat.resolution.y !== h)
+                mat.resolution.set(w, h);
+            if (mat.linewidth !== this.debugLineWidth)
+                mat.linewidth = this.debugLineWidth;
+        }
+    }
+    // 销毁调试射线（遍历每条射线自己的 debugLine + 2 条回弹线）
     _disposeDebugLines() {
         if (!this._debugRayGroup)
             return;
-        for (const line of this._debugLines) {
-            line.geometry.dispose();
-            line.material.dispose();
+        for (const ray of this._rays) {
+            const line = ray.debugLine;
+            if (line) {
+                line.geometry.dispose();
+                line.material.dispose();
+                ray.debugLine = null;
+            }
         }
-        this._debugLines = [];
+        this._debugLineMats.length = 0;
         this.scene.remove(this._debugRayGroup);
         this._debugRayGroup = null;
     }
@@ -223,9 +1207,20 @@ export default class FPScontrol extends EventDispatcher {
         canvas.addEventListener("pointerdown", this.mousedown);
         document.addEventListener("pointerup", this.mouseup);
         document.body.addEventListener("pointermove", this.mousemove);
-        this.enable = true;
+        // ⚠️ 不要在这里把 enable 置 true：enable 的语义是「由调用方显式开启」。
+        // 字段默认 false（见上方声明），调用方需自行 fps.enable = true 才驱动物理/相机。
+        // 否则默认即开启会让「不希望 FPS 接管相机」的场景（如主页用 OrbitControls）被迫再写一行 false 抵消。
     }
     keydown = (event) => {
+        // ⭐ 2026-09-26 皇上旨「参数做成滚轮输入的输入框」连带补的一条：
+        //   焦点在输入框里时按键不该再驱动人物（空格起跳、W/S 前后窜），
+        //   否则「一改参数人就乱动」。keyup 不拦：只放行不清会让按键卡在 true。
+        const t = event.target;
+        if (t &&
+            (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.tagName === "SELECT" ||
+                t.isContentEditable)) {
+            return;
+        }
         this.keyStates[event.code] = true;
     };
     keyup = (event) => {
@@ -243,7 +1238,8 @@ export default class FPScontrol extends EventDispatcher {
             if (this.thirdPerson) {
                 // 第三人称：旋转轨道角
                 this._thirdPersonAngleY -= event.movementX / 500;
-                this._thirdPersonAngleX -= event.movementY / 500;
+                // 俯仰与第一人称同向：鼠标下移 → 视角下压 → 相机升高俯视（故用 +=）
+                this._thirdPersonAngleX += event.movementY / 500;
                 this._thirdPersonAngleX = clamp(this._thirdPersonAngleX, degToRad(-89), degToRad(89));
             }
             else {
@@ -254,10 +1250,13 @@ export default class FPScontrol extends EventDispatcher {
         }
     };
     // 获取前进的向量
+    // ⚠️ 第三人称必须取「远离相机的方向」，与相机轨道偏移（见 updatePlayer）严格互为反向：
+    // 相机偏移 = +(sin(a), ·, cos(a))·dist，故前进 = -(sin(a), 0, cos(a)) = (-sin a, 0, -cos a)。
+    // 写成 +(sin, cos) 会让 W 键把玩家推向镜头（视觉上"前进像后退"），即"方向反了"的 bug。
     getForwardVector = () => {
         if (this.thirdPerson) {
-            // 第三人称：前进 = 轨道偏航方向
-            this.playerDirection.set(Math.sin(this._thirdPersonAngleY), 0, Math.cos(this._thirdPersonAngleY));
+            // 第三人称：前进 = 轨道偏航方向（相机在身后，故取轨道偏移的反方向）
+            this.playerDirection.set(-Math.sin(this._thirdPersonAngleY), 0, -Math.cos(this._thirdPersonAngleY));
             return this.playerDirection;
         }
         this.camera.getWorldDirection(this.playerDirection);
@@ -281,31 +1280,39 @@ export default class FPScontrol extends EventDispatcher {
     // 玩家移动控制器
     controls = (deltaTime) => {
         const speedDelta = deltaTime * (this.playerOnFloor ? 25 : 8) * this.speed;
+        // ⭐ 2026-09-26 皇上旨「碰撞就是按射线拾取算的，不用搞太复杂」：
+        //   旧的「接触法线缓存 + 加速度保速投影」整块删除 —— 撞墙的手感由位置侧负责
+        //   （命中即 playerVelocity.x/z = 0，再走迭代推格修正位置，皇上 2026-09-25 定案）。
+        //   ⭐ 2026-09-26 皇上八旨给这条加了个尾巴：位置修正判完之后，若本帧算出了方向且没和
+        //   输入方向对消，水平速度会整条换成 normalize(输入 + 回弹) × 碰撞前速率（贴墙不再走不动），
+        //   见 playerCollisions 末尾那段。清零本身照旧。
+        const accel = this._accelVec.set(0, 0, 0);
         if (this.keyStates["KeyW"]) {
-            this.playerVelocity.add(this.getForwardVector().multiplyScalar(speedDelta));
+            accel.addScaledVector(this.getForwardVector(), speedDelta);
         }
         if (this.keyStates["KeyS"]) {
-            this.playerVelocity.add(this.getForwardVector().multiplyScalar(-speedDelta));
+            accel.addScaledVector(this.getForwardVector(), -speedDelta);
         }
         if (this.keyStates["KeyA"]) {
-            this.playerVelocity.add(this.getSideVector().multiplyScalar(-speedDelta));
+            accel.addScaledVector(this.getSideVector(), -speedDelta);
         }
         if (this.keyStates["KeyD"]) {
-            this.playerVelocity.add(this.getSideVector().multiplyScalar(speedDelta));
+            accel.addScaledVector(this.getSideVector(), speedDelta);
         }
+        this.playerVelocity.add(accel);
         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;
+                this.playerVelocity.x *= this.inertiaDamp;
+                this.playerVelocity.z *= this.inertiaDamp;
             }
         }
-        if (this.playerOnFloor) {
+        if (this.playerOnFloor && this.jumpEnabled) {
             if (this.keyStates["Space"]) {
-                this.playerVelocity.y = 15;
+                this.playerVelocity.y = this.jumpSpeed;
                 this.jumping = true;
                 this.dispatchEvent({ type: "jump_start" });
             }
@@ -319,9 +1326,25 @@ export default class FPScontrol extends EventDispatcher {
             damping *= 0.1;
         }
         this.playerVelocity.addScaledVector(this.playerVelocity, damping);
-        const deltaPosition = this.playerVelocity.clone().multiplyScalar(deltaTime);
-        this.playerCollider.translate(deltaPosition);
-        this.playerCollisions();
+        // ⭐ 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）→ 直接跨过墙体（穿墙）。
+        const deltaPosition = this._tempVec5.copy(this.playerVelocity).multiplyScalar(deltaTime);
+        const stepCount = Math.min(this.MAX_STEP_COUNT, Math.max(1, Math.ceil(deltaPosition.length() / this.MAX_STEP_DISTANCE)));
+        deltaPosition.divideScalar(stepCount);
+        for (let s = 0; s < stepCount; s++) {
+            // ⭐⭐ 2026-10-02 皇上旨「模拟修正，不是真实修正」：**这里不再 translate 真实位置**。
+            //   本小步的位移交给 playerCollisions，在「真实位置 + 本位移」的模拟位置上把 xsh 的
+            //   while 跑完（含循环内的竖向读数），由它末尾唯一一次 translate 落地。
+            //   旧写法 = 先 translate 进墙 0.039m 再被修正弹出来 0.06m，一个渲染帧两趟 ⇒ 肉眼「超级抖」
+            //   （皇上 2026-10-02 台账：③位移折返 24 次 / ⑤单条位移峰 0.0565m / pen=corr=0.0600 恒等）。
+            this._subStep.copy(deltaPosition);
+            // 只有最后一步记录调试射线 + 分发移动/落地事件（细分只是碰撞中间过程，不应重复派发）
+            this.playerCollisions(s === stepCount - 1);
+        }
         // 设置相机位置（第一人称默认值）
         this.camera.position.copy(this.playerCollider.end);
         // 第三人称：偏移相机位置 + 朝向第一人称坐标
@@ -347,106 +1370,137 @@ export default class FPScontrol extends EventDispatcher {
         }
         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-react-three FPSControls.tsx 的 computerPosition 方法）
+     * @param isFinalStep 是否为位移细分的最后一步：
+     *   只有最后一步才记录调试射线数据、分发移动/跳跃落地事件，中间小步只做推离。
+     */
+    // 与 xsh-react-three 的对应关系（本地实现逐条对照）：
+    //   xsh: position prop → _localRayOrigins（本地已直接用米，不再 ×cv）
+    //   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
     //
-    // 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() {
+    // 现行 10 条布局逐条表 = 上方「★ 矩形射线法 ★」权威规格块（唯一数据源，不在这里重复一遍）。
+    /** 输出一条碰撞日志（唯一出口 = 浏览器控制台；皇上：「日志就是浏览器的控制台」） */
+    /** 第一人称碰撞主入口：xsh `computerPosition` 移植的迭代推离主循环。 */
+    playerCollisions(isFinalStep = true) {
         this.playerOnFloor = false;
         this._getColliders();
+        // ⭐⭐⭐ 2026-09-28 皇上旨（原话）：「你还是完完全全使用 xsh-react-three 项目里面的
+        //   第一人称控制器的碰撞计算的方法吧」。
+        //   ⇒ 本方法整体 = 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 各票天然抵消）；
+        //     ③ 下射线命中 ⇒ 竖直速度清零 + y 钉到「命中面之上 DOWN_RANGE」（xsh: cv − distance）；
+        //        上射线命中 ⇒ 竖直速度清零 + 修正（含三道闸天花板的血案守卫）；
+        //     ④ 某一轮全部射线脱开 ⇒ 收工；循环外唯一一次 translate 落地（血案护栏不变）。
+        //   ⭐⭐ 2026-10-02 皇上旨「模拟修正，不是真实修正，把最终结果算好了再应用到真实的第一人称
+        //     控制器上面」⇒ 那个 translate 落的是**「本步位移 + 允许的修正」一次到位**：
+        //     while 全程跑在模拟位置（真实 end + `_subStep` + 增量）上，真实 collider 在此之前**一动不动**
+        //     （旧写法先把它 translate 进墙里再由修正弹出来 ⇒ 一帧两趟来回甩 = 「超级抖」）。
+        //     ⭐ 10-02 同日曾加过「真实落地只许弹本步朝墙挤进的那一份」的上限 ⇒ **实测穿墙、当场作废**，
+        //     代码已整条删除（详见循环末尾那一段的实录，禁止复活护栏在 AI_INDEX.md 登记）。
+        //   与 xsh 的必要偏差（均为已验收修复，非自作主张）：
+        //     · 水平修正压平 y —— xsh 水平射线在中心高度（y=0）修正天然水平；
+        //       本布局射线在 y=−0.7/−0.75（皇上 09-26 五旨），不压平会把 y 混进推离；
+        //     · 水平射线 8 条（皇上 09-06/09-14 亲加的 6-9 共线反向组），xsh 原版 4 条；
+        //     · 竖向保留 faceUp / 天花板三道闸守卫（「掉出世界」血案修复）。
+        //   原 deficit / 票面合成(finalDir) / 逐格推离 / 白推保险丝 / 胶囊兜底机器整条拆除。
         const positionIncremental = this._tempVec4.set(0, 0, 0);
-        const collideVolume = this.COLLIDE_VOLUME;
-        const verticalRange = this.VERTICAL_RANGE;
+        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;
+        const downRange = this.DOWN_RANGE;
+        const upRange = this.UP_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) {
+        while (goOnComputer && (i === 0 || this._frameIterBudget > 0)) {
+            // ⚠️ 整帧共享预算（皇上 09-03「碰撞计算次数不超过 100」→ 10-03 旨改到 500）：每个子步保证至少 1 轮。
+            if (i > 0)
+                this._frameIterBudget--;
             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();
+            // xsh: object3d.getWorldPosition() —— 修正方向的锚点（循环内不变，不含增量）
+            // ⭐ 2026-10-02 模拟修正：真实 collider 此刻**还没被本步位移推过**，
+            //   所以锚点 = 真实位置 + 本步位移 =「这一步走完会站在哪儿」的**模拟位置**
+            //   （数值上与旧写法「先 translate 再取 end」完全相同 ⇒ 几何、方向、测试基线都不变）。
+            const basePos = this._tempVec3.copy(this.playerCollider.end).add(this._subStep);
+            // xsh: 射线原点 = 控制器位置 + positionIncremental（getIntersetResult(incremental) 语义）
+            const worldPos = this._candPos.copy(basePos).add(positionIncremental);
+            // xsh: Group3D rotation={x:-euler.x} 补偿 pitch → 只跟随 yaw
+            const yawQuat = this._tempQuat.setFromEuler(this._tempEuler.set(0, this.camera.rotation.y, 0, "YXZ"));
+            for (const ray of this._rays) {
+                ray.updateWorld(yawQuat, worldPos);
             }
-            // 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 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 原样：每条命中射线各推一小格）==========
+            for (let ri = 2; ri < this._rays.length; ri++) {
+                const ray = this._rays[ri];
+                ray.far = horizontalFar;
+                ray.applyToRaycaster(this._raycaster);
                 const intersets = this._raycaster.intersectObjects(this._colliders, false);
-                // 调试：第一次迭代记录射线数据
                 if (!debugRecorded) {
-                    const hasHit = intersets.length > 0;
-                    let closestDist = Infinity;
+                    // ⭐ 铁律（09-05 定案）：辅助线指示真实探测方向——命中画到最近命中点、未命中画满 far
                     let intersetPoint = null;
-                    if (hasHit) {
+                    if (intersets.length > 0) {
+                        let closestDist = Infinity;
                         for (const int of intersets) {
-                            const d = int.point.distanceTo(worldPos);
+                            const d = int.point.distanceTo(basePos);
                             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,
-                    };
+                    ray.recordHit(intersetPoint, horizontalFar);
                 }
-                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];
-                            }
-                        }
+                if (intersets.length === 0)
+                    continue;
+                // 最近命中（xsh: 离控制器位置最近的那个交点）
+                let interset = intersets[0];
+                for (let j = 1; j < intersets.length; j++) {
+                    if (intersets[j].point.distanceTo(basePos) < interset.point.distanceTo(basePos)) {
+                        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 旨「每执行一次，偏移量是多少」⇒ 按钮那一次：一格一行，带累计
                     }
-                    // 与 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;
+            const downRay = this._rays[0];
+            downRay.far = downFar;
+            downRay.applyToRaycaster(this._raycaster);
             let downIntersets = this._raycaster.intersectObjects(this._colliders, false);
             // 调试：记录向下射线
             if (!debugRecorded) {
@@ -462,13 +1516,9 @@ export default class FPScontrol extends EventDispatcher {
                         }
                     }
                 }
-                devRayData[0] = {
-                    origin: this._worldRayOrigins[0].clone(),
-                    farPoint: hasHit
-                        ? intersetPoint.clone()
-                        : this._worldRayOrigins[0].clone().addScaledVector(this._worldRayDirs[0], downFar),
-                    hit: hasHit,
-                };
+                // ⭐ 2026-09-25 皇上两条旨：竖向线命中不缩短、也不许往地板里多画 → 画到下射线自身长度
+                downRay.recordHit(intersetPoint, devVisualFarD);
+                downRay.responded = hasHit;
             }
             if (downIntersets.length > 0) {
                 let interset = downIntersets[0];
@@ -479,91 +1529,206 @@ export default class FPScontrol extends EventDispatcher {
                         }
                     }
                 }
-                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;
-                        }
+                const downPen = downRange - interset.distance;
+                // ⭐⭐ 2026-09-25 皇上旨「顶出来，不穿模」：命中面朝向决定这份修正能不能吃。
+                //   downPen > 0 = 面在脚底之上 = 脚底陷进地面 → 顶出来（原有行为，保留）。
+                //   downPen < 0 = 面在脚底之下 = 原有的「吸附到地面」(下楼梯/斜坡不悬空) ——
+                //   但只有**朝上的可行走面**才许吸：脚下是一块「朝下的面」（板底，或从实体
+                //   内部看到的底面）时吸下去 = 直接把人流送进板子里，从此两条竖射线全瞎。
+                const faceUp = (this._faceNormalWorldY(interset) ?? 1) > 0;
+                if (downPen >= 0 || faceUp) {
+                    this.playerVelocity.y = 0;
+                    positionIncremental.y += downPen;
+                    this.playerOnFloor = true;
+                    // ⚠️ 皇上：脚下踩实时 downPen≈0（玩家刚好停在距地 downRange 处），
+                    // 若无条件置 goOnComputer=true，while 循环会每帧跑满 MAX_ITERATIONS 次
+                    // （每次都重新检测到地面、再置 true）→ 站地面时碰撞开销暴涨 ~MAX_ITERATIONS×，FPS 骤降、
+                    // 鼠标视角卡顿；起跳离地后脚下射线不命中、循环 1 次即退出 → 反而流畅。
+                    // 只有「真实发生了有意义的垂直修正」才需要重跑循环重新校验水平碰撞。
+                    // （向上射线早就有 `if (upPen > 0)` 这层保护，唯独向下射线漏了 → 这就是根因。）
+                    if (Math.abs(downPen) > 1e-4) {
+                        goOnComputer = true;
                     }
                 }
-                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];
+                // ⭐ 2026-09-25 皇上旨「我说的日志就是浏览器的控制台，不是你开发一个控制台」：
+                //   原来这段是独立 console.log 探针（自带节流），现改为**只备料**，
+                //   文本并进下方【碰撞日志】同一次输出里 → 皇上抄一次就同时拿到水平方向 + 下射线全部数值。
+                //   ⚠️ 取样闸门 = `i === 1`（本帧第一次迭代；`i++` 在循环体最前面，故日志头「迭代轮次」首轮印 1）。
+                //     **不能**沿用旧探针的 `!debugRecorded`：`debugRecorded = !recordDebug`，而 `recordDebug`
+                //     跟着面板「碰撞射线」(dev) 走 → dev 关着时恒 true → 整段被跳过，
+                //     这正是皇上「在控制台里根本看不到下射线数值」的原因。
+                // ========== 向上射线（索引 1 = dwomToUpRay）==========
+                const upRay = this._rays[1];
+                upRay.far = upFar;
+                upRay.applyToRaycaster(this._raycaster);
+                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;
+                            }
                         }
                     }
+                    upRay.recordHit(intersetPoint, devVisualFarU);
+                    upRay.responded = hasHit;
+                    debugRecorded = true;
                 }
-                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;
+                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];
+                            }
+                        }
+                    }
+                    // 按距离解算（与下射线一致）：头顶离天花板 interset.distance，需保持 upRange → 下推 (upRange - distance)
+                    const upPen = upRange - interset.distance;
+                    if (upPen > 0 && downIntersets.length === 0
+                        && this.playerVelocity.y <= 0 && !this._floorBelow(worldPos)) {
+                        // ⭐⭐ 2026-09-25 皇上旨「顶出来，不穿模」（「下射线会陷入地面很长一个距离」的正解）
+                        //   上射线打到东西、**脚下却没有任何地面**、且人不正在往上蹿 → 我已经在这块面的
+                        //   下方/内部，再往下顶就是把它当「天花板」往下钻 = 死亡路径：
+                        //   实测脚底 −1.5 起手（1m 厚地板，tmp/TMP_vert_trace.mjs）——
+                        //   前 10 帧人在板内、FrontSide 看不到背面 → 上下射线全瞎 → 重力累加上坠；
+                        //   第 11 帧眼落到板底之下 0.0135，上射线打到**板底（法线朝下）**，旧口径
+                        //   `positionIncremental.y -= upPen` 一帧把人往下砸 **0.9865m** → 眼落到 −2.0，
+                        //   从此两条竖射线彻底够不着 → 自由落体到 **−13.161547** → 撞上 camera.y≤−10 的
+                        //   掉出世界复位（`this.playerCollider.end.set(0, 1, 10)`）→ 「陷进地面很长一段
+                        //   距离然后凭空回到原点」。这就是皇上看到的现象。
+                        //   新口径：**绝不往下顶**，一步顶到「脚底刚好落在这块面之上」（眼高 = 面 y +
+                        //   downRange + SKIN）。顶完眼只比板底高一个 SKIN → 下一轮迭代下射线立刻
+                        //   看得到板顶（distance≈SKIN）→ downPen≈downRange 把人整段托上板面站稳，
+                        //   上下射线互为 backup，全程 ≤ 十几帧、不再掉出世界。
+                        //   ⚠️ 三道闸缺一不可：
+                        //     · `downIntersets.length===0`：站在下层地板上、头顶真天花板时，往下鸭/躲矮洞
+                        //       是正确行为，不能把人吸到上层去；
+                        //     · `playerVelocity.y <= 0`：正往上跳、头顶撞到真天花板必须仍按普通天花板往下顶，
+                        //       否则「跳一下 → 被传上天花板」；
+                        //     · `!_floorBelow()`：竖向射线只够 downFar(1.52)/upFar(0.32)，而跳跃顶点 ≈1.06m 加上
+                        //       脚底悬浮 0.5m 已经超出下射线够得着的范围 →
+                        //       腾空时脚下本来就是瞎的，只靠上面两道闸会把「高空跳到天花板下方」也误判成穿模。往下深探
+                        //       VOID_PROBE_DOWN(8m) 问得到地面 = 正常腾空/下落 → 维持旧的天花板下压。
+                        //   ⚠️ 已知残留（实测 tmp/TMP_ceiling_ab.mjs ⑦）：板**厚度 > DOWN_RANGE(1.5m)** 时，
+                        //     顶到「板底之上」后人仍在板内 → 再次全瞎下坠 → 在板底往复。
+                        //     HEAD 版同一场景是「掉到 −10.9 → 凭空复位」，现在收敛为有界往复（不再掉出世界），
+                        //     彻底根治要加**背面探针**（FrontSide 看不到内部，量不到板顶）。
+                        this.playerVelocity.y = 0;
+                        const liftTo = interset.point.y + downRange + this.VERTICAL_SKIN - worldPos.y;
+                        if (liftTo > 1e-4) {
+                            positionIncremental.y += liftTo;
+                            this.playerOnFloor = true;
+                            goOnComputer = true;
+                        }
+                    }
+                    else if (upPen > 0) {
+                        this.playerVelocity.y = 0;
+                        positionIncremental.y -= upPen;
+                        goOnComputer = true;
+                    }
                 }
-                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);
+            // ========== 更新调试射线（dev 模式的最后一步）==========
+            if (recordDebug) {
+                this._initDebugLines();
+                // 像素宽依赖画布尺寸：resize / 改 debugLineWidth 都在这里跟上
+                this._syncDebugLineResolution();
+                // ⭐ 每条 FpsRay 自带 debugLine，直接 syncDebugLine（起点/终点由 ray.recordHit 冻结，
+                //    三态配色由 ray.syncDebugLine 写入）。射线与辅助线一一对应，不可能再错位。
+                for (let di = 0; di < this._rays.length; di++) {
+                    // ⚠️ 皇上 2026-09-03：横贯中央的 ±X 侧向射线默认不画（debugHideSideRays 开关）。
+                    //    （原 6/7 侧向已删；当前 6-9 是反向水平斜弦，isSideRay=false → 不受本开关影响，可见。
+                    //     皇上要「看到区别」→ 反向射线必须画出来。）若日后加回 ±X 侧向直射线，给那条 isSideRay 置 true 即自动隐藏。
+                    if (this.debugHideSideRays && this._rays[di].isSideRay)
+                        continue;
+                    const ray = this._rays[di];
+                    if (ray.debugLine)
+                        ray.syncDebugLine();
                 }
             }
+            // 应用推离
+            // ⚠️⚠️ 这一段**只能出现一次**（2026-09-21 血案：重构时误插入第二份，
+            //   位置推离量直接翻倍 → 陷 0.42m 被推 0.84m、垂距冲到 0.94（该停在 0.52）
+            //   → 皇上看到的「从侧面撞墙角一下子弹很远」）。改动本文件时务必确认
+            //   `positionIncremental` 全文件只被 `translate` 应用一次。
+            // ⭐⭐ 2026-09-25 皇上旨「加个开关可以关闭碰撞修正位置的计算，方便观察回弹向量」：
+            //   唯一的**位置写入口**就是这一行 → 在这一个闸门上关，才是真的「不修正位置」。
+            //   原先 `previewRetreat`（面板「回弹预览」）只跳过了上方 `!previewRetreat` 那个**水平**
+            //   修正块，竖向（下射线 `y += downPen` / 上射线 `y ± upPen`）照样从这里落地 →
+            //   标签写着「不修正位置」却仍在被顶，且陷进地面时每轮迭代累加一份 downPen，
+            //   预览模式下人被竖直弹飞。
+            //   ⚠️ 只跳「写位置」，不跳「记账」：`playerVelocity.y = 0`、`playerOnFloor = true`
+            //     与削速度/方向票全部保留 → 观察时不会一帧帧攒重力陷到地心，也不会触发
+            //     camera.y ≤ −10 的掉出世界复位。
         }
-        // 应用推离
-        if (positionIncremental.lengthSq() > 0) {
-            this.playerCollider.translate(positionIncremental);
+        // ⭐⭐ 2026-10-02 皇上旨（原话）：「在修正位置的时候，我希望的是**模拟修正**，而不是**真实的
+        //   修正**，在模拟修正中把最终结果计算好了，再应用到真实的第一人称控制器上面」。
+        //   ⇒ 上面那个 while 全在**模拟位置**（真实位置 + 本步位移 `_subStep`）上跑；真实 collider
+        //     在 while 期间**一动不动**，只在下面那**唯一一次** translate 上落到「本步位移 + 算好的
+        //     最终修正」。旧写法每小帧先 translate 进墙 0.04m、再被弹出来 0.06m ⇒ 一个渲染帧两趟。
+        //   ⚠️⚠️ 10-02 同日实测作废的那条「把弹出扣在本步挤进量以内」上限（cap = inward + 欠账）
+        //     **不许复活**：模拟算出的修正方向会在一小步之间换向（墙角 / 8 条斜弦 / 高速子步），
+        //     「每步沿自己的方向净位移 ≤ 0」加起来 = 沿着墙往几何体里漂。体检台实测：40 号
+        //     「跳跃+冲刺+掉帧」被扣住的弹出累计 3.12m ⇒ 人穿到墙背面，末位 x 从 3.9 跑到 162
+        //     ⇒ ❌穿墙红线（HEAD 基线 ❌0）。模拟位置是**保证脱开**的，全额落地才不会陷进去。
+        //   ⚠️ 竖向（y）一律真实落地 —— 皇上 2026-09-25 冻结，本段一个 y 都不改口径。
+        let corrX = positionIncremental.x;
+        let corrZ = positionIncremental.z;
+        let corrY = positionIncremental.y;
+        if (this.previewRetreat) {
+            // 「回弹预览」= 只走路、任何修正都不落地（连竖向都不落，2026-09-25 定的：
+            //   陷地面时每轮累加一份 downPen 会把人竖直弹飞）。
+            corrX = 0;
+            corrZ = 0;
+            corrY = 0;
         }
-        // 事件分发
-        if (this.jumping && !this.prePlayerOnFloor && this.playerOnFloor) {
-            this.jumping = false;
-            this.dispatchEvent({ type: "jump_end" });
+        // ⚠️⚠️ 全文件**唯一**的水平位置写入口（2026-09-21 血案：误插第二份 ⇒ 推离量翻倍 ⇒
+        //   陷 0.42m 被推 0.84m ⇒ 「从侧面撞墙角一下子弹很远」）。
+        //   模拟算完 → 本步位移 + 允许的修正 → 一次应用到真实控制器（皇上 10-02 旨）。
+        //   ⚠️ 本步位移在这里一起落地：走路从旧 updatePlayer 循环外的 translate 挪到了这一行，
+        //     位移永远照走（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);
         }
-        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" });
+        // 本步已消费：归零，面板那两颗直接调 playerCollisions 的按钮不会重复走一步
+        this._subStep.set(0, 0, 0);
+        // ⭐⭐ 2026-10-07 皇上旨「撞到墙后，加速度置为 0」：
+        //   抖动根因 = 撞墙后位置被推回包络边，但 playerVelocity 的水平分量（朝墙的冲量）一直保留，
+        //   下一帧 controls() 又叠加输入加速度 → 再次朝墙冲 → 再次被推回 → 来回甩 = 肉眼抖动。
+        //   ⇒ 本子步水平命中（_horizHit）即把 playerVelocity.x/z 清零：人贴墙即停，
+        //     不再被惯性反复往墙里拽、被推离反复弹回。（观察模式：单步/回弹预览不改速度，
+        //     免得不落地的观察帧把速度抹掉、干扰手感判断；竖向 y 一字不动——重力/跳跃照旧。）
+        if (this._horizHit && !this.previewRetreat) {
+            this.playerVelocity.x = 0;
+            this.playerVelocity.z = 0;
         }
-        else if (Math.abs(preX + preZ) > 0.1 && Math.abs(x + z) < 0.1) {
-            this.dispatchEvent({ type: "move_end" });
+        // ⭐ 十旨：一帧一条的抖动台账。**只由子步循环的最后一步（isFinalStep）记** ——
+        //   中间小步是碰撞细分的过渡状态，记了就变成「一帧好几条」，翻向/跳变的口径全乱。
+        // 事件分发（只在位移细分的最后一步执行，避免一次移动派发多组 move_start/move_end）
+        if (isFinalStep) {
+            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;
         }
-        this.prePlayerVelocity.copy(this.playerVelocity);
-        this.prePlayerOnFloor = this.playerOnFloor;
     }
     // 越界传送
     teleportPlayerIfOob = () => {
@@ -589,6 +1754,8 @@ export default class FPScontrol extends EventDispatcher {
                 this.camera.rotation.x = this._thirdPersonAngleX;
             }
             this._prevThirdPerson = this.thirdPerson;
+            // 每帧重置碰撞迭代预算（整帧共享，见 _frameIterBudget 注释）
+            this._frameIterBudget = this.MAX_ITERATIONS;
             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);
@@ -596,17 +1763,32 @@ export default class FPScontrol extends EventDispatcher {
                 this.teleportPlayerIfOob();
             }
         }
-        // dev 模式关闭时隐藏调试射线
-        if (!this.dev && this._debugRayGroup && this._debugRayGroup.visible) {
-            this._debugRayGroup.visible = false;
+        // 调试射线可见性：dev / 第三人称 任一开启即把整组放出来（碰撞射线跟随 dev / 第三人称）。
+        const showRays = this.dev || this.thirdPerson;
+        if (this._debugRayGroup && this._debugRayGroup.visible !== showRays) {
+            this._debugRayGroup.visible = showRays;
         }
-        else if (this.dev && this._debugRayGroup && !this._debugRayGroup.visible) {
-            this._debugRayGroup.visible = true;
+        if (this._debugRayGroup && this._rays.length > 0 && this._rays[0].debugLine) {
+            const showBase = this.dev || this.thirdPerson;
+            // ⭐ 射线辅助线可见性直接遍历 this._rays（与射线一一对应）
+            for (let di = 0; di < this._rays.length; di++) {
+                // ⚠️ 皇上 2026-09-03：原 ±X 侧向射线（ri=6/7）默认不画（太扎眼）。
+                //    ⚠️ 只改**可见性**，射线本身照常发射 —— 见 debugHideSideRays 注释，别去删射线。
+                //    现 di 最大=9（6-9 是反向水平斜弦，isSideRay=false → 不受本开关影响，可见）；
+                //    若日后加回 ±X 侧向直射线，给那条 isSideRay=true 即自动隐藏（与 L1750 守卫一致）。
+                const dl = this._rays[di].debugLine;
+                if (dl)
+                    dl.visible = showBase && !(this.debugHideSideRays && this._rays[di].isSideRay);
+            }
+            // 方向线的显示由 playerCollisions 里「本帧是否真算出回弹方向」决定，这里不再覆盖
         }
+        // 诊断日志已撤（皇上 2026-09-03）：[FPS-TP]/[FPS-CAM] 属当年第三人称排查的一次性诊断，
+        // 链路已验证正常；射线辅助线（画面可见）仍保留，仅去掉 console 输出。
     }
     // 销毁事件
     disposer() {
         this.enable = false;
+        fpsControlRegistry.delete(this);
         document.removeEventListener("keydown", this.keydown);
         document.removeEventListener("keyup", this.keyup);
         this.canvas.removeEventListener("pointerdown", this.mousedown);