three-base 2.0.142 → 2.0.166

package/WaterFlow/types.ts

@@ -1,189 +1,189 @@
-/**
- * WaterFlow 模块共享类型（单一来源，供 WaterFlow 目录内各 .ts 复用）。
- *
- * 2026-10-08 皇上旨「项目代码就应该写成 ts 来校验，尽量不写 js」——
- * 原 WaterFlow/ 下 7 个手写 .js 全部改写为 .ts，公共入参/出参类型集中在此，
- * 避免各文件重复声明高度相似的结构（也避免 any）。
- */
-import type {
-    Camera,
-    DepthTexture,
-    Scene,
-    Texture,
-    Vector3,
-    Vector4,
-    WebGLRenderer,
-    WebGLRenderTarget,
-} from 'three';
-
-/** 深度解码口径：普通透视深度 | three-base 的对数深度（logarithmicDepthBuffer）。 */
-export type DepthMode = 'standard' | 'logarithmic';
-
-/** 「注入基础纹理」模式：直接消费调用方已有的颜色/深度，省掉一遍主场景渲染。 */
-export interface WaterFlowBaseTextures {
-    colorTexture: Texture;
-    depthTexture: DepthTexture | Texture;
-    depthMode?: DepthMode;
-}
-
-/** renderInto 的入参：在基础纹理之上再加「输出目标 + 相机」。 */
-export interface WaterFlowRenderOptions extends WaterFlowBaseTextures {
-    /** 合成输出目标；null 表示沿用调用方当前渲染目标（由 renderer.getRenderTarget() 决定）。 */
-    outputTarget: WebGLRenderTarget | null;
-    camera: Camera;
-}
-
-/** 模拟参数（可部分更新，故全部可选）。 */
-export interface FluidParameters {
-    speed?: number;
-    aperture?: number;
-    fillRatio?: number;
-    emitting?: boolean;
-    turbulence?: number;
-}
-
-/** 蓄水池状态。 */
-export interface ReservoirState {
-    active?: boolean;
-    fillRatio?: number;
-}
-
-/** 容器（盆）几何口径：x 范围、z 半宽、中心、水面高度与壁高。 */
-export interface BasinConfig {
-    minX: number;
-    maxX: number;
-    halfZ: number;
-    centerZ?: number;
-    waterY: number;
-    wallTop: number;
-    floorY?: number;
-    containerFloorY?: number;
-    rimWidth?: number;
-}
-
-/** ShallowWaterSurface 构造选项。 */
-export interface ShallowWaterSurfaceOptions {
-    width?: number;
-    height?: number;
-    basinMinX?: number;
-    basinMaxX?: number;
-    basinHalfZ?: number;
-    basinCenterZ?: number;
-    waterY?: number;
-    cpuSampling?: boolean;
-}
-
-/** ShallowWaterSurface.setBounds 的入参（centerZ 省略时按 0 处理）。 */
-export interface ShallowWaterSurfaceBounds {
-    basinMinX: number;
-    basinMaxX: number;
-    basinHalfZ: number;
-    basinCenterZ?: number;
-    waterY: number;
-}
-
-/**
- * 水面采样结果（ShallowWaterSurface.sampleSurface 回填 target 后返回）。
- * 字段全为可选：调用方可只声明自己关心的部分，结构上兼容 FloatingDuck 的 DuckSurfaceSample。
- */
-export interface WaterSurfaceSample {
-    height?: number;
-    velocityY?: number;
-    slopeX?: number;
-    slopeZ?: number;
-    flowX?: number;
-    flowZ?: number;
-    impact?: number;
-}
-
-/** 渲染质量档。 */
-export interface FluidQuality {
-    scale: number;
-    activeCount: number;
-    blurRadius: number;
-}
-
-/** 外层 WaterFlow 构造选项。 */
-export interface WaterFlowOptions {
-    width?: number;
-    height?: number;
-    scale?: number;
-    size?: number;
-    speed?: number;
-    aperture?: number;
-    nozzle?: Vector3;
-    basin?: Vector4;
-    jetDirection?: Vector3;
-    collision?: boolean;
-}
-
-/** GPUFluidSimulation 构造选项（与外层同源，保留喷嘴/盆/喷流方向）。 */
-export interface FluidSimulationOptions {
-    size?: number;
-    nozzle?: Vector3;
-    basin?: Vector4;
-    speed?: number;
-    aperture?: number;
-    jetDirection?: Vector3;
-    collision?: boolean;
-}
-
-/** SPHField 构造选项。 */
-export interface SPHFieldOptions {
-    mobile?: boolean;
-}
-
-/** ScreenSpaceFluidPass 构造选项。 */
-export interface ScreenSpaceFluidPassOptions {
-    width?: number;
-    height?: number;
-    scale?: number;
-    activeCount?: number;
-    externalBase?: {
-        colorTexture: Texture;
-        depthTexture: DepthTexture | Texture;
-        depthMode: DepthMode;
-    } | null;
-}
-
-/** 屏幕空间 pass 需要的场景/相机（构造期持有，避免每帧反查）。 */
-export interface ScreenSpaceFluidContext {
-    scene: Scene;
-    camera: Camera;
-}
-
-/** setBaseTextures 的部分更新入参。 */
-export interface PartialBaseTextures {
-    colorTexture?: Texture;
-    depthTexture?: DepthTexture | Texture;
-    depthMode?: DepthMode;
-}
-
-/** 渲染器能力判定结果：非 WebGL2 或缺浮点扩展时整套流体不可用。 */
-export interface FluidSupportInfo {
-    renderer: WebGLRenderer;
-}
-
-/**
- * ScreenSpaceFluidPass 视角下的流体模拟器最小契约。
- * 只声明 pass 真正读取的成员（粒子纹理边长 / 粒子数 / 能力位 / 位置与速度纹理），
- * 使 pass 不必耦合 GPUFluidSimulation 的其余实现细节。
- * GPUFluidSimulation 实例天然满足本结构（结构化子类型）。
- */
-export interface ScreenSpaceFluidSource {
-    /** 粒子纹理边长，count === size * size。 */
-    size: number;
-    /** 粒子总数。 */
-    count: number;
-    /** 是否支持浮点纹理；false 时两个纹理成员为 null。 */
-    supported: boolean;
-    positionTexture: Texture | null;
-    velocityTexture: Texture | null;
-}
-
-/**
- * 「外部注入基础纹理」三元组的非空形态。
- * 等价于 ScreenSpaceFluidPassOptions['externalBase'] 去掉 null，
- * 供 pass 内部字段（externalBase）与 GPUFluidSimulation 之外的调用方直接复用。
- */
-export type ExternalBaseTextures = NonNullable<ScreenSpaceFluidPassOptions['externalBase']>;
+/**
+ * WaterFlow 模块共享类型（单一来源，供 WaterFlow 目录内各 .ts 复用）。
+ *
+ * 2026-10-08 皇上旨「项目代码就应该写成 ts 来校验，尽量不写 js」——
+ * 原 WaterFlow/ 下 7 个手写 .js 全部改写为 .ts，公共入参/出参类型集中在此，
+ * 避免各文件重复声明高度相似的结构（也避免 any）。
+ */
+import type {
+    Camera,
+    DepthTexture,
+    Scene,
+    Texture,
+    Vector3,
+    Vector4,
+    WebGLRenderer,
+    WebGLRenderTarget,
+} from 'three';
+
+/** 深度解码口径：普通透视深度 | three-base 的对数深度（logarithmicDepthBuffer）。 */
+export type DepthMode = 'standard' | 'logarithmic';
+
+/** 「注入基础纹理」模式：直接消费调用方已有的颜色/深度，省掉一遍主场景渲染。 */
+export interface WaterFlowBaseTextures {
+    colorTexture: Texture;
+    depthTexture: DepthTexture | Texture;
+    depthMode?: DepthMode;
+}
+
+/** renderInto 的入参：在基础纹理之上再加「输出目标 + 相机」。 */
+export interface WaterFlowRenderOptions extends WaterFlowBaseTextures {
+    /** 合成输出目标；null 表示沿用调用方当前渲染目标（由 renderer.getRenderTarget() 决定）。 */
+    outputTarget: WebGLRenderTarget | null;
+    camera: Camera;
+}
+
+/** 模拟参数（可部分更新，故全部可选）。 */
+export interface FluidParameters {
+    speed?: number;
+    aperture?: number;
+    fillRatio?: number;
+    emitting?: boolean;
+    turbulence?: number;
+}
+
+/** 蓄水池状态。 */
+export interface ReservoirState {
+    active?: boolean;
+    fillRatio?: number;
+}
+
+/** 容器（盆）几何口径：x 范围、z 半宽、中心、水面高度与壁高。 */
+export interface BasinConfig {
+    minX: number;
+    maxX: number;
+    halfZ: number;
+    centerZ?: number;
+    waterY: number;
+    wallTop: number;
+    floorY?: number;
+    containerFloorY?: number;
+    rimWidth?: number;
+}
+
+/** ShallowWaterSurface 构造选项。 */
+export interface ShallowWaterSurfaceOptions {
+    width?: number;
+    height?: number;
+    basinMinX?: number;
+    basinMaxX?: number;
+    basinHalfZ?: number;
+    basinCenterZ?: number;
+    waterY?: number;
+    cpuSampling?: boolean;
+}
+
+/** ShallowWaterSurface.setBounds 的入参（centerZ 省略时按 0 处理）。 */
+export interface ShallowWaterSurfaceBounds {
+    basinMinX: number;
+    basinMaxX: number;
+    basinHalfZ: number;
+    basinCenterZ?: number;
+    waterY: number;
+}
+
+/**
+ * 水面采样结果（ShallowWaterSurface.sampleSurface 回填 target 后返回）。
+ * 字段全为可选：调用方可只声明自己关心的部分，结构上兼容 FloatingDuck 的 DuckSurfaceSample。
+ */
+export interface WaterSurfaceSample {
+    height?: number;
+    velocityY?: number;
+    slopeX?: number;
+    slopeZ?: number;
+    flowX?: number;
+    flowZ?: number;
+    impact?: number;
+}
+
+/** 渲染质量档。 */
+export interface FluidQuality {
+    scale: number;
+    activeCount: number;
+    blurRadius: number;
+}
+
+/** 外层 WaterFlow 构造选项。 */
+export interface WaterFlowOptions {
+    width?: number;
+    height?: number;
+    scale?: number;
+    size?: number;
+    speed?: number;
+    aperture?: number;
+    nozzle?: Vector3;
+    basin?: Vector4;
+    jetDirection?: Vector3;
+    collision?: boolean;
+}
+
+/** GPUFluidSimulation 构造选项（与外层同源，保留喷嘴/盆/喷流方向）。 */
+export interface FluidSimulationOptions {
+    size?: number;
+    nozzle?: Vector3;
+    basin?: Vector4;
+    speed?: number;
+    aperture?: number;
+    jetDirection?: Vector3;
+    collision?: boolean;
+}
+
+/** SPHField 构造选项。 */
+export interface SPHFieldOptions {
+    mobile?: boolean;
+}
+
+/** ScreenSpaceFluidPass 构造选项。 */
+export interface ScreenSpaceFluidPassOptions {
+    width?: number;
+    height?: number;
+    scale?: number;
+    activeCount?: number;
+    externalBase?: {
+        colorTexture: Texture;
+        depthTexture: DepthTexture | Texture;
+        depthMode: DepthMode;
+    } | null;
+}
+
+/** 屏幕空间 pass 需要的场景/相机（构造期持有，避免每帧反查）。 */
+export interface ScreenSpaceFluidContext {
+    scene: Scene;
+    camera: Camera;
+}
+
+/** setBaseTextures 的部分更新入参。 */
+export interface PartialBaseTextures {
+    colorTexture?: Texture;
+    depthTexture?: DepthTexture | Texture;
+    depthMode?: DepthMode;
+}
+
+/** 渲染器能力判定结果：非 WebGL2 或缺浮点扩展时整套流体不可用。 */
+export interface FluidSupportInfo {
+    renderer: WebGLRenderer;
+}
+
+/**
+ * ScreenSpaceFluidPass 视角下的流体模拟器最小契约。
+ * 只声明 pass 真正读取的成员（粒子纹理边长 / 粒子数 / 能力位 / 位置与速度纹理），
+ * 使 pass 不必耦合 GPUFluidSimulation 的其余实现细节。
+ * GPUFluidSimulation 实例天然满足本结构（结构化子类型）。
+ */
+export interface ScreenSpaceFluidSource {
+    /** 粒子纹理边长，count === size * size。 */
+    size: number;
+    /** 粒子总数。 */
+    count: number;
+    /** 是否支持浮点纹理；false 时两个纹理成员为 null。 */
+    supported: boolean;
+    positionTexture: Texture | null;
+    velocityTexture: Texture | null;
+}
+
+/**
+ * 「外部注入基础纹理」三元组的非空形态。
+ * 等价于 ScreenSpaceFluidPassOptions['externalBase'] 去掉 null，
+ * 供 pass 内部字段（externalBase）与 GPUFluidSimulation 之外的调用方直接复用。
+ */
+export type ExternalBaseTextures = NonNullable<ScreenSpaceFluidPassOptions['externalBase']>;

package/WaterFlow/waterFlowPass.d.ts

@@ -1,3 +1,3 @@
-import { WebGLRenderer, WebGLRenderTarget, DepthTexture, Camera, Scene } from 'three';
-import { WaterFlow } from './WaterFlow';
-export default function waterFlowPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, baseRenderTarget: WebGLRenderTarget, baseDepthTexture: DepthTexture, waterFlow: WaterFlow): void;
+import { WebGLRenderer, WebGLRenderTarget, DepthTexture, Camera, Scene } from 'three';
+import { WaterFlow } from './WaterFlow';
+export default function waterFlowPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, baseRenderTarget: WebGLRenderTarget, baseDepthTexture: DepthTexture, waterFlow: WaterFlow): void;

package/WaterFlow/waterFlowPass.js

@@ -1,20 +1,20 @@
-export default function waterFlowPass(renderer, camera, scene, baseRenderTarget, baseDepthTexture, waterFlow) {
-    if (!waterFlow || !waterFlow.supported)
-        return;
-    // scene 仅占位以维持与 three-base 其它 pass 一致的参数形态；水面在 externalBase
-    // 模式下只消费基础纹理，不自渲染场景。
-    void scene;
-    void baseRenderTarget;
-    // 当前渲染目标（ThreeBase 此处即 screenRenderTarget，已是经 ssao/覆盖/磨砂后的合成画面）。
-    // 把它作为「场景颜色」注入给水面：水面内部先把当前目标拷到临时目标，再合成回当前目标，
-    // 既避免「读当前目标写当前目标」的反馈未定义行为，又完整保留既有后处理（不会被原始 base 覆盖）。
-    const originTarget = renderer.getRenderTarget();
-    const sceneColor = originTarget ? originTarget.texture : null;
-    waterFlow.renderInto(renderer, {
-        colorTexture: sceneColor ?? baseRenderTarget.texture,
-        depthTexture: baseDepthTexture,
-        depthMode: 'logarithmic',
-        outputTarget: originTarget,
-        camera,
-    });
-}
+export default function waterFlowPass(renderer, camera, scene, baseRenderTarget, baseDepthTexture, waterFlow) {
+    if (!waterFlow || !waterFlow.supported)
+        return;
+    // scene 仅占位以维持与 three-base 其它 pass 一致的参数形态；水面在 externalBase
+    // 模式下只消费基础纹理，不自渲染场景。
+    void scene;
+    void baseRenderTarget;
+    // 当前渲染目标（ThreeBase 此处即 screenRenderTarget，已是经 ssao/覆盖/磨砂后的合成画面）。
+    // 把它作为「场景颜色」注入给水面：水面内部先把当前目标拷到临时目标，再合成回当前目标，
+    // 既避免「读当前目标写当前目标」的反馈未定义行为，又完整保留既有后处理（不会被原始 base 覆盖）。
+    const originTarget = renderer.getRenderTarget();
+    const sceneColor = originTarget ? originTarget.texture : null;
+    waterFlow.renderInto(renderer, {
+        colorTexture: sceneColor ?? baseRenderTarget.texture,
+        depthTexture: baseDepthTexture,
+        depthMode: 'logarithmic',
+        outputTarget: originTarget,
+        camera,
+    });
+}

package/WaterFlow/waterFlowPass.ts

@@ -1,40 +1,40 @@
-/*
- * WaterFlow 函数式后处理入口（与 three-base 的 *_pass.ts 同形态）。
- *
- * 直接消费 baseRenderTarget.texture + baseDepthTexture（three-base 对数深度），
- * 把屏幕空间水面合成回当前渲染目标，复用 three-base「共用基础纹理/基础深度图」的
- * 后处理方案 —— 水面 pass 不自渲染主场景，省掉一遍全场景绘制。
- *
- * 调用位置（ThreeBase.render）：在 frosted_glass_pass 之后、screenCopy 之前，
- * 此时当前渲染目标仍是 baseRenderTarget，水面把结果合成回它，后续 screenCopy /
- * screenBloom 会自然带上水面（水面高光也能被 bloom 处理）。
- */
-import { WebGLRenderer, WebGLRenderTarget, DepthTexture, Camera, Scene, Texture } from 'three';
-import { WaterFlow } from './WaterFlow';
-
-export default function waterFlowPass(
-  renderer: WebGLRenderer,
-  camera: Camera,
-  scene: Scene,
-  baseRenderTarget: WebGLRenderTarget,
-  baseDepthTexture: DepthTexture,
-  waterFlow: WaterFlow,
-): void {
-  if (!waterFlow || !waterFlow.supported) return;
-  // scene 仅占位以维持与 three-base 其它 pass 一致的参数形态；水面在 externalBase
-  // 模式下只消费基础纹理，不自渲染场景。
-  void scene;
-  void baseRenderTarget;
-  // 当前渲染目标（ThreeBase 此处即 screenRenderTarget，已是经 ssao/覆盖/磨砂后的合成画面）。
-  // 把它作为「场景颜色」注入给水面：水面内部先把当前目标拷到临时目标，再合成回当前目标，
-  // 既避免「读当前目标写当前目标」的反馈未定义行为，又完整保留既有后处理（不会被原始 base 覆盖）。
-  const originTarget = renderer.getRenderTarget();
-  const sceneColor: Texture | null = originTarget ? originTarget.texture : null;
-  waterFlow.renderInto(renderer, {
-    colorTexture: sceneColor ?? baseRenderTarget.texture,
-    depthTexture: baseDepthTexture,
-    depthMode: 'logarithmic',
-    outputTarget: originTarget,
-    camera,
-  });
-}
+/*
+ * WaterFlow 函数式后处理入口（与 three-base 的 *_pass.ts 同形态）。
+ *
+ * 直接消费 baseRenderTarget.texture + baseDepthTexture（three-base 对数深度），
+ * 把屏幕空间水面合成回当前渲染目标，复用 three-base「共用基础纹理/基础深度图」的
+ * 后处理方案 —— 水面 pass 不自渲染主场景，省掉一遍全场景绘制。
+ *
+ * 调用位置（ThreeBase.render）：在 frosted_glass_pass 之后、screenCopy 之前，
+ * 此时当前渲染目标仍是 baseRenderTarget，水面把结果合成回它，后续 screenCopy /
+ * screenBloom 会自然带上水面（水面高光也能被 bloom 处理）。
+ */
+import { WebGLRenderer, WebGLRenderTarget, DepthTexture, Camera, Scene, Texture } from 'three';
+import { WaterFlow } from './WaterFlow';
+
+export default function waterFlowPass(
+  renderer: WebGLRenderer,
+  camera: Camera,
+  scene: Scene,
+  baseRenderTarget: WebGLRenderTarget,
+  baseDepthTexture: DepthTexture,
+  waterFlow: WaterFlow,
+): void {
+  if (!waterFlow || !waterFlow.supported) return;
+  // scene 仅占位以维持与 three-base 其它 pass 一致的参数形态；水面在 externalBase
+  // 模式下只消费基础纹理，不自渲染场景。
+  void scene;
+  void baseRenderTarget;
+  // 当前渲染目标（ThreeBase 此处即 screenRenderTarget，已是经 ssao/覆盖/磨砂后的合成画面）。
+  // 把它作为「场景颜色」注入给水面：水面内部先把当前目标拷到临时目标，再合成回当前目标，
+  // 既避免「读当前目标写当前目标」的反馈未定义行为，又完整保留既有后处理（不会被原始 base 覆盖）。
+  const originTarget = renderer.getRenderTarget();
+  const sceneColor: Texture | null = originTarget ? originTarget.texture : null;
+  waterFlow.renderInto(renderer, {
+    colorTexture: sceneColor ?? baseRenderTarget.texture,
+    depthTexture: baseDepthTexture,
+    depthMode: 'logarithmic',
+    outputTarget: originTarget,
+    camera,
+  });
+}

package/collisionOBB.d.ts

@@ -1,42 +1,42 @@
-/**
- * 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 declare const CAPSULE_DEPTH_EPS = 0.0001;
-/**
- * 竖直胶囊 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 declare function capsuleVsOBB(px: number, pz: number, radius: number, yBottom: number, yTop: number, obb: OBB, normalOut: Vector3, contactOut: Vector3): number;
+/**
+ * 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 declare const CAPSULE_DEPTH_EPS = 0.0001;
+/**
+ * 竖直胶囊 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 declare function capsuleVsOBB(px: number, pz: number, radius: number, yBottom: number, yTop: number, obb: OBB, normalOut: Vector3, contactOut: Vector3): number;