three-base 2.0.142 → 2.0.166

package/collisionOBB.js

@@ -1,112 +1,112 @@
-/**
- * capsuleVsOBB —— 竖直胶囊（第一人称角色）vs 有向包围盒（OBB）的精确穿透查询
- *
- * ⭐ 为什么是这套：玩家胶囊在 FPS 里是**竖直**的（start/end 的 x/z 相同，仅 y 不同），
- *   于是「胶囊 vs OBB」可精确化简为：
- *     · 水平面（XZ）= 一个点（胶囊中心水平投影）到 OBB 的 2D 最近距离；
- *     · 竖直（Y）= 胶囊竖直区间 [yBottom, yTop] 与 OBB 竖直区间是否重叠。
- *   这比「线段 vs box 通用最近点」更精确（box 是平面，法线恒定），
- *   也比「10 条射线模拟体积」物理正确且不抖（射线没有体积，贴墙必漏检）。
- *
- * ⭐ 一次调用得：穿透深度 depth（>0 即碰撞）+ 指向玩家的单位法线 normal + 碰撞体最近点 contact。
- *   位置修正 = 沿 normal 推出 depth（解析解，非贪心搜索）；速度修正 = 滑墙投影 v -= (v·n)n。
- *
- * 零依赖：只用 three 的 Vector3 / Quaternion（标量运算，任何环境可跑）。
- */
-import { Vector3, Quaternion } from "three";
-/**
- * ⭐ 穿透噪声门（2026-09-27 探针实测）：深度 ≤ 此值视为**未碰撞**。
- *   玩家停在「恰好贴合」位（如夹缝 = 胶囊直径）时，浮点残差会产生 ±1e-6 量级的
- *   微穿透 —— 不门掉的话，贴合面会以随机符号反复登记投票，回弹方向被钉死在
- *   某一面（实测：0.7m 夹缝里方向恒 +X 朝深墙）。真穿透都是毫米级以上，不受影响。
- */
-export const CAPSULE_DEPTH_EPS = 1e-4;
-// 复用的临时量（避免每帧 GC）
-const _local = new Vector3();
-const _invQ = new Quaternion();
-const _nLocal = new Vector3();
-const _closestLocal = new Vector3();
-/**
- * 竖直胶囊 vs 单个 OBB 的最近穿透。
- * @param px 胶囊中心水平 x
- * @param pz 胶囊中心水平 z
- * @param radius 胶囊半径
- * @param yBottom 胶囊竖直区间下界（= 脚底 = start.y - radius）
- * @param yTop 胶囊竖直区间上界（= 头顶球顶 = end.y + radius）
- * @param obb 世界空间 OBB
- * @param normalOut 输出：指向玩家的单位法线（世界空间，水平为主、地面/天花板为竖直）
- * @param contactOut 输出：碰撞体上最近点（世界空间）
- * @returns 穿透深度（>0 表示碰撞；≤0 表示不碰）
- */
-export function capsuleVsOBB(px, pz, radius, yBottom, yTop, obb, normalOut, contactOut) {
-    // 玩家水平点 → OBB 局部空间（只取 x/z；y 由竖直区间单独判定）
-    _local.set(px - obb.center.x, 0, pz - obb.center.z);
-    _invQ.copy(obb.quat).invert();
-    _local.applyQuaternion(_invQ);
-    const lx = _local.x;
-    const lz = _local.z;
-    // 2D 最近点（XZ 平面投影为 2D OBB，半尺寸 half.x / half.z）
-    const cx = Math.max(-obb.half.x, Math.min(obb.half.x, lx));
-    const cz = Math.max(-obb.half.z, Math.min(obb.half.z, lz));
-    const dx = lx - cx;
-    const dz = lz - cz;
-    const dH = Math.sqrt(dx * dx + dz * dz);
-    // 竖直区间重叠判定
-    const oyMin = obb.center.y - obb.half.y;
-    const oyMax = obb.center.y + obb.half.y;
-    const yOverlap = yBottom < oyMax && yTop > oyMin;
-    if (!yOverlap)
-        return 0;
-    if (dH > 1e-6) {
-        // 水平穿透（点在 OBB 水平投影之外或边缘）：法线 = 局部 (dx,0,dz) 指向玩家，转回世界
-        const depth = radius - dH;
-        if (depth <= CAPSULE_DEPTH_EPS)
-            return 0;
-        _nLocal.set(dx, 0, dz).normalize();
-        normalOut.copy(_nLocal).applyQuaternion(obb.quat);
-        // 接触点：box 侧面，y 取玩家竖直区间与 box 重叠段中点
-        const cy = Math.max(oyMin, Math.min(oyMax, (yBottom + yTop) * 0.5));
-        _closestLocal.set(cx, cy - obb.center.y, cz).applyQuaternion(obb.quat).add(obb.center);
-        contactOut.copy(_closestLocal);
-        return depth;
-    }
-    // 水平在 OBB 内部（dH≈0）：退化现场（玩家中心已陷进 box 水平投影）。
-    // ⚠️ 不能只做竖直（旧版会把陷进薄墙的角色竖直弹飞）；应取**最小正穿透**的那一面托出，法线朝外。
-    const penX = obb.half.x - Math.abs(lx);
-    const penZ = obb.half.z - Math.abs(lz);
-    const penYTop = oyMax - yBottom; // 到顶面(+y)
-    const penYBot = yTop - oyMin; // 到底面(-y)
-    let minPen = Infinity;
-    let fx = 0, fy = 0, fz = 0;
-    if (penX > 0 && penX < minPen) {
-        minPen = penX;
-        fx = Math.sign(lx) || 1;
-        fy = 0;
-        fz = 0;
-    }
-    if (penZ > 0 && penZ < minPen) {
-        minPen = penZ;
-        fx = 0;
-        fy = 0;
-        fz = Math.sign(lz) || 1;
-    }
-    if (penYTop > 0 && penYTop < minPen) {
-        minPen = penYTop;
-        fx = 0;
-        fy = 1;
-        fz = 0;
-    }
-    if (penYBot > 0 && penYBot < minPen) {
-        minPen = penYBot;
-        fx = 0;
-        fy = -1;
-        fz = 0;
-    }
-    if (minPen === Infinity || minPen <= CAPSULE_DEPTH_EPS)
-        return 0;
-    _nLocal.set(fx, fy, fz).normalize();
-    normalOut.copy(_nLocal).applyQuaternion(obb.quat);
-    const cy = fy !== 0 ? (fy > 0 ? oyMax : oyMin) : (yBottom + yTop) * 0.5;
-    contactOut.set(px, cy, pz);
-    return minPen;
-}
+/**
+ * capsuleVsOBB —— 竖直胶囊（第一人称角色）vs 有向包围盒（OBB）的精确穿透查询
+ *
+ * ⭐ 为什么是这套：玩家胶囊在 FPS 里是**竖直**的（start/end 的 x/z 相同，仅 y 不同），
+ *   于是「胶囊 vs OBB」可精确化简为：
+ *     · 水平面（XZ）= 一个点（胶囊中心水平投影）到 OBB 的 2D 最近距离；
+ *     · 竖直（Y）= 胶囊竖直区间 [yBottom, yTop] 与 OBB 竖直区间是否重叠。
+ *   这比「线段 vs box 通用最近点」更精确（box 是平面，法线恒定），
+ *   也比「10 条射线模拟体积」物理正确且不抖（射线没有体积，贴墙必漏检）。
+ *
+ * ⭐ 一次调用得：穿透深度 depth（>0 即碰撞）+ 指向玩家的单位法线 normal + 碰撞体最近点 contact。
+ *   位置修正 = 沿 normal 推出 depth（解析解，非贪心搜索）；速度修正 = 滑墙投影 v -= (v·n)n。
+ *
+ * 零依赖：只用 three 的 Vector3 / Quaternion（标量运算，任何环境可跑）。
+ */
+import { Vector3, Quaternion } from "three";
+/**
+ * ⭐ 穿透噪声门（2026-09-27 探针实测）：深度 ≤ 此值视为**未碰撞**。
+ *   玩家停在「恰好贴合」位（如夹缝 = 胶囊直径）时，浮点残差会产生 ±1e-6 量级的
+ *   微穿透 —— 不门掉的话，贴合面会以随机符号反复登记投票，回弹方向被钉死在
+ *   某一面（实测：0.7m 夹缝里方向恒 +X 朝深墙）。真穿透都是毫米级以上，不受影响。
+ */
+export const CAPSULE_DEPTH_EPS = 1e-4;
+// 复用的临时量（避免每帧 GC）
+const _local = new Vector3();
+const _invQ = new Quaternion();
+const _nLocal = new Vector3();
+const _closestLocal = new Vector3();
+/**
+ * 竖直胶囊 vs 单个 OBB 的最近穿透。
+ * @param px 胶囊中心水平 x
+ * @param pz 胶囊中心水平 z
+ * @param radius 胶囊半径
+ * @param yBottom 胶囊竖直区间下界（= 脚底 = start.y - radius）
+ * @param yTop 胶囊竖直区间上界（= 头顶球顶 = end.y + radius）
+ * @param obb 世界空间 OBB
+ * @param normalOut 输出：指向玩家的单位法线（世界空间，水平为主、地面/天花板为竖直）
+ * @param contactOut 输出：碰撞体上最近点（世界空间）
+ * @returns 穿透深度（>0 表示碰撞；≤0 表示不碰）
+ */
+export function capsuleVsOBB(px, pz, radius, yBottom, yTop, obb, normalOut, contactOut) {
+    // 玩家水平点 → OBB 局部空间（只取 x/z；y 由竖直区间单独判定）
+    _local.set(px - obb.center.x, 0, pz - obb.center.z);
+    _invQ.copy(obb.quat).invert();
+    _local.applyQuaternion(_invQ);
+    const lx = _local.x;
+    const lz = _local.z;
+    // 2D 最近点（XZ 平面投影为 2D OBB，半尺寸 half.x / half.z）
+    const cx = Math.max(-obb.half.x, Math.min(obb.half.x, lx));
+    const cz = Math.max(-obb.half.z, Math.min(obb.half.z, lz));
+    const dx = lx - cx;
+    const dz = lz - cz;
+    const dH = Math.sqrt(dx * dx + dz * dz);
+    // 竖直区间重叠判定
+    const oyMin = obb.center.y - obb.half.y;
+    const oyMax = obb.center.y + obb.half.y;
+    const yOverlap = yBottom < oyMax && yTop > oyMin;
+    if (!yOverlap)
+        return 0;
+    if (dH > 1e-6) {
+        // 水平穿透（点在 OBB 水平投影之外或边缘）：法线 = 局部 (dx,0,dz) 指向玩家，转回世界
+        const depth = radius - dH;
+        if (depth <= CAPSULE_DEPTH_EPS)
+            return 0;
+        _nLocal.set(dx, 0, dz).normalize();
+        normalOut.copy(_nLocal).applyQuaternion(obb.quat);
+        // 接触点：box 侧面，y 取玩家竖直区间与 box 重叠段中点
+        const cy = Math.max(oyMin, Math.min(oyMax, (yBottom + yTop) * 0.5));
+        _closestLocal.set(cx, cy - obb.center.y, cz).applyQuaternion(obb.quat).add(obb.center);
+        contactOut.copy(_closestLocal);
+        return depth;
+    }
+    // 水平在 OBB 内部（dH≈0）：退化现场（玩家中心已陷进 box 水平投影）。
+    // ⚠️ 不能只做竖直（旧版会把陷进薄墙的角色竖直弹飞）；应取**最小正穿透**的那一面托出，法线朝外。
+    const penX = obb.half.x - Math.abs(lx);
+    const penZ = obb.half.z - Math.abs(lz);
+    const penYTop = oyMax - yBottom; // 到顶面(+y)
+    const penYBot = yTop - oyMin; // 到底面(-y)
+    let minPen = Infinity;
+    let fx = 0, fy = 0, fz = 0;
+    if (penX > 0 && penX < minPen) {
+        minPen = penX;
+        fx = Math.sign(lx) || 1;
+        fy = 0;
+        fz = 0;
+    }
+    if (penZ > 0 && penZ < minPen) {
+        minPen = penZ;
+        fx = 0;
+        fy = 0;
+        fz = Math.sign(lz) || 1;
+    }
+    if (penYTop > 0 && penYTop < minPen) {
+        minPen = penYTop;
+        fx = 0;
+        fy = 1;
+        fz = 0;
+    }
+    if (penYBot > 0 && penYBot < minPen) {
+        minPen = penYBot;
+        fx = 0;
+        fy = -1;
+        fz = 0;
+    }
+    if (minPen === Infinity || minPen <= CAPSULE_DEPTH_EPS)
+        return 0;
+    _nLocal.set(fx, fy, fz).normalize();
+    normalOut.copy(_nLocal).applyQuaternion(obb.quat);
+    const cy = fy !== 0 ? (fy > 0 ? oyMax : oyMin) : (yBottom + yTop) * 0.5;
+    contactOut.set(px, cy, pz);
+    return minPen;
+}

package/collisionOBB.ts

@@ -1,108 +1,108 @@
-/**
- * capsuleVsOBB —— 竖直胶囊（第一人称角色）vs 有向包围盒（OBB）的精确穿透查询
- *
- * ⭐ 为什么是这套：玩家胶囊在 FPS 里是**竖直**的（start/end 的 x/z 相同，仅 y 不同），
- *   于是「胶囊 vs OBB」可精确化简为：
- *     · 水平面（XZ）= 一个点（胶囊中心水平投影）到 OBB 的 2D 最近距离；
- *     · 竖直（Y）= 胶囊竖直区间 [yBottom, yTop] 与 OBB 竖直区间是否重叠。
- *   这比「线段 vs box 通用最近点」更精确（box 是平面，法线恒定），
- *   也比「10 条射线模拟体积」物理正确且不抖（射线没有体积，贴墙必漏检）。
- *
- * ⭐ 一次调用得：穿透深度 depth（>0 即碰撞）+ 指向玩家的单位法线 normal + 碰撞体最近点 contact。
- *   位置修正 = 沿 normal 推出 depth（解析解，非贪心搜索）；速度修正 = 滑墙投影 v -= (v·n)n。
- *
- * 零依赖：只用 three 的 Vector3 / Quaternion（标量运算，任何环境可跑）。
- */
-
-import { Vector3, Quaternion } from "three";
-
-/** 有向包围盒（世界空间）：center + 旋转 quat + 半尺寸 half（已含 scale） */
-export interface OBB {
-    center: Vector3;
-    quat: Quaternion;
-    half: Vector3;
-}
-
-/**
- * ⭐ 穿透噪声门（2026-09-27 探针实测）：深度 ≤ 此值视为**未碰撞**。
- *   玩家停在「恰好贴合」位（如夹缝 = 胶囊直径）时，浮点残差会产生 ±1e-6 量级的
- *   微穿透 —— 不门掉的话，贴合面会以随机符号反复登记投票，回弹方向被钉死在
- *   某一面（实测：0.7m 夹缝里方向恒 +X 朝深墙）。真穿透都是毫米级以上，不受影响。
- */
-export const CAPSULE_DEPTH_EPS = 1e-4;
-
-// 复用的临时量（避免每帧 GC）
-const _local = new Vector3();
-const _invQ = new Quaternion();
-const _nLocal = new Vector3();
-const _closestLocal = new Vector3();
-
-/**
- * 竖直胶囊 vs 单个 OBB 的最近穿透。
- * @param px 胶囊中心水平 x
- * @param pz 胶囊中心水平 z
- * @param radius 胶囊半径
- * @param yBottom 胶囊竖直区间下界（= 脚底 = start.y - radius）
- * @param yTop 胶囊竖直区间上界（= 头顶球顶 = end.y + radius）
- * @param obb 世界空间 OBB
- * @param normalOut 输出：指向玩家的单位法线（世界空间，水平为主、地面/天花板为竖直）
- * @param contactOut 输出：碰撞体上最近点（世界空间）
- * @returns 穿透深度（>0 表示碰撞；≤0 表示不碰）
- */
-export function capsuleVsOBB(
-    px: number, pz: number, radius: number,
-    yBottom: number, yTop: number,
-    obb: OBB, normalOut: Vector3, contactOut: Vector3
-): number {
-    // 玩家水平点 → OBB 局部空间（只取 x/z；y 由竖直区间单独判定）
-    _local.set(px - obb.center.x, 0, pz - obb.center.z);
-    _invQ.copy(obb.quat).invert();
-    _local.applyQuaternion(_invQ);
-    const lx = _local.x;
-    const lz = _local.z;
-
-    // 2D 最近点（XZ 平面投影为 2D OBB，半尺寸 half.x / half.z）
-    const cx = Math.max(-obb.half.x, Math.min(obb.half.x, lx));
-    const cz = Math.max(-obb.half.z, Math.min(obb.half.z, lz));
-    const dx = lx - cx;
-    const dz = lz - cz;
-    const dH = Math.sqrt(dx * dx + dz * dz);
-
-    // 竖直区间重叠判定
-    const oyMin = obb.center.y - obb.half.y;
-    const oyMax = obb.center.y + obb.half.y;
-    const yOverlap = yBottom < oyMax && yTop > oyMin;
-    if (!yOverlap) return 0;
-
-    if (dH > 1e-6) {
-        // 水平穿透（点在 OBB 水平投影之外或边缘）：法线 = 局部 (dx,0,dz) 指向玩家，转回世界
-        const depth = radius - dH;
-        if (depth <= CAPSULE_DEPTH_EPS) return 0;
-        _nLocal.set(dx, 0, dz).normalize();
-        normalOut.copy(_nLocal).applyQuaternion(obb.quat);
-        // 接触点：box 侧面，y 取玩家竖直区间与 box 重叠段中点
-        const cy = Math.max(oyMin, Math.min(oyMax, (yBottom + yTop) * 0.5));
-        _closestLocal.set(cx, cy - obb.center.y, cz).applyQuaternion(obb.quat).add(obb.center);
-        contactOut.copy(_closestLocal);
-        return depth;
-    }
-
-    // 水平在 OBB 内部（dH≈0）：退化现场（玩家中心已陷进 box 水平投影）。
-    // ⚠️ 不能只做竖直（旧版会把陷进薄墙的角色竖直弹飞）；应取**最小正穿透**的那一面托出，法线朝外。
-    const penX = obb.half.x - Math.abs(lx);
-    const penZ = obb.half.z - Math.abs(lz);
-    const penYTop = oyMax - yBottom; // 到顶面(+y)
-    const penYBot = yTop - oyMin;    // 到底面(-y)
-    let minPen = Infinity;
-    let fx = 0, fy = 0, fz = 0;
-    if (penX > 0 && penX < minPen) { minPen = penX; fx = Math.sign(lx) || 1; fy = 0; fz = 0; }
-    if (penZ > 0 && penZ < minPen) { minPen = penZ; fx = 0; fy = 0; fz = Math.sign(lz) || 1; }
-    if (penYTop > 0 && penYTop < minPen) { minPen = penYTop; fx = 0; fy = 1; fz = 0; }
-    if (penYBot > 0 && penYBot < minPen) { minPen = penYBot; fx = 0; fy = -1; fz = 0; }
-    if (minPen === Infinity || minPen <= CAPSULE_DEPTH_EPS) return 0;
-    _nLocal.set(fx, fy, fz).normalize();
-    normalOut.copy(_nLocal).applyQuaternion(obb.quat);
-    const cy = fy !== 0 ? (fy > 0 ? oyMax : oyMin) : (yBottom + yTop) * 0.5;
-    contactOut.set(px, cy, pz);
-    return minPen;
-}
+/**
+ * capsuleVsOBB —— 竖直胶囊（第一人称角色）vs 有向包围盒（OBB）的精确穿透查询
+ *
+ * ⭐ 为什么是这套：玩家胶囊在 FPS 里是**竖直**的（start/end 的 x/z 相同，仅 y 不同），
+ *   于是「胶囊 vs OBB」可精确化简为：
+ *     · 水平面（XZ）= 一个点（胶囊中心水平投影）到 OBB 的 2D 最近距离；
+ *     · 竖直（Y）= 胶囊竖直区间 [yBottom, yTop] 与 OBB 竖直区间是否重叠。
+ *   这比「线段 vs box 通用最近点」更精确（box 是平面，法线恒定），
+ *   也比「10 条射线模拟体积」物理正确且不抖（射线没有体积，贴墙必漏检）。
+ *
+ * ⭐ 一次调用得：穿透深度 depth（>0 即碰撞）+ 指向玩家的单位法线 normal + 碰撞体最近点 contact。
+ *   位置修正 = 沿 normal 推出 depth（解析解，非贪心搜索）；速度修正 = 滑墙投影 v -= (v·n)n。
+ *
+ * 零依赖：只用 three 的 Vector3 / Quaternion（标量运算，任何环境可跑）。
+ */
+
+import { Vector3, Quaternion } from "three";
+
+/** 有向包围盒（世界空间）：center + 旋转 quat + 半尺寸 half（已含 scale） */
+export interface OBB {
+    center: Vector3;
+    quat: Quaternion;
+    half: Vector3;
+}
+
+/**
+ * ⭐ 穿透噪声门（2026-09-27 探针实测）：深度 ≤ 此值视为**未碰撞**。
+ *   玩家停在「恰好贴合」位（如夹缝 = 胶囊直径）时，浮点残差会产生 ±1e-6 量级的
+ *   微穿透 —— 不门掉的话，贴合面会以随机符号反复登记投票，回弹方向被钉死在
+ *   某一面（实测：0.7m 夹缝里方向恒 +X 朝深墙）。真穿透都是毫米级以上，不受影响。
+ */
+export const CAPSULE_DEPTH_EPS = 1e-4;
+
+// 复用的临时量（避免每帧 GC）
+const _local = new Vector3();
+const _invQ = new Quaternion();
+const _nLocal = new Vector3();
+const _closestLocal = new Vector3();
+
+/**
+ * 竖直胶囊 vs 单个 OBB 的最近穿透。
+ * @param px 胶囊中心水平 x
+ * @param pz 胶囊中心水平 z
+ * @param radius 胶囊半径
+ * @param yBottom 胶囊竖直区间下界（= 脚底 = start.y - radius）
+ * @param yTop 胶囊竖直区间上界（= 头顶球顶 = end.y + radius）
+ * @param obb 世界空间 OBB
+ * @param normalOut 输出：指向玩家的单位法线（世界空间，水平为主、地面/天花板为竖直）
+ * @param contactOut 输出：碰撞体上最近点（世界空间）
+ * @returns 穿透深度（>0 表示碰撞；≤0 表示不碰）
+ */
+export function capsuleVsOBB(
+    px: number, pz: number, radius: number,
+    yBottom: number, yTop: number,
+    obb: OBB, normalOut: Vector3, contactOut: Vector3
+): number {
+    // 玩家水平点 → OBB 局部空间（只取 x/z；y 由竖直区间单独判定）
+    _local.set(px - obb.center.x, 0, pz - obb.center.z);
+    _invQ.copy(obb.quat).invert();
+    _local.applyQuaternion(_invQ);
+    const lx = _local.x;
+    const lz = _local.z;
+
+    // 2D 最近点（XZ 平面投影为 2D OBB，半尺寸 half.x / half.z）
+    const cx = Math.max(-obb.half.x, Math.min(obb.half.x, lx));
+    const cz = Math.max(-obb.half.z, Math.min(obb.half.z, lz));
+    const dx = lx - cx;
+    const dz = lz - cz;
+    const dH = Math.sqrt(dx * dx + dz * dz);
+
+    // 竖直区间重叠判定
+    const oyMin = obb.center.y - obb.half.y;
+    const oyMax = obb.center.y + obb.half.y;
+    const yOverlap = yBottom < oyMax && yTop > oyMin;
+    if (!yOverlap) return 0;
+
+    if (dH > 1e-6) {
+        // 水平穿透（点在 OBB 水平投影之外或边缘）：法线 = 局部 (dx,0,dz) 指向玩家，转回世界
+        const depth = radius - dH;
+        if (depth <= CAPSULE_DEPTH_EPS) return 0;
+        _nLocal.set(dx, 0, dz).normalize();
+        normalOut.copy(_nLocal).applyQuaternion(obb.quat);
+        // 接触点：box 侧面，y 取玩家竖直区间与 box 重叠段中点
+        const cy = Math.max(oyMin, Math.min(oyMax, (yBottom + yTop) * 0.5));
+        _closestLocal.set(cx, cy - obb.center.y, cz).applyQuaternion(obb.quat).add(obb.center);
+        contactOut.copy(_closestLocal);
+        return depth;
+    }
+
+    // 水平在 OBB 内部（dH≈0）：退化现场（玩家中心已陷进 box 水平投影）。
+    // ⚠️ 不能只做竖直（旧版会把陷进薄墙的角色竖直弹飞）；应取**最小正穿透**的那一面托出，法线朝外。
+    const penX = obb.half.x - Math.abs(lx);
+    const penZ = obb.half.z - Math.abs(lz);
+    const penYTop = oyMax - yBottom; // 到顶面(+y)
+    const penYBot = yTop - oyMin;    // 到底面(-y)
+    let minPen = Infinity;
+    let fx = 0, fy = 0, fz = 0;
+    if (penX > 0 && penX < minPen) { minPen = penX; fx = Math.sign(lx) || 1; fy = 0; fz = 0; }
+    if (penZ > 0 && penZ < minPen) { minPen = penZ; fx = 0; fy = 0; fz = Math.sign(lz) || 1; }
+    if (penYTop > 0 && penYTop < minPen) { minPen = penYTop; fx = 0; fy = 1; fz = 0; }
+    if (penYBot > 0 && penYBot < minPen) { minPen = penYBot; fx = 0; fy = -1; fz = 0; }
+    if (minPen === Infinity || minPen <= CAPSULE_DEPTH_EPS) return 0;
+    _nLocal.set(fx, fy, fz).normalize();
+    normalOut.copy(_nLocal).applyQuaternion(obb.quat);
+    const cy = fy !== 0 ? (fy > 0 ? oyMax : oyMin) : (yBottom + yTop) * 0.5;
+    contactOut.set(px, cy, pz);
+    return minPen;
+}

package/declare.d.ts

@@ -1,25 +1,25 @@
-// three-base 独立编译 / npm 发包的环境声明。
-// three-base 脱离演示站单独跑 tsc 时没有 vite/client 提供静态资源模块声明，
-// 各组件 import 的 .png / .jpg / .glb 等在此声明，避免 TS2307。
-// （演示站根 tsconfig 走 vite/client，本文件与之并存无冲突，二者 wildcard 声明可合并。）
-declare module "*.png";
-declare module "*.jpg";
-declare module "*.jpeg";
-declare module "*.webp";
-declare module "*.svg";
-declare module "*.gif";
-declare module "*.glb";
-declare module "*.gltf";
-declare module "*.hdr";
-declare module "*.obj";
-declare module "*.stl";
-declare module "*.usdz";
-declare module "*.zip";
-declare module "*.mp3";
-declare module "*.mp4";
-declare module "*.woff";
-declare module "*.woff2";
-declare module "*.ttf";
-
-declare interface Window {
-}
+// three-base 独立编译 / npm 发包的环境声明。
+// three-base 脱离演示站单独跑 tsc 时没有 vite/client 提供静态资源模块声明，
+// 各组件 import 的 .png / .jpg / .glb 等在此声明，避免 TS2307。
+// （演示站根 tsconfig 走 vite/client，本文件与之并存无冲突，二者 wildcard 声明可合并。）
+declare module "*.png";
+declare module "*.jpg";
+declare module "*.jpeg";
+declare module "*.webp";
+declare module "*.svg";
+declare module "*.gif";
+declare module "*.glb";
+declare module "*.gltf";
+declare module "*.hdr";
+declare module "*.obj";
+declare module "*.stl";
+declare module "*.usdz";
+declare module "*.zip";
+declare module "*.mp3";
+declare module "*.mp4";
+declare module "*.woff";
+declare module "*.woff2";
+declare module "*.ttf";
+
+declare interface Window {
+}

package/index.d.ts

@@ -1 +1 @@
-export { default } from "./ThreeBase";
+export { default } from "./ThreeBase";

package/index.js

@@ -1 +1 @@
-export { default } from "./ThreeBase";
+export { default } from "./ThreeBase";

package/instanced/InstancedBatch.d.ts

@@ -1,57 +1,57 @@
-import { Group, InstancedMesh } from "three";
-import InstancedChild from "./InstancedChild";
-import { InstancedTemplate } from "./InstancedTemplate";
-/**
- * 内部类：封装一个 batch 的真实 InstancedMesh（多 submesh 时每个 submesh 一个，共享同一组实例序号）。
- * - 按 batchKey 分组（相同 geometry+material 或相同 instanceUrl+animation 为一类）；
- * - 增量同步：仅 needUpdate=true 的实例才重写 matrix/color，写完后立即置 false；
- * - 列表变化（增删/重排）时全量 compact 重写并重建索引；
- * - 含骨骼动画时：用共享姿态 AnimationMixer 驱动 skeleton，每帧烘焙到共享几何（LBS）；
- * - 含非骨骼节点动画时：同样用共享姿态 AnimationMixer 驱动节点变换，每帧把"节点相对根的世界变换"
- *   烘焙进几何（节点变换动画的实例化方案）。
- */
-export default class InstancedBatch {
-    key: string;
-    /** 渲染组：持有本 batch 的 InstancedMesh，由 InstancedGroup add 进 scene */
-    group: Group;
-    template?: InstancedTemplate;
-    ready: boolean;
-    private _children;
-    private _meshes;
-    private _capacity;
-    private _step;
-    private _loading?;
-    private _mixer?;
-    private _clipName?;
-    /** 当前正在播放的动画剪辑名（运行时可由 child.playClip 切换） */
-    private _currentClip?;
-    /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
-    private _sampleFpsCollision;
-    /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
-    private _currentAction?;
-    /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
-    private _nodeBake;
-    constructor(key: string, sample: InstancedChild, capacity?: number, step?: number);
-    /** 模板就绪后，为每个 submesh 建一个 InstancedMesh，并启动动画（若有） */
-    private buildMeshes;
-    /** 每帧同步：children 为按 batchKey 收集的 InstancedChild 列表 */
-    sync(children: InstancedChild[], delta: number): void;
-    /** 容量不足时按 step 扩容（只扩不缩，避免频繁 realloc） */
-    private ensureCapacity;
-    /** 全量重写所有实例（列表变化时调用） */
-    private compactWrite;
-    /** 根据当前首批实例的 fpsCollision 标记，把真实 InstancedMesh 的 userData.fpsCollision 同步过去，
-     *  并在开启时通知所有 FPScontrol 重建碰撞列表。碰撞以整个 batch 为单位开关。 */
-    private _applyCollisionFlag;
-    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
-    private writeInstance;
-    /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
-    resolveInstance(mesh: InstancedMesh, instanceId: number): InstancedChild | null;
-    /** 该 batch 是否有任一 child 注册了指定类型监听（供 ThreeMouse 决定是否可拾取） */
-    hasListener(types: string[]): boolean;
-    /** 该 batch 是否有任一 child 设置了鼠标手势（cursor），供 InstancedGroup 决定是否收集 */
-    hasCursor(): boolean;
-    /** 拾取用 InstancedMesh 列表 */
-    get pickables(): InstancedMesh[];
-    dispose(): void;
-}
+import { Group, InstancedMesh } from "three";
+import InstancedChild from "./InstancedChild";
+import { InstancedTemplate } from "./InstancedTemplate";
+/**
+ * 内部类：封装一个 batch 的真实 InstancedMesh（多 submesh 时每个 submesh 一个，共享同一组实例序号）。
+ * - 按 batchKey 分组（相同 geometry+material 或相同 instanceUrl+animation 为一类）；
+ * - 增量同步：仅 needUpdate=true 的实例才重写 matrix/color，写完后立即置 false；
+ * - 列表变化（增删/重排）时全量 compact 重写并重建索引；
+ * - 含骨骼动画时：用共享姿态 AnimationMixer 驱动 skeleton，每帧烘焙到共享几何（LBS）；
+ * - 含非骨骼节点动画时：同样用共享姿态 AnimationMixer 驱动节点变换，每帧把"节点相对根的世界变换"
+ *   烘焙进几何（节点变换动画的实例化方案）。
+ */
+export default class InstancedBatch {
+    key: string;
+    /** 渲染组：持有本 batch 的 InstancedMesh，由 InstancedGroup add 进 scene */
+    group: Group;
+    template?: InstancedTemplate;
+    ready: boolean;
+    private _children;
+    private _meshes;
+    private _capacity;
+    private _step;
+    private _loading?;
+    private _mixer?;
+    private _clipName?;
+    /** 当前正在播放的动画剪辑名（运行时可由 child.playClip 切换） */
+    private _currentClip?;
+    /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
+    private _sampleFpsCollision;
+    /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
+    private _currentAction?;
+    /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
+    private _nodeBake;
+    constructor(key: string, sample: InstancedChild, capacity?: number, step?: number);
+    /** 模板就绪后，为每个 submesh 建一个 InstancedMesh，并启动动画（若有） */
+    private buildMeshes;
+    /** 每帧同步：children 为按 batchKey 收集的 InstancedChild 列表 */
+    sync(children: InstancedChild[], delta: number): void;
+    /** 容量不足时按 step 扩容（只扩不缩，避免频繁 realloc） */
+    private ensureCapacity;
+    /** 全量重写所有实例（列表变化时调用） */
+    private compactWrite;
+    /** 根据当前首批实例的 fpsCollision 标记，把真实 InstancedMesh 的 userData.fpsCollision 同步过去，
+     *  并在开启时通知所有 FPScontrol 重建碰撞列表。碰撞以整个 batch 为单位开关。 */
+    private _applyCollisionFlag;
+    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
+    private writeInstance;
+    /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
+    resolveInstance(mesh: InstancedMesh, instanceId: number): InstancedChild | null;
+    /** 该 batch 是否有任一 child 注册了指定类型监听（供 ThreeMouse 决定是否可拾取） */
+    hasListener(types: string[]): boolean;
+    /** 该 batch 是否有任一 child 设置了鼠标手势（cursor），供 InstancedGroup 决定是否收集 */
+    hasCursor(): boolean;
+    /** 拾取用 InstancedMesh 列表 */
+    get pickables(): InstancedMesh[];
+    dispose(): void;
+}