@esengine/pathfinding 13.1.0 → 13.3.0

package/dist/FlowController-Dc3nuLq5.d.ts

@@ -0,0 +1,2751 @@
+import { c as IORCASolverConfig, i as ICollisionResolverConfig } from './CollisionResolver-CSgWsegP.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
+ */
+interface IPathfindingMap {
+    /**
+     * @zh 获取节点的邻居
+     * @en Get neighbors of a node
+     */
+    getNeighbors(node: IPathNode): IPathNode[];
+    /**
+     * @zh 获取指定位置的节点
+     * @en Get node at position
+     */
+    getNodeAt(x: number, y: number): IPathNode | null;
+    /**
+     * @zh 计算两点间的启发式距离
+     * @en Calculate heuristic distance between two points
+     */
+    heuristic(a: IPoint, b: IPoint): number;
+    /**
+     * @zh 计算两个邻居节点间的移动代价
+     * @en Calculate movement cost between two neighbor nodes
+     */
+    getMovementCost(from: IPathNode, to: IPathNode): number;
+    /**
+     * @zh 检查位置是否可通行
+     * @en Check if position is walkable
+     */
+    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 Agent radius, used to generate paths that consider collision volume
+     *
+     * @zh 如果指定，路径规划器会收缩 portal 宽度并偏移拐点，确保路径与障碍物保持足够距离
+     * @en If specified, the path planner will shrink portal widths and offset turning points to ensure sufficient clearance from obstacles
+     */
+    agentRadius?: number;
+}
+/**
+ * @zh 默认寻路配置
+ * @en Default pathfinding options
+ */
+declare const DEFAULT_PATHFINDING_OPTIONS: Required<IPathfindingOptions>;
+/**
+ * @zh 寻路器接口
+ * @en Pathfinder interface
+ */
+interface IPathfinder {
+    /**
+     * @zh 查找路径
+     * @en Find path
+     */
+    findPath(startX: number, startY: number, endX: number, endY: number, options?: IPathfindingOptions): IPathResult;
+    /**
+     * @zh 清理状态（用于重用）
+     * @en Clear state (for reuse)
+     */
+    clear(): void;
+}
+/**
+ * @zh 路径平滑器接口
+ * @en Path smoother interface
+ */
+interface IPathSmoother {
+    /**
+     * @zh 平滑路径
+     * @en Smooth path
+     */
+    smooth(path: readonly IPoint[], map: IPathfindingMap): IPoint[];
+}
+/**
+ * @zh 视线检测函数类型
+ * @en Line of sight check function type
+ */
+type LineOfSightCheck = (x1: number, y1: number, x2: number, y2: number, map: IPathfindingMap) => boolean;
+
+/**
+ * @zh 增量寻路系统接口
+ * @en Incremental Pathfinding System Interfaces
+ */
+
+/**
+ * @zh 增量寻路状态
+ * @en Incremental pathfinding state
+ */
+declare enum PathfindingState {
+    /** @zh 空闲，等待请求 @en Idle, waiting for request */
+    Idle = "idle",
+    /** @zh 正在搜索中 @en Search in progress */
+    InProgress = "in_progress",
+    /** @zh 已暂停 @en Paused */
+    Paused = "paused",
+    /** @zh 搜索完成，找到路径 @en Completed, path found */
+    Completed = "completed",
+    /** @zh 搜索失败，无法找到路径 @en Failed, no path found */
+    Failed = "failed",
+    /** @zh 已取消 @en Cancelled */
+    Cancelled = "cancelled"
+}
+/**
+ * @zh 增量寻路请求
+ * @en Incremental pathfinding request
+ */
+interface IPathRequest {
+    /**
+     * @zh 请求唯一标识符
+     * @en Unique request identifier
+     */
+    readonly id: number;
+    /**
+     * @zh 起点 X 坐标
+     * @en Start X coordinate
+     */
+    readonly startX: number;
+    /**
+     * @zh 起点 Y 坐标
+     * @en Start Y coordinate
+     */
+    readonly startY: number;
+    /**
+     * @zh 终点 X 坐标
+     * @en End X coordinate
+     */
+    readonly endX: number;
+    /**
+     * @zh 终点 Y 坐标
+     * @en End Y coordinate
+     */
+    readonly endY: number;
+    /**
+     * @zh 寻路配置选项
+     * @en Pathfinding options
+     */
+    readonly options?: IPathfindingOptions;
+    /**
+     * @zh 优先级（数值越小优先级越高）
+     * @en Priority (lower number = higher priority)
+     */
+    readonly priority: number;
+    /**
+     * @zh 创建时间戳
+     * @en Creation timestamp
+     */
+    readonly createdAt: number;
+}
+/**
+ * @zh 增量寻路进度
+ * @en Incremental pathfinding progress
+ */
+interface IPathProgress$1 {
+    /**
+     * @zh 当前寻路状态
+     * @en Current pathfinding state
+     */
+    readonly state: PathfindingState;
+    /**
+     * @zh 已搜索的节点数量
+     * @en Number of nodes searched
+     */
+    readonly nodesSearched: number;
+    /**
+     * @zh 开放列表当前大小
+     * @en Current open list size
+     */
+    readonly openListSize: number;
+    /**
+     * @zh 估计的搜索进度 (0-1)
+     * @en Estimated search progress (0-1)
+     */
+    readonly estimatedProgress: number;
+    /**
+     * @zh 当前最佳部分路径（可选）
+     * @en Current best partial path (optional)
+     */
+    readonly partialPath?: readonly IPoint[];
+}
+/**
+ * @zh 增量寻路结果（扩展自 IPathResult）
+ * @en Incremental pathfinding result (extends IPathResult)
+ */
+interface IIncrementalPathResult extends IPathResult {
+    /**
+     * @zh 关联的请求 ID
+     * @en Associated request ID
+     */
+    readonly requestId: number;
+    /**
+     * @zh 完成搜索所用的帧数
+     * @en Number of frames used to complete search
+     */
+    readonly framesUsed: number;
+    /**
+     * @zh 是否为部分路径（未到达终点）
+     * @en Whether this is a partial path (not reaching goal)
+     */
+    readonly isPartial: boolean;
+}
+/**
+ * @zh 增量寻路请求选项
+ * @en Incremental pathfinding request options
+ */
+interface IIncrementalPathfindingOptions extends IPathfindingOptions {
+    /**
+     * @zh 优先级（数值越小优先级越高，默认 50）
+     * @en Priority (lower = higher, default 50)
+     */
+    priority?: number;
+}
+/**
+ * @zh 增量寻路器接口
+ * @en Incremental pathfinder interface
+ *
+ * @zh 支持时间切片的寻路器，可跨多帧执行搜索
+ * @en Pathfinder with time slicing support, can execute search across multiple frames
+ */
+interface IIncrementalPathfinder {
+    /**
+     * @zh 请求寻路（非阻塞）
+     * @en Request pathfinding (non-blocking)
+     *
+     * @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 options - @zh 寻路选项 @en Pathfinding options
+     * @returns @zh 寻路请求对象 @en Path request object
+     */
+    requestPath(startX: number, startY: number, endX: number, endY: number, options?: IIncrementalPathfindingOptions): IPathRequest;
+    /**
+     * @zh 执行一步搜索
+     * @en Execute one step of search
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     * @param maxIterations - @zh 本步最大迭代次数 @en Maximum iterations this step
+     * @returns @zh 当前进度 @en Current progress
+     */
+    step(requestId: number, maxIterations: number): IPathProgress$1;
+    /**
+     * @zh 暂停寻路
+     * @en Pause pathfinding
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    pause(requestId: number): void;
+    /**
+     * @zh 恢复寻路
+     * @en Resume pathfinding
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    resume(requestId: number): void;
+    /**
+     * @zh 取消寻路
+     * @en Cancel pathfinding
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    cancel(requestId: number): void;
+    /**
+     * @zh 获取寻路结果（仅当状态为 Completed 或 Failed 时可用）
+     * @en Get pathfinding result (only available when state is Completed or Failed)
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     * @returns @zh 寻路结果或 null @en Path result or null
+     */
+    getResult(requestId: number): IIncrementalPathResult | null;
+    /**
+     * @zh 获取当前进度
+     * @en Get current progress
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     * @returns @zh 当前进度或 null @en Current progress or null
+     */
+    getProgress(requestId: number): IPathProgress$1 | null;
+    /**
+     * @zh 清理已完成的请求（释放内存）
+     * @en Clean up completed request (release memory)
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    cleanup(requestId: number): void;
+    /**
+     * @zh 通知障碍物变化（用于动态重规划）
+     * @en Notify obstacle change (for dynamic replanning)
+     *
+     * @param minX - @zh 变化区域最小 X @en Changed area min X
+     * @param minY - @zh 变化区域最小 Y @en Changed area min Y
+     * @param maxX - @zh 变化区域最大 X @en Changed area max X
+     * @param maxY - @zh 变化区域最大 Y @en Changed area max Y
+     */
+    notifyObstacleChange(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * @zh 清理所有请求
+     * @en Clear all requests
+     */
+    clear(): void;
+}
+/**
+ * @zh 路径验证结果
+ * @en Path validation result
+ */
+interface IPathValidationResult {
+    /**
+     * @zh 路径是否有效
+     * @en Whether the path is valid
+     */
+    readonly valid: boolean;
+    /**
+     * @zh 第一个无效点的索引（-1 表示全部有效）
+     * @en Index of first invalid point (-1 if all valid)
+     */
+    readonly invalidIndex: number;
+}
+/**
+ * @zh 路径验证器接口
+ * @en Path validator interface
+ */
+interface 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 动态重规划配置
+ * @en Dynamic replanning configuration
+ */
+interface IReplanningConfig {
+    /**
+     * @zh 是否启用动态重规划
+     * @en Whether dynamic replanning is enabled
+     */
+    enabled: boolean;
+    /**
+     * @zh 路径检查间隔（帧数）
+     * @en Path check interval (in frames)
+     */
+    checkInterval: number;
+    /**
+     * @zh 触发重规划的距离阈值
+     * @en Distance threshold to trigger replanning
+     */
+    distanceThreshold: number;
+    /**
+     * @zh 向前探测的距离（路径点数）
+     * @en Lookahead distance (in path points)
+     */
+    lookaheadDistance: number;
+}
+/**
+ * @zh 默认重规划配置
+ * @en Default replanning configuration
+ */
+declare const DEFAULT_REPLANNING_CONFIG: IReplanningConfig;
+/**
+ * @zh 空进度（用于无效请求）
+ * @en Empty progress (for invalid requests)
+ */
+declare const EMPTY_PROGRESS: IPathProgress$1;
+
+/**
+ * @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$1;
+    /**
+     * @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$1 | 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 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. 预计算集群内入口点之间的真实路径代价
+ * 5. 先在抽象图上寻路，再利用缓存细化为详细路径
+ *
+ * @en How it works:
+ * 1. Divide map into clusters
+ * 2. Detect entrances at cluster boundaries
+ * 3. Build abstract graph connecting entrances
+ * 4. Precompute actual path costs between entrances within clusters
+ * 5. First find path on abstract graph, then refine using cached paths
+ */
+
+/**
+ * @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 or use endpoint strategy)
+     */
+    maxEntranceWidth: number;
+    /**
+     * @zh 是否启用内部路径缓存
+     * @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* 配置
+ * @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 mapWidth;
+    private readonly mapHeight;
+    private clusters;
+    private clusterGrid;
+    private clustersX;
+    private clustersY;
+    private abstractNodes;
+    private nodesByCluster;
+    private nextNodeId;
+    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)
+     */
+    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;
+    /**
+     * @zh 构建集群
+     * @en Build clusters
+     */
+    private buildClusters;
+    /**
+     * @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;
+    /**
+     * @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;
+    /**
+     * @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;
+    /**
+     * @zh 启发式函数（Octile 距离）
+     * @en Heuristic function (Octile distance)
+     */
+    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
+ *
+ * @zh 支持动态障碍物：可以临时禁用多边形或添加圆形/矩形障碍物
+ * @en Supports dynamic obstacles: can temporarily disable polygons or add circular/rectangular obstacles
+ */
+
+/**
+ * @zh 动态障碍物类型
+ * @en Dynamic obstacle type
+ */
+type ObstacleType = 'circle' | 'rect' | 'polygon';
+/**
+ * @zh 动态障碍物
+ * @en Dynamic obstacle
+ */
+interface IDynamicObstacle {
+    /**
+     * @zh 障碍物 ID
+     * @en Obstacle ID
+     */
+    readonly id: number;
+    /**
+     * @zh 障碍物类型
+     * @en Obstacle type
+     */
+    readonly type: ObstacleType;
+    /**
+     * @zh 是否启用
+     * @en Whether enabled
+     */
+    enabled: boolean;
+    /**
+     * @zh 位置（圆形和矩形的中心）
+     * @en Position (center for circle and rect)
+     */
+    position: IPoint;
+    /**
+     * @zh 半径（圆形）或半宽/半高（矩形）
+     * @en Radius (circle) or half-width/half-height (rect)
+     */
+    radius?: number;
+    halfWidth?: number;
+    halfHeight?: number;
+    /**
+     * @zh 顶点（多边形）
+     * @en Vertices (polygon)
+     */
+    vertices?: readonly IPoint[];
+}
+/**
+ * @zh 导航多边形
+ * @en Navigation polygon
+ */
+interface INavPolygon {
+    /** @zh 多边形ID @en Polygon ID */
+    readonly id: number;
+    /** @zh 顶点列表 @en Vertex list */
+    readonly vertices: readonly IPoint[];
+    /** @zh 中心点 @en Center point */
+    readonly center: IPoint;
+    /** @zh 邻居多边形ID @en Neighbor polygon IDs */
+    readonly neighbors: readonly number[];
+    /** @zh 到邻居的共享边 @en Shared edges to neighbors */
+    readonly portals: ReadonlyMap<number, IPortal>;
+}
+/**
+ * @zh 入口（两个多边形之间的共享边）
+ * @en Portal (shared edge between two polygons)
+ */
+interface IPortal {
+    /** @zh 边的左端点 @en Left endpoint of edge */
+    readonly left: IPoint;
+    /** @zh 边的右端点 @en Right endpoint of edge */
+    readonly right: IPoint;
+}
+/**
+ * @zh 导航网格
+ * @en Navigation Mesh
+ *
+ * @zh 使用凸多边形网格进行高效寻路，适合复杂地形
+ * @en Uses convex polygon mesh for efficient pathfinding, suitable for complex terrain
+ *
+ * @example
+ * ```typescript
+ * const navmesh = new NavMesh();
+ *
+ * // Add polygons
+ * navmesh.addPolygon([
+ *     { x: 0, y: 0 }, { x: 10, y: 0 },
+ *     { x: 10, y: 10 }, { x: 0, y: 10 }
+ * ]);
+ *
+ * // Build connections
+ * navmesh.build();
+ *
+ * // Find path
+ * const result = navmesh.findPath(1, 1, 8, 8);
+ * ```
+ */
+declare class NavMesh implements IPathfindingMap {
+    private polygons;
+    private nodes;
+    private nextId;
+    private obstacles;
+    private nextObstacleId;
+    private disabledPolygons;
+    /**
+     * @zh 添加导航多边形
+     * @en Add navigation polygon
+     *
+     * @returns @zh 多边形ID @en Polygon ID
+     */
+    addPolygon(vertices: IPoint[], neighbors?: number[]): number;
+    /**
+     * @zh 设置两个多边形之间的连接
+     * @en Set connection between two polygons
+     */
+    setConnection(polyA: number, polyB: number, portal: IPortal): void;
+    /**
+     * @zh 自动检测并建立相邻多边形的连接
+     * @en Auto-detect and build connections between adjacent polygons
+     */
+    build(): void;
+    /**
+     * @zh 查找两个多边形的共享边
+     * @en Find shared edge between two polygons
+     */
+    private findSharedEdge;
+    /**
+     * @zh 计算多边形中心
+     * @en Calculate polygon center
+     */
+    private calculateCenter;
+    /**
+     * @zh 查找包含点的多边形
+     * @en Find polygon containing point
+     */
+    findPolygonAt(x: number, y: number): INavPolygon | null;
+    /**
+     * @zh 检查点是否在多边形内
+     * @en Check if point is inside polygon
+     */
+    private isPointInPolygon;
+    getNodeAt(x: number, y: number): IPathNode | null;
+    getNeighbors(node: IPathNode): IPathNode[];
+    heuristic(a: IPoint, b: IPoint): number;
+    getMovementCost(from: IPathNode, to: IPathNode): number;
+    isWalkable(x: number, y: number): boolean;
+    /**
+     * @zh 在导航网格上寻路
+     * @en Find path on navigation mesh
+     */
+    findPath(startX: number, startY: number, endX: number, endY: number, options?: IPathfindingOptions): IPathResult;
+    /**
+     * @zh 在多边形图上寻路
+     * @en Find path on polygon graph
+     *
+     * @param start - @zh 起始多边形 @en Start polygon
+     * @param end - @zh 目标多边形 @en End polygon
+     * @param opts - @zh 寻路选项 @en Pathfinding options
+     * @param checkObstacles - @zh 是否检查障碍物 @en Whether to check obstacles
+     */
+    private findPolygonPath;
+    /**
+     * @zh 使用漏斗算法优化路径（支持代理半径）
+     * @en Optimize path using funnel algorithm (supports agent radius)
+     *
+     * @param start - @zh 起点 @en Start point
+     * @param end - @zh 终点 @en End point
+     * @param polygons - @zh 多边形路径 @en Polygon path
+     * @param agentRadius - @zh 代理半径 @en Agent radius
+     */
+    private funnelPath;
+    /**
+     * @zh 收缩 portal（将两端点向内移动 agentRadius）
+     * @en Shrink portal (move endpoints inward by agentRadius)
+     */
+    private shrinkPortal;
+    /**
+     * @zh 偏移拐点以保持与角落的距离
+     * @en Offset turning point to maintain distance from corner
+     *
+     * @param prevApex - @zh 上一个顶点 @en Previous apex
+     * @param cornerOriginal - @zh 原始角落位置 @en Original corner position
+     * @param cornerShrunk - @zh 收缩后的角落位置 @en Shrunk corner position
+     * @param radius - @zh 代理半径 @en Agent radius
+     * @param side - @zh 转向侧 ('left' 或 'right') @en Turn side ('left' or 'right')
+     */
+    private offsetTurningPoint;
+    /**
+     * @zh 检查两点是否相等
+     * @en Check if two points are equal
+     */
+    private pointsEqual;
+    /**
+     * @zh 计算三角形面积的两倍（用于判断点的相对位置）
+     * @en Calculate twice the triangle area (for point relative position)
+     */
+    private triArea2;
+    /**
+     * @zh 计算路径总长度
+     * @en Calculate total path length
+     */
+    private calculatePathLength;
+    /**
+     * @zh 添加圆形障碍物
+     * @en Add circular obstacle
+     *
+     * @param x - @zh 中心 X @en Center X
+     * @param y - @zh 中心 Y @en Center Y
+     * @param radius - @zh 半径 @en Radius
+     * @returns @zh 障碍物 ID @en Obstacle ID
+     */
+    addCircleObstacle(x: number, y: number, radius: number): number;
+    /**
+     * @zh 添加矩形障碍物
+     * @en Add rectangular obstacle
+     *
+     * @param x - @zh 中心 X @en Center X
+     * @param y - @zh 中心 Y @en Center Y
+     * @param halfWidth - @zh 半宽 @en Half width
+     * @param halfHeight - @zh 半高 @en Half height
+     * @returns @zh 障碍物 ID @en Obstacle ID
+     */
+    addRectObstacle(x: number, y: number, halfWidth: number, halfHeight: number): number;
+    /**
+     * @zh 添加多边形障碍物
+     * @en Add polygon obstacle
+     *
+     * @param vertices - @zh 顶点列表 @en Vertex list
+     * @returns @zh 障碍物 ID @en Obstacle ID
+     */
+    addPolygonObstacle(vertices: IPoint[]): number;
+    /**
+     * @zh 移除障碍物
+     * @en Remove obstacle
+     */
+    removeObstacle(obstacleId: number): boolean;
+    /**
+     * @zh 启用/禁用障碍物
+     * @en Enable/disable obstacle
+     */
+    setObstacleEnabled(obstacleId: number, enabled: boolean): void;
+    /**
+     * @zh 更新障碍物位置
+     * @en Update obstacle position
+     */
+    updateObstaclePosition(obstacleId: number, x: number, y: number): void;
+    /**
+     * @zh 获取所有障碍物
+     * @en Get all obstacles
+     */
+    getObstacles(): IDynamicObstacle[];
+    /**
+     * @zh 获取启用的障碍物
+     * @en Get enabled obstacles
+     */
+    getEnabledObstacles(): IDynamicObstacle[];
+    /**
+     * @zh 清除所有障碍物
+     * @en Clear all obstacles
+     */
+    clearObstacles(): void;
+    /**
+     * @zh 禁用多边形
+     * @en Disable polygon
+     */
+    disablePolygon(polygonId: number): void;
+    /**
+     * @zh 启用多边形
+     * @en Enable polygon
+     */
+    enablePolygon(polygonId: number): void;
+    /**
+     * @zh 检查多边形是否被禁用
+     * @en Check if polygon is disabled
+     */
+    isPolygonDisabled(polygonId: number): boolean;
+    /**
+     * @zh 禁用包含指定点的多边形
+     * @en Disable polygon containing specified point
+     */
+    disablePolygonAt(x: number, y: number): number | null;
+    /**
+     * @zh 清除所有禁用的多边形
+     * @en Clear all disabled polygons
+     */
+    clearDisabledPolygons(): void;
+    /**
+     * @zh 获取被禁用的多边形 ID 列表
+     * @en Get list of disabled polygon IDs
+     */
+    getDisabledPolygons(): number[];
+    /**
+     * @zh 检查点是否在任何障碍物内
+     * @en Check if point is inside any obstacle
+     */
+    isPointInObstacle(x: number, y: number): boolean;
+    /**
+     * @zh 检查点是否在单个障碍物内
+     * @en Check if point is inside single obstacle
+     */
+    private isPointInSingleObstacle;
+    /**
+     * @zh 检查线段是否与任何障碍物相交
+     * @en Check if line segment intersects any obstacle
+     */
+    doesLineIntersectObstacle(x1: number, y1: number, x2: number, y2: number): boolean;
+    /**
+     * @zh 检查线段是否与单个障碍物相交
+     * @en Check if line segment intersects single obstacle
+     */
+    private doesLineIntersectSingleObstacle;
+    /**
+     * @zh 线段与圆相交检测
+     * @en Line segment circle intersection
+     */
+    private lineIntersectsCircle;
+    /**
+     * @zh 线段与矩形相交检测
+     * @en Line segment rectangle intersection
+     */
+    private lineIntersectsRect;
+    /**
+     * @zh 线段与多边形相交检测
+     * @en Line segment polygon intersection
+     */
+    private lineIntersectsPolygon;
+    /**
+     * @zh 两线段相交检测
+     * @en Two line segments intersection
+     */
+    private lineSegmentsIntersect;
+    private direction;
+    private onSegment;
+    /**
+     * @zh 检查多边形是否被障碍物阻挡
+     * @en Check if polygon is blocked by obstacle
+     *
+     * @zh 检查以下条件：
+     * @en Checks the following conditions:
+     * - @zh 多边形是否被禁用 @en Whether polygon is disabled
+     * - @zh 多边形中心是否在障碍物内 @en Whether polygon center is inside obstacle
+     * - @zh 多边形任意顶点是否在障碍物内 @en Whether any polygon vertex is inside obstacle
+     * - @zh 多边形任意边是否与障碍物相交 @en Whether any polygon edge intersects obstacle
+     */
+    isPolygonBlocked(polygonId: number): boolean;
+    /**
+     * @zh 在导航网格上寻路（考虑障碍物）
+     * @en Find path on navigation mesh (considering obstacles)
+     *
+     * @zh 此方法在规划阶段就考虑障碍物，自动绕过被阻挡的多边形
+     * @en This method considers obstacles during planning, automatically avoiding blocked polygons
+     *
+     * @zh 与 findPath 不同，此方法会：
+     * @en Unlike findPath, this method will:
+     * - @zh 在 A* 搜索中跳过被障碍物阻挡的多边形
+     * - @en Skip obstacle-blocked polygons during A* search
+     * - @zh 验证起点和终点不在障碍物内
+     * - @en Verify start and end points are not inside obstacles
+     */
+    findPathWithObstacles(startX: number, startY: number, endX: number, endY: number, options?: IPathfindingOptions): IPathResult;
+    /**
+     * @zh 清空导航网格
+     * @en Clear navigation mesh
+     */
+    clear(): void;
+    /**
+     * @zh 获取所有多边形
+     * @en Get all polygons
+     */
+    getPolygons(): INavPolygon[];
+    /**
+     * @zh 获取多边形数量
+     * @en Get polygon count
+     */
+    get polygonCount(): number;
+    /**
+     * @zh 获取障碍物数量
+     * @en Get obstacle count
+     */
+    get obstacleCount(): number;
+}
+/**
+ * @zh 创建导航网格
+ * @en Create navigation mesh
+ */
+declare function createNavMesh(): NavMesh;
+
+/**
+ * @zh 路径规划器接口
+ * @en Path Planner Interface
+ *
+ * @zh 统一的全局寻路接口，支持 NavMesh、A*、JPS、HPA*、Flow Field 等算法
+ * @en Unified global pathfinding interface, supports NavMesh, A*, JPS, HPA*, Flow Field, etc.
+ */
+/**
+ * @zh 2D 向量
+ * @en 2D Vector
+ */
+interface IVector2 {
+    x: number;
+    y: number;
+}
+/**
+ * @zh 路径规划结果
+ * @en Path planning result
+ */
+interface IPathPlanResult {
+    /**
+     * @zh 是否找到路径
+     * @en Whether path was found
+     */
+    readonly found: boolean;
+    /**
+     * @zh 路径点列表（世界坐标）
+     * @en List of path points (world coordinates)
+     */
+    readonly path: readonly IVector2[];
+    /**
+     * @zh 路径总代价
+     * @en Total path cost
+     */
+    readonly cost: number;
+    /**
+     * @zh 搜索的节点数（用于性能监控）
+     * @en Number of nodes searched (for performance monitoring)
+     */
+    readonly nodesSearched: number;
+}
+/**
+ * @zh 空路径结果
+ * @en Empty path result
+ */
+declare const EMPTY_PLAN_RESULT: IPathPlanResult;
+/**
+ * @zh 路径规划选项
+ * @en Path planning options
+ */
+interface IPathPlanOptions {
+    /**
+     * @zh 代理半径，用于生成考虑碰撞的路径
+     * @en Agent radius, used to generate collision-aware paths
+     *
+     * @zh 如果指定，路径规划器会确保生成的路径与障碍物保持足够距离
+     * @en If specified, the path planner will ensure the generated path maintains sufficient distance from obstacles
+     */
+    agentRadius?: number;
+}
+/**
+ * @zh 路径规划器接口
+ * @en Path planner interface
+ *
+ * @zh 统一的全局寻路接口，支持 NavMesh、A*、JPS、HPA*、Flow Field 等算法
+ * @en Unified global pathfinding interface, supports NavMesh, A*, JPS, HPA*, Flow Field, etc.
+ *
+ * @example
+ * ```typescript
+ * // 使用 NavMesh 规划器
+ * const planner = createNavMeshPathPlanner(navMesh);
+ * const result = planner.findPath({ x: 0, y: 0 }, { x: 100, y: 100 });
+ *
+ * // 使用带半径的路径规划
+ * const result = planner.findPath({ x: 0, y: 0 }, { x: 100, y: 100 }, { agentRadius: 0.5 });
+ *
+ * // 使用 A* 规划器
+ * const planner = createAStarPlanner(gridMap);
+ * const result = planner.findPath({ x: 0, y: 0 }, { x: 50, y: 50 });
+ * ```
+ */
+interface IPathPlanner {
+    /**
+     * @zh 规划器类型标识
+     * @en Planner type identifier
+     */
+    readonly type: string;
+    /**
+     * @zh 查找从起点到终点的路径
+     * @en Find path from start to end
+     *
+     * @param start - @zh 起点世界坐标 @en Start world position
+     * @param end - @zh 终点世界坐标 @en End world position
+     * @param options - @zh 路径规划选项 @en Path planning options
+     * @returns @zh 路径规划结果 @en Path planning result
+     */
+    findPath(start: IVector2, end: IVector2, options?: IPathPlanOptions): IPathPlanResult;
+    /**
+     * @zh 检查位置是否可通行
+     * @en Check if position is walkable
+     *
+     * @param position - @zh 要检查的位置 @en Position to check
+     * @returns @zh 是否可通行 @en Whether walkable
+     */
+    isWalkable(position: IVector2): boolean;
+    /**
+     * @zh 获取最近的可通行位置
+     * @en Get nearest walkable position
+     *
+     * @param position - @zh 参考位置 @en Reference position
+     * @returns @zh 最近的可通行位置，如果找不到则返回 null @en Nearest walkable position, or null if not found
+     */
+    getNearestWalkable(position: IVector2): IVector2 | null;
+    /**
+     * @zh 清理内部状态（用于重用）
+     * @en Clear internal state (for reuse)
+     */
+    clear(): void;
+    /**
+     * @zh 释放资源
+     * @en Dispose resources
+     */
+    dispose(): void;
+}
+/**
+ * @zh 寻路状态
+ * @en Pathfinding state
+ */
+declare enum PathPlanState {
+    /**
+     * @zh 空闲
+     * @en Idle
+     */
+    Idle = "idle",
+    /**
+     * @zh 进行中
+     * @en In progress
+     */
+    InProgress = "in_progress",
+    /**
+     * @zh 已完成
+     * @en Completed
+     */
+    Completed = "completed",
+    /**
+     * @zh 失败
+     * @en Failed
+     */
+    Failed = "failed",
+    /**
+     * @zh 已取消
+     * @en Cancelled
+     */
+    Cancelled = "cancelled"
+}
+/**
+ * @zh 增量寻路请求
+ * @en Incremental pathfinding request
+ */
+interface IIncrementalPathRequest {
+    /**
+     * @zh 请求 ID
+     * @en Request ID
+     */
+    readonly id: number;
+    /**
+     * @zh 当前状态
+     * @en Current state
+     */
+    readonly state: PathPlanState;
+}
+/**
+ * @zh 寻路进度信息
+ * @en Pathfinding progress info
+ */
+interface IPathProgress {
+    /**
+     * @zh 当前状态
+     * @en Current state
+     */
+    readonly state: PathPlanState;
+    /**
+     * @zh 估计进度 (0-1)
+     * @en Estimated progress (0-1)
+     */
+    readonly estimatedProgress: number;
+    /**
+     * @zh 本次步进搜索的节点数
+     * @en Nodes searched in this step
+     */
+    readonly nodesSearched: number;
+    /**
+     * @zh 累计搜索的节点数
+     * @en Total nodes searched
+     */
+    readonly totalNodesSearched: number;
+}
+/**
+ * @zh 增量路径规划器接口
+ * @en Incremental path planner interface
+ *
+ * @zh 支持时间切片的路径规划器，可以将寻路计算分散到多帧执行
+ * @en Path planner with time slicing support, can spread pathfinding computation across multiple frames
+ *
+ * @example
+ * ```typescript
+ * const planner = createIncrementalAStarPlanner(gridMap);
+ *
+ * // 请求路径
+ * const request = planner.requestPath({ x: 0, y: 0 }, { x: 100, y: 100 });
+ *
+ * // 每帧执行一定数量的迭代
+ * while (true) {
+ *     const progress = planner.step(request.id, 100); // 每帧 100 次迭代
+ *     if (progress.state === PathPlanState.Completed) {
+ *         const result = planner.getResult(request.id);
+ *         break;
+ *     }
+ *     if (progress.state === PathPlanState.Failed) {
+ *         break;
+ *     }
+ *     await nextFrame();
+ * }
+ *
+ * planner.cleanup(request.id);
+ * ```
+ */
+interface IIncrementalPathPlanner extends IPathPlanner {
+    /**
+     * @zh 是否支持增量计算
+     * @en Whether supports incremental computation
+     */
+    readonly supportsIncremental: true;
+    /**
+     * @zh 请求路径（异步开始）
+     * @en Request path (async start)
+     *
+     * @param start - @zh 起点 @en Start position
+     * @param end - @zh 终点 @en End position
+     * @param options - @zh 选项 @en Options
+     * @returns @zh 请求对象 @en Request object
+     */
+    requestPath(start: IVector2, end: IVector2, options?: IPathPlanOptions): IIncrementalPathRequest;
+    /**
+     * @zh 执行指定次数的迭代
+     * @en Execute specified number of iterations
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     * @param iterations - @zh 迭代次数 @en Number of iterations
+     * @returns @zh 进度信息 @en Progress info
+     */
+    step(requestId: number, iterations: number): IPathProgress;
+    /**
+     * @zh 获取结果
+     * @en Get result
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     * @returns @zh 结果，如果未完成或不存在返回 null @en Result, null if not completed or not found
+     */
+    getResult(requestId: number): IPathPlanResult | null;
+    /**
+     * @zh 取消请求
+     * @en Cancel request
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    cancel(requestId: number): void;
+    /**
+     * @zh 清理请求（释放资源）
+     * @en Cleanup request (release resources)
+     *
+     * @param requestId - @zh 请求 ID @en Request ID
+     */
+    cleanup(requestId: number): void;
+    /**
+     * @zh 获取活跃请求数量
+     * @en Get active request count
+     */
+    getActiveRequestCount(): number;
+}
+/**
+ * @zh 类型守卫：检查是否为增量路径规划器
+ * @en Type guard: check if is incremental path planner
+ */
+declare function isIncrementalPlanner(planner: IPathPlanner): planner is IIncrementalPathPlanner;
+
+/**
+ * @zh 局部避让接口
+ * @en Local Avoidance Interface
+ *
+ * @zh 统一的局部避让接口，支持 ORCA、RVO、Steering Behaviors 等算法
+ * @en Unified local avoidance interface, supports ORCA, RVO, Steering Behaviors, etc.
+ */
+
+/**
+ * @zh 避让代理数据（算法无关）
+ * @en Avoidance agent data (algorithm-agnostic)
+ */
+interface IAvoidanceAgentData {
+    /**
+     * @zh 代理唯一标识
+     * @en Unique agent identifier
+     */
+    readonly id: number;
+    /**
+     * @zh 当前位置
+     * @en Current position
+     */
+    readonly position: IVector2;
+    /**
+     * @zh 当前速度
+     * @en Current velocity
+     */
+    readonly velocity: IVector2;
+    /**
+     * @zh 首选速度（通常指向路径下一点）
+     * @en Preferred velocity (usually towards next path point)
+     */
+    readonly preferredVelocity: IVector2;
+    /**
+     * @zh 代理半径
+     * @en Agent radius
+     */
+    readonly radius: number;
+    /**
+     * @zh 最大速度
+     * @en Maximum speed
+     */
+    readonly maxSpeed: number;
+}
+/**
+ * @zh 静态障碍物数据
+ * @en Static obstacle data
+ */
+interface IObstacleData {
+    /**
+     * @zh 障碍物顶点（逆时针顺序）
+     * @en Obstacle vertices (counter-clockwise order)
+     */
+    readonly vertices: readonly IVector2[];
+}
+/**
+ * @zh 局部避让计算结果
+ * @en Local avoidance computation result
+ */
+interface IAvoidanceResult {
+    /**
+     * @zh 计算得到的新速度
+     * @en Computed new velocity
+     */
+    readonly velocity: IVector2;
+    /**
+     * @zh 是否找到可行解
+     * @en Whether a feasible solution was found
+     */
+    readonly feasible: boolean;
+}
+/**
+ * @zh 局部避让接口
+ * @en Local avoidance interface
+ *
+ * @zh 统一的局部避让接口，支持 ORCA、RVO、Steering Behaviors 等算法
+ * @en Unified local avoidance interface, supports ORCA, RVO, Steering Behaviors, etc.
+ *
+ * @example
+ * ```typescript
+ * // 使用 ORCA 避让
+ * const avoidance = createORCAAvoidance();
+ * const result = avoidance.computeAvoidanceVelocity(
+ *     agent, neighbors, obstacles, deltaTime
+ * );
+ *
+ * // 批量计算
+ * const results = avoidance.computeBatchAvoidance(agents, obstacles, deltaTime);
+ * ```
+ */
+interface ILocalAvoidance {
+    /**
+     * @zh 避让算法类型标识
+     * @en Avoidance algorithm type identifier
+     */
+    readonly type: string;
+    /**
+     * @zh 计算代理的避让速度
+     * @en Compute avoidance velocity for agent
+     *
+     * @param agent - @zh 当前代理数据 @en Current agent data
+     * @param neighbors - @zh 邻近代理列表 @en List of neighboring agents
+     * @param obstacles - @zh 静态障碍物列表 @en List of static obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 避让计算结果 @en Avoidance computation result
+     */
+    computeAvoidanceVelocity(agent: IAvoidanceAgentData, neighbors: readonly IAvoidanceAgentData[], obstacles: readonly IObstacleData[], deltaTime: number): IAvoidanceResult;
+    /**
+     * @zh 批量计算多个代理的避让速度（性能优化）
+     * @en Batch compute avoidance velocities for multiple agents (performance optimization)
+     *
+     * @param agents - @zh 代理列表 @en List of agents
+     * @param obstacles - @zh 静态障碍物列表 @en List of static obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 每个代理的避让结果（按 ID 索引）@en Avoidance results for each agent (indexed by ID)
+     */
+    computeBatchAvoidance(agents: readonly IAvoidanceAgentData[], obstacles: readonly IObstacleData[], deltaTime: number): Map<number, IAvoidanceResult>;
+    /**
+     * @zh 释放资源
+     * @en Dispose resources
+     */
+    dispose(): void;
+}
+
+/**
+ * @zh 碰撞解决器接口
+ * @en Collision Resolver Interface
+ *
+ * @zh 提供位置级别的硬碰撞检测和解决
+ * @en Provides position-level hard collision detection and resolution
+ */
+
+/**
+ * @zh 碰撞检测结果
+ * @en Collision detection result
+ */
+interface ICollisionResult {
+    /**
+     * @zh 是否发生碰撞
+     * @en Whether collision occurred
+     */
+    readonly collided: boolean;
+    /**
+     * @zh 穿透深度
+     * @en Penetration depth
+     */
+    readonly penetration: number;
+    /**
+     * @zh 碰撞法线（从障碍物指向代理）
+     * @en Collision normal (pointing from obstacle to agent)
+     */
+    readonly normal: IVector2;
+    /**
+     * @zh 障碍物上的最近点
+     * @en Closest point on obstacle
+     */
+    readonly closestPoint: IVector2;
+}
+/**
+ * @zh 空碰撞结果
+ * @en Empty collision result
+ */
+declare const EMPTY_COLLISION_RESULT: ICollisionResult;
+/**
+ * @zh 碰撞解决器接口
+ * @en Collision resolver interface
+ *
+ * @zh 提供位置级别的硬碰撞检测和解决，作为避让算法失效时的安全保护层
+ * @en Provides position-level hard collision detection and resolution, as safety layer when avoidance fails
+ *
+ * @example
+ * ```typescript
+ * const resolver = createDefaultCollisionResolver();
+ *
+ * // 检测碰撞
+ * const collision = resolver.detectCollision(position, radius, obstacles);
+ * if (collision.collided) {
+ *     // 解决碰撞
+ *     const newPos = resolver.resolveCollision(position, radius, obstacles);
+ * }
+ *
+ * // 验证速度
+ * const safeVelocity = resolver.validateVelocity(
+ *     position, velocity, radius, obstacles, deltaTime
+ * );
+ * ```
+ */
+interface ICollisionResolver {
+    /**
+     * @zh 解决器类型标识
+     * @en Resolver type identifier
+     */
+    readonly type: string;
+    /**
+     * @zh 检测圆与障碍物的碰撞
+     * @en Detect collision between circle and 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
+     */
+    detectCollision(position: IVector2, radius: number, obstacles: readonly IObstacleData[]): ICollisionResult;
+    /**
+     * @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
+     */
+    resolveCollision(position: IVector2, radius: number, obstacles: readonly IObstacleData[]): IVector2;
+    /**
+     * @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
+     */
+    validateVelocity(position: IVector2, velocity: IVector2, radius: number, obstacles: readonly IObstacleData[], deltaTime: number): IVector2;
+    /**
+     * @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
+     */
+    detectAgentCollision(posA: IVector2, radiusA: number, posB: IVector2, radiusB: number): ICollisionResult;
+    /**
+     * @zh 释放资源
+     * @en Dispose resources
+     */
+    dispose(): void;
+}
+
+/**
+ * @zh 流量控制器接口
+ * @en Flow Controller Interface
+ *
+ * @zh 管理拥堵区域的代理通行，防止死锁
+ * @en Manages agent passage through congested areas, prevents deadlocks
+ */
+
+/**
+ * @zh 通行许可类型
+ * @en Pass permission type
+ */
+declare enum PassPermission {
+    /**
+     * @zh 可以通行
+     * @en Can proceed
+     */
+    Proceed = "proceed",
+    /**
+     * @zh 需要等待
+     * @en Need to wait
+     */
+    Wait = "wait",
+    /**
+     * @zh 需要让路（减速或侧移）
+     * @en Need to yield (slow down or move aside)
+     */
+    Yield = "yield"
+}
+/**
+ * @zh 拥堵区域
+ * @en Congestion zone
+ */
+interface ICongestionZone {
+    /**
+     * @zh 区域 ID
+     * @en Zone ID
+     */
+    id: number;
+    /**
+     * @zh 区域中心
+     * @en Zone center
+     */
+    center: IVector2;
+    /**
+     * @zh 区域半径
+     * @en Zone radius
+     */
+    radius: number;
+    /**
+     * @zh 区域内的代理 ID 列表
+     * @en List of agent IDs in the zone
+     */
+    agentIds: number[];
+    /**
+     * @zh 区域容量（可同时通过的代理数）
+     * @en Zone capacity (agents that can pass simultaneously)
+     */
+    capacity: number;
+    /**
+     * @zh 拥堵程度 (0-1, 1 表示完全堵塞)
+     * @en Congestion level (0-1, 1 means fully blocked)
+     */
+    congestionLevel: number;
+}
+/**
+ * @zh 代理流量数据
+ * @en Agent flow data
+ */
+interface IFlowAgentData {
+    /**
+     * @zh 代理 ID
+     * @en Agent ID
+     */
+    id: number;
+    /**
+     * @zh 当前位置
+     * @en Current position
+     */
+    position: IVector2;
+    /**
+     * @zh 目标位置
+     * @en Destination position
+     */
+    destination: IVector2 | null;
+    /**
+     * @zh 当前路径点
+     * @en Current waypoint
+     */
+    currentWaypoint: IVector2 | null;
+    /**
+     * @zh 代理半径
+     * @en Agent radius
+     */
+    radius: number;
+    /**
+     * @zh 优先级（数值越小优先级越高）
+     * @en Priority (lower number = higher priority)
+     */
+    priority: number;
+    /**
+     * @zh 进入拥堵区域的时间戳
+     * @en Timestamp when entered congestion zone
+     */
+    enterTime?: number;
+}
+/**
+ * @zh 流量控制结果
+ * @en Flow control result
+ */
+interface IFlowControlResult {
+    /**
+     * @zh 通行许可
+     * @en Pass permission
+     */
+    permission: PassPermission;
+    /**
+     * @zh 如果需要等待，等待位置
+     * @en Wait position if waiting is required
+     */
+    waitPosition: IVector2 | null;
+    /**
+     * @zh 如果需要让路，建议的速度倍率 (0-1)
+     * @en Suggested speed multiplier if yielding (0-1)
+     */
+    speedMultiplier: number;
+    /**
+     * @zh 所在的拥堵区域（如果有）
+     * @en Congestion zone the agent is in (if any)
+     */
+    zone: ICongestionZone | null;
+    /**
+     * @zh 在队列中的位置（0 表示最前）
+     * @en Position in queue (0 means front)
+     */
+    queuePosition: number;
+}
+/**
+ * @zh 流量控制器配置
+ * @en Flow controller configuration
+ */
+interface IFlowControllerConfig {
+    /**
+     * @zh 拥堵检测半径
+     * @en Congestion detection radius
+     */
+    detectionRadius?: number;
+    /**
+     * @zh 触发拥堵的最小代理数
+     * @en Minimum agents to trigger congestion
+     */
+    minAgentsForCongestion?: number;
+    /**
+     * @zh 默认区域容量
+     * @en Default zone capacity
+     */
+    defaultCapacity?: number;
+    /**
+     * @zh 等待点距离（到拥堵区域边缘的距离）
+     * @en Wait point distance (from congestion zone edge)
+     */
+    waitPointDistance?: number;
+    /**
+     * @zh 让路速度倍率
+     * @en Yield speed multiplier
+     */
+    yieldSpeedMultiplier?: number;
+}
+/**
+ * @zh 默认流量控制器配置
+ * @en Default flow controller configuration
+ */
+declare const DEFAULT_FLOW_CONTROLLER_CONFIG: Required<IFlowControllerConfig>;
+/**
+ * @zh 流量控制器接口
+ * @en Flow controller interface
+ *
+ * @zh 管理代理在拥堵区域的通行顺序，防止死锁和回头现象
+ * @en Manages agent passage order in congested areas, prevents deadlocks and turning back
+ *
+ * @example
+ * ```typescript
+ * const flowController = createFlowController();
+ * navSystem.setFlowController(flowController);
+ *
+ * // 流量控制会自动：
+ * // 1. 检测拥堵区域
+ * // 2. 分配通行优先级
+ * // 3. 管理等待队列
+ * ```
+ */
+interface IFlowController {
+    /**
+     * @zh 控制器类型标识
+     * @en Controller type identifier
+     */
+    readonly type: string;
+    /**
+     * @zh 更新流量控制状态
+     * @en Update flow control state
+     *
+     * @param agents - @zh 所有代理数据 @en All agent data
+     * @param deltaTime - @zh 时间步长 @en Time step
+     */
+    update(agents: readonly IFlowAgentData[], deltaTime: number): void;
+    /**
+     * @zh 获取代理的流量控制结果
+     * @en Get flow control result for an agent
+     *
+     * @param agentId - @zh 代理 ID @en Agent ID
+     * @returns @zh 流量控制结果 @en Flow control result
+     */
+    getFlowControl(agentId: number): IFlowControlResult;
+    /**
+     * @zh 获取所有检测到的拥堵区域
+     * @en Get all detected congestion zones
+     *
+     * @returns @zh 拥堵区域列表 @en List of congestion zones
+     */
+    getCongestionZones(): readonly ICongestionZone[];
+    /**
+     * @zh 手动标记一个区域为拥堵区域
+     * @en Manually mark an area as congestion zone
+     *
+     * @param center - @zh 区域中心 @en Zone center
+     * @param radius - @zh 区域半径 @en Zone radius
+     * @param capacity - @zh 区域容量 @en Zone capacity
+     * @returns @zh 区域 ID @en Zone ID
+     */
+    addStaticZone(center: IVector2, radius: number, capacity: number): number;
+    /**
+     * @zh 移除手动标记的拥堵区域
+     * @en Remove manually marked congestion zone
+     *
+     * @param zoneId - @zh 区域 ID @en Zone ID
+     */
+    removeStaticZone(zoneId: number): void;
+    /**
+     * @zh 清除所有状态
+     * @en Clear all state
+     */
+    clear(): void;
+    /**
+     * @zh 释放资源
+     * @en Dispose resources
+     */
+    dispose(): void;
+}
+
+/**
+ * @zh NavMesh 路径规划器适配器
+ * @en NavMesh Path Planner Adapter
+ *
+ * @zh 将现有 NavMesh 适配到 IPathPlanner 接口
+ * @en Adapts existing NavMesh to IPathPlanner interface
+ */
+
+/**
+ * @zh NavMesh 路径规划器适配器
+ * @en NavMesh path planner adapter
+ *
+ * @example
+ * ```typescript
+ * const navMesh = createNavMesh();
+ * navMesh.addPolygon([...]);
+ * navMesh.build();
+ *
+ * const planner = createNavMeshPathPlanner(navMesh);
+ * const result = planner.findPath({ x: 0, y: 0 }, { x: 100, y: 100 });
+ * ```
+ */
+declare class NavMeshPathPlannerAdapter implements IPathPlanner {
+    private readonly navMesh;
+    readonly type = "navmesh";
+    constructor(navMesh: NavMesh);
+    findPath(start: IVector2, end: IVector2, options?: IPathPlanOptions): IPathPlanResult;
+    isWalkable(position: IVector2): boolean;
+    getNearestWalkable(position: IVector2): IVector2 | null;
+    clear(): void;
+    dispose(): void;
+}
+/**
+ * @zh 创建 NavMesh 路径规划器
+ * @en Create NavMesh path planner
+ *
+ * @param navMesh - @zh NavMesh 实例 @en NavMesh instance
+ * @returns @zh 路径规划器 @en Path planner
+ *
+ * @example
+ * ```typescript
+ * const planner = createNavMeshPathPlanner(navMesh);
+ * navSystem.setPathPlanner(planner);
+ * ```
+ */
+declare function createNavMeshPathPlanner(navMesh: NavMesh): IPathPlanner;
+
+/**
+ * @zh 网格寻路器适配器
+ * @en Grid Pathfinder Adapter
+ *
+ * @zh 将现有 IPathfinder (A*, JPS, HPA*) 适配到 IPathPlanner 接口
+ * @en Adapts existing IPathfinder (A*, JPS, HPA*) to IPathPlanner interface
+ */
+
+/**
+ * @zh 网格寻路器适配器配置
+ * @en Grid pathfinder adapter configuration
+ */
+interface IGridPathfinderAdapterConfig {
+    /**
+     * @zh 网格单元格大小（像素），用于坐标转换
+     * @en Grid cell size (pixels), used for coordinate conversion
+     *
+     * @zh 如果设置了此值，输入的像素坐标会自动转换为网格坐标，输出的网格坐标会转换回像素坐标（单元格中心）
+     * @en If set, input pixel coordinates are converted to grid coordinates, output grid coordinates are converted back to pixel coordinates (cell center)
+     *
+     * @default 1 (no conversion)
+     */
+    cellSize?: number;
+}
+/**
+ * @zh 网格寻路器适配器
+ * @en Grid pathfinder adapter
+ *
+ * @zh 将 A*、JPS、HPA* 等网格寻路器适配到统一的 IPathPlanner 接口
+ * @en Adapts A*, JPS, HPA* grid pathfinders to unified IPathPlanner interface
+ */
+declare class GridPathfinderAdapter implements IPathPlanner {
+    private readonly pathfinder;
+    private readonly map;
+    private readonly options?;
+    readonly type: string;
+    private readonly cellSize;
+    constructor(pathfinder: IPathfinder, map: IPathfindingMap, options?: IPathfindingOptions | undefined, type?: string, config?: IGridPathfinderAdapterConfig);
+    /**
+     * @zh 像素坐标转网格坐标
+     * @en Convert pixel coordinate to grid coordinate
+     */
+    private toGridCoord;
+    /**
+     * @zh 网格坐标转像素坐标（单元格中心）
+     * @en Convert grid coordinate to pixel coordinate (cell center)
+     */
+    private toPixelCoord;
+    findPath(start: IVector2, end: IVector2): IPathPlanResult;
+    isWalkable(position: IVector2): boolean;
+    getNearestWalkable(position: IVector2): IVector2 | null;
+    clear(): void;
+    dispose(): void;
+}
+/**
+ * @zh 创建 A* 路径规划器
+ * @en Create A* path planner
+ *
+ * @param map - @zh 寻路地图 @en Pathfinding map
+ * @param options - @zh 寻路选项 @en Pathfinding options
+ * @param config - @zh 适配器配置（包含 cellSize）@en Adapter config (includes cellSize)
+ * @returns @zh 路径规划器 @en Path planner
+ *
+ * @example
+ * ```typescript
+ * const gridMap = createGridMap(100, 100);
+ * // 如果使用像素坐标，需要指定 cellSize
+ * const planner = createAStarPlanner(gridMap, undefined, { cellSize: 20 });
+ * navSystem.setPathPlanner(planner);
+ * ```
+ */
+declare function createAStarPlanner(map: IPathfindingMap, options?: IPathfindingOptions, config?: IGridPathfinderAdapterConfig): IPathPlanner;
+/**
+ * @zh 创建 JPS 路径规划器
+ * @en Create JPS path planner
+ *
+ * @zh JPS（Jump Point Search）适用于均匀代价的网格地图，比 A* 快 10-100 倍
+ * @en JPS (Jump Point Search) is optimized for uniform-cost grids, 10-100x faster than A*
+ *
+ * @param map - @zh 寻路地图 @en Pathfinding map
+ * @param options - @zh 寻路选项 @en Pathfinding options
+ * @param config - @zh 适配器配置（包含 cellSize）@en Adapter config (includes cellSize)
+ * @returns @zh 路径规划器 @en Path planner
+ *
+ * @example
+ * ```typescript
+ * const gridMap = createGridMap(100, 100);
+ * const planner = createJPSPlanner(gridMap, undefined, { cellSize: 20 });
+ * navSystem.setPathPlanner(planner);
+ * ```
+ */
+declare function createJPSPlanner(map: IPathfindingMap, options?: IPathfindingOptions, config?: IGridPathfinderAdapterConfig): IPathPlanner;
+/**
+ * @zh 创建 HPA* 路径规划器
+ * @en Create HPA* path planner
+ *
+ * @zh HPA*（Hierarchical Pathfinding A*）适用于超大地图（1000x1000+）
+ * @en HPA* (Hierarchical Pathfinding A*) is optimized for very large maps (1000x1000+)
+ *
+ * @param map - @zh 寻路地图 @en Pathfinding map
+ * @param hpaConfig - @zh HPA* 配置 @en HPA* configuration
+ * @param options - @zh 寻路选项 @en Pathfinding options
+ * @param adapterConfig - @zh 适配器配置（包含 cellSize）@en Adapter config (includes cellSize)
+ * @returns @zh 路径规划器 @en Path planner
+ *
+ * @example
+ * ```typescript
+ * const gridMap = createGridMap(2000, 2000);
+ * const planner = createHPAPlanner(gridMap, { clusterSize: 16 }, undefined, { cellSize: 20 });
+ * navSystem.setPathPlanner(planner);
+ * ```
+ */
+declare function createHPAPlanner(map: IPathfindingMap, hpaConfig?: Partial<IHPAConfig>, options?: IPathfindingOptions, adapterConfig?: IGridPathfinderAdapterConfig): IPathPlanner;
+
+/**
+ * @zh 增量网格寻路器适配器
+ * @en Incremental Grid Pathfinder Adapter
+ *
+ * @zh 将 IncrementalAStarPathfinder 适配到 IIncrementalPathPlanner 接口
+ * @en Adapts IncrementalAStarPathfinder to IIncrementalPathPlanner interface
+ */
+
+/**
+ * @zh 增量网格寻路器适配器配置
+ * @en Incremental grid pathfinder adapter configuration
+ */
+interface IIncrementalGridPathPlannerConfig extends IIncrementalPathfinderConfig {
+    /**
+     * @zh 网格单元格大小（像素），用于坐标转换
+     * @en Grid cell size (pixels), used for coordinate conversion
+     *
+     * @default 1 (no conversion)
+     */
+    cellSize?: number;
+}
+/**
+ * @zh 增量网格寻路器适配器
+ * @en Incremental grid pathfinder adapter
+ *
+ * @zh 将 IncrementalAStarPathfinder 适配到 IIncrementalPathPlanner 接口，支持时间切片
+ * @en Adapts IncrementalAStarPathfinder to IIncrementalPathPlanner interface, supports time slicing
+ *
+ * @example
+ * ```typescript
+ * const gridMap = createGridMap(100, 100);
+ * const planner = createIncrementalAStarPlanner(gridMap, { cellSize: 20 });
+ *
+ * // 请求路径（像素坐标）
+ * const request = planner.requestPath({ x: 100, y: 100 }, { x: 500, y: 300 });
+ *
+ * // 每帧执行一定数量的迭代
+ * const progress = planner.step(request.id, 100);
+ * if (progress.state === PathPlanState.Completed) {
+ *     const result = planner.getResult(request.id);
+ *     // result.path 是像素坐标
+ * }
+ * ```
+ */
+declare class IncrementalGridPathPlannerAdapter implements IIncrementalPathPlanner {
+    readonly type: string;
+    readonly supportsIncremental: true;
+    private readonly pathfinder;
+    private readonly map;
+    private readonly options?;
+    private readonly cellSize;
+    /**
+     * @zh 活跃请求 ID 集合（用于跟踪）
+     * @en Active request IDs set (for tracking)
+     */
+    private readonly activeRequests;
+    /**
+     * @zh 每个请求的累计搜索节点数
+     * @en Accumulated searched nodes per request
+     */
+    private readonly requestTotalNodes;
+    constructor(map: IPathfindingMap, options?: IPathfindingOptions, config?: IIncrementalGridPathPlannerConfig);
+    /**
+     * @zh 像素坐标转网格坐标
+     * @en Convert pixel coordinate to grid coordinate
+     */
+    private toGridCoord;
+    /**
+     * @zh 网格坐标转像素坐标（单元格中心）
+     * @en Convert grid coordinate to pixel coordinate (cell center)
+     */
+    private toPixelCoord;
+    findPath(start: IVector2, end: IVector2, options?: IPathPlanOptions): IPathPlanResult;
+    isWalkable(position: IVector2): boolean;
+    getNearestWalkable(position: IVector2): IVector2 | null;
+    clear(): void;
+    dispose(): void;
+    requestPath(start: IVector2, end: IVector2, options?: IPathPlanOptions): IIncrementalPathRequest;
+    step(requestId: number, iterations: number): IPathProgress;
+    getResult(requestId: number): IPathPlanResult | null;
+    cancel(requestId: number): void;
+    cleanup(requestId: number): void;
+    getActiveRequestCount(): number;
+}
+/**
+ * @zh 创建增量 A* 路径规划器
+ * @en Create incremental A* path planner
+ *
+ * @zh 支持时间切片的 A* 路径规划器，可以将寻路计算分散到多帧执行
+ * @en A* path planner with time slicing support, can spread pathfinding computation across multiple frames
+ *
+ * @param map - @zh 寻路地图 @en Pathfinding map
+ * @param options - @zh 寻路选项 @en Pathfinding options
+ * @param config - @zh 适配器配置（包含 cellSize 和缓存配置）@en Adapter config (includes cellSize and cache config)
+ * @returns @zh 增量路径规划器 @en Incremental path planner
+ *
+ * @example
+ * ```typescript
+ * const gridMap = createGridMap(100, 100);
+ * const planner = createIncrementalAStarPlanner(gridMap, undefined, {
+ *     cellSize: 20,
+ *     enableCache: true
+ * });
+ *
+ * // 与 NavigationSystem 集成
+ * navSystem.setPathPlanner(planner);
+ *
+ * // 启用时间切片（NavigationSystem 会自动检测）
+ * const navSystem = new NavigationSystem({
+ *     enableTimeSlicing: true,
+ *     iterationsBudget: 1000,
+ *     maxAgentsPerFrame: 10
+ * });
+ * ```
+ */
+declare function createIncrementalAStarPlanner(map: IPathfindingMap, options?: IPathfindingOptions, config?: IIncrementalGridPathPlannerConfig): IIncrementalPathPlanner;
+
+/**
+ * @zh ORCA 局部避让适配器
+ * @en ORCA Local Avoidance Adapter
+ *
+ * @zh 将现有 ORCA 求解器适配到 ILocalAvoidance 接口
+ * @en Adapts existing ORCA solver to ILocalAvoidance interface
+ */
+
+/**
+ * @zh ORCA 默认参数
+ * @en ORCA default parameters
+ */
+interface IORCAParams {
+    /**
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     */
+    neighborDist: number;
+    /**
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors
+     */
+    maxNeighbors: number;
+    /**
+     * @zh 代理避让时间视野
+     * @en Time horizon for agent avoidance
+     */
+    timeHorizon: number;
+    /**
+     * @zh 障碍物避让时间视野
+     * @en Time horizon for obstacle avoidance
+     */
+    timeHorizonObst: number;
+}
+/**
+ * @zh ORCA 默认参数值
+ * @en ORCA default parameter values
+ */
+declare const DEFAULT_ORCA_PARAMS: IORCAParams;
+/**
+ * @zh ORCA 局部避让适配器
+ * @en ORCA local avoidance adapter
+ *
+ * @example
+ * ```typescript
+ * const avoidance = createORCAAvoidance();
+ * navSystem.setLocalAvoidance(avoidance);
+ *
+ * // 自定义参数
+ * const avoidance = createORCAAvoidance({
+ *     timeStep: 1/60
+ * });
+ * avoidance.setDefaultParams({ timeHorizon: 3.0 });
+ * ```
+ */
+declare class ORCALocalAvoidanceAdapter implements ILocalAvoidance {
+    readonly type = "orca";
+    private solver;
+    private kdTree;
+    private defaultParams;
+    constructor(config?: IORCASolverConfig);
+    /**
+     * @zh 设置默认 ORCA 参数
+     * @en Set default ORCA parameters
+     *
+     * @param params - @zh 参数 @en Parameters
+     */
+    setDefaultParams(params: Partial<IORCAParams>): void;
+    /**
+     * @zh 获取默认 ORCA 参数
+     * @en Get default ORCA parameters
+     */
+    getDefaultParams(): Readonly<IORCAParams>;
+    computeAvoidanceVelocity(agent: IAvoidanceAgentData, neighbors: readonly IAvoidanceAgentData[], obstacles: readonly IObstacleData[], deltaTime: number): IAvoidanceResult;
+    computeBatchAvoidance(agents: readonly IAvoidanceAgentData[], obstacles: readonly IObstacleData[], deltaTime: number): Map<number, IAvoidanceResult>;
+    dispose(): void;
+    private toORCAAgent;
+    private toORCAObstacle;
+}
+/**
+ * @zh 创建 ORCA 局部避让
+ * @en Create ORCA local avoidance
+ *
+ * @param config - @zh ORCA 求解器配置 @en ORCA solver configuration
+ * @returns @zh 局部避让实例 @en Local avoidance instance
+ *
+ * @example
+ * ```typescript
+ * const avoidance = createORCAAvoidance();
+ * navSystem.setLocalAvoidance(avoidance);
+ * ```
+ */
+declare function createORCAAvoidance(config?: IORCASolverConfig): ORCALocalAvoidanceAdapter;
+
+/**
+ * @zh 碰撞解决器适配器
+ * @en Collision Resolver Adapter
+ *
+ * @zh 将现有 CollisionResolver 适配到 ICollisionResolver 接口
+ * @en Adapts existing CollisionResolver to ICollisionResolver interface
+ */
+
+/**
+ * @zh 碰撞解决器适配器
+ * @en Collision resolver adapter
+ *
+ * @example
+ * ```typescript
+ * const resolver = createDefaultCollisionResolver();
+ * navSystem.setCollisionResolver(resolver);
+ * ```
+ */
+declare class CollisionResolverAdapter implements ICollisionResolver {
+    readonly type = "default";
+    private resolver;
+    constructor(config?: ICollisionResolverConfig);
+    detectCollision(position: IVector2, radius: number, obstacles: readonly IObstacleData[]): ICollisionResult;
+    resolveCollision(position: IVector2, radius: number, obstacles: readonly IObstacleData[]): IVector2;
+    validateVelocity(position: IVector2, velocity: IVector2, radius: number, obstacles: readonly IObstacleData[], deltaTime: number): IVector2;
+    detectAgentCollision(posA: IVector2, radiusA: number, posB: IVector2, radiusB: number): ICollisionResult;
+    dispose(): void;
+}
+/**
+ * @zh 创建默认碰撞解决器
+ * @en Create default collision resolver
+ *
+ * @param config - @zh 配置 @en Configuration
+ * @returns @zh 碰撞解决器 @en Collision resolver
+ *
+ * @example
+ * ```typescript
+ * const resolver = createDefaultCollisionResolver();
+ * navSystem.setCollisionResolver(resolver);
+ *
+ * // 自定义配置
+ * const resolver = createDefaultCollisionResolver({
+ *     responseFactor: 1.0,
+ *     safetyMargin: 0.01
+ * });
+ * ```
+ */
+declare function createDefaultCollisionResolver(config?: ICollisionResolverConfig): ICollisionResolver;
+
+/**
+ * @zh 流量控制器实现
+ * @en Flow Controller Implementation
+ *
+ * @zh 管理拥堵区域的代理通行，使用 FIFO + 优先级策略防止死锁
+ * @en Manages agent passage through congested areas using FIFO + priority to prevent deadlocks
+ */
+
+/**
+ * @zh 流量控制器
+ * @en Flow Controller
+ *
+ * @zh 检测拥堵区域并管理代理通行顺序
+ * @en Detects congestion zones and manages agent passage order
+ *
+ * @example
+ * ```typescript
+ * const flowController = createFlowController({
+ *     detectionRadius: 3.0,
+ *     minAgentsForCongestion: 3,
+ *     defaultCapacity: 2
+ * });
+ *
+ * // 每帧更新
+ * flowController.update(agents, deltaTime);
+ *
+ * // 获取代理的流量控制
+ * const result = flowController.getFlowControl(agentId);
+ * if (result.permission === PassPermission.Wait) {
+ *     // 移动到等待位置
+ *     agent.setDestination(result.waitPosition);
+ * }
+ * ```
+ */
+declare class FlowController implements IFlowController {
+    readonly type = "fifo-priority";
+    private config;
+    private zoneStates;
+    private agentZoneMap;
+    private agentResults;
+    private nextZoneId;
+    private currentTime;
+    constructor(config?: IFlowControllerConfig);
+    /**
+     * @zh 更新流量控制状态
+     * @en Update flow control state
+     */
+    update(agents: readonly IFlowAgentData[], deltaTime: number): void;
+    /**
+     * @zh 获取代理的流量控制结果
+     * @en Get flow control result for an agent
+     */
+    getFlowControl(agentId: number): IFlowControlResult;
+    /**
+     * @zh 获取所有拥堵区域
+     * @en Get all congestion zones
+     */
+    getCongestionZones(): readonly ICongestionZone[];
+    /**
+     * @zh 添加静态拥堵区域
+     * @en Add static congestion zone
+     */
+    addStaticZone(center: IVector2, radius: number, capacity: number): number;
+    /**
+     * @zh 移除静态拥堵区域
+     * @en Remove static congestion zone
+     */
+    removeStaticZone(zoneId: number): void;
+    /**
+     * @zh 清除所有状态
+     * @en Clear all state
+     */
+    clear(): void;
+    /**
+     * @zh 释放资源
+     * @en Dispose resources
+     */
+    dispose(): void;
+    /**
+     * @zh 检测动态拥堵区域
+     * @en Detect dynamic congestion zones
+     */
+    private detectDynamicCongestion;
+    /**
+     * @zh 聚类代理
+     * @en Cluster agents
+     */
+    private clusterAgents;
+    /**
+     * @zh 计算聚类中心
+     * @en Compute cluster center
+     */
+    private computeClusterCenter;
+    /**
+     * @zh 计算聚类半径
+     * @en Compute cluster radius
+     */
+    private computeClusterRadius;
+    /**
+     * @zh 查找包含点的区域
+     * @en Find zone containing point
+     */
+    private findZoneContaining;
+    /**
+     * @zh 更新动态区域
+     * @en Update dynamic zone
+     */
+    private updateDynamicZone;
+    /**
+     * @zh 创建动态区域
+     * @en Create dynamic zone
+     */
+    private createDynamicZone;
+    /**
+     * @zh 更新区域队列
+     * @en Update zone queues
+     */
+    private updateZoneQueues;
+    /**
+     * @zh 计算流量控制结果
+     * @en Compute flow control results
+     */
+    private computeFlowControlResults;
+    /**
+     * @zh 计算等待位置
+     * @en Compute wait position
+     */
+    private computeWaitPosition;
+    /**
+     * @zh 清理空的动态区域
+     * @en Cleanup empty dynamic zones
+     */
+    private cleanupEmptyZones;
+}
+/**
+ * @zh 创建流量控制器
+ * @en Create flow controller
+ *
+ * @param config - @zh 配置参数 @en Configuration
+ * @returns @zh 流量控制器实例 @en Flow controller instance
+ */
+declare function createFlowController(config?: IFlowControllerConfig): FlowController;
+
+export { type IAvoidanceResult as $, type IReplanningConfig as A, PathfindingState as B, DEFAULT_REPLANNING_CONFIG as C, DEFAULT_PATHFINDING_OPTIONS as D, EMPTY_PATH_RESULT as E, EMPTY_PROGRESS as F, IncrementalAStarPathfinder as G, type HeuristicFunction as H, type IPathfinder as I, createIncrementalAStarPathfinder as J, type INavPolygon as K, type LineOfSightCheck as L, type IPortal as M, type IDynamicObstacle as N, type ObstacleType as O, PathCache as P, NavMesh as Q, createNavMesh as R, type IVector2 as S, type IPathPlanResult as T, type IPathPlanOptions as U, type IPathPlanner as V, type IIncrementalPathPlanner as W, type IIncrementalPathRequest as X, type IPathProgress as Y, type IAvoidanceAgentData as Z, type IObstacleData as _, type IPathfindingMap as a, type ILocalAvoidance as a0, type ICollisionResult as a1, type ICollisionResolver as a2, type ICongestionZone as a3, type IFlowAgentData as a4, type IFlowControlResult as a5, type IFlowControllerConfig as a6, type IFlowController as a7, EMPTY_PLAN_RESULT as a8, EMPTY_COLLISION_RESULT as a9, PassPermission as aa, DEFAULT_FLOW_CONTROLLER_CONFIG as ab, PathPlanState as ac, isIncrementalPlanner as ad, NavMeshPathPlannerAdapter as ae, createNavMeshPathPlanner as af, GridPathfinderAdapter as ag, createAStarPlanner as ah, createJPSPlanner as ai, createHPAPlanner as aj, IncrementalGridPathPlannerAdapter as ak, createIncrementalAStarPlanner as al, ORCALocalAvoidanceAdapter as am, createORCAAvoidance as an, DEFAULT_ORCA_PARAMS as ao, CollisionResolverAdapter as ap, createDefaultCollisionResolver as aq, FlowController as ar, createFlowController as as, type IORCAParams as at, type IGridPathfinderAdapterConfig as au, type IIncrementalGridPathPlannerConfig as av, type IPathfindingOptions as b, type IPathResult as c, type IPathNode as d, type IPoint as e, type IPathValidator as f, type IPathValidationResult as g, type IPathSmoother as h, createPoint as i, euclideanDistance as j, chebyshevDistance as k, HPAPathfinder as l, manhattanDistance as m, createHPAPathfinder as n, octileDistance as o, DEFAULT_HPA_CONFIG as p, createPathCache as q, DEFAULT_PATH_CACHE_CONFIG as r, type IPathCacheConfig as s, type IHPAConfig as t, type IPathRequest as u, type IPathProgress$1 as v, type IIncrementalPathResult as w, type IIncrementalPathfinder as x, type IIncrementalPathfindingOptions as y, type IIncrementalPathfinderConfig as z };