@esengine/pathfinding 12.1.2 → 13.0.0

package/dist/{IIncrementalPathfinding-3qs7e_pO.d.ts → KDTree-Bw4Faf2O.d.ts}

@@ -1,3 +1,5 @@
+import { IVector2 } from '@esengine/ecs-framework-math';
+
 /**
  * @zh 寻路系统核心接口
  * @en Pathfinding System Core Interfaces
@@ -447,4 +449,372 @@ declare const DEFAULT_REPLANNING_CONFIG: IReplanningConfig;
  */
 declare const EMPTY_PROGRESS: IPathProgress;
 
-export { DEFAULT_PATHFINDING_OPTIONS as D, EMPTY_PATH_RESULT as E, type HeuristicFunction as H, type IPathfinder as I, type LineOfSightCheck as L, PathfindingState as P, type IPathfindingMap as a, type IPathfindingOptions as b, type IPathResult as c, type IPathNode as d, type IPoint as e, type IIncrementalPathfinder as f, type IIncrementalPathfindingOptions as g, type IPathRequest as h, type IPathProgress as i, type IIncrementalPathResult as j, type IPathValidator as k, type IPathValidationResult as l, type IPathSmoother as m, createPoint as n, manhattanDistance as o, euclideanDistance as p, chebyshevDistance as q, octileDistance as r, type IReplanningConfig as s, DEFAULT_REPLANNING_CONFIG as t, EMPTY_PROGRESS as u };
+/**
+ * @zh ORCA 局部避让接口定义
+ * @en ORCA Local Avoidance Interface Definitions
+ */
+
+/**
+ * @zh ORCA 约束线（半平面）
+ * @en ORCA constraint line (half-plane)
+ *
+ * @zh 约束线定义了一个半平面，代理的速度必须在允许的一侧
+ * @en A constraint line defines a half-plane, agent's velocity must be on the allowed side
+ */
+interface IORCALine {
+    /**
+     * @zh 线上的一点
+     * @en A point on the line
+     */
+    point: IVector2;
+    /**
+     * @zh 线的方向向量（单位向量，允许区域在左侧）
+     * @en Direction vector of the line (unit vector, allowed region is on the left)
+     */
+    direction: IVector2;
+}
+/**
+ * @zh 避让代理数据
+ * @en Avoidance agent data
+ *
+ * @zh 包含计算 ORCA 所需的所有代理信息
+ * @en Contains all agent information needed for ORCA computation
+ */
+interface IAvoidanceAgent {
+    /**
+     * @zh 代理唯一标识
+     * @en Unique identifier for the agent
+     */
+    id: number;
+    /**
+     * @zh 当前位置
+     * @en Current position
+     */
+    position: IVector2;
+    /**
+     * @zh 当前速度
+     * @en Current velocity
+     */
+    velocity: IVector2;
+    /**
+     * @zh 首选速度（通常指向目标方向）
+     * @en Preferred velocity (usually towards target)
+     */
+    preferredVelocity: IVector2;
+    /**
+     * @zh 代理半径
+     * @en Agent radius
+     */
+    radius: number;
+    /**
+     * @zh 最大速度
+     * @en Maximum speed
+     */
+    maxSpeed: number;
+    /**
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     */
+    neighborDist: number;
+    /**
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors to consider
+     */
+    maxNeighbors: number;
+    /**
+     * @zh 代理避让时间视野（秒）
+     * @en Time horizon for agent avoidance (seconds)
+     *
+     * @zh 更大的值会让代理更早开始避让
+     * @en Larger values make agents start avoiding earlier
+     */
+    timeHorizon: number;
+    /**
+     * @zh 障碍物避让时间视野（秒）
+     * @en Time horizon for obstacle avoidance (seconds)
+     */
+    timeHorizonObst: number;
+}
+/**
+ * @zh 静态障碍物（多边形）
+ * @en Static obstacle (polygon)
+ *
+ * @zh 重要：顶点必须按逆时针（CCW）顺序排列（在 Y 轴向上的坐标系中）
+ * @en Important: Vertices must be in counter-clockwise (CCW) order (in Y-axis up coordinate system)
+ *
+ * @zh 可以使用 math 库中的 Polygon.ensureCCW() 确保正确顺序
+ * @en Use Polygon.ensureCCW() from math library to ensure correct order
+ *
+ * @zh 在 Y 轴向下的坐标系（如 Canvas）中，视觉上的 CCW 需要传入 yAxisDown=true
+ * @en In Y-axis down coordinate system (like Canvas), use yAxisDown=true for visual CCW
+ *
+ * @example
+ * ```typescript
+ * import { Polygon } from '@esengine/ecs-framework-math';
+ *
+ * // 标准 Y 轴向上坐标系
+ * const obstacle: IObstacle = {
+ *     vertices: Polygon.ensureCCW(myVertices)
+ * };
+ *
+ * // Canvas/屏幕坐标系（Y 轴向下）
+ * const obstacle: IObstacle = {
+ *     vertices: Polygon.ensureCCW(myVertices, true)
+ * };
+ * ```
+ */
+interface IObstacle {
+    /**
+     * @zh 顶点列表（逆时针顺序，Y 轴向上坐标系）
+     * @en Vertex list (counter-clockwise order in Y-axis up coordinate system)
+     */
+    vertices: IVector2[];
+}
+/**
+ * @zh ORCA 求解器配置
+ * @en ORCA solver configuration
+ */
+interface IORCASolverConfig {
+    /**
+     * @zh 默认时间视野（代理）
+     * @en Default time horizon for agents
+     */
+    defaultTimeHorizon?: number;
+    /**
+     * @zh 默认时间视野（障碍物）
+     * @en Default time horizon for obstacles
+     */
+    defaultTimeHorizonObst?: number;
+    /**
+     * @zh 时间步长（用于碰撞响应）
+     * @en Time step (for collision response)
+     */
+    timeStep?: number;
+    /**
+     * @zh 数值精度阈值
+     * @en Numerical precision threshold
+     */
+    epsilon?: number;
+}
+/**
+ * @zh ORCA 求解结果
+ * @en ORCA solve result
+ */
+interface IORCAResult {
+    /**
+     * @zh 计算得到的新速度
+     * @en Computed new velocity
+     */
+    velocity: IVector2;
+    /**
+     * @zh 是否找到可行解
+     * @en Whether a feasible solution was found
+     */
+    feasible: boolean;
+    /**
+     * @zh 生成的 ORCA 约束线数量
+     * @en Number of ORCA lines generated
+     */
+    numLines: number;
+}
+/**
+ * @zh ORCA 求解器接口
+ * @en ORCA solver interface
+ */
+interface IORCASolver {
+    /**
+     * @zh 计算代理的新速度
+     * @en Compute new velocity for agent
+     *
+     * @param agent - @zh 当前代理 @en Current agent
+     * @param neighbors - @zh 邻近代理列表 @en List of neighbor agents
+     * @param obstacles - @zh 静态障碍物列表 @en List of static obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 新速度 @en New velocity
+     */
+    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+}
+/**
+ * @zh 邻居查询结果
+ * @en Neighbor query result
+ */
+interface INeighborResult {
+    /**
+     * @zh 代理数据
+     * @en Agent data
+     */
+    agent: IAvoidanceAgent;
+    /**
+     * @zh 距离的平方
+     * @en Squared distance
+     */
+    distanceSq: number;
+}
+/**
+ * @zh 空间索引接口（用于快速邻居查询）
+ * @en Spatial index interface (for fast neighbor queries)
+ */
+interface ISpatialIndex {
+    /**
+     * @zh 构建空间索引
+     * @en Build spatial index
+     *
+     * @param agents - @zh 代理列表 @en List of agents
+     */
+    build(agents: readonly IAvoidanceAgent[]): void;
+    /**
+     * @zh 查询指定范围内的邻居
+     * @en Query neighbors within specified range
+     *
+     * @param position - @zh 查询位置 @en Query position
+     * @param radius - @zh 查询半径 @en Query radius
+     * @param maxResults - @zh 最大返回数量 @en Maximum number of results
+     * @param excludeId - @zh 排除的代理 ID @en Agent ID to exclude
+     * @returns @zh 邻居列表（按距离排序）@en List of neighbors (sorted by distance)
+     */
+    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    /**
+     * @zh 清空索引
+     * @en Clear the index
+     */
+    clear(): void;
+}
+/**
+ * @zh 默认 ORCA 求解器配置
+ * @en Default ORCA solver configuration
+ */
+declare const DEFAULT_ORCA_CONFIG: Required<IORCASolverConfig>;
+/**
+ * @zh 默认代理参数
+ * @en Default agent parameters
+ */
+declare const DEFAULT_AGENT_PARAMS: {
+    radius: number;
+    maxSpeed: number;
+    neighborDist: number;
+    maxNeighbors: number;
+    timeHorizon: number;
+    timeHorizonObst: number;
+};
+
+/**
+ * @zh ORCA 避让算法求解器
+ * @en ORCA Avoidance Algorithm Solver
+ *
+ * @zh 实现最优互惠碰撞避免（ORCA）算法，用于多代理局部避让
+ * @en Implements Optimal Reciprocal Collision Avoidance (ORCA) algorithm for multi-agent local avoidance
+ */
+
+/**
+ * @zh ORCA 求解器实现
+ * @en ORCA Solver implementation
+ *
+ * @zh 实现最优互惠碰撞避免算法，计算代理的安全速度
+ * @en Implements Optimal Reciprocal Collision Avoidance algorithm to compute safe velocities for agents
+ */
+declare class ORCASolver implements IORCASolver {
+    private readonly config;
+    constructor(config?: IORCASolverConfig);
+    /**
+     * @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
+     */
+    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+    /**
+     * @zh 创建代理间的 ORCA 约束线
+     * @en Create ORCA constraint lines for agent-agent avoidance
+     */
+    private createAgentORCALines;
+    /**
+     * @zh 创建障碍物的 ORCA 约束线
+     * @en Create ORCA constraint lines for obstacle avoidance
+     */
+    private createObstacleORCALines;
+}
+/**
+ * @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 KD-Tree 空间索引
+ * @en KD-Tree spatial index
+ *
+ * @zh 每帧重建，支持高效的范围查询
+ * @en Rebuilt every frame, supports efficient range queries
+ */
+declare class KDTree implements ISpatialIndex {
+    private agents;
+    private agentIndices;
+    private nodes;
+    /**
+     * @zh 最大叶节点大小
+     * @en Maximum leaf size
+     */
+    private readonly maxLeafSize;
+    /**
+     * @zh 构建 KD-Tree
+     * @en Build KD-Tree
+     */
+    build(agents: readonly IAvoidanceAgent[]): void;
+    /**
+     * @zh 递归构建 KD-Tree
+     * @en Recursively build KD-Tree
+     */
+    private buildRecursive;
+    /**
+     * @zh 按 X 坐标排序
+     * @en Sort by X coordinate
+     */
+    private sortByX;
+    /**
+     * @zh 按 Y 坐标排序
+     * @en Sort by Y coordinate
+     */
+    private sortByY;
+    /**
+     * @zh 查询邻居
+     * @en Query neighbors
+     */
+    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    /**
+     * @zh 递归查询
+     * @en Recursive query
+     */
+    private queryRecursive;
+    /**
+     * @zh 清空索引
+     * @en Clear the index
+     */
+    clear(): void;
+    /**
+     * @zh 获取代理数量
+     * @en Get agent count
+     */
+    get agentCount(): number;
+}
+/**
+ * @zh 创建 KD-Tree
+ * @en Create KD-Tree
+ */
+declare function createKDTree(): KDTree;
+
+export { type IORCASolver as A, type INeighborResult as B, type ISpatialIndex as C, DEFAULT_PATHFINDING_OPTIONS as D, EMPTY_PATH_RESULT as E, DEFAULT_ORCA_CONFIG as F, DEFAULT_AGENT_PARAMS as G, type HeuristicFunction as H, type IPathfinder as I, createORCASolver as J, KDTree as K, type LineOfSightCheck as L, createKDTree as M, ORCASolver as O, PathfindingState as P, type IPathfindingMap as a, type IPathfindingOptions as b, type IPathResult as c, type IPathNode as d, type IPoint as e, type IIncrementalPathfinder as f, type IIncrementalPathfindingOptions as g, type IPathRequest as h, type IPathProgress as i, type IIncrementalPathResult as j, type IPathValidator as k, type IPathValidationResult as l, type IPathSmoother as m, type IORCALine as n, createPoint as o, manhattanDistance as p, euclideanDistance as q, chebyshevDistance as r, octileDistance as s, type IReplanningConfig as t, DEFAULT_REPLANNING_CONFIG as u, EMPTY_PROGRESS as v, type IAvoidanceAgent as w, type IObstacle as x, type IORCASolverConfig as y, type IORCAResult as z };