@esengine/pathfinding 13.1.0 → 13.2.0

package/dist/index.d.ts

@@ -1080,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
  */
 
 /**
@@ -1100,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;
     /**
@@ -1109,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* 配置
@@ -1137,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;
     /**
@@ -1183,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;
 }
 /**