@esengine/pathfinding 13.2.0 → 13.3.1

package/dist/{KDTree-2rs2EXvm.d.ts → CollisionResolver-CSgWsegP.d.ts}

@@ -182,6 +182,16 @@ interface IORCASolverConfig {
      * @en Numerical precision threshold
      */
     epsilon?: number;
+    /**
+     * @zh 是否使用 Y 轴向下的坐标系（如 Canvas/屏幕坐标）
+     * @en Whether using Y-axis down coordinate system (like Canvas/screen coords)
+     *
+     * @zh 这会影响障碍物顶点顺序的判断（CCW 检测）
+     * @en This affects obstacle vertex order detection (CCW check)
+     *
+     * @default false
+     */
+    yAxisDown?: boolean;
 }
 /**
  * @zh ORCA 求解结果
@@ -194,8 +204,8 @@ interface IORCAResult {
      */
     velocity: IVector2;
     /**
-     * @zh 是否找到可行解
-     * @en Whether a feasible solution was found
+     * @zh 是否找到可行解（满足所有约束）
+     * @en Whether a feasible solution was found (satisfies all constraints)
      */
     feasible: boolean;
     /**
@@ -203,6 +213,11 @@ interface IORCAResult {
      * @en Number of ORCA lines generated
      */
     numLines: number;
+    /**
+     * @zh 违反的约束数量
+     * @en Number of violated constraints
+     */
+    violatedConstraints: number;
 }
 /**
  * @zh ORCA 求解器接口
@@ -285,123 +300,144 @@ declare const DEFAULT_AGENT_PARAMS: {
 };
 
 /**
- * @zh ORCA 避让算法求解器
- * @en ORCA Avoidance Algorithm Solver
+ * @zh 碰撞解决器
+ * @en Collision Resolver
  *
- * @zh 实现最优互惠碰撞避免（ORCA）算法，用于多代理局部避让
- * @en Implements Optimal Reciprocal Collision Avoidance (ORCA) algorithm for multi-agent local avoidance
+ * @zh 提供位置级别的硬碰撞检测和解决，作为 ORCA 的补充保护层
+ * @en Provides position-level hard collision detection and resolution as a supplementary protection layer for ORCA
  */
 
 /**
- * @zh ORCA 求解器实现
- * @en ORCA Solver implementation
- *
- * @zh 实现最优互惠碰撞避免算法，计算代理的安全速度
- * @en Implements Optimal Reciprocal Collision Avoidance algorithm to compute safe velocities for agents
+ * @zh 碰撞检测结果
+ * @en Collision detection result
  */
-declare class ORCASolver implements IORCASolver {
-    private readonly config;
-    constructor(config?: IORCASolverConfig);
+interface ICollisionResult {
     /**
-     * @zh 计算代理的新速度
-     * @en Compute new velocity for agent
-     *
-     * @param agent - @zh 当前代理 @en Current agent
-     * @param neighbors - @zh 邻近代理列表 @en List of neighboring agents
-     * @param obstacles - @zh 障碍物列表 @en List of obstacles
-     * @param deltaTime - @zh 时间步长 @en Time step
-     * @returns @zh 计算得到的新速度 @en Computed new velocity
+     * @zh 是否发生碰撞
+     * @en Whether collision occurred
      */
-    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+    collided: boolean;
     /**
-     * @zh 创建代理间的 ORCA 约束线
-     * @en Create ORCA constraint lines for agent-agent avoidance
+     * @zh 穿透深度
+     * @en Penetration depth
      */
-    private createAgentORCALines;
+    penetration: number;
     /**
-     * @zh 创建障碍物的 ORCA 约束线
-     * @en Create ORCA constraint lines for obstacle avoidance
+     * @zh 碰撞法线（从障碍物指向代理）
+     * @en Collision normal (pointing from obstacle to agent)
      */
-    private createObstacleORCALines;
+    normal: IVector2;
+    /**
+     * @zh 最近点
+     * @en Closest point on obstacle
+     */
+    closestPoint: IVector2;
 }
 /**
- * @zh 创建 ORCA 求解器
- * @en Create ORCA solver
- *
- * @param config - @zh 可选配置参数 @en Optional configuration parameters
- * @returns @zh ORCA 求解器实例 @en ORCA solver instance
- */
-declare function createORCASolver(config?: IORCASolverConfig): ORCASolver;
-
-/**
- * @zh KD-Tree 空间索引
- * @en KD-Tree Spatial Index
- *
- * @zh 用于快速查询指定范围内的邻近代理
- * @en Used for fast neighbor queries within specified range
+ * @zh 空碰撞结果
+ * @en Empty collision result
  */
-
+declare const EMPTY_COLLISION: ICollisionResult;
 /**
- * @zh KD-Tree 空间索引
- * @en KD-Tree spatial index
- *
- * @zh 每帧重建，支持高效的范围查询
- * @en Rebuilt every frame, supports efficient range queries
+ * @zh 碰撞解决器配置
+ * @en Collision resolver configuration
  */
-declare class KDTree implements ISpatialIndex {
-    private agents;
-    private agentIndices;
-    private nodes;
+interface ICollisionResolverConfig {
     /**
-     * @zh 最大叶节点大小
-     * @en Maximum leaf size
+     * @zh 碰撞响应系数（0-1，1 表示完全推出）
+     * @en Collision response factor (0-1, 1 means fully push out)
      */
-    private readonly maxLeafSize;
+    responseFactor?: number;
     /**
-     * @zh 构建 KD-Tree
-     * @en Build KD-Tree
+     * @zh 安全边距（额外距离）
+     * @en Safety margin (extra distance)
      */
-    build(agents: readonly IAvoidanceAgent[]): void;
-    /**
-     * @zh 递归构建 KD-Tree
-     * @en Recursively build KD-Tree
-     */
-    private buildRecursive;
+    safetyMargin?: number;
+}
+/**
+ * @zh 默认配置
+ * @en Default configuration
+ */
+declare const DEFAULT_COLLISION_CONFIG: Required<ICollisionResolverConfig>;
+/**
+ * @zh 碰撞解决器
+ * @en Collision Resolver
+ *
+ * @zh 提供位置级别的硬碰撞检测和解决
+ * @en Provides position-level hard collision detection and resolution
+ */
+declare class CollisionResolver {
+    private readonly config;
+    constructor(config?: ICollisionResolverConfig);
     /**
-     * @zh 按 X 坐标排序
-     * @en Sort by X coordinate
+     * @zh 检测圆与单个障碍物的碰撞
+     * @en Detect collision between circle and single obstacle
+     *
+     * @param position - @zh 圆心位置 @en Circle center position
+     * @param radius - @zh 圆半径 @en Circle radius
+     * @param obstacle - @zh 障碍物 @en Obstacle
+     * @returns @zh 碰撞结果 @en Collision result
      */
-    private sortByX;
+    detectCollision(position: IVector2, radius: number, obstacle: IObstacle): ICollisionResult;
     /**
-     * @zh 按 Y 坐标排序
-     * @en Sort by Y coordinate
+     * @zh 检测圆与所有障碍物的碰撞
+     * @en Detect collision between circle and all obstacles
+     *
+     * @param position - @zh 圆心位置 @en Circle center position
+     * @param radius - @zh 圆半径 @en Circle radius
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @returns @zh 最严重的碰撞结果 @en Most severe collision result
      */
-    private sortByY;
+    detectCollisions(position: IVector2, radius: number, obstacles: readonly IObstacle[]): ICollisionResult;
     /**
-     * @zh 查询邻居
-     * @en Query neighbors
+     * @zh 解决碰撞，返回修正后的位置
+     * @en Resolve collision, return corrected position
+     *
+     * @param position - @zh 当前位置 @en Current position
+     * @param radius - @zh 半径 @en Radius
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @returns @zh 修正后的位置 @en Corrected position
      */
-    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    resolveCollision(position: IVector2, radius: number, obstacles: readonly IObstacle[]): IVector2;
     /**
-     * @zh 递归查询
-     * @en Recursive query
+     * @zh 验证速度是否会导致碰撞，返回安全速度
+     * @en Validate velocity won't cause collision, return safe velocity
+     *
+     * @param position - @zh 当前位置 @en Current position
+     * @param velocity - @zh 目标速度 @en Target velocity
+     * @param radius - @zh 半径 @en Radius
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 安全速度 @en Safe velocity
      */
-    private queryRecursive;
+    validateVelocity(position: IVector2, velocity: IVector2, radius: number, obstacles: readonly IObstacle[], deltaTime: number): IVector2;
     /**
-     * @zh 清空索引
-     * @en Clear the index
+     * @zh 检测两个代理之间的碰撞
+     * @en Detect collision between two agents
+     *
+     * @param posA - @zh 代理 A 位置 @en Agent A position
+     * @param radiusA - @zh 代理 A 半径 @en Agent A radius
+     * @param posB - @zh 代理 B 位置 @en Agent B position
+     * @param radiusB - @zh 代理 B 半径 @en Agent B radius
+     * @returns @zh 碰撞结果 @en Collision result
      */
-    clear(): void;
+    detectAgentCollision(posA: IVector2, radiusA: number, posB: IVector2, radiusB: number): ICollisionResult;
     /**
-     * @zh 获取代理数量
-     * @en Get agent count
+     * @zh 解决代理之间的碰撞
+     * @en Resolve collision between agents
+     *
+     * @param posA - @zh 代理 A 位置 @en Agent A position
+     * @param radiusA - @zh 代理 A 半径 @en Agent A radius
+     * @param posB - @zh 代理 B 位置 @en Agent B position
+     * @param radiusB - @zh 代理 B 半径 @en Agent B radius
+     * @returns @zh 修正后的位置 [A, B] @en Corrected positions [A, B]
      */
-    get agentCount(): number;
+    resolveAgentCollision(posA: IVector2, radiusA: number, posB: IVector2, radiusB: number): [IVector2, IVector2];
 }
 /**
- * @zh 创建 KD-Tree
- * @en Create KD-Tree
+ * @zh 创建碰撞解决器
+ * @en Create collision resolver
  */
-declare function createKDTree(): KDTree;
+declare function createCollisionResolver(config?: ICollisionResolverConfig): CollisionResolver;
 
-export { DEFAULT_ORCA_CONFIG as D, type IORCALine as I, KDTree as K, ORCASolver as O, type IAvoidanceAgent as a, type IObstacle as b, type IORCASolverConfig as c, type IORCAResult as d, type IORCASolver as e, type INeighborResult as f, type ISpatialIndex as g, DEFAULT_AGENT_PARAMS as h, createORCASolver as i, createKDTree as j, type IObstacleVertex as k };
+export { CollisionResolver as C, DEFAULT_ORCA_CONFIG as D, EMPTY_COLLISION as E, type IORCALine as I, type IAvoidanceAgent as a, type IObstacle as b, type IORCASolverConfig as c, type IORCAResult as d, type IORCASolver as e, type INeighborResult as f, type ISpatialIndex as g, type ICollisionResult as h, type ICollisionResolverConfig as i, DEFAULT_AGENT_PARAMS as j, DEFAULT_COLLISION_CONFIG as k, createCollisionResolver as l, type IObstacleVertex as m };