@esengine/pathfinding 13.1.0 → 13.3.0

package/dist/ecs.js

@@ -1,26 +1,32 @@
 import {
-  CatmullRomSmoother,
-  CombinedSmoother,
-  GridMap,
-  IncrementalAStarPathfinder,
-  LineOfSightSmoother,
-  PathValidator
-} from "./chunk-VNC2YAAL.js";
-import {
-  PathfindingState
-} from "./chunk-YKA3PWU3.js";
-import {
-  DEFAULT_AGENT_PARAMS,
-  DEFAULT_ORCA_CONFIG,
-  createKDTree,
-  createORCASolver
-} from "./chunk-JTZP55BJ.js";
+  CollisionResolverAdapter,
+  DEFAULT_FLOW_CONTROLLER_CONFIG,
+  DEFAULT_ORCA_PARAMS,
+  FlowController,
+  GridPathfinderAdapter,
+  IncrementalGridPathPlannerAdapter,
+  NavMeshPathPlannerAdapter,
+  ORCALocalAvoidanceAdapter,
+  PassPermission,
+  PathPlanState,
+  createAStarPlanner,
+  createDefaultCollisionResolver,
+  createFlowController,
+  createHPAPlanner,
+  createIncrementalAStarPlanner,
+  createJPSPlanner,
+  createNavMeshPathPlanner,
+  createORCAAvoidance,
+  isIncrementalPlanner
+} from "./chunk-NIKT3PQC.js";
+import "./chunk-YKA3PWU3.js";
+import "./chunk-3VEX32JO.js";
 import {
   __name,
   __publicField
 } from "./chunk-T626JPC7.js";
 
-// src/ecs/PathfindingAgentComponent.ts
+// src/ecs/NavigationAgentComponent.ts
 import { Component, ECSComponent, Serializable, Serialize, Property } from "@esengine/ecs-framework";
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -33,225 +39,264 @@ function _ts_metadata(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata, "_ts_metadata");
-var _PathfindingAgentComponent = class _PathfindingAgentComponent extends Component {
+var NavigationState = /* @__PURE__ */ (function(NavigationState2) {
+  NavigationState2["Idle"] = "idle";
+  NavigationState2["Navigating"] = "navigating";
+  NavigationState2["Arrived"] = "arrived";
+  NavigationState2["Blocked"] = "blocked";
+  NavigationState2["Unreachable"] = "unreachable";
+  return NavigationState2;
+})({});
+var _NavigationAgentComponent = class _NavigationAgentComponent extends Component {
   constructor() {
     super(...arguments);
     // =========================================================================
-    // 位置属性 | Position Properties
+    // 核心物理属性 | Core Physical Properties
     // =========================================================================
     /**
-     * @zh 当前位置 X 坐标
-     * @en Current position X coordinate
+     * @zh 代理半径
+     * @en Agent radius
+     */
+    __publicField(this, "radius", 0.5);
+    /**
+     * @zh 最大速度
+     * @en Maximum speed
      */
-    __publicField(this, "x", 0);
+    __publicField(this, "maxSpeed", 5);
     /**
-     * @zh 当前位置 Y 坐标
-     * @en Current position Y coordinate
+     * @zh 加速度（用于平滑移动）
+     * @en Acceleration (for smooth movement)
      */
-    __publicField(this, "y", 0);
+    __publicField(this, "acceleration", 10);
     // =========================================================================
-    // 目标属性 | Target Properties
+    // 寻路配置 | Pathfinding Configuration
     // =========================================================================
     /**
-     * @zh 目标位置 X 坐标
-     * @en Target position X coordinate
+     * @zh 路径点到达阈值
+     * @en Waypoint arrival threshold
      */
-    __publicField(this, "targetX", 0);
+    __publicField(this, "waypointThreshold", 0.5);
     /**
-     * @zh 目标位置 Y 坐标
-     * @en Target position Y coordinate
+     * @zh 目标到达阈值
+     * @en Destination arrival threshold
      */
-    __publicField(this, "targetY", 0);
+    __publicField(this, "arrivalThreshold", 0.3);
     /**
-     * @zh 是否有新的寻路请求待处理
-     * @en Whether there is a new path request pending
+     * @zh 路径重新计算间隔（秒）
+     * @en Path recalculation interval (seconds)
      */
-    __publicField(this, "hasRequest", false);
+    __publicField(this, "repathInterval", 0.5);
     // =========================================================================
-    // 配置属性 | Configuration Properties
+    // 配置选项 | Configuration Options
     // =========================================================================
     /**
-     * @zh 寻路优先级（数值越小优先级越高）
-     * @en Pathfinding priority (lower number = higher priority)
+     * @zh 是否启用导航
+     * @en Whether navigation is enabled
      */
-    __publicField(this, "priority", 50);
+    __publicField(this, "enabled", true);
     /**
-     * @zh 每帧最大迭代次数
-     * @en Maximum iterations per frame
+     * @zh 是否自动重新计算被阻挡的路径
+     * @en Whether to auto repath when blocked
      */
-    __publicField(this, "maxIterationsPerFrame", 100);
+    __publicField(this, "autoRepath", true);
     /**
-     * @zh 是否启用动态重规划
-     * @en Whether dynamic replanning is enabled
+     * @zh 是否启用平滑转向
+     * @en Whether to enable smooth steering
      */
-    __publicField(this, "enableDynamicReplan", true);
+    __publicField(this, "smoothSteering", true);
+    // =========================================================================
+    // 运行时状态 | Runtime State (Non-serialized)
+    // =========================================================================
     /**
-     * @zh 向前探测距离（用于障碍物检测）
-     * @en Lookahead distance for obstacle detection
+     * @zh 当前位置
+     * @en Current position
      */
-    __publicField(this, "lookaheadDistance", 5);
+    __publicField(this, "position", {
+      x: 0,
+      y: 0
+    });
     /**
-     * @zh 路径验证间隔（帧数）
-     * @en Path validation interval (in frames)
+     * @zh 当前速度
+     * @en Current velocity
      */
-    __publicField(this, "validationInterval", 10);
-    // =========================================================================
-    // 运行时状态（不序列化）| Runtime State (not serialized)
-    // =========================================================================
+    __publicField(this, "velocity", {
+      x: 0,
+      y: 0
+    });
     /**
-     * @zh 当前寻路状态
-     * @en Current pathfinding state
+     * @zh 目标位置
+     * @en Destination position
      */
-    __publicField(this, "state", PathfindingState.Idle);
+    __publicField(this, "destination", null);
     /**
-     * @zh 当前请求 ID
-     * @en Current request ID
+     * @zh 当前导航状态
+     * @en Current navigation state
      */
-    __publicField(this, "currentRequestId", -1);
+    __publicField(this, "state", "idle");
     /**
-     * @zh 当前路径点列表
-     * @en Current path waypoints
+     * @zh 当前路径
+     * @en Current path
      */
     __publicField(this, "path", []);
     /**
-     * @zh 当前路径索引
-     * @en Current path index
+     * @zh 当前路径点索引
+     * @en Current waypoint index
      */
-    __publicField(this, "pathIndex", 0);
+    __publicField(this, "currentWaypointIndex", 0);
     /**
-     * @zh 路径总代价
-     * @en Total path cost
+     * @zh 上次重新计算路径的时间
+     * @en Last repath time
      */
-    __publicField(this, "pathCost", 0);
+    __publicField(this, "lastRepathTime", 0);
+    // =========================================================================
+    // 增量寻路状态（时间切片）| Incremental Pathfinding State (Time Slicing)
+    // =========================================================================
     /**
-     * @zh 寻路进度 (0-1)
-     * @en Pathfinding progress (0-1)
+     * @zh 当前增量寻路请求 ID
+     * @en Current incremental pathfinding request ID
      */
-    __publicField(this, "progress", 0);
+    __publicField(this, "currentRequestId", -1);
     /**
-     * @zh 上次验证的帧号
-     * @en Last validation frame number
+     * @zh 寻路进度 (0-1)
+     * @en Pathfinding progress (0-1)
      */
-    __publicField(this, "lastValidationFrame", 0);
+    __publicField(this, "pathProgress", 0);
     /**
-     * @zh 寻路完成回调
-     * @en Pathfinding complete callback
+     * @zh 优先级（数字越小优先级越高）
+     * @en Priority (lower number = higher priority)
      */
-    __publicField(this, "onPathComplete");
+    __publicField(this, "priority", 50);
     /**
-     * @zh 寻路进度回调
-     * @en Pathfinding progress callback
+     * @zh 是否正在等待路径计算完成
+     * @en Whether waiting for path computation to complete
      */
-    __publicField(this, "onPathProgress");
+    __publicField(this, "isComputingPath", false);
   }
   // =========================================================================
   // 公共方法 | Public Methods
   // =========================================================================
   /**
-   * @zh 请求寻路到目标位置
-   * @en Request path to target position
+   * @zh 设置位置
+   * @en Set position
    *
-   * @param targetX - @zh 目标 X 坐标 @en Target X coordinate
-   * @param targetY - @zh 目标 Y 坐标 @en Target Y coordinate
+   * @param x - @zh X 坐标 @en X coordinate
+   * @param y - @zh Y 坐标 @en Y coordinate
    */
-  requestPathTo(targetX, targetY) {
-    this.targetX = targetX;
-    this.targetY = targetY;
-    this.hasRequest = true;
-    this.state = PathfindingState.Idle;
-    this.progress = 0;
+  setPosition(x, y) {
+    this.position = {
+      x,
+      y
+    };
   }
   /**
-   * @zh 取消当前寻路
-   * @en Cancel current pathfinding
+   * @zh 设置目标位置
+   * @en Set destination
+   *
+   * @param x - @zh 目标 X 坐标 @en Destination X coordinate
+   * @param y - @zh 目标 Y 坐标 @en Destination Y coordinate
    */
-  cancelPath() {
-    this.hasRequest = false;
-    this.state = PathfindingState.Cancelled;
+  setDestination(x, y) {
+    this.destination = {
+      x,
+      y
+    };
+    this.state = "navigating";
     this.path = [];
-    this.pathIndex = 0;
-    this.progress = 0;
-    this.currentRequestId = -1;
+    this.currentWaypointIndex = 0;
+    this.lastRepathTime = 0;
   }
   /**
-   * @zh 获取下一个路径点
-   * @en Get next waypoint
-   *
-   * @returns @zh 下一个路径点或 null @en Next waypoint or null
+   * @zh 停止导航
+   * @en Stop navigation
    */
-  getNextWaypoint() {
-    if (this.pathIndex < this.path.length) {
-      return this.path[this.pathIndex];
-    }
-    return null;
+  stop() {
+    this.destination = null;
+    this.state = "idle";
+    this.path = [];
+    this.currentWaypointIndex = 0;
+    this.velocity = {
+      x: 0,
+      y: 0
+    };
   }
   /**
-   * @zh 前进到下一个路径点
-   * @en Advance to next waypoint
+   * @zh 获取当前路径点
+   * @en Get current waypoint
+   *
+   * @returns @zh 当前路径点，如果没有则返回 null @en Current waypoint, or null if none
    */
-  advanceWaypoint() {
-    if (this.pathIndex < this.path.length) {
-      this.pathIndex++;
+  getCurrentWaypoint() {
+    if (this.currentWaypointIndex < this.path.length) {
+      return this.path[this.currentWaypointIndex];
     }
+    return 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() {
-    return this.pathIndex >= this.path.length;
+  getDistanceToDestination() {
+    if (!this.destination) return Infinity;
+    const dx = this.destination.x - this.position.x;
+    const dy = this.destination.y - this.position.y;
+    return Math.sqrt(dx * dx + dy * dy);
   }
   /**
-   * @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() {
-    return this.state === PathfindingState.InProgress;
+  getCurrentSpeed() {
+    return Math.sqrt(this.velocity.x * this.velocity.x + this.velocity.y * this.velocity.y);
   }
   /**
-   * @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() {
-    return this.state === PathfindingState.Completed && this.path.length > 0;
+  hasArrived() {
+    return this.state === "arrived";
   }
   /**
-   * @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() {
-    return Math.max(0, this.path.length - this.pathIndex);
+  isBlocked() {
+    return this.state === "blocked";
   }
   /**
-   * @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() {
-    return this.path.length;
+  isUnreachable() {
+    return this.state === "unreachable";
   }
   /**
    * @zh 重置组件状态
    * @en Reset component state
    */
   reset() {
-    this.state = PathfindingState.Idle;
-    this.currentRequestId = -1;
+    this.position = {
+      x: 0,
+      y: 0
+    };
+    this.velocity = {
+      x: 0,
+      y: 0
+    };
+    this.destination = null;
+    this.state = "idle";
     this.path = [];
-    this.pathIndex = 0;
-    this.pathCost = 0;
-    this.progress = 0;
-    this.hasRequest = false;
-    this.lastValidationFrame = 0;
+    this.currentWaypointIndex = 0;
+    this.lastRepathTime = 0;
   }
   /**
    * @zh 组件从实体移除时调用
@@ -259,102 +304,104 @@ var _PathfindingAgentComponent = class _PathfindingAgentComponent extends Compon
    */
   onRemovedFromEntity() {
     this.reset();
-    this.onPathComplete = void 0;
-    this.onPathProgress = void 0;
   }
 };
-__name(_PathfindingAgentComponent, "PathfindingAgentComponent");
-var PathfindingAgentComponent = _PathfindingAgentComponent;
+__name(_NavigationAgentComponent, "NavigationAgentComponent");
+var NavigationAgentComponent = _NavigationAgentComponent;
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Position X"
+    label: "Radius",
+    min: 0.1,
+    max: 10
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "x", void 0);
+], NavigationAgentComponent.prototype, "radius", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Position Y"
+    label: "Max Speed",
+    min: 0.1,
+    max: 100
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "y", void 0);
+], NavigationAgentComponent.prototype, "maxSpeed", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Target X"
+    label: "Acceleration",
+    min: 0.1,
+    max: 100
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "targetX", void 0);
+], NavigationAgentComponent.prototype, "acceleration", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Target Y"
+    label: "Waypoint Threshold",
+    min: 0.1,
+    max: 10
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "targetY", void 0);
+], NavigationAgentComponent.prototype, "waypointThreshold", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Priority",
-    min: 0,
-    max: 100
+    label: "Arrival Threshold",
+    min: 0.1,
+    max: 10
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "priority", void 0);
+], NavigationAgentComponent.prototype, "arrivalThreshold", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "number",
-    label: "Max Iterations/Frame",
-    min: 10,
-    max: 1e3
+    label: "Repath Interval",
+    min: 0.1,
+    max: 10
   }),
   _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "maxIterationsPerFrame", void 0);
+], NavigationAgentComponent.prototype, "repathInterval", void 0);
 _ts_decorate([
   Serialize(),
   Property({
     type: "boolean",
-    label: "Dynamic Replan"
+    label: "Enabled"
   }),
   _ts_metadata("design:type", Boolean)
-], PathfindingAgentComponent.prototype, "enableDynamicReplan", void 0);
+], NavigationAgentComponent.prototype, "enabled", void 0);
 _ts_decorate([
   Serialize(),
   Property({
-    type: "number",
-    label: "Lookahead Distance",
-    min: 1,
-    max: 20
+    type: "boolean",
+    label: "Auto Repath"
   }),
-  _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "lookaheadDistance", void 0);
+  _ts_metadata("design:type", Boolean)
+], NavigationAgentComponent.prototype, "autoRepath", void 0);
 _ts_decorate([
   Serialize(),
   Property({
-    type: "number",
-    label: "Validation Interval",
-    min: 1,
-    max: 60
+    type: "boolean",
+    label: "Smooth Steering"
   }),
-  _ts_metadata("design:type", Number)
-], PathfindingAgentComponent.prototype, "validationInterval", void 0);
-PathfindingAgentComponent = _ts_decorate([
-  ECSComponent("PathfindingAgent"),
+  _ts_metadata("design:type", Boolean)
+], NavigationAgentComponent.prototype, "smoothSteering", void 0);
+NavigationAgentComponent = _ts_decorate([
+  ECSComponent("NavigationAgent"),
   Serializable({
     version: 1,
-    typeId: "PathfindingAgent"
+    typeId: "NavigationAgent"
   })
-], PathfindingAgentComponent);
+], NavigationAgentComponent);
 
-// src/ecs/PathfindingMapComponent.ts
-import { Component as Component2, ECSComponent as ECSComponent2, Serializable as Serializable2, Serialize as Serialize2, Property as Property2 } from "@esengine/ecs-framework";
+// src/ecs/NavigationSystem.ts
+import { EntitySystem, Matcher, ECSSystem } from "@esengine/ecs-framework";
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -366,1357 +413,914 @@ function _ts_metadata2(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata2, "_ts_metadata");
-var _PathfindingMapComponent = class _PathfindingMapComponent extends Component2 {
-  constructor() {
-    super(...arguments);
-    // =========================================================================
-    // 地图配置 | Map Configuration
-    // =========================================================================
-    /**
-     * @zh 地图类型
-     * @en Map type
-     */
-    __publicField(this, "mapType", "grid");
-    /**
-     * @zh 网格宽度（仅 grid 类型）
-     * @en Grid width (grid type only)
-     */
-    __publicField(this, "width", 100);
-    /**
-     * @zh 网格高度（仅 grid 类型）
-     * @en Grid height (grid type only)
-     */
-    __publicField(this, "height", 100);
-    /**
-     * @zh 是否允许对角移动
-     * @en Whether diagonal movement is allowed
-     */
-    __publicField(this, "allowDiagonal", true);
-    /**
-     * @zh 是否避免穿角
-     * @en Whether to avoid corner cutting
-     */
-    __publicField(this, "avoidCorners", true);
-    // =========================================================================
-    // 系统配置 | System Configuration
-    // =========================================================================
-    /**
-     * @zh 每帧处理的最大代理数
-     * @en Maximum agents processed per frame
-     */
-    __publicField(this, "maxAgentsPerFrame", 10);
-    /**
-     * @zh 每帧总迭代次数预算
-     * @en Total iterations budget per frame
-     */
-    __publicField(this, "iterationsBudget", 1e3);
-    /**
-     * @zh 是否启用路径平滑
-     * @en Whether path smoothing is enabled
-     */
-    __publicField(this, "enableSmoothing", true);
-    /**
-     * @zh 路径平滑类型
-     * @en Path smoothing type
-     */
-    __publicField(this, "smoothingType", "los");
-    // =========================================================================
-    // 缓存配置 | Cache Configuration
-    // =========================================================================
-    /**
-     * @zh 是否启用路径缓存
-     * @en Whether path caching is enabled
-     */
-    __publicField(this, "enableCache", true);
-    /**
-     * @zh 缓存最大条目数
-     * @en Maximum cache entries
-     */
-    __publicField(this, "cacheMaxEntries", 1e3);
-    /**
-     * @zh 缓存过期时间（毫秒），0 表示不过期
-     * @en Cache TTL in milliseconds, 0 means no expiration
-     */
-    __publicField(this, "cacheTtlMs", 5e3);
-    // =========================================================================
-    // 调试配置 | Debug Configuration
-    // =========================================================================
-    /**
-     * @zh 是否显示调试信息
-     * @en Whether to show debug info
-     */
-    __publicField(this, "debugMode", false);
-    /**
-     * @zh 是否显示网格
-     * @en Whether to show grid
-     */
-    __publicField(this, "showGrid", false);
-    /**
-     * @zh 是否显示路径
-     * @en Whether to show paths
-     */
-    __publicField(this, "showPaths", false);
-    // =========================================================================
-    // 运行时实例（不序列化）| Runtime Instances (not serialized)
-    // =========================================================================
-    /**
-     * @zh 地图实例
-     * @en Map instance
-     */
-    __publicField(this, "map", null);
-    /**
-     * @zh 增量寻路器实例
-     * @en Incremental pathfinder instance
-     */
-    __publicField(this, "pathfinder", null);
-    /**
-     * @zh 路径平滑器实例
-     * @en Path smoother instance
-     */
-    __publicField(this, "smoother", null);
-    /**
-     * @zh 是否已初始化
-     * @en Whether initialized
-     */
-    __publicField(this, "initialized", false);
+var DEFAULT_CONFIG = {
+  timeStep: 1 / 60,
+  enablePathPlanning: true,
+  enableFlowControl: true,
+  enableLocalAvoidance: true,
+  enableCollisionResolution: true,
+  enableAgentCollisionResolution: true,
+  enableTimeSlicing: false,
+  iterationsBudget: 1e3,
+  maxAgentsPerFrame: 10,
+  maxIterationsPerAgent: 200
+};
+var _NavigationSystem = class _NavigationSystem extends EntitySystem {
+  constructor(config = {}) {
+    super(Matcher.all(NavigationAgentComponent));
+    __publicField(this, "config");
+    __publicField(this, "pathPlanner", null);
+    __publicField(this, "flowController", null);
+    __publicField(this, "localAvoidance", null);
+    __publicField(this, "collisionResolver", null);
+    /**
+     * @zh 静态障碍物（墙壁、建筑等）- 由 PathPlanner 和 CollisionResolver 处理
+     * @en Static obstacles (walls, buildings) - handled by PathPlanner and CollisionResolver
+     */
+    __publicField(this, "staticObstacles", []);
+    /**
+     * @zh 动态障碍物（移动物体等）- 由 ORCA 和 CollisionResolver 处理
+     * @en Dynamic obstacles (moving objects) - handled by ORCA and CollisionResolver
+     */
+    __publicField(this, "dynamicObstacles", []);
+    __publicField(this, "currentTime", 0);
+    __publicField(this, "agentEnterTimes", /* @__PURE__ */ new Map());
     // =========================================================================
-    // 统计信息 | Statistics
+    // 时间切片状态 | Time Slicing State
     // =========================================================================
     /**
-     * @zh 当前活跃请求数
-     * @en Current active request count
-     */
-    __publicField(this, "activeRequests", 0);
-    /**
-     * @zh 本帧使用的迭代次数
-     * @en Iterations used this frame
-     */
-    __publicField(this, "iterationsUsedThisFrame", 0);
-    /**
-     * @zh 本帧处理的代理数
-     * @en Agents processed this frame
+     * @zh 是否为增量寻路器
+     * @en Whether the path planner is incremental
      */
-    __publicField(this, "agentsProcessedThisFrame", 0);
+    __publicField(this, "isIncrementalPlanner", false);
     /**
-     * @zh 缓存命中次数
-     * @en Cache hit count
+     * @zh 等待寻路的代理队列（按优先级排序）
+     * @en Queue of agents waiting for pathfinding (sorted by priority)
      */
-    __publicField(this, "cacheHits", 0);
-    /**
-     * @zh 缓存未命中次数
-     * @en Cache miss count
-     */
-    __publicField(this, "cacheMisses", 0);
+    __publicField(this, "pendingPathRequests", /* @__PURE__ */ new Set());
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config
+    };
   }
   // =========================================================================
-  // 公共方法 | Public Methods
+  // 算法设置 | Algorithm Setters
   // =========================================================================
   /**
-   * @zh 设置网格单元格是否可通行
-   * @en Set grid cell walkability
+   * @zh 设置路径规划器
+   * @en Set path planner
    *
-   * @param x - @zh X 坐标 @en X coordinate
-   * @param y - @zh Y 坐标 @en Y coordinate
-   * @param walkable - @zh 是否可通行 @en Is walkable
+   * @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);  // 禁用
+   * ```
    */
-  setWalkable(x, y, walkable) {
-    if (this.map && "setWalkable" in this.map) {
-      this.map.setWalkable(x, y, walkable);
-      if (this.pathfinder) {
-        this.pathfinder.notifyObstacleChange(x - 1, y - 1, x + 1, y + 1);
-      }
-    }
+  setPathPlanner(planner) {
+    this.pathPlanner?.dispose();
+    this.pathPlanner = planner;
+    this.isIncrementalPlanner = planner !== null && isIncrementalPlanner(planner);
+    this.pendingPathRequests.clear();
   }
   /**
-   * @zh 设置矩形区域是否可通行
-   * @en Set rectangular area walkability
-   *
-   * @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
+   * @zh 获取当前路径规划器
+   * @en Get current path planner
    */
-  setRectWalkable(x, y, rectWidth, rectHeight, walkable) {
-    if (this.map && "setRectWalkable" in this.map) {
-      this.map.setRectWalkable(x, y, rectWidth, rectHeight, walkable);
-      if (this.pathfinder) {
-        this.pathfinder.notifyObstacleChange(x - 1, y - 1, x + rectWidth + 1, y + rectHeight + 1);
-      }
-    }
+  getPathPlanner() {
+    return this.pathPlanner;
   }
   /**
-   * @zh 检查位置是否可通行
-   * @en Check if position is walkable
+   * @zh 设置流量控制器
+   * @en Set flow controller
    *
-   * @param x - @zh X 坐标 @en X coordinate
-   * @param y - @zh Y 坐标 @en Y coordinate
-   * @returns @zh 是否可通行 @en Is walkable
+   * @param controller - @zh 流量控制器，传入 null 禁用流量控制 @en Flow controller, pass null to disable
+   *
+   * @example
+   * ```typescript
+   * navSystem.setFlowController(createFlowController());
+   * navSystem.setFlowController(null);  // 禁用
+   * ```
    */
-  isWalkable(x, y) {
-    return this.map?.isWalkable(x, y) ?? false;
+  setFlowController(controller) {
+    this.flowController?.dispose();
+    this.flowController = controller;
   }
   /**
-   * @zh 重置统计信息
-   * @en Reset statistics
+   * @zh 获取当前流量控制器
+   * @en Get current flow controller
    */
-  resetStats() {
-    this.iterationsUsedThisFrame = 0;
-    this.agentsProcessedThisFrame = 0;
+  getFlowController() {
+    return this.flowController;
   }
   /**
-   * @zh 获取剩余迭代预算
-   * @en Get remaining iteration budget
+   * @zh 设置局部避让算法
+   * @en Set local avoidance algorithm
    *
-   * @returns @zh 剩余预算 @en Remaining budget
+   * @param avoidance - @zh 局部避让算法，传入 null 禁用避让 @en Local avoidance, pass null to disable
+   *
+   * @example
+   * ```typescript
+   * navSystem.setLocalAvoidance(createORCAAvoidance());
+   * navSystem.setLocalAvoidance(null);  // 禁用
+   * ```
    */
-  getRemainingBudget() {
-    return Math.max(0, this.iterationsBudget - this.iterationsUsedThisFrame);
+  setLocalAvoidance(avoidance) {
+    this.localAvoidance?.dispose();
+    this.localAvoidance = avoidance;
   }
   /**
-   * @zh 获取缓存统计信息
-   * @en Get cache statistics
-   *
-   * @returns @zh 缓存统计 @en Cache statistics
+   * @zh 获取当前局部避让算法
+   * @en Get current local avoidance algorithm
    */
-  getCacheStats() {
-    const pathfinderWithCache = this.pathfinder;
-    if (pathfinderWithCache?.getCacheStats) {
-      const stats = pathfinderWithCache.getCacheStats();
-      this.cacheHits = stats.hits;
-      this.cacheMisses = stats.misses;
-      return {
-        enabled: this.enableCache,
-        hits: stats.hits,
-        misses: stats.misses,
-        hitRate: stats.hitRate
-      };
-    }
-    return {
-      enabled: this.enableCache,
-      hits: this.cacheHits,
-      misses: this.cacheMisses,
-      hitRate: this.cacheHits + this.cacheMisses > 0 ? this.cacheHits / (this.cacheHits + this.cacheMisses) : 0
-    };
+  getLocalAvoidance() {
+    return this.localAvoidance;
   }
   /**
-   * @zh 组件从实体移除时调用
-   * @en Called when component is removed from entity
+   * @zh 设置碰撞解决器
+   * @en Set collision resolver
+   *
+   * @param resolver - @zh 碰撞解决器，传入 null 禁用碰撞解决 @en Collision resolver, pass null to disable
+   *
+   * @example
+   * ```typescript
+   * navSystem.setCollisionResolver(createDefaultCollisionResolver());
+   * navSystem.setCollisionResolver(null);  // 禁用
+   * ```
    */
-  onRemovedFromEntity() {
-    if (this.pathfinder) {
-      this.pathfinder.clear();
-    }
-    this.map = null;
-    this.pathfinder = null;
-    this.smoother = null;
-    this.initialized = false;
-  }
-};
-__name(_PathfindingMapComponent, "PathfindingMapComponent");
-var PathfindingMapComponent = _PathfindingMapComponent;
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "enum",
-    label: "Map Type",
-    options: [
-      {
-        value: "grid",
-        label: "Grid"
-      },
-      {
-        value: "navmesh",
-        label: "NavMesh"
-      }
-    ]
-  }),
-  _ts_metadata2("design:type", typeof PathfindingMapType === "undefined" ? Object : PathfindingMapType)
-], PathfindingMapComponent.prototype, "mapType", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Map Width",
-    min: 1,
-    max: 1e4
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "width", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Map Height",
-    min: 1,
-    max: 1e4
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "height", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Allow Diagonal"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "allowDiagonal", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Avoid Corners"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "avoidCorners", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Max Agents/Frame",
-    min: 1,
-    max: 100
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "maxAgentsPerFrame", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Iterations Budget",
-    min: 100,
-    max: 1e4
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "iterationsBudget", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Enable Smoothing"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "enableSmoothing", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "enum",
-    label: "Smoothing Type",
-    options: [
-      {
-        value: "los",
-        label: "Line of Sight"
-      },
-      {
-        value: "catmullrom",
-        label: "Catmull-Rom"
-      },
-      {
-        value: "combined",
-        label: "Combined"
-      }
-    ]
-  }),
-  _ts_metadata2("design:type", String)
-], PathfindingMapComponent.prototype, "smoothingType", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Enable Cache"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "enableCache", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Cache Size",
-    min: 100,
-    max: 1e4
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "cacheMaxEntries", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "number",
-    label: "Cache TTL (ms)",
-    min: 0,
-    max: 6e4
-  }),
-  _ts_metadata2("design:type", Number)
-], PathfindingMapComponent.prototype, "cacheTtlMs", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Debug Mode"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "debugMode", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Show Grid"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "showGrid", void 0);
-_ts_decorate2([
-  Serialize2(),
-  Property2({
-    type: "boolean",
-    label: "Show Paths"
-  }),
-  _ts_metadata2("design:type", Boolean)
-], PathfindingMapComponent.prototype, "showPaths", void 0);
-PathfindingMapComponent = _ts_decorate2([
-  ECSComponent2("PathfindingMap"),
-  Serializable2({
-    version: 1,
-    typeId: "PathfindingMap"
-  })
-], PathfindingMapComponent);
-
-// src/ecs/PathfindingSystem.ts
-import { EntitySystem, Matcher, ECSSystem } from "@esengine/ecs-framework";
-function _ts_decorate3(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate3, "_ts_decorate");
-function _ts_metadata3(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata3, "_ts_metadata");
-var _PathfindingSystem = class _PathfindingSystem extends EntitySystem {
-  constructor() {
-    super(Matcher.all(PathfindingAgentComponent));
-    __publicField(this, "mapEntity", null);
-    __publicField(this, "mapComponent", null);
-    __publicField(this, "pathValidator");
-    __publicField(this, "agentQueue", []);
-    __publicField(this, "frameCounter", 0);
-    this.pathValidator = new PathValidator();
+  setCollisionResolver(resolver) {
+    this.collisionResolver?.dispose();
+    this.collisionResolver = resolver;
   }
   /**
-   * @zh 系统初始化
-   * @en System initialization
+   * @zh 获取当前碰撞解决器
+   * @en Get current collision resolver
    */
-  onInitialize() {
-    this.findMapEntity();
-    this.initializeMap();
+  getCollisionResolver() {
+    return this.collisionResolver;
   }
+  // =========================================================================
+  // 障碍物管理 | Obstacle Management
+  // =========================================================================
   /**
-   * @zh 系统激活时调用
-   * @en Called when system is enabled
+   * @zh 添加静态障碍物（墙壁、建筑等）
+   * @en Add static obstacle (walls, buildings, etc.)
+   *
+   * @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
+   *
+   * @param obstacle - @zh 障碍物数据 @en Obstacle data
    */
-  onEnable() {
-    this.findMapEntity();
+  addStaticObstacle(obstacle) {
+    this.staticObstacles.push(obstacle);
   }
   /**
-   * @zh 处理实体
-   * @en Process entities
+   * @zh 添加动态障碍物（移动物体、临时障碍等）
+   * @en Add dynamic obstacle (moving objects, temporary obstacles, etc.)
+   *
+   * @zh 动态障碍物由 ORCA 进行局部避让，CollisionResolver 防止穿透
+   * @en Dynamic obstacles are handled by ORCA for local avoidance, CollisionResolver for penetration prevention
+   *
+   * @param obstacle - @zh 障碍物数据 @en Obstacle data
    */
-  process(entities) {
-    if (!this.mapComponent?.pathfinder) {
-      this.findMapEntity();
-      if (!this.mapComponent?.pathfinder) {
-        return;
-      }
-    }
-    this.frameCounter++;
-    this.mapComponent.resetStats();
-    this.buildAgentQueue(entities);
-    this.processAgentsWithBudget();
-    this.validatePaths(entities);
+  addDynamicObstacle(obstacle) {
+    this.dynamicObstacles.push(obstacle);
   }
-  // =========================================================================
-  // 私有方法 | Private Methods
-  // =========================================================================
   /**
-   * @zh 查找地图实体
-   * @en Find map entity
+   * @zh 移除所有静态障碍物
+   * @en Remove all static obstacles
    */
-  findMapEntity() {
-    if (!this.scene) return;
-    const entities = this.scene.entities.findEntitiesWithComponent(PathfindingMapComponent);
-    if (entities.length > 0) {
-      const entity = entities[0];
-      const mapComp = entity.getComponent(PathfindingMapComponent);
-      if (mapComp) {
-        this.mapEntity = entity;
-        this.mapComponent = mapComp;
-        if (!mapComp.initialized) {
-          this.initializeMap();
-        }
-      }
-    }
+  clearStaticObstacles() {
+    this.staticObstacles = [];
   }
   /**
-   * @zh 初始化地图
-   * @en Initialize map
+   * @zh 移除所有动态障碍物
+   * @en Remove all dynamic obstacles
    */
-  initializeMap() {
-    if (!this.mapComponent) return;
-    if (this.mapComponent.initialized) return;
-    if (!this.mapComponent.map) {
-      if (this.mapComponent.mapType === "grid") {
-        this.mapComponent.map = new GridMap(this.mapComponent.width, this.mapComponent.height, {
-          allowDiagonal: this.mapComponent.allowDiagonal,
-          avoidCorners: this.mapComponent.avoidCorners
-        });
-      }
+  clearDynamicObstacles() {
+    this.dynamicObstacles = [];
+  }
+  /**
+   * @zh 移除所有障碍物（静态和动态）
+   * @en Remove all obstacles (static and dynamic)
+   */
+  clearObstacles() {
+    this.staticObstacles = [];
+    this.dynamicObstacles = [];
+  }
+  /**
+   * @zh 获取静态障碍物列表
+   * @en Get static obstacles list
+   */
+  getStaticObstacles() {
+    return this.staticObstacles;
+  }
+  /**
+   * @zh 获取动态障碍物列表
+   * @en Get dynamic obstacles list
+   */
+  getDynamicObstacles() {
+    return this.dynamicObstacles;
+  }
+  /**
+   * @zh 获取所有障碍物列表（静态+动态）
+   * @en Get all obstacles list (static + dynamic)
+   */
+  getObstacles() {
+    return [
+      ...this.staticObstacles,
+      ...this.dynamicObstacles
+    ];
+  }
+  /**
+   * @zh 获取所有障碍物用于碰撞检测
+   * @en Get all obstacles for collision detection
+   */
+  getAllObstaclesForCollision() {
+    return [
+      ...this.staticObstacles,
+      ...this.dynamicObstacles
+    ];
+  }
+  /**
+   * @zh 设置静态障碍物列表
+   * @en Set static obstacles list
+   *
+   * @param obstacles - @zh 障碍物列表 @en Obstacles list
+   */
+  setStaticObstacles(obstacles) {
+    this.staticObstacles = [
+      ...obstacles
+    ];
+  }
+  /**
+   * @zh 设置动态障碍物列表
+   * @en Set dynamic obstacles list
+   *
+   * @param obstacles - @zh 障碍物列表 @en Obstacles list
+   */
+  setDynamicObstacles(obstacles) {
+    this.dynamicObstacles = [
+      ...obstacles
+    ];
+  }
+  // =========================================================================
+  // 系统生命周期 | System Lifecycle
+  // =========================================================================
+  /**
+   * @zh 系统销毁时调用
+   * @en Called when system is destroyed
+   */
+  onDestroy() {
+    this.pathPlanner?.dispose();
+    this.flowController?.dispose();
+    this.localAvoidance?.dispose();
+    this.collisionResolver?.dispose();
+    this.pathPlanner = null;
+    this.flowController = null;
+    this.localAvoidance = null;
+    this.collisionResolver = null;
+    this.staticObstacles = [];
+    this.dynamicObstacles = [];
+    this.agentEnterTimes.clear();
+    this.pendingPathRequests.clear();
+    this.isIncrementalPlanner = false;
+  }
+  // =========================================================================
+  // 处理管线 | Processing Pipeline
+  // =========================================================================
+  /**
+   * @zh 处理实体
+   * @en Process entities
+   */
+  process(entities) {
+    if (entities.length === 0) return;
+    const deltaTime = this.config.timeStep;
+    this.currentTime += deltaTime;
+    const agentDataMap = /* @__PURE__ */ new Map();
+    const flowAgentDataList = [];
+    const entityMap = /* @__PURE__ */ new Map();
+    for (const entity of entities) {
+      entityMap.set(entity.id, entity);
     }
-    if (!this.mapComponent.pathfinder && this.mapComponent.map) {
-      this.mapComponent.pathfinder = new IncrementalAStarPathfinder(this.mapComponent.map, {
-        enableCache: this.mapComponent.enableCache,
-        cacheConfig: {
-          maxEntries: this.mapComponent.cacheMaxEntries,
-          ttlMs: this.mapComponent.cacheTtlMs
+    if (this.config.enablePathPlanning && this.pathPlanner) {
+      if (this.config.enableTimeSlicing && this.isIncrementalPlanner) {
+        const agentList = [];
+        for (const entity of entities) {
+          const agent = entity.getComponent(NavigationAgentComponent);
+          if (agent.enabled) {
+            agentList.push({
+              entityId: entity.id,
+              agent
+            });
+          }
+        }
+        this.processIncrementalPathPlanning(agentList, entityMap);
+      } else {
+        for (const entity of entities) {
+          const agent = entity.getComponent(NavigationAgentComponent);
+          if (!agent.enabled) continue;
+          this.processPathPlanning(agent, deltaTime);
         }
-      });
-    }
-    if (!this.mapComponent.smoother && this.mapComponent.enableSmoothing) {
-      switch (this.mapComponent.smoothingType) {
-        case "catmullrom":
-          this.mapComponent.smoother = new CatmullRomSmoother();
-          break;
-        case "combined":
-          this.mapComponent.smoother = new CombinedSmoother();
-          break;
-        case "los":
-        default:
-          this.mapComponent.smoother = new LineOfSightSmoother();
-          break;
       }
     }
-    this.mapComponent.initialized = true;
-  }
-  /**
-   * @zh 构建代理优先级队列
-   * @en Build agent priority queue
-   */
-  buildAgentQueue(entities) {
-    this.agentQueue.length = 0;
     for (const entity of entities) {
-      const agent = entity.getComponent(PathfindingAgentComponent);
-      if (!agent) continue;
-      if (!agent.hasRequest && (agent.state === PathfindingState.Idle || agent.state === PathfindingState.Completed || agent.state === PathfindingState.Cancelled)) {
-        continue;
+      const agent = entity.getComponent(NavigationAgentComponent);
+      if (!agent.enabled) continue;
+      if (!this.agentEnterTimes.has(entity.id)) {
+        this.agentEnterTimes.set(entity.id, this.currentTime);
       }
-      this.agentQueue.push({
-        entity,
-        component: agent
+      const preferredVelocity = this.calculatePreferredVelocity(agent);
+      const agentData = this.buildAgentData(entity, agent, preferredVelocity);
+      agentDataMap.set(entity.id, agentData);
+      flowAgentDataList.push({
+        id: entity.id,
+        position: {
+          x: agent.position.x,
+          y: agent.position.y
+        },
+        destination: agent.destination,
+        currentWaypoint: agent.getCurrentWaypoint(),
+        radius: agent.radius,
+        priority: 50,
+        enterTime: this.agentEnterTimes.get(entity.id)
       });
     }
-    this.agentQueue.sort((a, b) => a.component.priority - b.component.priority);
+    if (this.config.enableFlowControl && this.flowController) {
+      this.flowController.update(flowAgentDataList, deltaTime);
+    }
+    if (this.config.enableLocalAvoidance && this.localAvoidance && agentDataMap.size > 0) {
+      const proceedingAgents = [];
+      const proceedingEntityIds = /* @__PURE__ */ new Set();
+      for (const entity of entities) {
+        const agent = entity.getComponent(NavigationAgentComponent);
+        if (!agent.enabled) continue;
+        const flowResult = this.flowController?.getFlowControl(entity.id);
+        const permission = flowResult?.permission ?? PassPermission.Proceed;
+        if (permission === PassPermission.Wait) {
+          this.handleWaitingAgent(entity, agent, flowResult.waitPosition, deltaTime);
+        } else {
+          const agentData = agentDataMap.get(entity.id);
+          if (agentData) {
+            const speedMult = flowResult?.speedMultiplier ?? 1;
+            if (speedMult < 1) {
+              const modifiedAgentData = {
+                ...agentData,
+                preferredVelocity: {
+                  x: agentData.preferredVelocity.x * speedMult,
+                  y: agentData.preferredVelocity.y * speedMult
+                }
+              };
+              proceedingAgents.push(modifiedAgentData);
+            } else {
+              proceedingAgents.push(agentData);
+            }
+            proceedingEntityIds.add(entity.id);
+          }
+        }
+      }
+      if (proceedingAgents.length > 0) {
+        const avoidanceResults = this.localAvoidance.computeBatchAvoidance(proceedingAgents, this.dynamicObstacles, deltaTime);
+        for (const entity of entities) {
+          if (!proceedingEntityIds.has(entity.id)) continue;
+          const agent = entity.getComponent(NavigationAgentComponent);
+          if (!agent.enabled) continue;
+          const result = avoidanceResults.get(entity.id);
+          if (result) {
+            this.applyAvoidanceResult(entity, agent, result.velocity, deltaTime);
+          } else {
+            const agentData = agentDataMap.get(entity.id);
+            if (agentData) {
+              this.applyAvoidanceResult(entity, agent, agentData.preferredVelocity, deltaTime);
+            }
+          }
+        }
+      }
+    } else {
+      for (const entity of entities) {
+        const agent = entity.getComponent(NavigationAgentComponent);
+        if (!agent.enabled) continue;
+        const flowResult = this.flowController?.getFlowControl(entity.id);
+        const permission = flowResult?.permission ?? PassPermission.Proceed;
+        if (permission === PassPermission.Wait && this.config.enableFlowControl && this.flowController) {
+          this.handleWaitingAgent(entity, agent, flowResult.waitPosition, deltaTime);
+        } else {
+          const agentData = agentDataMap.get(entity.id);
+          if (agentData) {
+            let velocity = agentData.preferredVelocity;
+            const speedMult = flowResult?.speedMultiplier ?? 1;
+            if (speedMult < 1) {
+              velocity = {
+                x: velocity.x * speedMult,
+                y: velocity.y * speedMult
+              };
+            }
+            this.applyAvoidanceResult(entity, agent, velocity, deltaTime);
+          }
+        }
+      }
+    }
+    if (this.config.enableAgentCollisionResolution && this.collisionResolver) {
+      this.resolveAgentCollisions(entities);
+    }
+    this.cleanupEnterTimes(entities);
   }
   /**
-   * @zh 使用预算处理代理
-   * @en Process agents with budget
+   * @zh 处理等待中的代理
+   * @en Handle waiting agent
    */
-  processAgentsWithBudget() {
-    const pathfinder = this.mapComponent.pathfinder;
-    const maxAgents = this.mapComponent.maxAgentsPerFrame;
-    let remainingBudget = this.mapComponent.iterationsBudget;
-    let agentsProcessed = 0;
-    for (const { component: agent } of this.agentQueue) {
-      if (agentsProcessed >= maxAgents || remainingBudget <= 0) {
-        break;
-      }
-      if (agent.hasRequest && agent.state === PathfindingState.Idle) {
-        this.startNewRequest(agent, pathfinder);
-      }
-      if (agent.state === PathfindingState.InProgress) {
-        const iterations = Math.min(agent.maxIterationsPerFrame, remainingBudget);
-        const progress = pathfinder.step(agent.currentRequestId, iterations);
-        this.updateAgentFromProgress(agent, progress, pathfinder);
-        remainingBudget -= progress.nodesSearched;
-        this.mapComponent.iterationsUsedThisFrame += progress.nodesSearched;
+  handleWaitingAgent(entity, agent, waitPosition, deltaTime) {
+    if (waitPosition) {
+      const dx = waitPosition.x - agent.position.x;
+      const dy = waitPosition.y - agent.position.y;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      if (dist > agent.arrivalThreshold) {
+        const speed = Math.min(agent.maxSpeed * 0.5, dist);
+        const velocity = {
+          x: dx / dist * speed,
+          y: dy / dist * speed
+        };
+        this.applyAvoidanceResult(entity, agent, velocity, deltaTime);
+      } else {
+        agent.velocity = {
+          x: 0,
+          y: 0
+        };
       }
-      agentsProcessed++;
+    } else {
+      agent.velocity = {
+        x: 0,
+        y: 0
+      };
     }
-    this.mapComponent.agentsProcessedThisFrame = agentsProcessed;
   }
   /**
-   * @zh 启动新的寻路请求
-   * @en Start new pathfinding request
+   * @zh 清理已移除代理的进入时间记录
+   * @en Cleanup enter times for removed agents
    */
-  startNewRequest(agent, pathfinder) {
-    if (agent.currentRequestId >= 0) {
-      pathfinder.cancel(agent.currentRequestId);
-      pathfinder.cleanup(agent.currentRequestId);
+  cleanupEnterTimes(entities) {
+    const activeIds = new Set(entities.map((e) => e.id));
+    for (const id of this.agentEnterTimes.keys()) {
+      if (!activeIds.has(id)) {
+        this.agentEnterTimes.delete(id);
+      }
     }
-    const request = pathfinder.requestPath(agent.x, agent.y, agent.targetX, agent.targetY, {
-      priority: agent.priority
-    });
-    agent.currentRequestId = request.id;
-    agent.state = PathfindingState.InProgress;
-    agent.hasRequest = false;
-    agent.progress = 0;
-    agent.path = [];
-    agent.pathIndex = 0;
-    this.mapComponent.activeRequests++;
   }
   /**
-   * @zh 从进度更新代理状态
-   * @en Update agent state from progress
+   * @zh 处理路径规划（同步模式）
+   * @en Process path planning (synchronous mode)
    */
-  updateAgentFromProgress(agent, progress, pathfinder) {
-    agent.state = progress.state;
-    agent.progress = progress.estimatedProgress;
-    agent.onPathProgress?.(progress.estimatedProgress);
-    if (progress.state === PathfindingState.Completed) {
-      const result = pathfinder.getResult(agent.currentRequestId);
-      if (result && result.found) {
-        const smoother = this.mapComponent?.smoother;
-        const map = this.mapComponent?.map;
-        if (smoother && map && this.mapComponent?.enableSmoothing) {
-          agent.path = smoother.smooth(result.path, map);
-        } else {
-          agent.path = [
-            ...result.path
-          ];
-        }
-        agent.pathIndex = 0;
-        agent.pathCost = result.cost;
-        agent.onPathComplete?.(true, agent.path);
+  processPathPlanning(agent, deltaTime) {
+    if (!agent.destination || agent.state === NavigationState.Arrived) {
+      return;
+    }
+    const needsRepath = agent.path.length === 0 || agent.autoRepath && this.currentTime - agent.lastRepathTime > agent.repathInterval;
+    if (needsRepath && this.pathPlanner) {
+      const result = this.pathPlanner.findPath(agent.position, agent.destination, {
+        agentRadius: agent.radius
+      });
+      if (result.found) {
+        agent.path = result.path.map((p) => ({
+          x: p.x,
+          y: p.y
+        }));
+        agent.currentWaypointIndex = 0;
+        agent.state = NavigationState.Navigating;
       } else {
+        agent.state = NavigationState.Unreachable;
         agent.path = [];
-        agent.state = PathfindingState.Failed;
-        agent.onPathComplete?.(false, []);
       }
-      pathfinder.cleanup(agent.currentRequestId);
-      this.mapComponent.activeRequests--;
-    } else if (progress.state === PathfindingState.Failed) {
-      agent.path = [];
-      agent.onPathComplete?.(false, []);
-      pathfinder.cleanup(agent.currentRequestId);
-      this.mapComponent.activeRequests--;
+      agent.lastRepathTime = this.currentTime;
     }
+    this.advanceWaypoint(agent);
   }
   /**
-   * @zh 周期性验证路径有效性
-   * @en Periodically validate path validity
+   * @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
    */
-  validatePaths(entities) {
-    const map = this.mapComponent?.map;
-    if (!map) return;
-    for (const entity of entities) {
-      const agent = entity.getComponent(PathfindingAgentComponent);
-      if (!agent || !agent.enableDynamicReplan) continue;
-      if (agent.path.length === 0 || agent.isPathComplete()) continue;
-      if (this.frameCounter - agent.lastValidationFrame < agent.validationInterval) {
+  processIncrementalPathPlanning(agents, entityMap) {
+    if (!this.pathPlanner || !this.isIncrementalPlanner) return;
+    const planner = this.pathPlanner;
+    let remainingBudget = this.config.iterationsBudget;
+    let processedCount = 0;
+    for (const { entityId, agent } of agents) {
+      if (!agent.destination || agent.state === NavigationState.Arrived) {
+        if (agent.currentRequestId >= 0) {
+          planner.cleanup(agent.currentRequestId);
+          agent.currentRequestId = -1;
+          agent.isComputingPath = false;
+        }
         continue;
       }
-      agent.lastValidationFrame = this.frameCounter;
-      const checkEnd = Math.min(agent.pathIndex + agent.lookaheadDistance, agent.path.length);
-      const result = this.pathValidator.validatePath(agent.path, agent.pathIndex, checkEnd, map);
-      if (!result.valid) {
-        agent.x = agent.path[agent.pathIndex]?.x ?? agent.x;
-        agent.y = agent.path[agent.pathIndex]?.y ?? agent.y;
-        agent.requestPathTo(agent.targetX, agent.targetY);
+      const needsRepath = !agent.isComputingPath && agent.currentRequestId < 0 && (agent.path.length === 0 || agent.autoRepath && this.currentTime - agent.lastRepathTime > agent.repathInterval);
+      if (needsRepath) {
+        this.pendingPathRequests.add(entityId);
       }
     }
-  }
-};
-__name(_PathfindingSystem, "PathfindingSystem");
-var PathfindingSystem = _PathfindingSystem;
-PathfindingSystem = _ts_decorate3([
-  ECSSystem("Pathfinding", {
-    updateOrder: 0
-  }),
-  _ts_metadata3("design:type", Function),
-  _ts_metadata3("design:paramtypes", [])
-], PathfindingSystem);
-
-// src/ecs/AvoidanceAgentComponent.ts
-import { Component as Component3, ECSComponent as ECSComponent3, Serializable as Serializable3, Serialize as Serialize3, Property as Property3 } from "@esengine/ecs-framework";
-function _ts_decorate4(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate4, "_ts_decorate");
-function _ts_metadata4(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata4, "_ts_metadata");
-var _AvoidanceAgentComponent = class _AvoidanceAgentComponent extends Component3 {
-  constructor() {
-    super(...arguments);
-    // =========================================================================
-    // 物理属性 | Physical Properties
-    // =========================================================================
-    /**
-     * @zh 代理半径
-     * @en Agent radius
-     *
-     * @zh 用于碰撞检测和避让计算
-     * @en Used for collision detection and avoidance computation
-     */
-    __publicField(this, "radius", DEFAULT_AGENT_PARAMS.radius);
-    /**
-     * @zh 最大速度
-     * @en Maximum speed
-     */
-    __publicField(this, "maxSpeed", DEFAULT_AGENT_PARAMS.maxSpeed);
-    // =========================================================================
-    // ORCA 参数 | ORCA Parameters
-    // =========================================================================
-    /**
-     * @zh 邻居检测距离
-     * @en Neighbor detection distance
-     *
-     * @zh 只考虑此范围内的其他代理
-     * @en Only considers other agents within this range
-     */
-    __publicField(this, "neighborDist", DEFAULT_AGENT_PARAMS.neighborDist);
-    /**
-     * @zh 最大邻居数量
-     * @en Maximum number of neighbors to consider
-     *
-     * @zh 限制计算量，优先考虑最近的邻居
-     * @en Limits computation, prioritizes closest neighbors
-     */
-    __publicField(this, "maxNeighbors", DEFAULT_AGENT_PARAMS.maxNeighbors);
-    /**
-     * @zh 代理避让时间视野（秒）
-     * @en Time horizon for agent avoidance (seconds)
-     *
-     * @zh 更大的值会让代理更早开始避让，但可能导致过于保守
-     * @en Larger values make agents start avoiding earlier, but may be too conservative
-     */
-    __publicField(this, "timeHorizon", DEFAULT_AGENT_PARAMS.timeHorizon);
-    /**
-     * @zh 障碍物避让时间视野（秒）
-     * @en Time horizon for obstacle avoidance (seconds)
-     */
-    __publicField(this, "timeHorizonObst", DEFAULT_AGENT_PARAMS.timeHorizonObst);
-    // =========================================================================
-    // 位置和速度（运行时状态）| Position & Velocity (Runtime State)
-    // =========================================================================
-    /**
-     * @zh 当前位置 X
-     * @en Current position X
-     *
-     * @zh 如果实体有 Transform 组件，系统会自动同步
-     * @en If entity has Transform component, system will sync automatically
-     */
-    __publicField(this, "positionX", 0);
-    /**
-     * @zh 当前位置 Y
-     * @en Current position Y
-     */
-    __publicField(this, "positionY", 0);
-    /**
-     * @zh 当前速度 X
-     * @en Current velocity X
-     */
-    __publicField(this, "velocityX", 0);
-    /**
-     * @zh 当前速度 Y
-     * @en Current velocity Y
-     */
-    __publicField(this, "velocityY", 0);
-    /**
-     * @zh 首选速度 X（通常指向目标方向）
-     * @en Preferred velocity X (usually towards target)
-     */
-    __publicField(this, "preferredVelocityX", 0);
-    /**
-     * @zh 首选速度 Y
-     * @en Preferred velocity Y
-     */
-    __publicField(this, "preferredVelocityY", 0);
-    /**
-     * @zh ORCA 计算的新速度 X
-     * @en New velocity X computed by ORCA
-     */
-    __publicField(this, "newVelocityX", 0);
-    /**
-     * @zh ORCA 计算的新速度 Y
-     * @en New velocity Y computed by ORCA
-     */
-    __publicField(this, "newVelocityY", 0);
-    // =========================================================================
-    // 配置选项 | Configuration Options
-    // =========================================================================
-    /**
-     * @zh 是否启用避让
-     * @en Whether avoidance is enabled
-     */
-    __publicField(this, "enabled", true);
-    /**
-     * @zh 是否自动应用新速度
-     * @en Whether to automatically apply new velocity
-     *
-     * @zh 如果为 true，系统会在计算后自动将 newVelocity 赋值给 velocity
-     * @en If true, system will automatically assign newVelocity to velocity after computation
-     */
-    __publicField(this, "autoApplyVelocity", true);
-  }
-  // =========================================================================
-  // 公共方法 | Public Methods
-  // =========================================================================
-  /**
-   * @zh 设置位置
-   * @en Set position
-   */
-  setPosition(x, y) {
-    this.positionX = x;
-    this.positionY = y;
-  }
-  /**
-   * @zh 设置当前速度
-   * @en Set current velocity
-   */
-  setVelocity(x, y) {
-    this.velocityX = x;
-    this.velocityY = y;
+    const pendingArray = Array.from(this.pendingPathRequests);
+    pendingArray.sort((a, b) => {
+      const agentA = agents.find((x) => x.entityId === a);
+      const agentB = agents.find((x) => x.entityId === b);
+      return (agentA?.agent.priority ?? 50) - (agentB?.agent.priority ?? 50);
+    });
+    for (const entityId of pendingArray) {
+      if (processedCount >= this.config.maxAgentsPerFrame) break;
+      const entry = agents.find((x) => x.entityId === entityId);
+      const destination = entry?.agent.destination;
+      if (!entry || !destination) {
+        this.pendingPathRequests.delete(entityId);
+        continue;
+      }
+      const { agent } = entry;
+      const request = planner.requestPath(agent.position, destination, {
+        agentRadius: agent.radius
+      });
+      agent.currentRequestId = request.id;
+      agent.isComputingPath = true;
+      agent.pathProgress = 0;
+      this.pendingPathRequests.delete(entityId);
+      processedCount++;
+    }
+    const activeAgents = agents.filter((x) => x.agent.isComputingPath && x.agent.currentRequestId >= 0);
+    activeAgents.sort((a, b) => a.agent.priority - b.agent.priority);
+    for (const { agent } of activeAgents) {
+      if (remainingBudget <= 0) break;
+      const iterations = Math.min(remainingBudget, this.config.maxIterationsPerAgent);
+      const progress = planner.step(agent.currentRequestId, iterations);
+      remainingBudget -= progress.nodesSearched;
+      agent.pathProgress = progress.estimatedProgress;
+      if (progress.state === PathPlanState.Completed) {
+        const result = planner.getResult(agent.currentRequestId);
+        planner.cleanup(agent.currentRequestId);
+        if (result && result.found) {
+          agent.path = result.path.map((p) => ({
+            x: p.x,
+            y: p.y
+          }));
+          agent.currentWaypointIndex = 0;
+          agent.state = NavigationState.Navigating;
+        } else {
+          agent.state = NavigationState.Unreachable;
+          agent.path = [];
+        }
+        agent.currentRequestId = -1;
+        agent.isComputingPath = false;
+        agent.pathProgress = 0;
+        agent.lastRepathTime = this.currentTime;
+      } else if (progress.state === PathPlanState.Failed || progress.state === PathPlanState.Cancelled) {
+        planner.cleanup(agent.currentRequestId);
+        agent.state = NavigationState.Unreachable;
+        agent.path = [];
+        agent.currentRequestId = -1;
+        agent.isComputingPath = false;
+        agent.pathProgress = 0;
+        agent.lastRepathTime = this.currentTime;
+      }
+    }
+    for (const { agent } of agents) {
+      this.advanceWaypoint(agent);
+    }
   }
   /**
-   * @zh 设置首选速度
-   * @en Set preferred velocity
+   * @zh 推进路径点
+   * @en Advance waypoint
    */
-  setPreferredVelocity(x, y) {
-    this.preferredVelocityX = x;
-    this.preferredVelocityY = y;
+  advanceWaypoint(agent) {
+    while (agent.currentWaypointIndex < agent.path.length) {
+      const waypoint = agent.path[agent.currentWaypointIndex];
+      const dx = waypoint.x - agent.position.x;
+      const dy = waypoint.y - agent.position.y;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      if (dist < agent.waypointThreshold) {
+        agent.currentWaypointIndex++;
+      } else {
+        break;
+      }
+    }
   }
   /**
-   * @zh 设置首选速度朝向目标
-   * @en Set preferred velocity towards target
-   *
-   * @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)
+   * @zh 计算首选速度
+   * @en Calculate preferred velocity
    */
-  setPreferredVelocityTowards(targetX, targetY, currentX, currentY) {
-    const x = currentX ?? this.positionX;
-    const y = currentY ?? this.positionY;
-    const dx = targetX - x;
-    const dy = targetY - y;
-    const dist = Math.sqrt(dx * dx + dy * dy);
-    if (dist > 1e-4) {
-      const speed = Math.min(this.maxSpeed, dist);
-      this.preferredVelocityX = dx / dist * speed;
-      this.preferredVelocityY = dy / dist * speed;
+  calculatePreferredVelocity(agent) {
+    if (!agent.destination) {
+      return {
+        x: 0,
+        y: 0
+      };
+    }
+    let targetX, targetY;
+    let isLastWaypoint = false;
+    if (agent.currentWaypointIndex < agent.path.length) {
+      const waypoint = agent.path[agent.currentWaypointIndex];
+      targetX = waypoint.x;
+      targetY = waypoint.y;
+      isLastWaypoint = agent.currentWaypointIndex === agent.path.length - 1;
     } else {
-      this.preferredVelocityX = 0;
-      this.preferredVelocityY = 0;
+      targetX = agent.destination.x;
+      targetY = agent.destination.y;
+      isLastWaypoint = true;
     }
+    const dx = targetX - agent.position.x;
+    const dy = targetY - agent.position.y;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    if (dist < 1e-4) {
+      return {
+        x: 0,
+        y: 0
+      };
+    }
+    const speed = isLastWaypoint ? Math.min(agent.maxSpeed, dist) : agent.maxSpeed;
+    return {
+      x: dx / dist * speed,
+      y: dy / dist * speed
+    };
   }
   /**
-   * @zh 应用 ORCA 计算的新速度
-   * @en Apply new velocity computed by ORCA
-   */
-  applyNewVelocity() {
-    this.velocityX = this.newVelocityX;
-    this.velocityY = this.newVelocityY;
-  }
-  /**
-   * @zh 获取新速度的长度
-   * @en Get length of new velocity
+   * @zh 构建代理数据
+   * @en Build agent data
    */
-  getNewSpeed() {
-    return Math.sqrt(this.newVelocityX * this.newVelocityX + this.newVelocityY * this.newVelocityY);
+  buildAgentData(entity, agent, preferredVelocity) {
+    return {
+      id: entity.id,
+      position: {
+        x: agent.position.x,
+        y: agent.position.y
+      },
+      velocity: {
+        x: agent.velocity.x,
+        y: agent.velocity.y
+      },
+      preferredVelocity,
+      radius: agent.radius,
+      maxSpeed: agent.maxSpeed
+    };
   }
   /**
-   * @zh 获取当前速度的长度
-   * @en Get length of current velocity
+   * @zh 应用避让结果
+   * @en Apply avoidance result
    */
-  getCurrentSpeed() {
-    return Math.sqrt(this.velocityX * this.velocityX + this.velocityY * this.velocityY);
+  applyAvoidanceResult(entity, agent, newVelocity, deltaTime) {
+    const allObstacles = this.getAllObstaclesForCollision();
+    if (this.config.enableCollisionResolution && this.collisionResolver && allObstacles.length > 0) {
+      newVelocity = this.collisionResolver.validateVelocity(agent.position, newVelocity, agent.radius, allObstacles, deltaTime);
+    }
+    if (agent.smoothSteering) {
+      newVelocity = this.applySmoothSteering(agent, newVelocity, deltaTime);
+    }
+    agent.velocity = {
+      x: newVelocity.x,
+      y: newVelocity.y
+    };
+    let newPosition = {
+      x: agent.position.x + newVelocity.x * deltaTime,
+      y: agent.position.y + newVelocity.y * deltaTime
+    };
+    if (this.config.enableCollisionResolution && this.collisionResolver && allObstacles.length > 0) {
+      newPosition = this.collisionResolver.resolveCollision(newPosition, agent.radius, allObstacles);
+    }
+    agent.position = newPosition;
+    this.checkArrival(agent);
   }
   /**
-   * @zh 停止代理
-   * @en Stop the agent
+   * @zh 应用平滑转向
+   * @en Apply smooth steering
    */
-  stop() {
-    this.velocityX = 0;
-    this.velocityY = 0;
-    this.preferredVelocityX = 0;
-    this.preferredVelocityY = 0;
-    this.newVelocityX = 0;
-    this.newVelocityY = 0;
+  applySmoothSteering(agent, targetVelocity, deltaTime) {
+    const maxChange = agent.acceleration * deltaTime;
+    const dvx = targetVelocity.x - agent.velocity.x;
+    const dvy = targetVelocity.y - agent.velocity.y;
+    const changeMag = Math.sqrt(dvx * dvx + dvy * dvy);
+    if (changeMag <= maxChange) {
+      return targetVelocity;
+    }
+    const factor = maxChange / changeMag;
+    const newVel = {
+      x: agent.velocity.x + dvx * factor,
+      y: agent.velocity.y + dvy * factor
+    };
+    const targetSpeed = Math.sqrt(targetVelocity.x * targetVelocity.x + targetVelocity.y * targetVelocity.y);
+    const newSpeed = Math.sqrt(newVel.x * newVel.x + newVel.y * newVel.y);
+    if (newSpeed > 1e-4 && targetSpeed > 1e-4) {
+      const scale = targetSpeed / newSpeed;
+      newVel.x *= scale;
+      newVel.y *= scale;
+    }
+    return newVel;
   }
   /**
-   * @zh 重置组件状态
-   * @en Reset component state
+   * @zh 检查是否到达目标
+   * @en Check if arrived at destination
    */
-  reset() {
-    this.positionX = 0;
-    this.positionY = 0;
-    this.velocityX = 0;
-    this.velocityY = 0;
-    this.preferredVelocityX = 0;
-    this.preferredVelocityY = 0;
-    this.newVelocityX = 0;
-    this.newVelocityY = 0;
+  checkArrival(agent) {
+    if (!agent.destination) return;
+    const dx = agent.destination.x - agent.position.x;
+    const dy = agent.destination.y - agent.position.y;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    if (dist < agent.arrivalThreshold) {
+      agent.state = NavigationState.Arrived;
+      agent.velocity = {
+        x: 0,
+        y: 0
+      };
+    }
   }
   /**
-   * @zh 组件从实体移除时调用
-   * @en Called when component is removed from entity
+   * @zh 解决代理间碰撞
+   * @en Resolve agent-agent collisions
    */
-  onRemovedFromEntity() {
-    this.reset();
+  resolveAgentCollisions(entities) {
+    if (!this.collisionResolver) return;
+    const corrections = /* @__PURE__ */ new Map();
+    const activeEntities = entities.filter((e) => {
+      const agent = e.getComponent(NavigationAgentComponent);
+      return agent.enabled;
+    });
+    for (let i = 0; i < activeEntities.length; i++) {
+      for (let j = i + 1; j < activeEntities.length; j++) {
+        const entityA = activeEntities[i];
+        const entityB = activeEntities[j];
+        const agentA = entityA.getComponent(NavigationAgentComponent);
+        const agentB = entityB.getComponent(NavigationAgentComponent);
+        const collision = this.collisionResolver.detectAgentCollision(agentA.position, agentA.radius, agentB.position, agentB.radius);
+        if (collision.collided) {
+          const halfPush = (collision.penetration + 0.01) * 0.5;
+          const corrA = corrections.get(entityA.id) ?? {
+            x: 0,
+            y: 0
+          };
+          corrA.x += collision.normal.x * halfPush;
+          corrA.y += collision.normal.y * halfPush;
+          corrections.set(entityA.id, corrA);
+          const corrB = corrections.get(entityB.id) ?? {
+            x: 0,
+            y: 0
+          };
+          corrB.x -= collision.normal.x * halfPush;
+          corrB.y -= collision.normal.y * halfPush;
+          corrections.set(entityB.id, corrB);
+        }
+      }
+    }
+    const allObstacles = this.getAllObstaclesForCollision();
+    for (const [entityId, correction] of corrections) {
+      const entity = activeEntities.find((e) => e.id === entityId);
+      if (!entity) continue;
+      const agent = entity.getComponent(NavigationAgentComponent);
+      let newPosition = {
+        x: agent.position.x + correction.x,
+        y: agent.position.y + correction.y
+      };
+      if (allObstacles.length > 0) {
+        newPosition = this.collisionResolver.resolveCollision(newPosition, agent.radius, allObstacles);
+      }
+      agent.position = newPosition;
+    }
   }
 };
-__name(_AvoidanceAgentComponent, "AvoidanceAgentComponent");
-var AvoidanceAgentComponent = _AvoidanceAgentComponent;
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Radius",
-    min: 0.1,
-    max: 10
+__name(_NavigationSystem, "NavigationSystem");
+var NavigationSystem = _NavigationSystem;
+NavigationSystem = _ts_decorate2([
+  ECSSystem("Navigation", {
+    updateOrder: 45
   }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "radius", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Max Speed",
-    min: 0.1,
-    max: 100
-  }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "maxSpeed", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Neighbor Dist",
-    min: 1,
-    max: 100
-  }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "neighborDist", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Max Neighbors",
-    min: 1,
-    max: 50
-  }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "maxNeighbors", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Time Horizon",
-    min: 0.1,
-    max: 10
-  }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "timeHorizon", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "number",
-    label: "Time Horizon Obst",
-    min: 0.1,
-    max: 10
-  }),
-  _ts_metadata4("design:type", Number)
-], AvoidanceAgentComponent.prototype, "timeHorizonObst", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "boolean",
-    label: "Enabled"
-  }),
-  _ts_metadata4("design:type", Boolean)
-], AvoidanceAgentComponent.prototype, "enabled", void 0);
-_ts_decorate4([
-  Serialize3(),
-  Property3({
-    type: "boolean",
-    label: "Auto Apply"
-  }),
-  _ts_metadata4("design:type", Boolean)
-], AvoidanceAgentComponent.prototype, "autoApplyVelocity", void 0);
-AvoidanceAgentComponent = _ts_decorate4([
-  ECSComponent3("AvoidanceAgent"),
-  Serializable3({
-    version: 1,
-    typeId: "AvoidanceAgent"
-  })
-], AvoidanceAgentComponent);
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof INavigationSystemConfig === "undefined" ? Object : INavigationSystemConfig
+  ])
+], NavigationSystem);
 
-// src/ecs/AvoidanceWorldComponent.ts
-import { Component as Component4, ECSComponent as ECSComponent4, Serializable as Serializable4, Serialize as Serialize4, Property as Property4 } from "@esengine/ecs-framework";
-function _ts_decorate5(decorators, target, key, desc) {
+// src/ecs/ORCAConfigComponent.ts
+import { Component as Component2, ECSComponent as ECSComponent2, Serializable as Serializable2, Serialize as Serialize2, Property as Property2 } from "@esengine/ecs-framework";
+function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate5, "_ts_decorate");
-function _ts_metadata5(k, v) {
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata3(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata5, "_ts_metadata");
-var _AvoidanceWorldComponent = class _AvoidanceWorldComponent extends Component4 {
+__name(_ts_metadata3, "_ts_metadata");
+var _ORCAConfigComponent = class _ORCAConfigComponent extends Component2 {
   constructor() {
     super(...arguments);
-    // =========================================================================
-    // ORCA 配置 | ORCA Configuration
-    // =========================================================================
-    /**
-     * @zh 默认时间视野（代理）
-     * @en Default time horizon for agents
-     */
-    __publicField(this, "defaultTimeHorizon", DEFAULT_ORCA_CONFIG.defaultTimeHorizon);
-    /**
-     * @zh 默认时间视野（障碍物）
-     * @en Default time horizon for obstacles
-     */
-    __publicField(this, "defaultTimeHorizonObst", DEFAULT_ORCA_CONFIG.defaultTimeHorizonObst);
-    /**
-     * @zh 时间步长
-     * @en Time step
-     */
-    __publicField(this, "timeStep", DEFAULT_ORCA_CONFIG.timeStep);
-    // =========================================================================
-    // 运行时实例（不序列化）| Runtime Instances (not serialized)
-    // =========================================================================
-    /**
-     * @zh ORCA 求解器实例
-     * @en ORCA solver instance
-     */
-    __publicField(this, "solver", null);
     /**
-     * @zh KD-Tree 实例
-     * @en KD-Tree instance
-     */
-    __publicField(this, "kdTree", null);
-    /**
-     * @zh 静态障碍物列表
-     * @en List of static obstacles
-     */
-    __publicField(this, "obstacles", []);
-    /**
-     * @zh 是否已初始化
-     * @en Whether initialized
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     *
+     * @zh 代理检测邻居的最大距离，更大的值意味着更早开始避让但也更消耗性能
+     * @en Maximum distance for detecting neighbors, larger value means earlier avoidance but more performance cost
      */
-    __publicField(this, "initialized", false);
-    // =========================================================================
-    // 统计信息 | Statistics
-    // =========================================================================
+    __publicField(this, "neighborDist", 15);
     /**
-     * @zh 当前代理数量
-     * @en Current agent count
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors
+     *
+     * @zh 计算避让时考虑的最大邻居数量，更多邻居意味着更精确但也更消耗性能
+     * @en Maximum neighbors considered for avoidance, more neighbors means more accurate but slower
      */
-    __publicField(this, "agentCount", 0);
+    __publicField(this, "maxNeighbors", 10);
     /**
-     * @zh 本帧处理的代理数
-     * @en Agents processed this frame
+     * @zh 代理避让时间视野
+     * @en Time horizon for agent avoidance
+     *
+     * @zh 预测其他代理未来位置的时间范围，更长意味着更平滑但可能过度避让
+     * @en Time range for predicting other agents' future positions, longer means smoother but may over-avoid
      */
-    __publicField(this, "agentsProcessedThisFrame", 0);
+    __publicField(this, "timeHorizon", 2);
     /**
-     * @zh 本帧 ORCA 计算耗时（毫秒）
-     * @en ORCA computation time this frame (ms)
+     * @zh 障碍物避让时间视野
+     * @en Time horizon for obstacle avoidance
+     *
+     * @zh 预测与障碍物碰撞的时间范围，通常比代理视野短
+     * @en Time range for predicting obstacle collisions, usually shorter than agent horizon
      */
-    __publicField(this, "computeTimeMs", 0);
-  }
-  // =========================================================================
-  // 公共方法 | Public Methods
-  // =========================================================================
-  /**
-   * @zh 获取 ORCA 配置
-   * @en Get ORCA configuration
-   */
-  getConfig() {
-    return {
-      defaultTimeHorizon: this.defaultTimeHorizon,
-      defaultTimeHorizonObst: this.defaultTimeHorizonObst,
-      timeStep: this.timeStep
-    };
-  }
-  /**
-   * @zh 添加静态障碍物
-   * @en Add static obstacle
-   *
-   * @param obstacle - @zh 障碍物（顶点列表，逆时针顺序）@en Obstacle (vertex list, counter-clockwise)
-   */
-  addObstacle(obstacle) {
-    this.obstacles.push(obstacle);
-  }
-  /**
-   * @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
-   */
-  addRectObstacle(x, y, width, height) {
-    this.obstacles.push({
-      vertices: [
-        {
-          x,
-          y
-        },
-        {
-          x: x + width,
-          y
-        },
-        {
-          x: x + width,
-          y: y + height
-        },
-        {
-          x,
-          y: y + height
-        }
-      ]
-    });
-  }
-  /**
-   * @zh 移除所有障碍物
-   * @en Remove all obstacles
-   */
-  clearObstacles() {
-    this.obstacles = [];
-  }
-  /**
-   * @zh 重置统计信息
-   * @en Reset statistics
-   */
-  resetStats() {
-    this.agentsProcessedThisFrame = 0;
-    this.computeTimeMs = 0;
-  }
-  /**
-   * @zh 组件从实体移除时调用
-   * @en Called when component is removed from entity
-   */
-  onRemovedFromEntity() {
-    this.solver = null;
-    this.kdTree = null;
-    this.obstacles = [];
-    this.initialized = false;
+    __publicField(this, "timeHorizonObst", 1);
   }
 };
-__name(_AvoidanceWorldComponent, "AvoidanceWorldComponent");
-var AvoidanceWorldComponent = _AvoidanceWorldComponent;
-_ts_decorate5([
-  Serialize4(),
-  Property4({
+__name(_ORCAConfigComponent, "ORCAConfigComponent");
+var ORCAConfigComponent = _ORCAConfigComponent;
+_ts_decorate3([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Neighbor Dist",
+    min: 1,
+    max: 100
+  }),
+  _ts_metadata3("design:type", Number)
+], ORCAConfigComponent.prototype, "neighborDist", void 0);
+_ts_decorate3([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Max Neighbors",
+    min: 1,
+    max: 50
+  }),
+  _ts_metadata3("design:type", Number)
+], ORCAConfigComponent.prototype, "maxNeighbors", void 0);
+_ts_decorate3([
+  Serialize2(),
+  Property2({
     type: "number",
     label: "Time Horizon",
     min: 0.1,
     max: 10
   }),
-  _ts_metadata5("design:type", Number)
-], AvoidanceWorldComponent.prototype, "defaultTimeHorizon", void 0);
-_ts_decorate5([
-  Serialize4(),
-  Property4({
+  _ts_metadata3("design:type", Number)
+], ORCAConfigComponent.prototype, "timeHorizon", void 0);
+_ts_decorate3([
+  Serialize2(),
+  Property2({
     type: "number",
     label: "Time Horizon Obst",
     min: 0.1,
     max: 10
   }),
-  _ts_metadata5("design:type", Number)
-], AvoidanceWorldComponent.prototype, "defaultTimeHorizonObst", void 0);
-_ts_decorate5([
-  Serialize4(),
-  Property4({
-    type: "number",
-    label: "Time Step",
-    min: 1e-3,
-    max: 0.1
-  }),
-  _ts_metadata5("design:type", Number)
-], AvoidanceWorldComponent.prototype, "timeStep", void 0);
-AvoidanceWorldComponent = _ts_decorate5([
-  ECSComponent4("AvoidanceWorld"),
-  Serializable4({
+  _ts_metadata3("design:type", Number)
+], ORCAConfigComponent.prototype, "timeHorizonObst", void 0);
+ORCAConfigComponent = _ts_decorate3([
+  ECSComponent2("ORCAConfig"),
+  Serializable2({
     version: 1,
-    typeId: "AvoidanceWorld"
+    typeId: "ORCAConfig"
   })
-], AvoidanceWorldComponent);
-
-// src/ecs/LocalAvoidanceSystem.ts
-import { EntitySystem as EntitySystem2, Matcher as Matcher2, ECSSystem as ECSSystem2 } from "@esengine/ecs-framework";
-function _ts_decorate6(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate6, "_ts_decorate");
-function _ts_metadata6(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata6, "_ts_metadata");
-var _LocalAvoidanceSystem = class _LocalAvoidanceSystem extends EntitySystem2 {
-  constructor() {
-    super(Matcher2.all(AvoidanceAgentComponent));
-    __publicField(this, "worldEntity", null);
-    __publicField(this, "worldComponent", null);
-    __publicField(this, "solver", null);
-    __publicField(this, "kdTree", null);
-  }
-  /**
-   * @zh 系统初始化
-   * @en System initialization
-   */
-  onInitialize() {
-    this.findWorldEntity();
-    this.initializeSolver();
-  }
-  /**
-   * @zh 系统激活时调用
-   * @en Called when system is enabled
-   */
-  onEnable() {
-    this.findWorldEntity();
-  }
-  /**
-   * @zh 处理实体
-   * @en Process entities
-   */
-  process(entities) {
-    if (entities.length === 0) return;
-    if (!this.solver) {
-      this.initializeSolver();
-    }
-    const startTime = performance.now();
-    const agents = this.collectAgentData(entities);
-    this.kdTree.build(agents);
-    const obstacles = this.worldComponent?.obstacles ?? [];
-    const deltaTime = this.worldComponent?.timeStep ?? 1 / 60;
-    for (let i = 0; i < entities.length; i++) {
-      const entity = entities[i];
-      const component = entity.getComponent(AvoidanceAgentComponent);
-      if (!component.enabled) continue;
-      const agent = agents[i];
-      const neighborResults = this.kdTree.queryNeighbors(agent.position, agent.neighborDist, agent.maxNeighbors, agent.id);
-      const neighbors = neighborResults.map((r) => r.agent);
-      const newVelocity = this.solver.computeNewVelocity(agent, neighbors, obstacles, deltaTime);
-      component.newVelocityX = newVelocity.x;
-      component.newVelocityY = newVelocity.y;
-      if (component.autoApplyVelocity) {
-        component.applyNewVelocity();
-      }
-    }
-    const endTime = performance.now();
-    if (this.worldComponent) {
-      this.worldComponent.agentCount = entities.length;
-      this.worldComponent.agentsProcessedThisFrame = entities.length;
-      this.worldComponent.computeTimeMs = endTime - startTime;
-    }
-  }
-  // =========================================================================
-  // 私有方法 | Private Methods
-  // =========================================================================
-  /**
-   * @zh 查找世界实体
-   * @en Find world entity
-   */
-  findWorldEntity() {
-    if (!this.scene) return;
-    const entities = this.scene.entities.findEntitiesWithComponent(AvoidanceWorldComponent);
-    if (entities.length > 0) {
-      const entity = entities[0];
-      const worldComp = entity.getComponent(AvoidanceWorldComponent);
-      if (worldComp) {
-        this.worldEntity = entity;
-        this.worldComponent = worldComp;
-        if (this.solver && !worldComp.solver) {
-          worldComp.solver = this.solver;
-        }
-        if (this.kdTree && !worldComp.kdTree) {
-          worldComp.kdTree = this.kdTree;
-        }
-        worldComp.initialized = true;
-      }
-    }
-  }
-  /**
-   * @zh 初始化求解器
-   * @en Initialize solver
-   */
-  initializeSolver() {
-    const config = this.worldComponent?.getConfig();
-    this.solver = createORCASolver(config);
-    this.kdTree = createKDTree();
-    if (this.worldComponent) {
-      this.worldComponent.solver = this.solver;
-      this.worldComponent.kdTree = this.kdTree;
-    }
-  }
-  /**
-   * @zh 收集代理数据
-   * @en Collect agent data
-   */
-  collectAgentData(entities) {
-    const agents = [];
-    for (const entity of entities) {
-      const avoidance = entity.getComponent(AvoidanceAgentComponent);
-      const pathAgent = entity.getComponent(PathfindingAgentComponent);
-      if (pathAgent) {
-        avoidance.positionX = pathAgent.x;
-        avoidance.positionY = pathAgent.y;
-        const waypoint = pathAgent.getNextWaypoint();
-        if (waypoint && avoidance.preferredVelocityX === 0 && avoidance.preferredVelocityY === 0) {
-          avoidance.setPreferredVelocityTowards(waypoint.x, waypoint.y);
-        }
-      }
-      agents.push({
-        id: entity.id,
-        position: {
-          x: avoidance.positionX,
-          y: avoidance.positionY
-        },
-        velocity: {
-          x: avoidance.velocityX,
-          y: avoidance.velocityY
-        },
-        preferredVelocity: {
-          x: avoidance.preferredVelocityX,
-          y: avoidance.preferredVelocityY
-        },
-        radius: avoidance.radius,
-        maxSpeed: avoidance.maxSpeed,
-        neighborDist: avoidance.neighborDist,
-        maxNeighbors: avoidance.maxNeighbors,
-        timeHorizon: avoidance.timeHorizon,
-        timeHorizonObst: avoidance.timeHorizonObst
-      });
-    }
-    return agents;
-  }
-};
-__name(_LocalAvoidanceSystem, "LocalAvoidanceSystem");
-var LocalAvoidanceSystem = _LocalAvoidanceSystem;
-LocalAvoidanceSystem = _ts_decorate6([
-  ECSSystem2("LocalAvoidance", {
-    updateOrder: 50
-  }),
-  _ts_metadata6("design:type", Function),
-  _ts_metadata6("design:paramtypes", [])
-], LocalAvoidanceSystem);
+], ORCAConfigComponent);
 export {
-  AvoidanceAgentComponent,
-  AvoidanceWorldComponent,
-  LocalAvoidanceSystem,
-  PathfindingAgentComponent,
-  PathfindingMapComponent,
-  PathfindingSystem
+  CollisionResolverAdapter,
+  DEFAULT_FLOW_CONTROLLER_CONFIG,
+  DEFAULT_ORCA_PARAMS,
+  FlowController,
+  GridPathfinderAdapter,
+  IncrementalGridPathPlannerAdapter,
+  NavMeshPathPlannerAdapter,
+  NavigationAgentComponent,
+  NavigationState,
+  NavigationSystem,
+  ORCAConfigComponent,
+  ORCALocalAvoidanceAdapter,
+  PassPermission,
+  createAStarPlanner,
+  createDefaultCollisionResolver,
+  createFlowController,
+  createHPAPlanner,
+  createIncrementalAStarPlanner,
+  createJPSPlanner,
+  createNavMeshPathPlanner,
+  createORCAAvoidance
 };
 //# sourceMappingURL=ecs.js.map