@esengine/pathfinding 13.0.0 → 13.2.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { I as IPathfinder, a as IPathfindingMap, b as IPathfindingOptions, c as IPathResult, H as HeuristicFunction, d as IPathNode, e as IPoint, f as IIncrementalPathfinder, g as IIncrementalPathfindingOptions, h as IPathRequest, i as IPathProgress, j as IIncrementalPathResult, k as IPathValidator, l as IPathValidationResult, m as IPathSmoother, n as IORCALine } from './KDTree-Bw4Faf2O.js';
-export { G as DEFAULT_AGENT_PARAMS, F as DEFAULT_ORCA_CONFIG, D as DEFAULT_PATHFINDING_OPTIONS, u as DEFAULT_REPLANNING_CONFIG, E as EMPTY_PATH_RESULT, v as EMPTY_PROGRESS, w as IAvoidanceAgent, B as INeighborResult, z as IORCAResult, A as IORCASolver, y as IORCASolverConfig, x as IObstacle, t as IReplanningConfig, C as ISpatialIndex, K as KDTree, L as LineOfSightCheck, O as ORCASolver, P as PathfindingState, r as chebyshevDistance, M as createKDTree, J as createORCASolver, o as createPoint, q as euclideanDistance, p as manhattanDistance, s as octileDistance } from './KDTree-Bw4Faf2O.js';
-import { IVector2, Vector2 } from '@esengine/ecs-framework-math';
+import { I as IPathfinder, a as IPathfindingMap, b as IPathfindingOptions, c as IPathResult, H as HeuristicFunction, d as IPathNode, e as IPoint, f as IIncrementalPathfinder, g as IIncrementalPathfindingOptions, h as IPathRequest, i as IPathProgress, j as IIncrementalPathResult, k as IPathValidator, l as IPathValidationResult, m as IPathSmoother } from './IIncrementalPathfinding-3qs7e_pO.js';
+export { D as DEFAULT_PATHFINDING_OPTIONS, t as DEFAULT_REPLANNING_CONFIG, E as EMPTY_PATH_RESULT, u as EMPTY_PROGRESS, s as IReplanningConfig, L as LineOfSightCheck, P as PathfindingState, q as chebyshevDistance, n as createPoint, p as euclideanDistance, o as manhattanDistance, r as octileDistance } from './IIncrementalPathfinding-3qs7e_pO.js';
+export { h as DEFAULT_AGENT_PARAMS, D as DEFAULT_ORCA_CONFIG, a as IAvoidanceAgent, f as INeighborResult, I as IORCALine, d as IORCAResult, e as IORCASolver, c as IORCASolverConfig, b as IObstacle, g as ISpatialIndex, K as KDTree, O as ORCASolver, j as createKDTree, i as createORCASolver } from './KDTree-2rs2EXvm.js';
+export { s as solveORCALinearProgram } from './LinearProgram-DyD3pI6v.js';
 export { IVector2 } from '@esengine/ecs-framework-math';
 
 /**
@@ -1079,13 +1080,15 @@ declare function createJPSPathfinder(map: IPathfindingMap): JPSPathfinder;
  * 1. 将地图划分为集群 (clusters)
  * 2. 在集群边界检测入口点 (entrances)
  * 3. 构建抽象图 (abstract graph) 连接入口点
- * 4. 先在抽象图上寻路，再细化为详细路径
+ * 4. 预计算集群内入口点之间的真实路径代价
+ * 5. 先在抽象图上寻路，再利用缓存细化为详细路径
  *
  * @en How it works:
  * 1. Divide map into clusters
  * 2. Detect entrances at cluster boundaries
  * 3. Build abstract graph connecting entrances
- * 4. First find path on abstract graph, then refine to detailed path
+ * 4. Precompute actual path costs between entrances within clusters
+ * 5. First find path on abstract graph, then refine using cached paths
  */
 
 /**
@@ -1099,8 +1102,8 @@ interface IHPAConfig {
      */
     clusterSize: number;
     /**
-     * @zh 最大入口宽度（超过此宽度会拆分为多个入口）
-     * @en Maximum entrance width (entrances wider than this will be split)
+     * @zh 最大入口宽度（超过此宽度会拆分或使用端点策略）
+     * @en Maximum entrance width (entrances wider than this will be split or use endpoint strategy)
      */
     maxEntranceWidth: number;
     /**
@@ -1108,6 +1111,16 @@ interface IHPAConfig {
      * @en Whether to enable internal path caching
      */
     cacheInternalPaths: boolean;
+    /**
+     * @zh 入口策略：'middle' 在中间放节点，'end' 在宽入口两端各放节点
+     * @en Entrance strategy: 'middle' places node at center, 'end' places nodes at both ends for wide entrances
+     */
+    entranceStrategy?: 'middle' | 'end';
+    /**
+     * @zh 是否延迟计算 intra-edges（大幅加速预处理，首次查询时计算真实路径）
+     * @en Whether to lazily compute intra-edges (greatly speeds up preprocessing, computes actual paths on first query)
+     */
+    lazyIntraEdges?: boolean;
 }
 /**
  * @zh 默认 HPA* 配置
@@ -1136,24 +1149,24 @@ declare const DEFAULT_HPA_CONFIG: IHPAConfig;
 declare class HPAPathfinder implements IPathfinder {
     private readonly map;
     private readonly config;
-    private readonly width;
-    private readonly height;
+    private readonly mapWidth;
+    private readonly mapHeight;
     private clusters;
-    private entrances;
-    private abstractNodes;
     private clusterGrid;
-    private nextEntranceId;
+    private clustersX;
+    private clustersY;
+    private abstractNodes;
+    private nodesByCluster;
     private nextNodeId;
-    private internalPathCache;
-    private localPathfinder;
+    private entranceCount;
+    private readonly localPathfinder;
+    private readonly pathCache;
+    private mapVersion;
     private preprocessed;
     constructor(map: IPathfindingMap, config?: Partial<IHPAConfig>);
     /**
      * @zh 预处理地图（构建抽象图）
      * @en Preprocess map (build abstract graph)
-     *
-     * @zh 在地图变化后需要重新调用
-     * @en Need to call again after map changes
      */
     preprocess(): void;
     /**
@@ -1182,22 +1195,110 @@ declare class HPAPathfinder implements IPathfinder {
         cacheSize: number;
     };
     private getMapBounds;
+    /**
+     * @zh 构建集群
+     * @en Build clusters
+     */
     private buildClusters;
-    private findEntrances;
-    private findEntrancesBetween;
-    private createEntrance;
-    private buildAbstractGraph;
+    /**
+     * @zh 检测入口并创建抽象节点
+     * @en Detect entrances and create abstract nodes
+     */
+    private buildEntrances;
+    /**
+     * @zh 检测并创建两个相邻集群之间的入口
+     * @en Detect and create entrances between two adjacent clusters
+     */
+    private detectAndCreateEntrances;
+    /**
+     * @zh 检测边界上的连续可通行区间
+     * @en Detect continuous walkable spans on boundary
+     */
+    private detectEntranceSpans;
+    /**
+     * @zh 为入口区间创建抽象节点
+     * @en Create abstract nodes for entrance span
+     */
+    private createEntranceNodes;
+    /**
+     * @zh 创建抽象节点
+     * @en Create abstract node
+     */
     private createAbstractNode;
-    private connectIntraClusterNodes;
+    /**
+     * @zh 构建所有集群的 intra-edges
+     * @en Build intra-edges for all clusters
+     */
+    private buildIntraEdges;
+    /**
+     * @zh 构建单个集群的 intra-edges
+     * @en Build intra-edges for single cluster
+     */
+    private buildClusterIntraEdges;
+    /**
+     * @zh 延迟构建 intra-edges（只用启发式距离）
+     * @en Build lazy intra-edges (using heuristic distance only)
+     */
+    private buildLazyIntraEdges;
+    /**
+     * @zh 立即构建 intra-edges（计算真实路径）
+     * @en Build eager intra-edges (compute actual paths)
+     */
+    private buildEagerIntraEdges;
+    /**
+     * @zh 按需计算 intra-edge 的真实路径
+     * @en Compute actual path for intra-edge on demand
+     */
+    private computeIntraEdgePath;
+    /**
+     * @zh 获取指定位置的集群
+     * @en Get cluster at position
+     */
     private getClusterAt;
-    private insertTemporaryNode;
-    private removeTemporaryNodes;
-    private searchAbstractGraph;
-    private reconstructAbstractPath;
+    /**
+     * @zh 获取受影响的集群
+     * @en Get affected clusters
+     */
+    private getAffectedClusters;
+    /**
+     * @zh 插入临时节点
+     * @en Insert temporary node
+     */
+    private insertTempNode;
+    /**
+     * @zh 移除临时节点
+     * @en Remove temporary node
+     */
+    private removeTempNode;
+    /**
+     * @zh 在抽象图上进行 A* 搜索
+     * @en Perform A* search on abstract graph
+     */
+    private abstractSearch;
+    /**
+     * @zh 重建抽象路径
+     * @en Reconstruct abstract path
+     */
+    private reconstructPath;
+    /**
+     * @zh 细化抽象路径为具体路径
+     * @en Refine abstract path to concrete path
+     */
     private refinePath;
+    /**
+     * @zh 追加路径（避免重复点）
+     * @en Append path (avoid duplicate points)
+     */
+    private appendPath;
+    /**
+     * @zh 局部寻路
+     * @en Local pathfinding
+     */
     private findLocalPath;
-    private findInternalPath;
-    private calculatePathCost;
+    /**
+     * @zh 启发式函数（Octile 距离）
+     * @en Heuristic function (Octile distance)
+     */
     private heuristic;
 }
 /**
@@ -1433,27 +1534,4 @@ declare function createCatmullRomSmoother(segments?: number, tension?: number):
  */
 declare function createCombinedSmoother(curveSegments?: number, tension?: number): CombinedSmoother;
 
-/**
- * @zh 2D 线性规划求解器
- * @en 2D Linear Programming Solver
- *
- * @zh 用于 ORCA 算法中的速度优化求解
- * @en Used for velocity optimization in ORCA algorithm
- */
-
-/**
- * @zh 求解 ORCA 线性规划
- * @en Solve ORCA Linear Programming
- *
- * @zh 综合使用 2D 和 3D 线性规划求解最优速度
- * @en Use both 2D and 3D LP to solve for optimal velocity
- *
- * @param lines - @zh ORCA 约束线列表 @en List of ORCA constraint lines
- * @param numObstLines - @zh 障碍物约束线数量（优先级更高）@en Number of obstacle lines (higher priority)
- * @param maxSpeed - @zh 最大速度 @en Maximum speed
- * @param preferredVelocity - @zh 首选速度 @en Preferred velocity
- * @returns @zh 计算得到的新速度 @en Computed new velocity
- */
-declare function solveORCALinearProgram(lines: IORCALine[], numObstLines: number, maxSpeed: number, preferredVelocity: IVector2): Vector2;
-
-export { AStarPathfinder, BinaryHeap, CatmullRomSmoother, CombinedSmoother, DEFAULT_GRID_OPTIONS, DEFAULT_HPA_CONFIG, DEFAULT_PATH_CACHE_CONFIG, DIRECTIONS_4, DIRECTIONS_8, GridMap, GridNode, GridPathfinder, type GridPathfinderMode, HPAPathfinder, HeuristicFunction, type IChangeRegion, type IGridMapOptions, type IGridPathfinderConfig, type IHPAConfig, type IHeapIndexable, IIncrementalPathResult, IIncrementalPathfinder, type IIncrementalPathfinderConfig, IIncrementalPathfindingOptions, type INavPolygon, IORCALine, type IObstacleChange, type IPathCacheConfig, IPathNode, IPathProgress, IPathRequest, IPathResult, IPathSmoother, IPathValidationResult, IPathValidator, IPathfinder, IPathfindingMap, IPathfindingOptions, IPoint, type IPortal, IncrementalAStarPathfinder, IndexedBinaryHeap, JPSPathfinder, LineOfSightSmoother, NavMesh, ObstacleChangeManager, PathCache, PathValidator, bresenhamLineOfSight, createAStarPathfinder, createCatmullRomSmoother, createCombinedSmoother, createGridMap, createGridPathfinder, createHPAPathfinder, createIncrementalAStarPathfinder, createJPSPathfinder, createLineOfSightSmoother, createNavMesh, createObstacleChangeManager, createPathCache, createPathValidator, raycastLineOfSight, solveORCALinearProgram };
+export { AStarPathfinder, BinaryHeap, CatmullRomSmoother, CombinedSmoother, DEFAULT_GRID_OPTIONS, DEFAULT_HPA_CONFIG, DEFAULT_PATH_CACHE_CONFIG, DIRECTIONS_4, DIRECTIONS_8, GridMap, GridNode, GridPathfinder, type GridPathfinderMode, HPAPathfinder, HeuristicFunction, type IChangeRegion, type IGridMapOptions, type IGridPathfinderConfig, type IHPAConfig, type IHeapIndexable, IIncrementalPathResult, IIncrementalPathfinder, type IIncrementalPathfinderConfig, IIncrementalPathfindingOptions, type INavPolygon, type IObstacleChange, type IPathCacheConfig, IPathNode, IPathProgress, IPathRequest, IPathResult, IPathSmoother, IPathValidationResult, IPathValidator, IPathfinder, IPathfindingMap, IPathfindingOptions, IPoint, type IPortal, IncrementalAStarPathfinder, IndexedBinaryHeap, JPSPathfinder, LineOfSightSmoother, NavMesh, ObstacleChangeManager, PathCache, PathValidator, bresenhamLineOfSight, createAStarPathfinder, createCatmullRomSmoother, createCombinedSmoother, createGridMap, createGridPathfinder, createHPAPathfinder, createIncrementalAStarPathfinder, createJPSPathfinder, createLineOfSightSmoother, createNavMesh, createObstacleChangeManager, createPathCache, createPathValidator, raycastLineOfSight };