@esengine/pathfinding 12.0.0 → 12.1.0

package/dist/index.d.ts

@@ -1,176 +1,97 @@
-import { BlueprintNodeTemplate, INodeExecutor, BlueprintNode, ExecutionResult } from '@esengine/blueprint';
+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';
 
 /**
- * @zh 寻路系统核心接口
- * @en Pathfinding System Core Interfaces
- */
-/**
- * @zh 2D 坐标点
- * @en 2D coordinate point
- */
-interface IPoint {
-    readonly x: number;
-    readonly y: number;
-}
-/**
- * @zh 创建点
- * @en Create a point
- */
-declare function createPoint(x: number, y: number): IPoint;
-/**
- * @zh 路径节点
- * @en Path node
- */
-interface IPathNode {
-    /** @zh 节点唯一标识 @en Unique node identifier */
-    readonly id: string | number;
-    /** @zh 节点位置 @en Node position */
-    readonly position: IPoint;
-    /** @zh 移动代价 @en Movement cost */
-    readonly cost: number;
-    /** @zh 是否可通行 @en Is walkable */
-    readonly walkable: boolean;
-}
-/**
- * @zh 路径结果
- * @en Path result
- */
-interface IPathResult {
-    /** @zh 是否找到路径 @en Whether path was found */
-    readonly found: boolean;
-    /** @zh 路径点列表 @en List of path points */
-    readonly path: readonly IPoint[];
-    /** @zh 路径总代价 @en Total path cost */
-    readonly cost: number;
-    /** @zh 搜索的节点数 @en Number of nodes searched */
-    readonly nodesSearched: number;
-}
-/**
- * @zh 空路径结果
- * @en Empty path result
- */
-declare const EMPTY_PATH_RESULT: IPathResult;
-/**
- * @zh 寻路地图接口
- * @en Pathfinding map interface
+ * @zh 二叉堆（优先队列）
+ * @en Binary Heap (Priority Queue)
+ *
+ * @zh 用于 A* 算法的高效开放列表
+ * @en Efficient open list for A* algorithm
  */
-interface IPathfindingMap {
+declare class BinaryHeap<T> {
+    private heap;
+    private readonly compare;
     /**
-     * @zh 获取节点的邻居
-     * @en Get neighbors of a node
+     * @zh 创建二叉堆
+     * @en Create binary heap
+     *
+     * @param compare - @zh 比较函数，返回负数表示 a < b @en Compare function, returns negative if a < b
      */
-    getNeighbors(node: IPathNode): IPathNode[];
+    constructor(compare: (a: T, b: T) => number);
     /**
-     * @zh 获取指定位置的节点
-     * @en Get node at position
+     * @zh 堆大小
+     * @en Heap size
      */
-    getNodeAt(x: number, y: number): IPathNode | null;
+    get size(): number;
     /**
-     * @zh 计算两点间的启发式距离
-     * @en Calculate heuristic distance between two points
+     * @zh 是否为空
+     * @en Is empty
      */
-    heuristic(a: IPoint, b: IPoint): number;
+    get isEmpty(): boolean;
     /**
-     * @zh 计算两个邻居节点间的移动代价
-     * @en Calculate movement cost between two neighbor nodes
+     * @zh 插入元素
+     * @en Push element
      */
-    getMovementCost(from: IPathNode, to: IPathNode): number;
+    push(item: T): void;
     /**
-     * @zh 检查位置是否可通行
-     * @en Check if position is walkable
+     * @zh 弹出最小元素
+     * @en Pop minimum element
      */
-    isWalkable(x: number, y: number): boolean;
-}
-/**
- * @zh 启发式函数类型
- * @en Heuristic function type
- */
-type HeuristicFunction = (a: IPoint, b: IPoint) => number;
-/**
- * @zh 曼哈顿距离（4方向移动）
- * @en Manhattan distance (4-directional movement)
- */
-declare function manhattanDistance(a: IPoint, b: IPoint): number;
-/**
- * @zh 欧几里得距离（任意方向移动）
- * @en Euclidean distance (any direction movement)
- */
-declare function euclideanDistance(a: IPoint, b: IPoint): number;
-/**
- * @zh 切比雪夫距离（8方向移动）
- * @en Chebyshev distance (8-directional movement)
- */
-declare function chebyshevDistance(a: IPoint, b: IPoint): number;
-/**
- * @zh 八角距离（8方向移动，对角线代价为 √2）
- * @en Octile distance (8-directional, diagonal cost √2)
- */
-declare function octileDistance(a: IPoint, b: IPoint): number;
-/**
- * @zh 寻路配置
- * @en Pathfinding options
- */
-interface IPathfindingOptions {
-    /** @zh 最大搜索节点数 @en Maximum nodes to search */
-    maxNodes?: number;
-    /** @zh 启发式权重 (>1 更快但可能非最优) @en Heuristic weight (>1 faster but may be suboptimal) */
-    heuristicWeight?: number;
-    /** @zh 是否允许对角移动 @en Allow diagonal movement */
-    allowDiagonal?: boolean;
-    /** @zh 是否避免穿角 @en Avoid corner cutting */
-    avoidCorners?: boolean;
-}
-/**
- * @zh 默认寻路配置
- * @en Default pathfinding options
- */
-declare const DEFAULT_PATHFINDING_OPTIONS: Required<IPathfindingOptions>;
-/**
- * @zh 寻路器接口
- * @en Pathfinder interface
- */
-interface IPathfinder {
+    pop(): T | undefined;
     /**
-     * @zh 查找路径
-     * @en Find path
+     * @zh 查看最小元素（不移除）
+     * @en Peek minimum element (without removing)
      */
-    findPath(startX: number, startY: number, endX: number, endY: number, options?: IPathfindingOptions): IPathResult;
+    peek(): T | undefined;
     /**
-     * @zh 清理状态（用于重用）
-     * @en Clear state (for reuse)
+     * @zh 更新元素（重新排序）
+     * @en Update element (re-sort)
+     */
+    update(item: T): void;
+    /**
+     * @zh 检查是否包含元素
+     * @en Check if contains element
+     */
+    contains(item: T): boolean;
+    /**
+     * @zh 清空堆
+     * @en Clear heap
      */
     clear(): void;
-}
-/**
- * @zh 路径平滑器接口
- * @en Path smoother interface
- */
-interface IPathSmoother {
     /**
-     * @zh 平滑路径
-     * @en Smooth path
+     * @zh 上浮操作
+     * @en Bubble up operation
      */
-    smooth(path: readonly IPoint[], map: IPathfindingMap): IPoint[];
+    private bubbleUp;
+    /**
+     * @zh 下沉操作
+     * @en Sink down operation
+     */
+    private sinkDown;
 }
+
 /**
- * @zh 视线检测函数类型
- * @en Line of sight check function type
+ * @zh 带索引追踪的二叉堆（优先队列）
+ * @en Indexed Binary Heap (Priority Queue) with index tracking
  */
-type LineOfSightCheck = (x1: number, y1: number, x2: number, y2: number, map: IPathfindingMap) => boolean;
-
 /**
- * @zh 二叉堆（优先队列）
- * @en Binary Heap (Priority Queue)
- *
- * @zh 用于 A* 算法的高效开放列表
- * @en Efficient open list for A* algorithm
+ * @zh 可索引的堆元素接口
+ * @en Interface for indexable heap elements
  */
-declare class BinaryHeap<T> {
+interface IHeapIndexable {
+    /** @zh 堆中的索引位置 @en Index position in heap */
+    heapIndex: number;
+}
+/**
+ * @zh 带索引追踪的二叉堆
+ * @en Binary Heap with index tracking
+ */
+declare class IndexedBinaryHeap<T extends IHeapIndexable> {
     private heap;
     private readonly compare;
     /**
-     * @zh 创建二叉堆
-     * @en Create binary heap
+     * @zh 创建带索引追踪的二叉堆
+     * @en Create indexed binary heap
      *
      * @param compare - @zh 比较函数，返回负数表示 a < b @en Compare function, returns negative if a < b
      */
@@ -201,8 +122,8 @@ declare class BinaryHeap<T> {
      */
     peek(): T | undefined;
     /**
-     * @zh 更新元素（重新排序）
-     * @en Update element (re-sort)
+     * @zh 更新元素
+     * @en Update element
      */
     update(item: T): void;
     /**
@@ -210,6 +131,11 @@ declare class BinaryHeap<T> {
      * @en Check if contains element
      */
     contains(item: T): boolean;
+    /**
+     * @zh 从堆中移除指定元素
+     * @en Remove specific element from heap
+     */
+    remove(item: T): boolean;
     /**
      * @zh 清空堆
      * @en Clear heap
@@ -291,13 +217,13 @@ declare function createAStarPathfinder(map: IPathfindingMap): AStarPathfinder;
  * @en Grid node
  */
 declare class GridNode implements IPathNode {
-    readonly id: string;
+    readonly id: number;
     readonly position: IPoint;
     readonly x: number;
     readonly y: number;
     cost: number;
     walkable: boolean;
-    constructor(x: number, y: number, walkable?: boolean, cost?: number);
+    constructor(x: number, y: number, width: number, walkable?: boolean, cost?: number);
 }
 /**
  * @zh 4方向偏移 (上下左右)
@@ -426,6 +352,11 @@ declare class GridMap implements IPathfindingMap {
      * @en Get neighbors of a node
      */
     getNeighbors(node: IPathNode): GridNode[];
+    /**
+     * @zh 遍历节点的邻居（零分配）
+     * @en Iterate over neighbors (zero allocation)
+     */
+    forEachNeighbor(node: IPathNode, callback: (neighbor: GridNode) => boolean | void): void;
     /**
      * @zh 计算启发式距离
      * @en Calculate heuristic distance
@@ -472,6 +403,811 @@ declare class GridMap implements IPathfindingMap {
  */
 declare function createGridMap(width: number, height: number, options?: IGridMapOptions): GridMap;
 
+/**
+ * @zh 网格寻路器（统一实现）
+ * @en Grid Pathfinder (unified implementation)
+ */
+
+/**
+ * @zh 寻路模式
+ * @en Pathfinding mode
+ */
+type GridPathfinderMode = 'standard' | 'fast' | 'bidirectional';
+/**
+ * @zh 网格寻路器配置
+ * @en Grid pathfinder configuration
+ */
+interface IGridPathfinderConfig {
+    /**
+     * @zh 寻路模式
+     * @en Pathfinding mode
+     *
+     * - standard: 标准A*，适合小地图
+     * - fast: TypedArray优化，适合中大地图
+     * - bidirectional: 双向搜索，适合超大地图
+     */
+    mode?: GridPathfinderMode;
+}
+/**
+ * @zh 网格寻路器
+ * @en Grid Pathfinder
+ */
+declare class GridPathfinder implements IPathfinder {
+    private readonly map;
+    private readonly mode;
+    private readonly state;
+    private readonly openList;
+    private readonly openListBack;
+    constructor(map: GridMap, config?: IGridPathfinderConfig);
+    findPath(startX: number, startY: number, endX: number, endY: number, options?: IPathfindingOptions): IPathResult;
+    private findPathUnidirectional;
+    private findPathBidirectional;
+    private validate;
+    private buildPath;
+    private buildPathBidirectional;
+    clear(): void;
+}
+/**
+ * @zh 创建网格寻路器
+ * @en Create grid pathfinder
+ */
+declare function createGridPathfinder(map: GridMap, config?: IGridPathfinderConfig): GridPathfinder;
+
+/**
+ * @zh 路径缓存模块
+ * @en Path Cache Module
+ *
+ * @zh 缓存已计算的路径，避免重复计算相同起点终点的路径
+ * @en Cache computed paths to avoid recalculating paths with the same start and end points
+ */
+
+/**
+ * @zh 缓存配置
+ * @en Cache configuration
+ */
+interface IPathCacheConfig {
+    /**
+     * @zh 最大缓存条目数
+     * @en Maximum number of cache entries
+     */
+    maxEntries: number;
+    /**
+     * @zh 缓存过期时间（毫秒），0 表示不过期
+     * @en Cache expiration time in milliseconds, 0 means no expiration
+     */
+    ttlMs: number;
+    /**
+     * @zh 是否启用近似匹配（在一定范围内的起点/终点视为相同）
+     * @en Whether to enable approximate matching (start/end within range considered same)
+     */
+    enableApproximateMatch: boolean;
+    /**
+     * @zh 近似匹配范围
+     * @en Approximate matching range
+     */
+    approximateRange: number;
+}
+/**
+ * @zh 默认缓存配置
+ * @en Default cache configuration
+ */
+declare const DEFAULT_PATH_CACHE_CONFIG: IPathCacheConfig;
+/**
+ * @zh 路径缓存
+ * @en Path Cache
+ *
+ * @zh 缓存已计算的路径，支持 LRU 淘汰策略和 TTL 过期
+ * @en Cache computed paths with LRU eviction and TTL expiration
+ *
+ * @example
+ * ```typescript
+ * const cache = new PathCache({ maxEntries: 500 });
+ * const cached = cache.get(0, 0, 10, 10, mapVersion);
+ * if (!cached) {
+ *     const result = pathfinder.findPath(0, 0, 10, 10);
+ *     cache.set(0, 0, 10, 10, result, mapVersion);
+ * }
+ * ```
+ */
+declare class PathCache {
+    private readonly config;
+    private readonly cache;
+    private readonly accessOrder;
+    constructor(config?: Partial<IPathCacheConfig>);
+    /**
+     * @zh 获取缓存的路径
+     * @en Get cached path
+     *
+     * @param startX - @zh 起点 X 坐标 @en Start X coordinate
+     * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate
+     * @param endX - @zh 终点 X 坐标 @en End X coordinate
+     * @param endY - @zh 终点 Y 坐标 @en End Y coordinate
+     * @param mapVersion - @zh 地图版本号 @en Map version number
+     * @returns @zh 缓存的路径结果或 null @en Cached path result or null
+     */
+    get(startX: number, startY: number, endX: number, endY: number, mapVersion: number): IPathResult | null;
+    /**
+     * @zh 设置缓存路径
+     * @en Set cached path
+     *
+     * @param startX - @zh 起点 X 坐标 @en Start X coordinate
+     * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate
+     * @param endX - @zh 终点 X 坐标 @en End X coordinate
+     * @param endY - @zh 终点 Y 坐标 @en End Y coordinate
+     * @param result - @zh 路径结果 @en Path result
+     * @param mapVersion - @zh 地图版本号 @en Map version number
+     */
+    set(startX: number, startY: number, endX: number, endY: number, result: IPathResult, mapVersion: number): void;
+    /**
+     * @zh 使所有缓存失效
+     * @en Invalidate all cache
+     */
+    invalidateAll(): void;
+    /**
+     * @zh 使指定区域的缓存失效
+     * @en Invalidate cache for specified region
+     *
+     * @param minX - @zh 最小 X 坐标 @en Minimum X coordinate
+     * @param minY - @zh 最小 Y 坐标 @en Minimum Y coordinate
+     * @param maxX - @zh 最大 X 坐标 @en Maximum X coordinate
+     * @param maxY - @zh 最大 Y 坐标 @en Maximum Y coordinate
+     */
+    invalidateRegion(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * @zh 获取缓存统计信息
+     * @en Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate?: number;
+    };
+    /**
+     * @zh 清理过期条目
+     * @en Clean up expired entries
+     */
+    cleanup(): void;
+    private generateKey;
+    private isValid;
+    private getApproximate;
+    private adjustPathForApproximate;
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+    private evictLRU;
+}
+/**
+ * @zh 创建路径缓存
+ * @en Create path cache
+ *
+ * @param config - @zh 缓存配置 @en Cache configuration
+ * @returns @zh 路径缓存实例 @en Path cache instance
+ */
+declare function createPathCache(config?: Partial<IPathCacheConfig>): PathCache;
+
+/**
+ * @zh 增量 A* 寻路算法实现
+ * @en Incremental A* Pathfinding Algorithm Implementation
+ */
+
+/**
+ * @zh 增量寻路器配置
+ * @en Incremental pathfinder configuration
+ */
+interface IIncrementalPathfinderConfig {
+    /**
+     * @zh 是否启用路径缓存
+     * @en Whether to enable path caching
+     */
+    enableCache?: boolean;
+    /**
+     * @zh 缓存配置
+     * @en Cache configuration
+     */
+    cacheConfig?: Partial<IPathCacheConfig>;
+}
+/**
+ * @zh 增量 A* 寻路器
+ * @en Incremental A* Pathfinder
+ *
+ * @zh 支持时间切片的 A* 算法实现，可跨多帧执行搜索
+ * @en A* algorithm implementation with time slicing, can execute search across multiple frames
+ *
+ * @example
+ * ```typescript
+ * const map = createGridMap(100, 100);
+ * const pathfinder = createIncrementalAStarPathfinder(map);
+ *
+ * // Request path (non-blocking)
+ * const request = pathfinder.requestPath(0, 0, 99, 99);
+ *
+ * // Process over multiple frames
+ * function gameLoop() {
+ *     const progress = pathfinder.step(request.id, 100);
+ *
+ *     if (progress.state === PathfindingState.Completed) {
+ *         const result = pathfinder.getResult(request.id);
+ *         console.log('Path found:', result?.path);
+ *     } else if (progress.state === PathfindingState.InProgress) {
+ *         requestAnimationFrame(gameLoop);
+ *     }
+ * }
+ * gameLoop();
+ * ```
+ */
+declare class IncrementalAStarPathfinder implements IIncrementalPathfinder {
+    private readonly map;
+    private readonly sessions;
+    private nextRequestId;
+    private readonly affectedRegions;
+    private readonly maxRegionAge;
+    private readonly cache;
+    private readonly enableCache;
+    private mapVersion;
+    private cacheHits;
+    private cacheMisses;
+    /**
+     * @zh 创建增量 A* 寻路器
+     * @en Create incremental A* pathfinder
+     *
+     * @param map - @zh 寻路地图实例 @en Pathfinding map instance
+     * @param config - @zh 配置选项 @en Configuration options
+     */
+    constructor(map: IPathfindingMap, config?: IIncrementalPathfinderConfig);
+    /**
+     * @zh 请求寻路（非阻塞）
+     * @en Request pathfinding (non-blocking)
+     */
+    requestPath(startX: number, startY: number, endX: number, endY: number, options?: IIncrementalPathfindingOptions): IPathRequest;
+    /**
+     * @zh 执行一步搜索
+     * @en Execute one step of search
+     */
+    step(requestId: number, maxIterations: number): IPathProgress;
+    /**
+     * @zh 暂停寻路
+     * @en Pause pathfinding
+     */
+    pause(requestId: number): void;
+    /**
+     * @zh 恢复寻路
+     * @en Resume pathfinding
+     */
+    resume(requestId: number): void;
+    /**
+     * @zh 取消寻路
+     * @en Cancel pathfinding
+     */
+    cancel(requestId: number): void;
+    /**
+     * @zh 获取寻路结果
+     * @en Get pathfinding result
+     */
+    getResult(requestId: number): IIncrementalPathResult | null;
+    /**
+     * @zh 获取当前进度
+     * @en Get current progress
+     */
+    getProgress(requestId: number): IPathProgress | null;
+    /**
+     * @zh 清理已完成的请求
+     * @en Clean up completed request
+     */
+    cleanup(requestId: number): void;
+    /**
+     * @zh 通知障碍物变化
+     * @en Notify obstacle change
+     */
+    notifyObstacleChange(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * @zh 清理所有请求
+     * @en Clear all requests
+     */
+    clear(): void;
+    /**
+     * @zh 清空路径缓存
+     * @en Clear path cache
+     */
+    clearCache(): void;
+    /**
+     * @zh 获取缓存统计信息
+     * @en Get cache statistics
+     */
+    getCacheStats(): {
+        enabled: boolean;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
+    /**
+     * @zh 检查会话是否被障碍物变化影响
+     * @en Check if session is affected by obstacle change
+     */
+    isAffectedByChange(requestId: number): boolean;
+    /**
+     * @zh 清除会话的变化标记
+     * @en Clear session's change flag
+     */
+    clearChangeFlag(requestId: number): void;
+    /**
+     * @zh 展开邻居节点
+     * @en Expand neighbor nodes
+     */
+    private expandNeighbors;
+    /**
+     * @zh 创建进度对象
+     * @en Create progress object
+     */
+    private createProgress;
+    /**
+     * @zh 构建路径结果
+     * @en Build path result
+     */
+    private buildResult;
+    /**
+     * @zh 创建空结果
+     * @en Create empty result
+     */
+    private createEmptyResult;
+    /**
+     * @zh 检查会话是否被区域影响
+     * @en Check if session is affected by region
+     */
+    private sessionAffectedByRegion;
+    /**
+     * @zh 清理过期的变化区域
+     * @en Clean up expired change regions
+     */
+    private cleanupOldRegions;
+}
+/**
+ * @zh 创建增量 A* 寻路器
+ * @en Create incremental A* pathfinder
+ *
+ * @param map - @zh 寻路地图实例 @en Pathfinding map instance
+ * @returns @zh 增量 A* 寻路器实例 @en Incremental A* pathfinder instance
+ */
+declare function createIncrementalAStarPathfinder(map: IPathfindingMap): IncrementalAStarPathfinder;
+
+/**
+ * @zh 路径验证器
+ * @en Path Validator
+ */
+
+/**
+ * @zh 路径验证器
+ * @en Path Validator
+ *
+ * @zh 用于检查现有路径在地图变化后是否仍然有效
+ * @en Used to check if an existing path is still valid after map changes
+ *
+ * @example
+ * ```typescript
+ * const validator = new PathValidator();
+ * const result = validator.validatePath(path, 0, path.length, map);
+ *
+ * if (!result.valid) {
+ *     console.log('Path invalid at index:', result.invalidIndex);
+ *     // Trigger replanning from current position
+ * }
+ * ```
+ */
+declare class PathValidator implements IPathValidator {
+    /**
+     * @zh 验证路径段的有效性
+     * @en Validate path segment validity
+     *
+     * @param path - @zh 要验证的路径 @en Path to validate
+     * @param fromIndex - @zh 起始索引 @en Start index
+     * @param toIndex - @zh 结束索引 @en End index
+     * @param map - @zh 地图实例 @en Map instance
+     * @returns @zh 验证结果 @en Validation result
+     */
+    validatePath(path: readonly IPoint[], fromIndex: number, toIndex: number, map: IPathfindingMap): IPathValidationResult;
+    /**
+     * @zh 检查两点之间的视线（使用 Bresenham 算法）
+     * @en Check line of sight between two points (using Bresenham algorithm)
+     *
+     * @param x1 - @zh 起点 X @en Start X
+     * @param y1 - @zh 起点 Y @en Start Y
+     * @param x2 - @zh 终点 X @en End X
+     * @param y2 - @zh 终点 Y @en End Y
+     * @param map - @zh 地图实例 @en Map instance
+     * @returns @zh 是否有视线 @en Whether there is line of sight
+     */
+    private checkLineOfSight;
+}
+/**
+ * @zh 障碍物变化记录
+ * @en Obstacle change record
+ */
+interface IObstacleChange {
+    /**
+     * @zh X 坐标
+     * @en X coordinate
+     */
+    readonly x: number;
+    /**
+     * @zh Y 坐标
+     * @en Y coordinate
+     */
+    readonly y: number;
+    /**
+     * @zh 变化前是否可通行
+     * @en Was walkable before change
+     */
+    readonly wasWalkable: boolean;
+    /**
+     * @zh 变化时间戳
+     * @en Change timestamp
+     */
+    readonly timestamp: number;
+}
+/**
+ * @zh 障碍物变化区域
+ * @en Obstacle change region
+ */
+interface IChangeRegion {
+    /**
+     * @zh 最小 X 坐标
+     * @en Minimum X coordinate
+     */
+    readonly minX: number;
+    /**
+     * @zh 最小 Y 坐标
+     * @en Minimum Y coordinate
+     */
+    readonly minY: number;
+    /**
+     * @zh 最大 X 坐标
+     * @en Maximum X coordinate
+     */
+    readonly maxX: number;
+    /**
+     * @zh 最大 Y 坐标
+     * @en Maximum Y coordinate
+     */
+    readonly maxY: number;
+}
+/**
+ * @zh 障碍物变化管理器
+ * @en Obstacle Change Manager
+ *
+ * @zh 跟踪地图障碍物变化，用于触发动态重规划
+ * @en Tracks map obstacle changes, used to trigger dynamic replanning
+ *
+ * @example
+ * ```typescript
+ * const manager = new ObstacleChangeManager();
+ *
+ * // Record change when obstacle is added/removed
+ * manager.recordChange(10, 20, true);  // Was walkable, now blocked
+ *
+ * // Get affected region for notification
+ * const region = manager.getAffectedRegion();
+ * if (region) {
+ *     pathfinder.notifyObstacleChange(
+ *         region.minX, region.minY,
+ *         region.maxX, region.maxY
+ *     );
+ * }
+ *
+ * // Clear after notification
+ * manager.flush();
+ * ```
+ */
+declare class ObstacleChangeManager {
+    private readonly changes;
+    private epoch;
+    /**
+     * @zh 记录障碍物变化
+     * @en Record obstacle change
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param wasWalkable - @zh 变化前是否可通行 @en Was walkable before change
+     */
+    recordChange(x: number, y: number, wasWalkable: boolean): void;
+    /**
+     * @zh 获取影响区域
+     * @en Get affected region
+     *
+     * @returns @zh 影响区域或 null（如果没有变化）@en Affected region or null if no changes
+     */
+    getAffectedRegion(): IChangeRegion | null;
+    /**
+     * @zh 获取所有变化
+     * @en Get all changes
+     *
+     * @returns @zh 变化列表 @en List of changes
+     */
+    getChanges(): IObstacleChange[];
+    /**
+     * @zh 检查是否有变化
+     * @en Check if there are changes
+     *
+     * @returns @zh 是否有变化 @en Whether there are changes
+     */
+    hasChanges(): boolean;
+    /**
+     * @zh 获取当前 epoch
+     * @en Get current epoch
+     *
+     * @returns @zh 当前 epoch @en Current epoch
+     */
+    getEpoch(): number;
+    /**
+     * @zh 清空变化记录并推进 epoch
+     * @en Clear changes and advance epoch
+     */
+    flush(): void;
+    /**
+     * @zh 清空所有状态
+     * @en Clear all state
+     */
+    clear(): void;
+}
+/**
+ * @zh 创建路径验证器
+ * @en Create path validator
+ *
+ * @returns @zh 路径验证器实例 @en Path validator instance
+ */
+declare function createPathValidator(): PathValidator;
+/**
+ * @zh 创建障碍物变化管理器
+ * @en Create obstacle change manager
+ *
+ * @returns @zh 障碍物变化管理器实例 @en Obstacle change manager instance
+ */
+declare function createObstacleChangeManager(): ObstacleChangeManager;
+
+/**
+ * @zh JPS (Jump Point Search) 寻路算法实现
+ * @en JPS (Jump Point Search) Pathfinding Algorithm Implementation
+ *
+ * @zh JPS 是 A* 的优化版本，通过跳跃点剪枝大幅提升开放地形的搜索效率
+ * @en JPS is an optimized version of A* that significantly improves search efficiency on open terrain through jump point pruning
+ */
+
+/**
+ * @zh JPS 寻路器
+ * @en JPS Pathfinder
+ *
+ * @zh 适用于均匀代价网格地图，在开放地形上比标准 A* 快 10-100 倍
+ * @en Suitable for uniform cost grid maps, 10-100x faster than standard A* on open terrain
+ *
+ * @example
+ * ```typescript
+ * const map = createGridMap(100, 100);
+ * const pathfinder = new JPSPathfinder(map);
+ * const result = pathfinder.findPath(0, 0, 99, 99);
+ * ```
+ */
+declare class JPSPathfinder implements IPathfinder {
+    private readonly map;
+    private readonly width;
+    private readonly height;
+    private openList;
+    private nodeGrid;
+    constructor(map: IPathfindingMap);
+    /**
+     * @zh 寻找路径
+     * @en Find path
+     */
+    findPath(startX: number, startY: number, endX: number, endY: number, options?: Partial<IPathfindingOptions>): IPathResult;
+    /**
+     * @zh 清理状态
+     * @en Clear state
+     */
+    clear(): void;
+    /**
+     * @zh 获取地图边界
+     * @en Get map bounds
+     */
+    private getMapBounds;
+    /**
+     * @zh 初始化节点网格
+     * @en Initialize node grid
+     */
+    private initGrid;
+    /**
+     * @zh 获取或创建节点
+     * @en Get or create node
+     */
+    private getOrCreateNode;
+    /**
+     * @zh 启发式函数（八方向距离）
+     * @en Heuristic function (octile distance)
+     */
+    private heuristic;
+    /**
+     * @zh 识别后继节点（跳跃点）
+     * @en Identify successors (jump points)
+     */
+    private identifySuccessors;
+    /**
+     * @zh 查找邻居（根据父节点方向剪枝）
+     * @en Find neighbors (pruned based on parent direction)
+     */
+    private findNeighbors;
+    /**
+     * @zh 跳跃函数（迭代版本，避免递归开销）
+     * @en Jump function (iterative version to avoid recursion overhead)
+     */
+    private jump;
+    /**
+     * @zh 直线跳跃（水平或垂直方向）
+     * @en Straight jump (horizontal or vertical direction)
+     */
+    private jumpStraight;
+    /**
+     * @zh 检查位置是否可通行
+     * @en Check if position is walkable
+     */
+    private isWalkableAt;
+    /**
+     * @zh 构建路径
+     * @en Build path
+     */
+    private buildPath;
+    /**
+     * @zh 插值路径（在跳跃点之间填充中间点）
+     * @en Interpolate path (fill intermediate points between jump points)
+     */
+    private interpolatePath;
+}
+/**
+ * @zh 创建 JPS 寻路器
+ * @en Create JPS pathfinder
+ *
+ * @param map - @zh 寻路地图实例 @en Pathfinding map instance
+ * @returns @zh JPS 寻路器实例 @en JPS pathfinder instance
+ */
+declare function createJPSPathfinder(map: IPathfindingMap): JPSPathfinder;
+
+/**
+ * @zh HPA* (Hierarchical Pathfinding A*) 寻路算法实现
+ * @en HPA* (Hierarchical Pathfinding A*) Pathfinding Algorithm Implementation
+ *
+ * @zh HPA* 是一种分层寻路算法，适用于超大地图 (1000x1000+)
+ * @en HPA* is a hierarchical pathfinding algorithm suitable for very large maps (1000x1000+)
+ *
+ * @zh 工作原理：
+ * 1. 将地图划分为集群 (clusters)
+ * 2. 在集群边界检测入口点 (entrances)
+ * 3. 构建抽象图 (abstract graph) 连接入口点
+ * 4. 先在抽象图上寻路，再细化为详细路径
+ *
+ * @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
+ */
+
+/**
+ * @zh HPA* 配置
+ * @en HPA* Configuration
+ */
+interface IHPAConfig {
+    /**
+     * @zh 集群大小（边长）
+     * @en Cluster size (side length)
+     */
+    clusterSize: number;
+    /**
+     * @zh 最大入口宽度（超过此宽度会拆分为多个入口）
+     * @en Maximum entrance width (entrances wider than this will be split)
+     */
+    maxEntranceWidth: number;
+    /**
+     * @zh 是否启用内部路径缓存
+     * @en Whether to enable internal path caching
+     */
+    cacheInternalPaths: boolean;
+}
+/**
+ * @zh 默认 HPA* 配置
+ * @en Default HPA* configuration
+ */
+declare const DEFAULT_HPA_CONFIG: IHPAConfig;
+/**
+ * @zh HPA* 寻路器
+ * @en HPA* Pathfinder
+ *
+ * @zh 适用于超大地图的分层寻路算法
+ * @en Hierarchical pathfinding algorithm for very large maps
+ *
+ * @example
+ * ```typescript
+ * const map = createGridMap(1000, 1000);
+ * const pathfinder = new HPAPathfinder(map, { clusterSize: 20 });
+ *
+ * // Preprocess (do once after map changes)
+ * pathfinder.preprocess();
+ *
+ * // Find path
+ * const result = pathfinder.findPath(0, 0, 999, 999);
+ * ```
+ */
+declare class HPAPathfinder implements IPathfinder {
+    private readonly map;
+    private readonly config;
+    private readonly width;
+    private readonly height;
+    private clusters;
+    private entrances;
+    private abstractNodes;
+    private clusterGrid;
+    private nextEntranceId;
+    private nextNodeId;
+    private internalPathCache;
+    private localPathfinder;
+    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;
+    /**
+     * @zh 寻找路径
+     * @en Find path
+     */
+    findPath(startX: number, startY: number, endX: number, endY: number, options?: Partial<IPathfindingOptions>): IPathResult;
+    /**
+     * @zh 清理状态
+     * @en Clear state
+     */
+    clear(): void;
+    /**
+     * @zh 通知地图区域变化
+     * @en Notify map region change
+     */
+    notifyRegionChange(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * @zh 获取预处理统计信息
+     * @en Get preprocessing statistics
+     */
+    getStats(): {
+        clusters: number;
+        entrances: number;
+        abstractNodes: number;
+        cacheSize: number;
+    };
+    private getMapBounds;
+    private buildClusters;
+    private findEntrances;
+    private findEntrancesBetween;
+    private createEntrance;
+    private buildAbstractGraph;
+    private createAbstractNode;
+    private connectIntraClusterNodes;
+    private getClusterAt;
+    private insertTemporaryNode;
+    private removeTemporaryNodes;
+    private searchAbstractGraph;
+    private reconstructAbstractPath;
+    private refinePath;
+    private findLocalPath;
+    private findInternalPath;
+    private calculatePathCost;
+    private heuristic;
+}
+/**
+ * @zh 创建 HPA* 寻路器
+ * @en Create HPA* pathfinder
+ *
+ * @param map - @zh 寻路地图实例 @en Pathfinding map instance
+ * @param config - @zh HPA* 配置 @en HPA* configuration
+ * @returns @zh HPA* 寻路器实例 @en HPA* pathfinder instance
+ */
+declare function createHPAPathfinder(map: IPathfindingMap, config?: Partial<IHPAConfig>): HPAPathfinder;
+
 /**
  * @zh 导航网格实现
  * @en NavMesh Implementation
@@ -695,46 +1431,4 @@ declare function createCatmullRomSmoother(segments?: number, tension?: number):
  */
 declare function createCombinedSmoother(curveSegments?: number, tension?: number): CombinedSmoother;
 
-/**
- * @zh 寻路系统蓝图节点
- * @en Pathfinding System Blueprint Nodes
- */
-
-declare const FindPathTemplate: BlueprintNodeTemplate;
-declare class FindPathExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const FindPathSmoothTemplate: BlueprintNodeTemplate;
-declare class FindPathSmoothExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const IsWalkableTemplate: BlueprintNodeTemplate;
-declare class IsWalkableExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const GetPathLengthTemplate: BlueprintNodeTemplate;
-declare class GetPathLengthExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const GetPathDistanceTemplate: BlueprintNodeTemplate;
-declare class GetPathDistanceExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const GetPathPointTemplate: BlueprintNodeTemplate;
-declare class GetPathPointExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const MoveAlongPathTemplate: BlueprintNodeTemplate;
-declare class MoveAlongPathExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const HasLineOfSightTemplate: BlueprintNodeTemplate;
-declare class HasLineOfSightExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: unknown): ExecutionResult;
-}
-declare const PathfindingNodeDefinitions: {
-    templates: BlueprintNodeTemplate[];
-    executors: Map<string, INodeExecutor>;
-};
-
-export { AStarPathfinder, BinaryHeap, CatmullRomSmoother, CombinedSmoother, DEFAULT_GRID_OPTIONS, DEFAULT_PATHFINDING_OPTIONS, DIRECTIONS_4, DIRECTIONS_8, EMPTY_PATH_RESULT, FindPathExecutor, FindPathSmoothExecutor, FindPathSmoothTemplate, FindPathTemplate, GetPathDistanceExecutor, GetPathDistanceTemplate, GetPathLengthExecutor, GetPathLengthTemplate, GetPathPointExecutor, GetPathPointTemplate, GridMap, GridNode, HasLineOfSightExecutor, HasLineOfSightTemplate, type HeuristicFunction, type IGridMapOptions, type INavPolygon, type IPathNode, type IPathResult, type IPathSmoother, type IPathfinder, type IPathfindingMap, type IPathfindingOptions, type IPoint, type IPortal, IsWalkableExecutor, IsWalkableTemplate, type LineOfSightCheck, LineOfSightSmoother, MoveAlongPathExecutor, MoveAlongPathTemplate, NavMesh, PathfindingNodeDefinitions, bresenhamLineOfSight, chebyshevDistance, createAStarPathfinder, createCatmullRomSmoother, createCombinedSmoother, createGridMap, createLineOfSightSmoother, createNavMesh, createPoint, euclideanDistance, manhattanDistance, octileDistance, raycastLineOfSight };
+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 };