@esengine/pathfinding 13.2.0 → 13.3.1

package/dist/ecs.d.ts

@@ -1,196 +1,237 @@
 import { Component, EntitySystem, Entity } from '@esengine/ecs-framework';
-import { P as PathfindingState, e as IPoint, a as IPathfindingMap, f as IIncrementalPathfinder, m as IPathSmoother } from './IIncrementalPathfinding-3qs7e_pO.js';
-import { O as ORCASolver, K as KDTree, b as IObstacle, c as IORCASolverConfig } from './KDTree-2rs2EXvm.js';
+import { S as IVector2, V as IPathPlanner, a7 as IFlowController, a0 as ILocalAvoidance, a2 as ICollisionResolver, _ as IObstacleData } from './FlowController-BztOzQsW.js';
+export { ap as CollisionResolverAdapter, ab as DEFAULT_FLOW_CONTROLLER_CONFIG, ao as DEFAULT_ORCA_PARAMS, ar as FlowController, ag as GridPathfinderAdapter, a3 as ICongestionZone, a4 as IFlowAgentData, a5 as IFlowControlResult, a6 as IFlowControllerConfig, au as IGridPathfinderAdapterConfig, av as IIncrementalGridPathPlannerConfig, at as IORCAParams, ak as IncrementalGridPathPlannerAdapter, ae as NavMeshPathPlannerAdapter, am as ORCALocalAvoidanceAdapter, aa as PassPermission, ah as createAStarPlanner, aq as createDefaultCollisionResolver, as as createFlowController, aj as createHPAPlanner, al as createIncrementalAStarPlanner, ai as createJPSPlanner, af as createNavMeshPathPlanner, an as createORCAAvoidance } from './FlowController-BztOzQsW.js';
+import './CollisionResolver-CSgWsegP.js';
 import '@esengine/ecs-framework-math';
 
 /**
- * @zh 寻路代理组件
- * @en Pathfinding Agent Component
+ * @zh 统一导航代理组件
+ * @en Unified Navigation Agent Component
+ *
+ * @zh 算法无关的通用导航属性，配合 NavigationSystem 使用
+ * @en Algorithm-agnostic common navigation properties, works with NavigationSystem
  */
 
 /**
- * @zh 寻路代理组件
- * @en Pathfinding Agent Component
+ * @zh 导航状态
+ * @en Navigation state
+ */
+declare enum NavigationState {
+    /**
+     * @zh 空闲
+     * @en Idle
+     */
+    Idle = "idle",
+    /**
+     * @zh 正在导航
+     * @en Navigating
+     */
+    Navigating = "navigating",
+    /**
+     * @zh 已到达
+     * @en Arrived
+     */
+    Arrived = "arrived",
+    /**
+     * @zh 路径被阻挡
+     * @en Path blocked
+     */
+    Blocked = "blocked",
+    /**
+     * @zh 无法到达
+     * @en Unreachable
+     */
+    Unreachable = "unreachable"
+}
+/**
+ * @zh 统一导航代理组件
+ * @en Unified navigation agent component
  *
- * @zh 附加到需要寻路的实体上，管理寻路请求和结果
- * @en Attach to entities that need pathfinding, manages path requests and results
+ * @zh 包含算法无关的通用导航属性，不包含算法特定参数
+ * @en Contains algorithm-agnostic common navigation properties, no algorithm-specific parameters
  *
  * @example
  * ```typescript
  * const entity = scene.createEntity('Agent');
- * const agent = entity.addComponent(new PathfindingAgentComponent());
  *
- * // Set initial position
- * agent.x = 10;
- * agent.y = 10;
+ * // 添加导航代理组件
+ * const nav = entity.addComponent(new NavigationAgentComponent());
+ * nav.radius = 0.5;
+ * nav.maxSpeed = 5.0;
  *
- * // Request path to target
- * agent.requestPathTo(50, 50);
+ * // 设置目标
+ * nav.setDestination(100, 200);
  *
- * // In movement system, follow the path
- * const waypoint = agent.getNextWaypoint();
- * if (waypoint) {
- *     // Move towards waypoint
- *     // When reached, call agent.advanceWaypoint()
- * }
+ * // NavigationSystem 会自动处理：
+ * // 1. 使用 IPathPlanner 计算全局路径
+ * // 2. 使用 ILocalAvoidance 进行局部避让
+ * // 3. 使用 ICollisionResolver 防止穿透
  * ```
  */
-declare class PathfindingAgentComponent extends Component {
+declare class NavigationAgentComponent extends Component {
     /**
-     * @zh 当前位置 X 坐标
-     * @en Current position X coordinate
+     * @zh 代理半径
+     * @en Agent radius
      */
-    x: number;
+    radius: number;
     /**
-     * @zh 当前位置 Y 坐标
-     * @en Current position Y coordinate
+     * @zh 最大速度
+     * @en Maximum speed
      */
-    y: number;
+    maxSpeed: number;
     /**
-     * @zh 目标位置 X 坐标
-     * @en Target position X coordinate
+     * @zh 加速度（用于平滑移动）
+     * @en Acceleration (for smooth movement)
      */
-    targetX: number;
+    acceleration: number;
     /**
-     * @zh 目标位置 Y 坐标
-     * @en Target position Y coordinate
+     * @zh 路径点到达阈值
+     * @en Waypoint arrival threshold
      */
-    targetY: number;
+    waypointThreshold: number;
     /**
-     * @zh 是否有新的寻路请求待处理
-     * @en Whether there is a new path request pending
+     * @zh 目标到达阈值
+     * @en Destination arrival threshold
      */
-    hasRequest: boolean;
+    arrivalThreshold: number;
     /**
-     * @zh 寻路优先级（数值越小优先级越高）
-     * @en Pathfinding priority (lower number = higher priority)
+     * @zh 路径重新计算间隔（秒）
+     * @en Path recalculation interval (seconds)
      */
-    priority: number;
+    repathInterval: number;
     /**
-     * @zh 每帧最大迭代次数
-     * @en Maximum iterations per frame
+     * @zh 是否启用导航
+     * @en Whether navigation is enabled
      */
-    maxIterationsPerFrame: number;
+    enabled: boolean;
     /**
-     * @zh 是否启用动态重规划
-     * @en Whether dynamic replanning is enabled
+     * @zh 是否自动重新计算被阻挡的路径
+     * @en Whether to auto repath when blocked
      */
-    enableDynamicReplan: boolean;
+    autoRepath: boolean;
     /**
-     * @zh 向前探测距离（用于障碍物检测）
-     * @en Lookahead distance for obstacle detection
+     * @zh 是否启用平滑转向
+     * @en Whether to enable smooth steering
      */
-    lookaheadDistance: number;
+    smoothSteering: boolean;
     /**
-     * @zh 路径验证间隔（帧数）
-     * @en Path validation interval (in frames)
+     * @zh 当前位置
+     * @en Current position
      */
-    validationInterval: number;
+    position: IVector2;
     /**
-     * @zh 当前寻路状态
-     * @en Current pathfinding state
+     * @zh 当前速度
+     * @en Current velocity
      */
-    state: PathfindingState;
+    velocity: IVector2;
     /**
-     * @zh 当前请求 ID
-     * @en Current request ID
+     * @zh 目标位置
+     * @en Destination position
      */
-    currentRequestId: number;
+    destination: IVector2 | null;
     /**
-     * @zh 当前路径点列表
-     * @en Current path waypoints
+     * @zh 当前导航状态
+     * @en Current navigation state
      */
-    path: IPoint[];
+    state: NavigationState;
     /**
-     * @zh 当前路径索引
-     * @en Current path index
+     * @zh 当前路径
+     * @en Current path
      */
-    pathIndex: number;
+    path: IVector2[];
     /**
-     * @zh 路径总代价
-     * @en Total path cost
+     * @zh 当前路径点索引
+     * @en Current waypoint index
      */
-    pathCost: number;
+    currentWaypointIndex: number;
+    /**
+     * @zh 上次重新计算路径的时间
+     * @en Last repath time
+     */
+    lastRepathTime: number;
+    /**
+     * @zh 当前增量寻路请求 ID
+     * @en Current incremental pathfinding request ID
+     */
+    currentRequestId: number;
     /**
      * @zh 寻路进度 (0-1)
      * @en Pathfinding progress (0-1)
      */
-    progress: number;
+    pathProgress: number;
     /**
-     * @zh 上次验证的帧号
-     * @en Last validation frame number
+     * @zh 优先级（数字越小优先级越高）
+     * @en Priority (lower number = higher priority)
      */
-    lastValidationFrame: number;
+    priority: number;
     /**
-     * @zh 寻路完成回调
-     * @en Pathfinding complete callback
+     * @zh 是否正在等待路径计算完成
+     * @en Whether waiting for path computation to complete
      */
-    onPathComplete?: (found: boolean, path: readonly IPoint[]) => void;
+    isComputingPath: boolean;
     /**
-     * @zh 寻路进度回调
-     * @en Pathfinding progress callback
+     * @zh 设置位置
+     * @en Set position
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
      */
-    onPathProgress?: (progress: number) => void;
+    setPosition(x: number, y: number): void;
     /**
-     * @zh 请求寻路到目标位置
-     * @en Request path to target position
+     * @zh 设置目标位置
+     * @en Set destination
      *
-     * @param targetX - @zh 目标 X 坐标 @en Target X coordinate
-     * @param targetY - @zh 目标 Y 坐标 @en Target Y coordinate
+     * @param x - @zh 目标 X 坐标 @en Destination X coordinate
+     * @param y - @zh 目标 Y 坐标 @en Destination Y coordinate
      */
-    requestPathTo(targetX: number, targetY: number): void;
+    setDestination(x: number, y: number): void;
     /**
-     * @zh 取消当前寻路
-     * @en Cancel current pathfinding
+     * @zh 停止导航
+     * @en Stop navigation
      */
-    cancelPath(): void;
+    stop(): void;
     /**
-     * @zh 获取下一个路径点
-     * @en Get next waypoint
+     * @zh 获取当前路径点
+     * @en Get current waypoint
      *
-     * @returns @zh 下一个路径点或 null @en Next waypoint or null
-     */
-    getNextWaypoint(): IPoint | null;
-    /**
-     * @zh 前进到下一个路径点
-     * @en Advance to next waypoint
+     * @returns @zh 当前路径点，如果没有则返回 null @en Current waypoint, or null if none
      */
-    advanceWaypoint(): void;
+    getCurrentWaypoint(): IVector2 | null;
     /**
-     * @zh 检查是否到达路径终点
-     * @en Check if reached path end
+     * @zh 获取到目标的距离
+     * @en Get distance to destination
      *
-     * @returns @zh 是否到达终点 @en Whether reached end
+     * @returns @zh 到目标的距离，如果没有目标则返回 Infinity @en Distance to destination, or Infinity if no destination
      */
-    isPathComplete(): boolean;
+    getDistanceToDestination(): number;
     /**
-     * @zh 检查是否正在寻路
-     * @en Check if pathfinding is in progress
+     * @zh 获取当前速度大小
+     * @en Get current speed
      *
-     * @returns @zh 是否正在寻路 @en Whether pathfinding is in progress
+     * @returns @zh 当前速度大小 @en Current speed magnitude
      */
-    isSearching(): boolean;
+    getCurrentSpeed(): number;
     /**
-     * @zh 检查是否有有效路径
-     * @en Check if has valid path
+     * @zh 检查是否已到达目标
+     * @en Check if arrived at destination
      *
-     * @returns @zh 是否有有效路径 @en Whether has valid path
+     * @returns @zh 是否已到达 @en Whether arrived
      */
-    hasValidPath(): boolean;
+    hasArrived(): boolean;
     /**
-     * @zh 获取剩余路径点数量
-     * @en Get remaining waypoint count
+     * @zh 检查路径是否被阻挡
+     * @en Check if path is blocked
      *
-     * @returns @zh 剩余路径点数量 @en Remaining waypoint count
+     * @returns @zh 是否被阻挡 @en Whether blocked
      */
-    getRemainingWaypointCount(): number;
+    isBlocked(): boolean;
     /**
-     * @zh 获取当前路径的总长度
-     * @en Get total path length
+     * @zh 检查目标是否无法到达
+     * @en Check if destination is unreachable
      *
-     * @returns @zh 路径总长度 @en Total path length
+     * @returns @zh 是否无法到达 @en Whether unreachable
      */
-    getPathLength(): number;
+    isUnreachable(): boolean;
     /**
      * @zh 重置组件状态
      * @en Reset component state
@@ -204,681 +245,433 @@ declare class PathfindingAgentComponent extends Component {
 }
 
 /**
- * @zh 寻路地图组件
- * @en Pathfinding Map Component
+ * @zh 统一导航系统
+ * @en Unified Navigation System
+ *
+ * @zh 可插拔的导航系统，支持运行时切换寻路、避让、碰撞检测算法
+ * @en Pluggable navigation system, supports runtime swapping of pathfinding, avoidance, and collision detection algorithms
  */
 
 /**
- * @zh 地图类型
- * @en Map type
- */
-type PathfindingMapType = 'grid' | 'navmesh';
-/**
- * @zh 寻路地图组件
- * @en Pathfinding Map Component
- *
- * @zh 挂载在场景实体上，持有地图实例和增量寻路器
- * @en Attached to scene entity, holds map instance and incremental pathfinder
- *
- * @example
- * ```typescript
- * const mapEntity = scene.createEntity('PathfindingMap');
- * const mapComp = mapEntity.addComponent(new PathfindingMapComponent());
- *
- * // Configure map
- * mapComp.width = 100;
- * mapComp.height = 100;
- * mapComp.iterationsBudget = 2000;
- *
- * // Map and pathfinder will be initialized by PathfindingSystem
- * ```
+ * @zh 导航系统配置
+ * @en Navigation system configuration
  */
-declare class PathfindingMapComponent extends Component {
-    /**
-     * @zh 地图类型
-     * @en Map type
-     */
-    mapType: PathfindingMapType;
-    /**
-     * @zh 网格宽度（仅 grid 类型）
-     * @en Grid width (grid type only)
-     */
-    width: number;
-    /**
-     * @zh 网格高度（仅 grid 类型）
-     * @en Grid height (grid type only)
-     */
-    height: number;
-    /**
-     * @zh 是否允许对角移动
-     * @en Whether diagonal movement is allowed
-     */
-    allowDiagonal: boolean;
-    /**
-     * @zh 是否避免穿角
-     * @en Whether to avoid corner cutting
-     */
-    avoidCorners: boolean;
-    /**
-     * @zh 每帧处理的最大代理数
-     * @en Maximum agents processed per frame
-     */
-    maxAgentsPerFrame: number;
+interface INavigationSystemConfig {
     /**
-     * @zh 每帧总迭代次数预算
-     * @en Total iterations budget per frame
-     */
-    iterationsBudget: number;
-    /**
-     * @zh 是否启用路径平滑
-     * @en Whether path smoothing is enabled
-     */
-    enableSmoothing: boolean;
-    /**
-     * @zh 路径平滑类型
-     * @en Path smoothing type
-     */
-    smoothingType: 'los' | 'catmullrom' | 'combined';
-    /**
-     * @zh 是否启用路径缓存
-     * @en Whether path caching is enabled
-     */
-    enableCache: boolean;
-    /**
-     * @zh 缓存最大条目数
-     * @en Maximum cache entries
-     */
-    cacheMaxEntries: number;
-    /**
-     * @zh 缓存过期时间（毫秒），0 表示不过期
-     * @en Cache TTL in milliseconds, 0 means no expiration
-     */
-    cacheTtlMs: number;
-    /**
-     * @zh 是否显示调试信息
-     * @en Whether to show debug info
-     */
-    debugMode: boolean;
-    /**
-     * @zh 是否显示网格
-     * @en Whether to show grid
-     */
-    showGrid: boolean;
-    /**
-     * @zh 是否显示路径
-     * @en Whether to show paths
-     */
-    showPaths: boolean;
-    /**
-     * @zh 地图实例
-     * @en Map instance
-     */
-    map: IPathfindingMap | null;
-    /**
-     * @zh 增量寻路器实例
-     * @en Incremental pathfinder instance
-     */
-    pathfinder: IIncrementalPathfinder | null;
-    /**
-     * @zh 路径平滑器实例
-     * @en Path smoother instance
-     */
-    smoother: IPathSmoother | null;
-    /**
-     * @zh 是否已初始化
-     * @en Whether initialized
+     * @zh 时间步长
+     * @en Time step
      */
-    initialized: boolean;
+    timeStep?: number;
     /**
-     * @zh 当前活跃请求数
-     * @en Current active request count
+     * @zh 是否启用路径规划阶段
+     * @en Whether to enable path planning stage
      */
-    activeRequests: number;
+    enablePathPlanning?: boolean;
     /**
-     * @zh 本帧使用的迭代次数
-     * @en Iterations used this frame
+     * @zh 是否启用流量控制阶段
+     * @en Whether to enable flow control stage
      */
-    iterationsUsedThisFrame: number;
+    enableFlowControl?: boolean;
     /**
-     * @zh 本帧处理的代理数
-     * @en Agents processed this frame
+     * @zh 是否启用局部避让阶段
+     * @en Whether to enable local avoidance stage
      */
-    agentsProcessedThisFrame: number;
+    enableLocalAvoidance?: boolean;
     /**
-     * @zh 缓存命中次数
-     * @en Cache hit count
+     * @zh 是否启用碰撞解决阶段
+     * @en Whether to enable collision resolution stage
      */
-    cacheHits: number;
+    enableCollisionResolution?: boolean;
     /**
-     * @zh 缓存未命中次数
-     * @en Cache miss count
+     * @zh 是否启用代理间碰撞解决
+     * @en Whether to enable agent-agent collision resolution
      */
-    cacheMisses: number;
+    enableAgentCollisionResolution?: boolean;
     /**
-     * @zh 设置网格单元格是否可通行
-     * @en Set grid cell walkability
+     * @zh 是否启用时间切片寻路（需要 IIncrementalPathPlanner）
+     * @en Whether to enable time-sliced pathfinding (requires IIncrementalPathPlanner)
      *
-     * @param x - @zh X 坐标 @en X coordinate
-     * @param y - @zh Y 坐标 @en Y coordinate
-     * @param walkable - @zh 是否可通行 @en Is walkable
+     * @zh 启用后，寻路计算会分散到多帧执行，避免卡顿
+     * @en When enabled, pathfinding computation is spread across multiple frames to avoid stuttering
      */
-    setWalkable(x: number, y: number, walkable: boolean): void;
+    enableTimeSlicing?: boolean;
     /**
-     * @zh 设置矩形区域是否可通行
-     * @en Set rectangular area walkability
+     * @zh 每帧总迭代预算
+     * @en Total iteration budget per frame
      *
-     * @param x - @zh 起始 X @en Start X
-     * @param y - @zh 起始 Y @en Start Y
-     * @param width - @zh 宽度 @en Width
-     * @param height - @zh 高度 @en Height
-     * @param walkable - @zh 是否可通行 @en Is walkable
-     */
-    setRectWalkable(x: number, y: number, rectWidth: number, rectHeight: number, walkable: boolean): void;
-    /**
-     * @zh 检查位置是否可通行
-     * @en Check if position is walkable
+     * @zh 所有代理共享此预算，根据优先级分配
+     * @en All agents share this budget, allocated by priority
      *
-     * @param x - @zh X 坐标 @en X coordinate
-     * @param y - @zh Y 坐标 @en Y coordinate
-     * @returns @zh 是否可通行 @en Is walkable
-     */
-    isWalkable(x: number, y: number): boolean;
-    /**
-     * @zh 重置统计信息
-     * @en Reset statistics
+     * @default 1000
      */
-    resetStats(): void;
+    iterationsBudget?: number;
     /**
-     * @zh 获取剩余迭代预算
-     * @en Get remaining iteration budget
+     * @zh 每帧最大处理代理数
+     * @en Maximum agents to process per frame
      *
-     * @returns @zh 剩余预算 @en Remaining budget
-     */
-    getRemainingBudget(): number;
-    /**
-     * @zh 获取缓存统计信息
-     * @en Get cache statistics
+     * @zh 限制每帧处理的代理数量，避免过载
+     * @en Limits the number of agents processed per frame to avoid overload
      *
-     * @returns @zh 缓存统计 @en Cache statistics
+     * @default 10
      */
-    getCacheStats(): {
-        enabled: boolean;
-        hits: number;
-        misses: number;
-        hitRate: number;
-    };
+    maxAgentsPerFrame?: number;
     /**
-     * @zh 组件从实体移除时调用
-     * @en Called when component is removed from entity
+     * @zh 每个代理每帧最大迭代数
+     * @en Maximum iterations per agent per frame
+     *
+     * @default 200
      */
-    onRemovedFromEntity(): void;
+    maxIterationsPerAgent?: number;
 }
-
 /**
- * @zh 寻路系统
- * @en Pathfinding System
- */
-
-/**
- * @zh 寻路系统
- * @en Pathfinding System
+ * @zh 统一导航系统
+ * @en Unified Navigation System
  *
- * @zh 处理所有 PathfindingAgentComponent，支持时间切片和动态重规划
- * @en Processes all PathfindingAgentComponents, supports time slicing and dynamic replanning
+ * @zh 可插拔的导航系统，处理管线：PathPlanning → LocalAvoidance → CollisionResolution
+ * @en Pluggable navigation system, pipeline: PathPlanning → LocalAvoidance → CollisionResolution
  *
  * @example
  * ```typescript
- * // Add system to scene
- * scene.addSystem(new PathfindingSystem());
+ * import {
+ *     NavigationSystem,
+ *     NavigationAgentComponent,
+ *     createNavMeshPathPlanner,
+ *     createORCAAvoidance,
+ *     createDefaultCollisionResolver
+ * } from '@esengine/pathfinding/ecs';
+ *
+ * // 创建系统
+ * const navSystem = new NavigationSystem();
+ *
+ * // 配置算法（可选，每个阶段都可以独立启用/禁用）
+ * navSystem.setPathPlanner(createNavMeshPathPlanner(navMesh));
+ * navSystem.setLocalAvoidance(createORCAAvoidance());
+ * navSystem.setCollisionResolver(createDefaultCollisionResolver());
  *
- * // Create map entity
- * const mapEntity = scene.createEntity('Map');
- * mapEntity.addComponent(new PathfindingMapComponent());
+ * scene.addSystem(navSystem);
  *
- * // Create agents
+ * // 添加障碍物
+ * navSystem.addObstacle({ vertices: [...] });
+ *
+ * // 创建代理
  * const agent = scene.createEntity('Agent');
- * const pathAgent = agent.addComponent(new PathfindingAgentComponent());
- * pathAgent.requestPathTo(50, 50);
+ * const nav = agent.addComponent(new NavigationAgentComponent());
+ * nav.setPosition(0, 0);
+ * nav.setDestination(100, 100);
  *
- * // System handles pathfinding automatically each frame
+ * // 运行时切换算法
+ * navSystem.setPathPlanner(createJPSPlanner(gridMap));
+ * navSystem.setLocalAvoidance(null);  // 禁用避让
  * ```
  */
-declare class PathfindingSystem extends EntitySystem {
-    private mapEntity;
-    private mapComponent;
-    private pathValidator;
-    private agentQueue;
-    private frameCounter;
-    constructor();
+declare class NavigationSystem extends EntitySystem {
+    private config;
+    private pathPlanner;
+    private flowController;
+    private localAvoidance;
+    private collisionResolver;
     /**
-     * @zh 系统初始化
-     * @en System initialization
+     * @zh 静态障碍物（墙壁、建筑等）- 由 PathPlanner 和 CollisionResolver 处理
+     * @en Static obstacles (walls, buildings) - handled by PathPlanner and CollisionResolver
      */
-    protected onInitialize(): void;
+    private staticObstacles;
     /**
-     * @zh 系统激活时调用
-     * @en Called when system is enabled
+     * @zh 动态障碍物（移动物体等）- 由 ORCA 和 CollisionResolver 处理
+     * @en Dynamic obstacles (moving objects) - handled by ORCA and CollisionResolver
      */
-    protected onEnable(): void;
+    private dynamicObstacles;
+    private currentTime;
+    private agentEnterTimes;
     /**
-     * @zh 处理实体
-     * @en Process entities
+     * @zh 是否为增量寻路器
+     * @en Whether the path planner is incremental
      */
-    protected process(entities: readonly Entity[]): void;
+    private isIncrementalPlanner;
     /**
-     * @zh 查找地图实体
-     * @en Find map entity
+     * @zh 等待寻路的代理队列（按优先级排序）
+     * @en Queue of agents waiting for pathfinding (sorted by priority)
      */
-    private findMapEntity;
+    private pendingPathRequests;
+    constructor(config?: INavigationSystemConfig);
     /**
-     * @zh 初始化地图
-     * @en Initialize map
+     * @zh 设置路径规划器
+     * @en Set path planner
+     *
+     * @param planner - @zh 路径规划器，传入 null 禁用路径规划 @en Path planner, pass null to disable
+     *
+     * @zh 如果传入 IIncrementalPathPlanner 且启用了时间切片，会自动使用增量寻路
+     * @en If passing IIncrementalPathPlanner and time slicing is enabled, will automatically use incremental pathfinding
+     *
+     * @example
+     * ```typescript
+     * navSystem.setPathPlanner(createNavMeshPathPlanner(navMesh));
+     * navSystem.setPathPlanner(createAStarPlanner(gridMap));
+     * navSystem.setPathPlanner(createIncrementalAStarPlanner(gridMap));  // 支持时间切片
+     * navSystem.setPathPlanner(null);  // 禁用
+     * ```
      */
-    private initializeMap;
+    setPathPlanner(planner: IPathPlanner | null): void;
     /**
-     * @zh 构建代理优先级队列
-     * @en Build agent priority queue
+     * @zh 获取当前路径规划器
+     * @en Get current path planner
      */
-    private buildAgentQueue;
+    getPathPlanner(): IPathPlanner | null;
     /**
-     * @zh 使用预算处理代理
-     * @en Process agents with budget
+     * @zh 设置流量控制器
+     * @en Set flow controller
+     *
+     * @param controller - @zh 流量控制器，传入 null 禁用流量控制 @en Flow controller, pass null to disable
+     *
+     * @example
+     * ```typescript
+     * navSystem.setFlowController(createFlowController());
+     * navSystem.setFlowController(null);  // 禁用
+     * ```
      */
-    private processAgentsWithBudget;
+    setFlowController(controller: IFlowController | null): void;
     /**
-     * @zh 启动新的寻路请求
-     * @en Start new pathfinding request
+     * @zh 获取当前流量控制器
+     * @en Get current flow controller
      */
-    private startNewRequest;
+    getFlowController(): IFlowController | null;
     /**
-     * @zh 从进度更新代理状态
-     * @en Update agent state from progress
+     * @zh 设置局部避让算法
+     * @en Set local avoidance algorithm
+     *
+     * @param avoidance - @zh 局部避让算法，传入 null 禁用避让 @en Local avoidance, pass null to disable
+     *
+     * @example
+     * ```typescript
+     * navSystem.setLocalAvoidance(createORCAAvoidance());
+     * navSystem.setLocalAvoidance(null);  // 禁用
+     * ```
      */
-    private updateAgentFromProgress;
+    setLocalAvoidance(avoidance: ILocalAvoidance | null): void;
     /**
-     * @zh 周期性验证路径有效性
-     * @en Periodically validate path validity
+     * @zh 获取当前局部避让算法
+     * @en Get current local avoidance algorithm
      */
-    private validatePaths;
-}
-
-/**
- * @zh 避让代理组件
- * @en Avoidance Agent Component
- */
-
-/**
- * @zh 避让代理组件
- * @en Avoidance Agent Component
- *
- * @zh 附加到需要局部避让的实体上，与 ORCA 系统配合使用
- * @en Attach to entities that need local avoidance, works with ORCA system
- *
- * @example
- * ```typescript
- * const entity = scene.createEntity('Monster');
- *
- * // 添加避让代理
- * const avoidance = entity.addComponent(new AvoidanceAgentComponent());
- * avoidance.radius = 0.5;
- * avoidance.maxSpeed = 5.0;
- *
- * // 设置首选速度（朝向目标）
- * avoidance.setPreferredVelocityTowards(targetX, targetY, currentX, currentY);
- *
- * // 系统计算后，使用新速度更新位置
- * // After system computes, use new velocity to update position
- * x += avoidance.newVelocityX * deltaTime;
- * y += avoidance.newVelocityY * deltaTime;
- * ```
- */
-declare class AvoidanceAgentComponent extends Component {
+    getLocalAvoidance(): ILocalAvoidance | null;
     /**
-     * @zh 代理半径
-     * @en Agent radius
+     * @zh 设置碰撞解决器
+     * @en Set collision resolver
      *
-     * @zh 用于碰撞检测和避让计算
-     * @en Used for collision detection and avoidance computation
+     * @param resolver - @zh 碰撞解决器，传入 null 禁用碰撞解决 @en Collision resolver, pass null to disable
+     *
+     * @example
+     * ```typescript
+     * navSystem.setCollisionResolver(createDefaultCollisionResolver());
+     * navSystem.setCollisionResolver(null);  // 禁用
+     * ```
      */
-    radius: number;
+    setCollisionResolver(resolver: ICollisionResolver | null): void;
     /**
-     * @zh 最大速度
-     * @en Maximum speed
+     * @zh 获取当前碰撞解决器
+     * @en Get current collision resolver
      */
-    maxSpeed: number;
+    getCollisionResolver(): ICollisionResolver | null;
     /**
-     * @zh 邻居检测距离
-     * @en Neighbor detection distance
+     * @zh 添加静态障碍物（墙壁、建筑等）
+     * @en Add static obstacle (walls, buildings, etc.)
      *
-     * @zh 只考虑此范围内的其他代理
-     * @en Only considers other agents within this range
-     */
-    neighborDist: number;
-    /**
-     * @zh 最大邻居数量
-     * @en Maximum number of neighbors to consider
+     * @zh 静态障碍物由 PathPlanner 规划路径时考虑，CollisionResolver 防止穿透
+     * @zh ORCA 不会处理静态障碍物，因为路径规划已经绑开了它们
+     * @en Static obstacles are considered by PathPlanner for routing, CollisionResolver for penetration prevention
+     * @en ORCA does NOT process static obstacles since path planning already avoids them
      *
-     * @zh 限制计算量，优先考虑最近的邻居
-     * @en Limits computation, prioritizes closest neighbors
+     * @param obstacle - @zh 障碍物数据 @en Obstacle data
      */
-    maxNeighbors: number;
+    addStaticObstacle(obstacle: IObstacleData): void;
     /**
-     * @zh 代理避让时间视野（秒）
-     * @en Time horizon for agent avoidance (seconds)
+     * @zh 添加动态障碍物（移动物体、临时障碍等）
+     * @en Add dynamic obstacle (moving objects, temporary obstacles, etc.)
      *
-     * @zh 更大的值会让代理更早开始避让，但可能导致过于保守
-     * @en Larger values make agents start avoiding earlier, but may be too conservative
-     */
-    timeHorizon: number;
-    /**
-     * @zh 障碍物避让时间视野（秒）
-     * @en Time horizon for obstacle avoidance (seconds)
-     */
-    timeHorizonObst: number;
-    /**
-     * @zh 当前位置 X
-     * @en Current position X
+     * @zh 动态障碍物由 ORCA 进行局部避让，CollisionResolver 防止穿透
+     * @en Dynamic obstacles are handled by ORCA for local avoidance, CollisionResolver for penetration prevention
      *
-     * @zh 如果实体有 Transform 组件，系统会自动同步
-     * @en If entity has Transform component, system will sync automatically
-     */
-    positionX: number;
-    /**
-     * @zh 当前位置 Y
-     * @en Current position Y
+     * @param obstacle - @zh 障碍物数据 @en Obstacle data
      */
-    positionY: number;
+    addDynamicObstacle(obstacle: IObstacleData): void;
     /**
-     * @zh 当前速度 X
-     * @en Current velocity X
+     * @zh 移除所有静态障碍物
+     * @en Remove all static obstacles
      */
-    velocityX: number;
+    clearStaticObstacles(): void;
     /**
-     * @zh 当前速度 Y
-     * @en Current velocity Y
+     * @zh 移除所有动态障碍物
+     * @en Remove all dynamic obstacles
      */
-    velocityY: number;
+    clearDynamicObstacles(): void;
     /**
-     * @zh 首选速度 X（通常指向目标方向）
-     * @en Preferred velocity X (usually towards target)
+     * @zh 移除所有障碍物（静态和动态）
+     * @en Remove all obstacles (static and dynamic)
      */
-    preferredVelocityX: number;
+    clearObstacles(): void;
     /**
-     * @zh 首选速度 Y
-     * @en Preferred velocity Y
+     * @zh 获取静态障碍物列表
+     * @en Get static obstacles list
      */
-    preferredVelocityY: number;
+    getStaticObstacles(): readonly IObstacleData[];
     /**
-     * @zh ORCA 计算的新速度 X
-     * @en New velocity X computed by ORCA
+     * @zh 获取动态障碍物列表
+     * @en Get dynamic obstacles list
      */
-    newVelocityX: number;
+    getDynamicObstacles(): readonly IObstacleData[];
     /**
-     * @zh ORCA 计算的新速度 Y
-     * @en New velocity Y computed by ORCA
+     * @zh 获取所有障碍物列表（静态+动态）
+     * @en Get all obstacles list (static + dynamic)
      */
-    newVelocityY: number;
+    getObstacles(): readonly IObstacleData[];
     /**
-     * @zh 是否启用避让
-     * @en Whether avoidance is enabled
+     * @zh 获取所有障碍物用于碰撞检测
+     * @en Get all obstacles for collision detection
      */
-    enabled: boolean;
+    private getAllObstaclesForCollision;
     /**
-     * @zh 是否自动应用新速度
-     * @en Whether to automatically apply new velocity
+     * @zh 设置静态障碍物列表
+     * @en Set static obstacles list
      *
-     * @zh 如果为 true，系统会在计算后自动将 newVelocity 赋值给 velocity
-     * @en If true, system will automatically assign newVelocity to velocity after computation
+     * @param obstacles - @zh 障碍物列表 @en Obstacles list
      */
-    autoApplyVelocity: boolean;
+    setStaticObstacles(obstacles: IObstacleData[]): void;
     /**
-     * @zh 设置位置
-     * @en Set position
-     */
-    setPosition(x: number, y: number): void;
-    /**
-     * @zh 设置当前速度
-     * @en Set current velocity
-     */
-    setVelocity(x: number, y: number): void;
-    /**
-     * @zh 设置首选速度
-     * @en Set preferred velocity
-     */
-    setPreferredVelocity(x: number, y: number): void;
-    /**
-     * @zh 设置首选速度朝向目标
-     * @en Set preferred velocity towards target
+     * @zh 设置动态障碍物列表
+     * @en Set dynamic obstacles list
      *
-     * @param targetX - @zh 目标 X @en Target X
-     * @param targetY - @zh 目标 Y @en Target Y
-     * @param currentX - @zh 当前 X（可选，默认使用 positionX）@en Current X (optional, defaults to positionX)
-     * @param currentY - @zh 当前 Y（可选，默认使用 positionY）@en Current Y (optional, defaults to positionY)
-     */
-    setPreferredVelocityTowards(targetX: number, targetY: number, currentX?: number, currentY?: number): void;
-    /**
-     * @zh 应用 ORCA 计算的新速度
-     * @en Apply new velocity computed by ORCA
-     */
-    applyNewVelocity(): void;
-    /**
-     * @zh 获取新速度的长度
-     * @en Get length of new velocity
-     */
-    getNewSpeed(): number;
-    /**
-     * @zh 获取当前速度的长度
-     * @en Get length of current velocity
-     */
-    getCurrentSpeed(): number;
-    /**
-     * @zh 停止代理
-     * @en Stop the agent
-     */
-    stop(): void;
-    /**
-     * @zh 重置组件状态
-     * @en Reset component state
-     */
-    reset(): void;
-    /**
-     * @zh 组件从实体移除时调用
-     * @en Called when component is removed from entity
+     * @param obstacles - @zh 障碍物列表 @en Obstacles list
      */
-    onRemovedFromEntity(): void;
-}
-
-/**
- * @zh 避让世界组件
- * @en Avoidance World Component
- */
-
-/**
- * @zh 避让世界组件
- * @en Avoidance World Component
- *
- * @zh 挂载在场景实体上，持有 ORCA 求解器和静态障碍物
- * @en Attached to scene entity, holds ORCA solver and static obstacles
- *
- * @example
- * ```typescript
- * const worldEntity = scene.createEntity('AvoidanceWorld');
- * const world = worldEntity.addComponent(new AvoidanceWorldComponent());
- *
- * // 添加静态障碍物（墙壁）
- * world.addObstacle({
- *     vertices: [
- *         { x: 0, y: 0 },
- *         { x: 10, y: 0 },
- *         { x: 10, y: 1 },
- *         { x: 0, y: 1 }
- *     ]
- * });
- *
- * // LocalAvoidanceSystem 会自动使用此组件
- * ```
- */
-declare class AvoidanceWorldComponent extends Component {
-    /**
-     * @zh 默认时间视野（代理）
-     * @en Default time horizon for agents
-     */
-    defaultTimeHorizon: number;
+    setDynamicObstacles(obstacles: IObstacleData[]): void;
     /**
-     * @zh 默认时间视野（障碍物）
-     * @en Default time horizon for obstacles
-     */
-    defaultTimeHorizonObst: number;
-    /**
-     * @zh 时间步长
-     * @en Time step
+     * @zh 系统销毁时调用
+     * @en Called when system is destroyed
      */
-    timeStep: number;
+    protected onDestroy(): void;
     /**
-     * @zh ORCA 求解器实例
-     * @en ORCA solver instance
+     * @zh 处理实体
+     * @en Process entities
      */
-    solver: ORCASolver | null;
+    protected process(entities: readonly Entity[]): void;
     /**
-     * @zh KD-Tree 实例
-     * @en KD-Tree instance
+     * @zh 处理等待中的代理
+     * @en Handle waiting agent
      */
-    kdTree: KDTree | null;
+    private handleWaitingAgent;
     /**
-     * @zh 静态障碍物列表
-     * @en List of static obstacles
+     * @zh 清理已移除代理的进入时间记录
+     * @en Cleanup enter times for removed agents
      */
-    obstacles: IObstacle[];
+    private cleanupEnterTimes;
     /**
-     * @zh 是否已初始化
-     * @en Whether initialized
+     * @zh 处理路径规划（同步模式）
+     * @en Process path planning (synchronous mode)
      */
-    initialized: boolean;
+    private processPathPlanning;
     /**
-     * @zh 当前代理数量
-     * @en Current agent count
+     * @zh 处理增量路径规划（时间切片模式）
+     * @en Process incremental path planning (time slicing mode)
+     *
+     * @param agents - @zh 代理列表 @en Agent list
+     * @param entityMap - @zh 实体 ID 到代理的映射 @en Entity ID to agent mapping
      */
-    agentCount: number;
+    private processIncrementalPathPlanning;
     /**
-     * @zh 本帧处理的代理数
-     * @en Agents processed this frame
+     * @zh 推进路径点
+     * @en Advance waypoint
      */
-    agentsProcessedThisFrame: number;
+    private advanceWaypoint;
     /**
-     * @zh 本帧 ORCA 计算耗时（毫秒）
-     * @en ORCA computation time this frame (ms)
+     * @zh 计算首选速度
+     * @en Calculate preferred velocity
      */
-    computeTimeMs: number;
+    private calculatePreferredVelocity;
     /**
-     * @zh 获取 ORCA 配置
-     * @en Get ORCA configuration
+     * @zh 构建代理数据
+     * @en Build agent data
      */
-    getConfig(): IORCASolverConfig;
+    private buildAgentData;
     /**
-     * @zh 添加静态障碍物
-     * @en Add static obstacle
-     *
-     * @param obstacle - @zh 障碍物（顶点列表，逆时针顺序）@en Obstacle (vertex list, counter-clockwise)
+     * @zh 应用避让结果
+     * @en Apply avoidance result
      */
-    addObstacle(obstacle: IObstacle): void;
+    private applyAvoidanceResult;
     /**
-     * @zh 添加矩形障碍物
-     * @en Add rectangular obstacle
-     *
-     * @param x - @zh 左下角 X @en Bottom-left X
-     * @param y - @zh 左下角 Y @en Bottom-left Y
-     * @param width - @zh 宽度 @en Width
-     * @param height - @zh 高度 @en Height
+     * @zh 应用平滑转向
+     * @en Apply smooth steering
      */
-    addRectObstacle(x: number, y: number, width: number, height: number): void;
+    private applySmoothSteering;
     /**
-     * @zh 移除所有障碍物
-     * @en Remove all obstacles
+     * @zh 检查是否到达目标
+     * @en Check if arrived at destination
      */
-    clearObstacles(): void;
+    private checkArrival;
     /**
-     * @zh 重置统计信息
-     * @en Reset statistics
+     * @zh 解决代理间碰撞
+     * @en Resolve agent-agent collisions
      */
-    resetStats(): void;
-    /**
-     * @zh 组件从实体移除时调用
-     * @en Called when component is removed from entity
-     */
-    onRemovedFromEntity(): void;
+    private resolveAgentCollisions;
 }
 
 /**
- * @zh 局部避让系统
- * @en Local Avoidance System
+ * @zh ORCA 算法配置组件
+ * @en ORCA Algorithm Configuration Component
+ *
+ * @zh 可选组件，仅当使用 ORCA 避让算法时需要，用于覆盖默认 ORCA 参数
+ * @en Optional component, only needed when using ORCA avoidance, to override default ORCA parameters
  */
 
 /**
- * @zh 局部避让系统
- * @en Local Avoidance System
+ * @zh ORCA 算法配置组件
+ * @en ORCA algorithm configuration component
  *
- * @zh 使用 ORCA 算法计算代理的避让速度
- * @en Uses ORCA algorithm to compute avoidance velocities for agents
+ * @zh 可选组件，附加到代理实体上以覆盖默认 ORCA 参数
+ * @en Optional component, attach to agent entities to override default ORCA parameters
  *
  * @example
  * ```typescript
- * // 添加系统到场景
- * scene.addSystem(new LocalAvoidanceSystem());
- *
- * // 创建避让世界（可选，用于静态障碍物）
- * const worldEntity = scene.createEntity('AvoidanceWorld');
- * worldEntity.addComponent(new AvoidanceWorldComponent());
- *
- * // 创建代理
- * const agent = scene.createEntity('Agent');
- * const avoidance = agent.addComponent(new AvoidanceAgentComponent());
- *
- * // 可选：同时添加寻路代理，系统会自动同步位置
- * agent.addComponent(new PathfindingAgentComponent());
+ * const entity = scene.createEntity('Agent');
  *
- * // 每帧设置首选速度（朝向目标）
- * avoidance.setPreferredVelocityTowards(targetX, targetY);
+ * // 添加导航代理
+ * entity.addComponent(new NavigationAgentComponent());
  *
- * // 系统计算后，newVelocity 会被更新
- * // 如果 autoApplyVelocity = true，velocity 也会自动更新
+ * // 可选：添加 ORCA 配置以自定义参数
+ * const orcaConfig = entity.addComponent(new ORCAConfigComponent());
+ * orcaConfig.timeHorizon = 3.0;  // 更长的预测时间
+ * orcaConfig.neighborDist = 20.0;  // 更大的邻居检测范围
  * ```
  */
-declare class LocalAvoidanceSystem extends EntitySystem {
-    private worldEntity;
-    private worldComponent;
-    private solver;
-    private kdTree;
-    constructor();
-    /**
-     * @zh 系统初始化
-     * @en System initialization
-     */
-    protected onInitialize(): void;
-    /**
-     * @zh 系统激活时调用
-     * @en Called when system is enabled
-     */
-    protected onEnable(): void;
+declare class ORCAConfigComponent extends Component {
     /**
-     * @zh 处理实体
-     * @en Process entities
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     *
+     * @zh 代理检测邻居的最大距离，更大的值意味着更早开始避让但也更消耗性能
+     * @en Maximum distance for detecting neighbors, larger value means earlier avoidance but more performance cost
      */
-    protected process(entities: readonly Entity[]): void;
+    neighborDist: number;
     /**
-     * @zh 查找世界实体
-     * @en Find world entity
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors
+     *
+     * @zh 计算避让时考虑的最大邻居数量，更多邻居意味着更精确但也更消耗性能
+     * @en Maximum neighbors considered for avoidance, more neighbors means more accurate but slower
      */
-    private findWorldEntity;
+    maxNeighbors: number;
     /**
-     * @zh 初始化求解器
-     * @en Initialize solver
+     * @zh 代理避让时间视野
+     * @en Time horizon for agent avoidance
+     *
+     * @zh 预测其他代理未来位置的时间范围，更长意味着更平滑但可能过度避让
+     * @en Time range for predicting other agents' future positions, longer means smoother but may over-avoid
      */
-    private initializeSolver;
+    timeHorizon: number;
     /**
-     * @zh 收集代理数据
-     * @en Collect agent data
+     * @zh 障碍物避让时间视野
+     * @en Time horizon for obstacle avoidance
+     *
+     * @zh 预测与障碍物碰撞的时间范围，通常比代理视野短
+     * @en Time range for predicting obstacle collisions, usually shorter than agent horizon
      */
-    private collectAgentData;
+    timeHorizonObst: number;
 }
 
-export { AvoidanceAgentComponent, AvoidanceWorldComponent, LocalAvoidanceSystem, PathfindingAgentComponent, PathfindingMapComponent, type PathfindingMapType, PathfindingSystem };
+export { IFlowController, type INavigationSystemConfig, NavigationAgentComponent, NavigationState, NavigationSystem, ORCAConfigComponent };