@esengine/pathfinding 13.2.0 → 13.3.1

package/dist/index.js

@@ -1,326 +1,71 @@
 import {
-  CatmullRomSmoother,
-  CombinedSmoother,
-  DEFAULT_GRID_OPTIONS,
+  AStarPathfinder,
+  BinaryHeap,
+  CollisionResolverAdapter,
+  DEFAULT_FLOW_CONTROLLER_CONFIG,
+  DEFAULT_HPA_CONFIG,
+  DEFAULT_ORCA_PARAMS,
   DEFAULT_PATHFINDING_OPTIONS,
   DEFAULT_PATH_CACHE_CONFIG,
-  DIRECTIONS_4,
-  DIRECTIONS_8,
+  EMPTY_COLLISION_RESULT,
   EMPTY_PATH_RESULT,
-  GridMap,
-  GridNode,
+  EMPTY_PLAN_RESULT,
+  FlowController,
+  GridPathfinderAdapter,
+  HPAPathfinder,
   IncrementalAStarPathfinder,
+  IncrementalGridPathPlannerAdapter,
   IndexedBinaryHeap,
-  LineOfSightSmoother,
-  ObstacleChangeManager,
+  JPSPathfinder,
+  NavMeshPathPlannerAdapter,
+  ORCALocalAvoidanceAdapter,
+  PassPermission,
   PathCache,
-  PathValidator,
-  bresenhamLineOfSight,
+  PathPlanState,
   chebyshevDistance,
-  createCatmullRomSmoother,
-  createCombinedSmoother,
-  createGridMap,
+  createAStarPathfinder,
+  createAStarPlanner,
+  createDefaultCollisionResolver,
+  createFlowController,
+  createHPAPathfinder,
+  createHPAPlanner,
   createIncrementalAStarPathfinder,
-  createLineOfSightSmoother,
-  createObstacleChangeManager,
+  createIncrementalAStarPlanner,
+  createJPSPathfinder,
+  createJPSPlanner,
+  createNavMeshPathPlanner,
+  createORCAAvoidance,
   createPathCache,
-  createPathValidator,
   createPoint,
   euclideanDistance,
+  isIncrementalPlanner,
   manhattanDistance,
-  octileDistance,
-  raycastLineOfSight
-} from "./chunk-VNC2YAAL.js";
+  octileDistance
+} from "./chunk-ZYGBA7VK.js";
 import {
   DEFAULT_REPLANNING_CONFIG,
   EMPTY_PROGRESS,
   PathfindingState
 } from "./chunk-YKA3PWU3.js";
-import "./chunk-KEYTX37K.js";
+import "./chunk-H5EFZBBT.js";
 import {
+  CollisionResolver,
   DEFAULT_AGENT_PARAMS,
+  DEFAULT_COLLISION_CONFIG,
   DEFAULT_ORCA_CONFIG,
+  EMPTY_COLLISION,
   KDTree,
   ORCASolver,
+  createCollisionResolver,
   createKDTree,
   createORCASolver,
   solveORCALinearProgram
-} from "./chunk-JTZP55BJ.js";
+} from "./chunk-3VEX32JO.js";
 import {
   __name,
   __publicField
 } from "./chunk-T626JPC7.js";
 
-// src/core/BinaryHeap.ts
-var _BinaryHeap = class _BinaryHeap {
-  /**
-   * @zh 创建二叉堆
-   * @en Create binary heap
-   *
-   * @param compare - @zh 比较函数，返回负数表示 a < b @en Compare function, returns negative if a < b
-   */
-  constructor(compare) {
-    __publicField(this, "heap", []);
-    __publicField(this, "compare");
-    this.compare = compare;
-  }
-  /**
-   * @zh 堆大小
-   * @en Heap size
-   */
-  get size() {
-    return this.heap.length;
-  }
-  /**
-   * @zh 是否为空
-   * @en Is empty
-   */
-  get isEmpty() {
-    return this.heap.length === 0;
-  }
-  /**
-   * @zh 插入元素
-   * @en Push element
-   */
-  push(item) {
-    this.heap.push(item);
-    this.bubbleUp(this.heap.length - 1);
-  }
-  /**
-   * @zh 弹出最小元素
-   * @en Pop minimum element
-   */
-  pop() {
-    if (this.heap.length === 0) {
-      return void 0;
-    }
-    const result = this.heap[0];
-    const last = this.heap.pop();
-    if (this.heap.length > 0) {
-      this.heap[0] = last;
-      this.sinkDown(0);
-    }
-    return result;
-  }
-  /**
-   * @zh 查看最小元素（不移除）
-   * @en Peek minimum element (without removing)
-   */
-  peek() {
-    return this.heap[0];
-  }
-  /**
-   * @zh 更新元素（重新排序）
-   * @en Update element (re-sort)
-   */
-  update(item) {
-    const index = this.heap.indexOf(item);
-    if (index !== -1) {
-      this.bubbleUp(index);
-      this.sinkDown(index);
-    }
-  }
-  /**
-   * @zh 检查是否包含元素
-   * @en Check if contains element
-   */
-  contains(item) {
-    return this.heap.indexOf(item) !== -1;
-  }
-  /**
-   * @zh 清空堆
-   * @en Clear heap
-   */
-  clear() {
-    this.heap.length = 0;
-  }
-  /**
-   * @zh 上浮操作
-   * @en Bubble up operation
-   */
-  bubbleUp(index) {
-    const item = this.heap[index];
-    while (index > 0) {
-      const parentIndex = Math.floor((index - 1) / 2);
-      const parent = this.heap[parentIndex];
-      if (this.compare(item, parent) >= 0) {
-        break;
-      }
-      this.heap[index] = parent;
-      index = parentIndex;
-    }
-    this.heap[index] = item;
-  }
-  /**
-   * @zh 下沉操作
-   * @en Sink down operation
-   */
-  sinkDown(index) {
-    const length = this.heap.length;
-    const item = this.heap[index];
-    while (true) {
-      const leftIndex = 2 * index + 1;
-      const rightIndex = 2 * index + 2;
-      let smallest = index;
-      if (leftIndex < length && this.compare(this.heap[leftIndex], this.heap[smallest]) < 0) {
-        smallest = leftIndex;
-      }
-      if (rightIndex < length && this.compare(this.heap[rightIndex], this.heap[smallest]) < 0) {
-        smallest = rightIndex;
-      }
-      if (smallest === index) {
-        break;
-      }
-      this.heap[index] = this.heap[smallest];
-      this.heap[smallest] = item;
-      index = smallest;
-    }
-  }
-};
-__name(_BinaryHeap, "BinaryHeap");
-var BinaryHeap = _BinaryHeap;
-
-// src/core/AStarPathfinder.ts
-var _AStarPathfinder = class _AStarPathfinder {
-  constructor(map) {
-    __publicField(this, "map");
-    __publicField(this, "nodeCache", /* @__PURE__ */ new Map());
-    __publicField(this, "openList");
-    this.map = map;
-    this.openList = new IndexedBinaryHeap((a, b) => a.f - b.f);
-  }
-  /**
-   * @zh 查找路径
-   * @en Find path
-   */
-  findPath(startX, startY, endX, endY, options) {
-    const opts = {
-      ...DEFAULT_PATHFINDING_OPTIONS,
-      ...options
-    };
-    this.clear();
-    const startNode = this.map.getNodeAt(startX, startY);
-    const endNode = this.map.getNodeAt(endX, endY);
-    if (!startNode || !endNode) {
-      return EMPTY_PATH_RESULT;
-    }
-    if (!startNode.walkable || !endNode.walkable) {
-      return EMPTY_PATH_RESULT;
-    }
-    if (startNode.id === endNode.id) {
-      return {
-        found: true,
-        path: [
-          startNode.position
-        ],
-        cost: 0,
-        nodesSearched: 1
-      };
-    }
-    const start = this.getOrCreateAStarNode(startNode);
-    start.g = 0;
-    start.h = this.map.heuristic(startNode.position, endNode.position) * opts.heuristicWeight;
-    start.f = start.h;
-    start.opened = true;
-    this.openList.push(start);
-    let nodesSearched = 0;
-    const endPosition = endNode.position;
-    while (!this.openList.isEmpty && nodesSearched < opts.maxNodes) {
-      const current = this.openList.pop();
-      current.closed = true;
-      nodesSearched++;
-      if (current.node.id === endNode.id) {
-        return this.buildPath(current, nodesSearched);
-      }
-      const neighbors = this.map.getNeighbors(current.node);
-      for (const neighborNode of neighbors) {
-        if (!neighborNode.walkable) {
-          continue;
-        }
-        const neighbor = this.getOrCreateAStarNode(neighborNode);
-        if (neighbor.closed) {
-          continue;
-        }
-        const movementCost = this.map.getMovementCost(current.node, neighborNode);
-        const tentativeG = current.g + movementCost;
-        if (!neighbor.opened) {
-          neighbor.g = tentativeG;
-          neighbor.h = this.map.heuristic(neighborNode.position, endPosition) * opts.heuristicWeight;
-          neighbor.f = neighbor.g + neighbor.h;
-          neighbor.parent = current;
-          neighbor.opened = true;
-          this.openList.push(neighbor);
-        } else if (tentativeG < neighbor.g) {
-          neighbor.g = tentativeG;
-          neighbor.f = neighbor.g + neighbor.h;
-          neighbor.parent = current;
-          this.openList.update(neighbor);
-        }
-      }
-    }
-    return {
-      found: false,
-      path: [],
-      cost: 0,
-      nodesSearched
-    };
-  }
-  /**
-   * @zh 清理状态
-   * @en Clear state
-   */
-  clear() {
-    this.nodeCache.clear();
-    this.openList.clear();
-  }
-  /**
-   * @zh 获取或创建 A* 节点
-   * @en Get or create A* node
-   */
-  getOrCreateAStarNode(node) {
-    let astarNode = this.nodeCache.get(node.id);
-    if (!astarNode) {
-      astarNode = {
-        node,
-        g: Infinity,
-        h: 0,
-        f: Infinity,
-        parent: null,
-        closed: false,
-        opened: false,
-        heapIndex: -1
-      };
-      this.nodeCache.set(node.id, astarNode);
-    }
-    return astarNode;
-  }
-  /**
-   * @zh 构建路径结果
-   * @en Build path result
-   */
-  buildPath(endNode, nodesSearched) {
-    const path = [];
-    let current = endNode;
-    while (current) {
-      path.push(current.node.position);
-      current = current.parent;
-    }
-    path.reverse();
-    return {
-      found: true,
-      path,
-      cost: endNode.g,
-      nodesSearched
-    };
-  }
-};
-__name(_AStarPathfinder, "AStarPathfinder");
-var AStarPathfinder = _AStarPathfinder;
-function createAStarPathfinder(map) {
-  return new AStarPathfinder(map);
-}
-__name(createAStarPathfinder, "createAStarPathfinder");
-
 // src/core/GridPathfinder.ts
 var CLOSED_FLAG = 1;
 var OPENED_FLAG = 2;
@@ -967,1555 +712,524 @@ function createGridPathfinder(map, config) {
 }
 __name(createGridPathfinder, "createGridPathfinder");
 
-// src/core/JPSPathfinder.ts
-var _JPSPathfinder = class _JPSPathfinder {
-  constructor(map) {
-    __publicField(this, "map");
-    __publicField(this, "width");
-    __publicField(this, "height");
-    __publicField(this, "openList");
-    __publicField(this, "nodeGrid");
-    this.map = map;
-    const bounds = this.getMapBounds();
-    this.width = bounds.width;
-    this.height = bounds.height;
-    this.openList = new BinaryHeap((a, b) => a.f - b.f);
-    this.nodeGrid = [];
-  }
+// src/core/PathValidator.ts
+var _PathValidator = class _PathValidator {
   /**
-   * @zh 寻找路径
-   * @en Find path
-   */
-  findPath(startX, startY, endX, endY, options) {
-    const opts = {
-      ...DEFAULT_PATHFINDING_OPTIONS,
-      ...options
-    };
-    if (!this.map.isWalkable(startX, startY) || !this.map.isWalkable(endX, endY)) {
-      return EMPTY_PATH_RESULT;
-    }
-    if (startX === endX && startY === endY) {
-      return {
-        found: true,
-        path: [
-          {
-            x: startX,
-            y: startY
-          }
-        ],
-        cost: 0,
-        nodesSearched: 1
-      };
-    }
-    this.initGrid();
-    this.openList.clear();
-    const startNode = this.getOrCreateNode(startX, startY);
-    startNode.g = 0;
-    startNode.h = this.heuristic(startX, startY, endX, endY) * opts.heuristicWeight;
-    startNode.f = startNode.h;
-    this.openList.push(startNode);
-    let nodesSearched = 0;
-    while (!this.openList.isEmpty && nodesSearched < opts.maxNodes) {
-      const current = this.openList.pop();
-      current.closed = true;
-      nodesSearched++;
-      if (current.x === endX && current.y === endY) {
+   * @zh 验证路径段的有效性
+   * @en Validate path segment validity
+   *
+   * @param path - @zh 要验证的路径 @en Path to validate
+   * @param fromIndex - @zh 起始索引 @en Start index
+   * @param toIndex - @zh 结束索引 @en End index
+   * @param map - @zh 地图实例 @en Map instance
+   * @returns @zh 验证结果 @en Validation result
+   */
+  validatePath(path, fromIndex, toIndex, map) {
+    const end = Math.min(toIndex, path.length);
+    for (let i = fromIndex; i < end; i++) {
+      const point = path[i];
+      const x = Math.floor(point.x);
+      const y = Math.floor(point.y);
+      if (!map.isWalkable(x, y)) {
         return {
-          found: true,
-          path: this.buildPath(current),
-          cost: current.g,
-          nodesSearched
+          valid: false,
+          invalidIndex: i
         };
       }
-      this.identifySuccessors(current, endX, endY, opts);
+      if (i > fromIndex) {
+        const prev = path[i - 1];
+        if (!this.checkLineOfSight(prev.x, prev.y, point.x, point.y, map)) {
+          return {
+            valid: false,
+            invalidIndex: i
+          };
+        }
+      }
     }
     return {
-      found: false,
-      path: [],
-      cost: 0,
-      nodesSearched
+      valid: true,
+      invalidIndex: -1
     };
   }
   /**
-   * @zh 清理状态
-   * @en Clear state
-   */
-  clear() {
-    this.openList.clear();
-    this.nodeGrid = [];
+   * @zh 检查两点之间的视线（使用 Bresenham 算法）
+   * @en Check line of sight between two points (using Bresenham algorithm)
+   *
+   * @param x1 - @zh 起点 X @en Start X
+   * @param y1 - @zh 起点 Y @en Start Y
+   * @param x2 - @zh 终点 X @en End X
+   * @param y2 - @zh 终点 Y @en End Y
+   * @param map - @zh 地图实例 @en Map instance
+   * @returns @zh 是否有视线 @en Whether there is line of sight
+   */
+  checkLineOfSight(x1, y1, x2, y2, map) {
+    const ix1 = Math.floor(x1);
+    const iy1 = Math.floor(y1);
+    const ix2 = Math.floor(x2);
+    const iy2 = Math.floor(y2);
+    let dx = Math.abs(ix2 - ix1);
+    let dy = Math.abs(iy2 - iy1);
+    let x = ix1;
+    let y = iy1;
+    const sx = ix1 < ix2 ? 1 : -1;
+    const sy = iy1 < iy2 ? 1 : -1;
+    if (dx > dy) {
+      let err = dx / 2;
+      while (x !== ix2) {
+        if (!map.isWalkable(x, y)) {
+          return false;
+        }
+        err -= dy;
+        if (err < 0) {
+          y += sy;
+          err += dx;
+        }
+        x += sx;
+      }
+    } else {
+      let err = dy / 2;
+      while (y !== iy2) {
+        if (!map.isWalkable(x, y)) {
+          return false;
+        }
+        err -= dx;
+        if (err < 0) {
+          x += sx;
+          err += dy;
+        }
+        y += sy;
+      }
+    }
+    return map.isWalkable(ix2, iy2);
+  }
+};
+__name(_PathValidator, "PathValidator");
+var PathValidator = _PathValidator;
+var _ObstacleChangeManager = class _ObstacleChangeManager {
+  constructor() {
+    __publicField(this, "changes", /* @__PURE__ */ new Map());
+    __publicField(this, "epoch", 0);
+  }
+  /**
+   * @zh 记录障碍物变化
+   * @en Record obstacle change
+   *
+   * @param x - @zh X 坐标 @en X coordinate
+   * @param y - @zh Y 坐标 @en Y coordinate
+   * @param wasWalkable - @zh 变化前是否可通行 @en Was walkable before change
+   */
+  recordChange(x, y, wasWalkable) {
+    const key = `${x},${y}`;
+    this.changes.set(key, {
+      x,
+      y,
+      wasWalkable,
+      timestamp: Date.now()
+    });
   }
-  // =========================================================================
-  // 私有方法 | Private Methods
-  // =========================================================================
   /**
-   * @zh 获取地图边界
-   * @en Get map bounds
+   * @zh 获取影响区域
+   * @en Get affected region
+   *
+   * @returns @zh 影响区域或 null（如果没有变化）@en Affected region or null if no changes
    */
-  getMapBounds() {
-    const mapAny = this.map;
-    if (typeof mapAny.width === "number" && typeof mapAny.height === "number") {
-      return {
-        width: mapAny.width,
-        height: mapAny.height
-      };
+  getAffectedRegion() {
+    if (this.changes.size === 0) {
+      return null;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const change of this.changes.values()) {
+      minX = Math.min(minX, change.x);
+      minY = Math.min(minY, change.y);
+      maxX = Math.max(maxX, change.x);
+      maxY = Math.max(maxY, change.y);
     }
     return {
-      width: 1e3,
-      height: 1e3
+      minX,
+      minY,
+      maxX,
+      maxY
     };
   }
   /**
-   * @zh 初始化节点网格
-   * @en Initialize node grid
+   * @zh 获取所有变化
+   * @en Get all changes
+   *
+   * @returns @zh 变化列表 @en List of changes
    */
-  initGrid() {
-    this.nodeGrid = [];
-    for (let i = 0; i < this.width; i++) {
-      this.nodeGrid[i] = [];
-    }
+  getChanges() {
+    return Array.from(this.changes.values());
   }
   /**
-   * @zh 获取或创建节点
-   * @en Get or create node
+   * @zh 检查是否有变化
+   * @en Check if there are changes
+   *
+   * @returns @zh 是否有变化 @en Whether there are changes
    */
-  getOrCreateNode(x, y) {
-    const xi = x | 0;
-    const yi = y | 0;
-    if (xi < 0 || xi >= this.width || yi < 0 || yi >= this.height) {
-      throw new Error("[JPSPathfinder] Invalid grid coordinates");
-    }
-    if (!this.nodeGrid[xi]) {
-      this.nodeGrid[xi] = [];
-    }
-    if (!this.nodeGrid[xi][yi]) {
-      this.nodeGrid[xi][yi] = {
-        x: xi,
-        y: yi,
-        g: Infinity,
-        h: 0,
-        f: Infinity,
-        parent: null,
-        closed: false
-      };
+  hasChanges() {
+    return this.changes.size > 0;
+  }
+  /**
+   * @zh 获取当前 epoch
+   * @en Get current epoch
+   *
+   * @returns @zh 当前 epoch @en Current epoch
+   */
+  getEpoch() {
+    return this.epoch;
+  }
+  /**
+   * @zh 清空变化记录并推进 epoch
+   * @en Clear changes and advance epoch
+   */
+  flush() {
+    this.changes.clear();
+    this.epoch++;
+  }
+  /**
+   * @zh 清空所有状态
+   * @en Clear all state
+   */
+  clear() {
+    this.changes.clear();
+    this.epoch = 0;
+  }
+};
+__name(_ObstacleChangeManager, "ObstacleChangeManager");
+var ObstacleChangeManager = _ObstacleChangeManager;
+function createPathValidator() {
+  return new PathValidator();
+}
+__name(createPathValidator, "createPathValidator");
+function createObstacleChangeManager() {
+  return new ObstacleChangeManager();
+}
+__name(createObstacleChangeManager, "createObstacleChangeManager");
+
+// src/grid/GridMap.ts
+var _GridNode = class _GridNode {
+  constructor(x, y, width, walkable = true, cost = 1) {
+    __publicField(this, "id");
+    __publicField(this, "position");
+    __publicField(this, "x");
+    __publicField(this, "y");
+    __publicField(this, "cost");
+    __publicField(this, "walkable");
+    this.x = x;
+    this.y = y;
+    this.id = y * width + x;
+    this.position = createPoint(x, y);
+    this.walkable = walkable;
+    this.cost = cost;
+  }
+};
+__name(_GridNode, "GridNode");
+var GridNode = _GridNode;
+var DIRECTIONS_4 = [
+  {
+    dx: 0,
+    dy: -1
+  },
+  {
+    dx: 1,
+    dy: 0
+  },
+  {
+    dx: 0,
+    dy: 1
+  },
+  {
+    dx: -1,
+    dy: 0
+  }
+  // Left
+];
+var DIRECTIONS_8 = [
+  {
+    dx: 0,
+    dy: -1
+  },
+  {
+    dx: 1,
+    dy: -1
+  },
+  {
+    dx: 1,
+    dy: 0
+  },
+  {
+    dx: 1,
+    dy: 1
+  },
+  {
+    dx: 0,
+    dy: 1
+  },
+  {
+    dx: -1,
+    dy: 1
+  },
+  {
+    dx: -1,
+    dy: 0
+  },
+  {
+    dx: -1,
+    dy: -1
+  }
+  // Up-Left
+];
+var DEFAULT_GRID_OPTIONS = {
+  allowDiagonal: true,
+  diagonalCost: Math.SQRT2,
+  avoidCorners: true,
+  heuristic: octileDistance
+};
+var _GridMap = class _GridMap {
+  constructor(width, height, options) {
+    __publicField(this, "width");
+    __publicField(this, "height");
+    __publicField(this, "nodes");
+    __publicField(this, "options");
+    if (width <= 0 || !Number.isFinite(width) || !Number.isInteger(width)) {
+      throw new Error(`width must be a positive integer, got: ${width}`);
     }
-    return this.nodeGrid[xi][yi];
-  }
-  /**
-   * @zh 启发式函数（八方向距离）
-   * @en Heuristic function (octile distance)
-   */
-  heuristic(x1, y1, x2, y2) {
-    const dx = Math.abs(x1 - x2);
-    const dy = Math.abs(y1 - y2);
-    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
-  }
-  /**
-   * @zh 识别后继节点（跳跃点）
-   * @en Identify successors (jump points)
-   */
-  identifySuccessors(node, endX, endY, opts) {
-    const neighbors = this.findNeighbors(node);
-    for (const neighbor of neighbors) {
-      const jumpPoint = this.jump(neighbor.x, neighbor.y, node.x, node.y, endX, endY);
-      if (jumpPoint) {
-        const jx = jumpPoint.x;
-        const jy = jumpPoint.y;
-        const jpNode = this.getOrCreateNode(jx, jy);
-        if (jpNode.closed) continue;
-        const dx = Math.abs(jx - node.x);
-        const dy = Math.abs(jy - node.y);
-        const distance = Math.sqrt(dx * dx + dy * dy);
-        const tentativeG = node.g + distance;
-        if (tentativeG < jpNode.g) {
-          jpNode.g = tentativeG;
-          jpNode.h = this.heuristic(jx, jy, endX, endY) * opts.heuristicWeight;
-          jpNode.f = jpNode.g + jpNode.h;
-          jpNode.parent = node;
-          if (!this.openList.contains(jpNode)) {
-            this.openList.push(jpNode);
-          } else {
-            this.openList.update(jpNode);
-          }
-        }
-      }
+    if (height <= 0 || !Number.isFinite(height) || !Number.isInteger(height)) {
+      throw new Error(`height must be a positive integer, got: ${height}`);
     }
+    this.width = width;
+    this.height = height;
+    this.options = {
+      ...DEFAULT_GRID_OPTIONS,
+      ...options
+    };
+    this.nodes = this.createNodes();
   }
   /**
-   * @zh 查找邻居（根据父节点方向剪枝）
-   * @en Find neighbors (pruned based on parent direction)
+   * @zh 创建网格节点
+   * @en Create grid nodes
    */
-  findNeighbors(node) {
-    const { x, y, parent } = node;
-    const neighbors = [];
-    if (!parent) {
-      for (let dx2 = -1; dx2 <= 1; dx2++) {
-        for (let dy2 = -1; dy2 <= 1; dy2++) {
-          if (dx2 === 0 && dy2 === 0) continue;
-          const nx = x + dx2;
-          const ny = y + dy2;
-          if (this.isWalkableAt(nx, ny)) {
-            if (dx2 !== 0 && dy2 !== 0) {
-              if (this.isWalkableAt(x + dx2, y) || this.isWalkableAt(x, y + dy2)) {
-                neighbors.push({
-                  x: nx,
-                  y: ny
-                });
-              }
-            } else {
-              neighbors.push({
-                x: nx,
-                y: ny
-              });
-            }
-          }
-        }
+  createNodes() {
+    const nodes = [];
+    for (let y = 0; y < this.height; y++) {
+      nodes[y] = [];
+      for (let x = 0; x < this.width; x++) {
+        nodes[y][x] = new GridNode(x, y, this.width, true, 1);
       }
-      return neighbors;
     }
-    const dx = Math.sign(x - parent.x);
-    const dy = Math.sign(y - parent.y);
-    if (dx !== 0 && dy !== 0) {
-      if (this.isWalkableAt(x, y + dy)) {
-        neighbors.push({
-          x,
-          y: y + dy
-        });
-      }
-      if (this.isWalkableAt(x + dx, y)) {
-        neighbors.push({
-          x: x + dx,
-          y
-        });
-      }
-      if (this.isWalkableAt(x, y + dy) || this.isWalkableAt(x + dx, y)) {
-        if (this.isWalkableAt(x + dx, y + dy)) {
-          neighbors.push({
-            x: x + dx,
-            y: y + dy
-          });
-        }
-      }
-      if (!this.isWalkableAt(x - dx, y) && this.isWalkableAt(x, y + dy)) {
-        if (this.isWalkableAt(x - dx, y + dy)) {
-          neighbors.push({
-            x: x - dx,
-            y: y + dy
-          });
-        }
-      }
-      if (!this.isWalkableAt(x, y - dy) && this.isWalkableAt(x + dx, y)) {
-        if (this.isWalkableAt(x + dx, y - dy)) {
-          neighbors.push({
-            x: x + dx,
-            y: y - dy
-          });
-        }
-      }
-    } else if (dx !== 0) {
-      if (this.isWalkableAt(x + dx, y)) {
-        neighbors.push({
-          x: x + dx,
-          y
-        });
-        if (!this.isWalkableAt(x, y + 1) && this.isWalkableAt(x + dx, y + 1)) {
-          neighbors.push({
-            x: x + dx,
-            y: y + 1
-          });
-        }
-        if (!this.isWalkableAt(x, y - 1) && this.isWalkableAt(x + dx, y - 1)) {
-          neighbors.push({
-            x: x + dx,
-            y: y - 1
-          });
-        }
-      }
-    } else if (dy !== 0) {
-      if (this.isWalkableAt(x, y + dy)) {
-        neighbors.push({
-          x,
-          y: y + dy
-        });
-        if (!this.isWalkableAt(x + 1, y) && this.isWalkableAt(x + 1, y + dy)) {
-          neighbors.push({
-            x: x + 1,
-            y: y + dy
-          });
-        }
-        if (!this.isWalkableAt(x - 1, y) && this.isWalkableAt(x - 1, y + dy)) {
-          neighbors.push({
-            x: x - 1,
-            y: y + dy
-          });
-        }
-      }
-    }
-    return neighbors;
+    return nodes;
   }
   /**
-   * @zh 跳跃函数（迭代版本，避免递归开销）
-   * @en Jump function (iterative version to avoid recursion overhead)
+   * @zh 获取指定位置的节点
+   * @en Get node at position
    */
-  jump(startX, startY, px, py, endX, endY) {
-    const dx = startX - px;
-    const dy = startY - py;
-    let x = startX;
-    let y = startY;
-    while (true) {
-      if (!this.isWalkableAt(x, y)) {
-        return null;
-      }
-      if (x === endX && y === endY) {
-        return {
-          x,
-          y
-        };
-      }
-      if (dx !== 0 && dy !== 0) {
-        if (this.isWalkableAt(x - dx, y + dy) && !this.isWalkableAt(x - dx, y) || this.isWalkableAt(x + dx, y - dy) && !this.isWalkableAt(x, y - dy)) {
-          return {
-            x,
-            y
-          };
-        }
-        if (this.jumpStraight(x + dx, y, dx, 0, endX, endY) || this.jumpStraight(x, y + dy, 0, dy, endX, endY)) {
-          return {
-            x,
-            y
-          };
-        }
-        if (!this.isWalkableAt(x + dx, y) && !this.isWalkableAt(x, y + dy)) {
-          return null;
-        }
-      } else if (dx !== 0) {
-        if (this.isWalkableAt(x + dx, y + 1) && !this.isWalkableAt(x, y + 1) || this.isWalkableAt(x + dx, y - 1) && !this.isWalkableAt(x, y - 1)) {
-          return {
-            x,
-            y
-          };
-        }
-      } else if (dy !== 0) {
-        if (this.isWalkableAt(x + 1, y + dy) && !this.isWalkableAt(x + 1, y) || this.isWalkableAt(x - 1, y + dy) && !this.isWalkableAt(x - 1, y)) {
-          return {
-            x,
-            y
-          };
-        }
-      }
-      x += dx;
-      y += dy;
+  getNodeAt(x, y) {
+    if (!this.isInBounds(x, y)) {
+      return null;
     }
+    return this.nodes[y][x];
   }
   /**
-   * @zh 直线跳跃（水平或垂直方向）
-   * @en Straight jump (horizontal or vertical direction)
+   * @zh 检查坐标是否在边界内
+   * @en Check if coordinates are within bounds
    */
-  jumpStraight(startX, startY, dx, dy, endX, endY) {
-    let x = startX;
-    let y = startY;
-    while (true) {
-      if (!this.isWalkableAt(x, y)) {
-        return false;
-      }
-      if (x === endX && y === endY) {
-        return true;
-      }
-      if (dx !== 0) {
-        if (this.isWalkableAt(x + dx, y + 1) && !this.isWalkableAt(x, y + 1) || this.isWalkableAt(x + dx, y - 1) && !this.isWalkableAt(x, y - 1)) {
-          return true;
-        }
-      } else if (dy !== 0) {
-        if (this.isWalkableAt(x + 1, y + dy) && !this.isWalkableAt(x + 1, y) || this.isWalkableAt(x - 1, y + dy) && !this.isWalkableAt(x - 1, y)) {
-          return true;
-        }
-      }
-      x += dx;
-      y += dy;
-    }
+  isInBounds(x, y) {
+    return x >= 0 && x < this.width && y >= 0 && y < this.height;
   }
   /**
    * @zh 检查位置是否可通行
    * @en Check if position is walkable
    */
-  isWalkableAt(x, y) {
-    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-      return false;
-    }
-    return this.map.isWalkable(x, y);
+  isWalkable(x, y) {
+    const node = this.getNodeAt(x, y);
+    return node !== null && node.walkable;
   }
   /**
-   * @zh 构建路径
-   * @en Build path
+   * @zh 设置位置是否可通行
+   * @en Set position walkability
    */
-  buildPath(endNode) {
-    const path = [];
-    let current = endNode;
-    while (current) {
-      path.unshift({
-        x: current.x,
-        y: current.y
-      });
-      current = current.parent;
+  setWalkable(x, y, walkable) {
+    const node = this.getNodeAt(x, y);
+    if (node) {
+      node.walkable = walkable;
     }
-    return this.interpolatePath(path);
   }
   /**
-   * @zh 插值路径（在跳跃点之间填充中间点）
-   * @en Interpolate path (fill intermediate points between jump points)
+   * @zh 设置位置的移动代价
+   * @en Set movement cost at position
+   *
+   * @param x - @zh X 坐标 @en X coordinate
+   * @param y - @zh Y 坐标 @en Y coordinate
+   * @param cost - @zh 移动代价，必须为正数 @en Movement cost, must be positive
+   * @throws @zh 如果 cost 不是正数则抛出错误 @en Throws if cost is not positive
    */
-  interpolatePath(jumpPoints) {
-    if (jumpPoints.length < 2) {
-      return jumpPoints;
+  setCost(x, y, cost) {
+    if (cost <= 0 || !Number.isFinite(cost)) {
+      throw new Error(`cost must be a positive finite number, got: ${cost}`);
     }
-    const path = [
-      jumpPoints[0]
-    ];
-    for (let i = 1; i < jumpPoints.length; i++) {
-      const prev = jumpPoints[i - 1];
-      const curr = jumpPoints[i];
-      const dx = curr.x - prev.x;
-      const dy = curr.y - prev.y;
-      const steps = Math.max(Math.abs(dx), Math.abs(dy));
-      const stepX = dx === 0 ? 0 : dx / Math.abs(dx);
-      const stepY = dy === 0 ? 0 : dy / Math.abs(dy);
-      let x = prev.x;
-      let y = prev.y;
-      for (let j = 0; j < steps; j++) {
-        if (x !== curr.x && y !== curr.y) {
-          x += stepX;
-          y += stepY;
-        } else if (x !== curr.x) {
-          x += stepX;
-        } else if (y !== curr.y) {
-          y += stepY;
-        }
-        if (x !== prev.x || y !== prev.y) {
-          path.push({
-            x,
-            y
-          });
-        }
-      }
+    const node = this.getNodeAt(x, y);
+    if (node) {
+      node.cost = cost;
     }
-    return path;
-  }
-};
-__name(_JPSPathfinder, "JPSPathfinder");
-var JPSPathfinder = _JPSPathfinder;
-function createJPSPathfinder(map) {
-  return new JPSPathfinder(map);
-}
-__name(createJPSPathfinder, "createJPSPathfinder");
-
-// src/core/HPAPathfinder.ts
-var DEFAULT_HPA_CONFIG = {
-  clusterSize: 64,
-  maxEntranceWidth: 16,
-  cacheInternalPaths: true,
-  entranceStrategy: "end",
-  lazyIntraEdges: true
-};
-var _a3;
-var SubMap = (_a3 = class {
-  constructor(parentMap, originX, originY, width, height) {
-    __publicField(this, "parentMap");
-    __publicField(this, "originX");
-    __publicField(this, "originY");
-    __publicField(this, "width");
-    __publicField(this, "height");
-    this.parentMap = parentMap;
-    this.originX = originX;
-    this.originY = originY;
-    this.width = width;
-    this.height = height;
   }
   /**
-   * @zh 局部坐标转全局坐标
-   * @en Convert local to global coordinates
+   * @zh 获取节点的邻居
+   * @en Get neighbors of a node
    */
-  localToGlobal(localX, localY) {
-    return {
-      x: this.originX + localX,
-      y: this.originY + localY
-    };
-  }
-  /**
-   * @zh 全局坐标转局部坐标
-   * @en Convert global to local coordinates
-   */
-  globalToLocal(globalX, globalY) {
-    return {
-      x: globalX - this.originX,
-      y: globalY - this.originY
-    };
-  }
-  isWalkable(x, y) {
-    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-      return false;
-    }
-    return this.parentMap.isWalkable(this.originX + x, this.originY + y);
-  }
-  getNodeAt(x, y) {
-    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-      return null;
-    }
-    const globalNode = this.parentMap.getNodeAt(this.originX + x, this.originY + y);
-    if (!globalNode) return null;
-    return {
-      id: y * this.width + x,
-      position: {
-        x,
-        y
-      },
-      cost: globalNode.cost,
-      walkable: globalNode.walkable
-    };
-  }
   getNeighbors(node) {
     const neighbors = [];
     const { x, y } = node.position;
-    const directions = [
-      {
-        dx: 0,
-        dy: -1
-      },
-      {
-        dx: 1,
-        dy: -1
-      },
-      {
-        dx: 1,
-        dy: 0
-      },
-      {
-        dx: 1,
-        dy: 1
-      },
-      {
-        dx: 0,
-        dy: 1
-      },
-      {
-        dx: -1,
-        dy: 1
-      },
-      {
-        dx: -1,
-        dy: 0
-      },
-      {
-        dx: -1,
-        dy: -1
-      }
-      // NW
-    ];
-    for (const dir of directions) {
+    const directions = this.options.allowDiagonal ? DIRECTIONS_8 : DIRECTIONS_4;
+    for (let i = 0; i < directions.length; i++) {
+      const dir = directions[i];
       const nx = x + dir.dx;
       const ny = y + dir.dy;
       if (nx < 0 || nx >= this.width || ny < 0 || ny >= this.height) {
         continue;
       }
-      if (!this.isWalkable(nx, ny)) {
+      const neighbor = this.nodes[ny][nx];
+      if (!neighbor.walkable) {
         continue;
       }
-      if (dir.dx !== 0 && dir.dy !== 0) {
-        if (!this.isWalkable(x + dir.dx, y) || !this.isWalkable(x, y + dir.dy)) {
+      if (this.options.avoidCorners && dir.dx !== 0 && dir.dy !== 0) {
+        const hNode = this.nodes[y][x + dir.dx];
+        const vNode = this.nodes[y + dir.dy][x];
+        if (!hNode.walkable || !vNode.walkable) {
           continue;
         }
       }
-      const neighborNode = this.getNodeAt(nx, ny);
-      if (neighborNode) {
-        neighbors.push(neighborNode);
-      }
+      neighbors.push(neighbor);
     }
     return neighbors;
   }
-  heuristic(a, b) {
-    const dx = Math.abs(a.x - b.x);
-    const dy = Math.abs(a.y - b.y);
-    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
-  }
-  getMovementCost(from, to) {
-    const dx = Math.abs(to.position.x - from.position.x);
-    const dy = Math.abs(to.position.y - from.position.y);
-    const baseCost = dx !== 0 && dy !== 0 ? Math.SQRT2 : 1;
-    return baseCost * to.cost;
-  }
-}, __name(_a3, "SubMap"), _a3);
-var _a4;
-var Cluster = (_a4 = class {
-  constructor(id, originX, originY, width, height, parentMap) {
-    __publicField(this, "id");
-    __publicField(this, "originX");
-    __publicField(this, "originY");
-    __publicField(this, "width");
-    __publicField(this, "height");
-    __publicField(this, "subMap");
-    /** @zh 集群内的抽象节点 ID 列表 @en Abstract node IDs in this cluster */
-    __publicField(this, "nodeIds", []);
-    /** @zh 预计算的距离缓存 @en Precomputed distance cache */
-    __publicField(this, "distanceCache", /* @__PURE__ */ new Map());
-    /** @zh 预计算的路径缓存 @en Precomputed path cache */
-    __publicField(this, "pathCache", /* @__PURE__ */ new Map());
-    this.id = id;
-    this.originX = originX;
-    this.originY = originY;
-    this.width = width;
-    this.height = height;
-    this.subMap = new SubMap(parentMap, originX, originY, width, height);
-  }
-  /**
-   * @zh 检查点是否在集群内
-   * @en Check if point is in cluster
-   */
-  containsPoint(x, y) {
-    return x >= this.originX && x < this.originX + this.width && y >= this.originY && y < this.originY + this.height;
-  }
-  /**
-   * @zh 添加节点 ID
-   * @en Add node ID
-   */
-  addNodeId(nodeId) {
-    if (!this.nodeIds.includes(nodeId)) {
-      this.nodeIds.push(nodeId);
-    }
-  }
-  /**
-   * @zh 移除节点 ID
-   * @en Remove node ID
-   */
-  removeNodeId(nodeId) {
-    const idx = this.nodeIds.indexOf(nodeId);
-    if (idx !== -1) {
-      this.nodeIds.splice(idx, 1);
-    }
-  }
-  /**
-   * @zh 生成缓存键
-   * @en Generate cache key
-   */
-  getCacheKey(fromId, toId) {
-    return `${fromId}->${toId}`;
-  }
-  /**
-   * @zh 设置缓存
-   * @en Set cache
-   */
-  setCache(fromId, toId, cost, path) {
-    const key = this.getCacheKey(fromId, toId);
-    this.distanceCache.set(key, cost);
-    this.pathCache.set(key, path);
-  }
-  /**
-   * @zh 获取缓存的距离
-   * @en Get cached distance
-   */
-  getCachedDistance(fromId, toId) {
-    return this.distanceCache.get(this.getCacheKey(fromId, toId));
-  }
-  /**
-   * @zh 获取缓存的路径
-   * @en Get cached path
-   */
-  getCachedPath(fromId, toId) {
-    return this.pathCache.get(this.getCacheKey(fromId, toId));
-  }
-  /**
-   * @zh 清除缓存
-   * @en Clear cache
-   */
-  clearCache() {
-    this.distanceCache.clear();
-    this.pathCache.clear();
-  }
-  /**
-   * @zh 获取缓存大小
-   * @en Get cache size
-   */
-  getCacheSize() {
-    return this.distanceCache.size;
-  }
-}, __name(_a4, "Cluster"), _a4);
-var _HPAPathfinder = class _HPAPathfinder {
-  constructor(map, config) {
-    __publicField(this, "map");
-    __publicField(this, "config");
-    __publicField(this, "mapWidth");
-    __publicField(this, "mapHeight");
-    // 集群管理
-    __publicField(this, "clusters", []);
-    __publicField(this, "clusterGrid", []);
-    __publicField(this, "clustersX", 0);
-    __publicField(this, "clustersY", 0);
-    // 抽象图
-    __publicField(this, "abstractNodes", /* @__PURE__ */ new Map());
-    __publicField(this, "nodesByCluster", /* @__PURE__ */ new Map());
-    __publicField(this, "nextNodeId", 0);
-    // 入口统计
-    __publicField(this, "entranceCount", 0);
-    // 内部寻路器
-    __publicField(this, "localPathfinder");
-    // 完整路径缓存
-    __publicField(this, "pathCache");
-    __publicField(this, "mapVersion", 0);
-    __publicField(this, "preprocessed", false);
-    this.map = map;
-    this.config = {
-      ...DEFAULT_HPA_CONFIG,
-      ...config
-    };
-    const bounds = this.getMapBounds();
-    this.mapWidth = bounds.width;
-    this.mapHeight = bounds.height;
-    this.localPathfinder = new AStarPathfinder(map);
-    this.pathCache = new PathCache({
-      maxEntries: 1e3,
-      ttlMs: 0
-    });
-  }
-  // =========================================================================
-  // 公共 API | Public API
-  // =========================================================================
-  /**
-   * @zh 预处理地图（构建抽象图）
-   * @en Preprocess map (build abstract graph)
-   */
-  preprocess() {
-    this.clear();
-    this.buildClusters();
-    this.buildEntrances();
-    this.buildIntraEdges();
-    this.preprocessed = true;
-  }
-  /**
-   * @zh 寻找路径
-   * @en Find path
-   */
-  findPath(startX, startY, endX, endY, options) {
-    if (!this.preprocessed) {
-      this.preprocess();
-    }
-    const opts = {
-      ...DEFAULT_PATHFINDING_OPTIONS,
-      ...options
-    };
-    if (!this.map.isWalkable(startX, startY) || !this.map.isWalkable(endX, endY)) {
-      return EMPTY_PATH_RESULT;
-    }
-    if (startX === endX && startY === endY) {
-      return {
-        found: true,
-        path: [
-          {
-            x: startX,
-            y: startY
-          }
-        ],
-        cost: 0,
-        nodesSearched: 1
-      };
-    }
-    const cached = this.pathCache.get(startX, startY, endX, endY, this.mapVersion);
-    if (cached) {
-      return cached;
-    }
-    const startCluster = this.getClusterAt(startX, startY);
-    const endCluster = this.getClusterAt(endX, endY);
-    if (!startCluster || !endCluster) {
-      return EMPTY_PATH_RESULT;
-    }
-    let result;
-    if (startCluster.id === endCluster.id) {
-      result = this.findLocalPath(startX, startY, endX, endY, opts);
-    } else {
-      const startTemp = this.insertTempNode(startX, startY, startCluster);
-      const endTemp = this.insertTempNode(endX, endY, endCluster);
-      const abstractPath = this.abstractSearch(startTemp, endTemp, opts);
-      this.removeTempNode(startTemp, startCluster);
-      this.removeTempNode(endTemp, endCluster);
-      if (!abstractPath || abstractPath.length === 0) {
-        return EMPTY_PATH_RESULT;
-      }
-      result = this.refinePath(abstractPath, startX, startY, endX, endY, opts);
-    }
-    if (result.found) {
-      this.pathCache.set(startX, startY, endX, endY, result, this.mapVersion);
-    }
-    return result;
-  }
   /**
-   * @zh 清理状态
-   * @en Clear state
+   * @zh 遍历节点的邻居（零分配）
+   * @en Iterate over neighbors (zero allocation)
    */
-  clear() {
-    this.clusters = [];
-    this.clusterGrid = [];
-    this.abstractNodes.clear();
-    this.nodesByCluster.clear();
-    this.nextNodeId = 0;
-    this.entranceCount = 0;
-    this.pathCache.invalidateAll();
-    this.mapVersion++;
-    this.preprocessed = false;
-  }
-  /**
-   * @zh 通知地图区域变化
-   * @en Notify map region change
-   */
-  notifyRegionChange(minX, minY, maxX, maxY) {
-    const affectedClusters = this.getAffectedClusters(minX, minY, maxX, maxY);
-    for (const cluster of affectedClusters) {
-      cluster.clearCache();
-      for (const nodeId of cluster.nodeIds) {
-        const node = this.abstractNodes.get(nodeId);
-        if (node) {
-          node.edges = node.edges.filter((e) => e.isInterEdge);
-        }
-      }
-      this.buildClusterIntraEdges(cluster);
-    }
-    this.pathCache.invalidateRegion(minX, minY, maxX, maxY);
-    this.mapVersion++;
-  }
-  /**
-   * @zh 获取预处理统计信息
-   * @en Get preprocessing statistics
-   */
-  getStats() {
-    let cacheSize = 0;
-    for (const cluster of this.clusters) {
-      cacheSize += cluster.getCacheSize();
-    }
-    return {
-      clusters: this.clusters.length,
-      entrances: this.entranceCount,
-      abstractNodes: this.abstractNodes.size,
-      cacheSize
-    };
-  }
-  // =========================================================================
-  // 预处理方法 | Preprocessing Methods
-  // =========================================================================
-  getMapBounds() {
-    const mapAny = this.map;
-    if (typeof mapAny.width === "number" && typeof mapAny.height === "number") {
-      return {
-        width: mapAny.width,
-        height: mapAny.height
-      };
-    }
-    return {
-      width: 1e3,
-      height: 1e3
-    };
-  }
-  /**
-   * @zh 构建集群
-   * @en Build clusters
-   */
-  buildClusters() {
-    const clusterSize = this.config.clusterSize;
-    this.clustersX = Math.ceil(this.mapWidth / clusterSize);
-    this.clustersY = Math.ceil(this.mapHeight / clusterSize);
-    this.clusterGrid = [];
-    for (let cx = 0; cx < this.clustersX; cx++) {
-      this.clusterGrid[cx] = [];
-      for (let cy = 0; cy < this.clustersY; cy++) {
-        this.clusterGrid[cx][cy] = null;
-      }
-    }
-    let clusterId = 0;
-    for (let cy = 0; cy < this.clustersY; cy++) {
-      for (let cx = 0; cx < this.clustersX; cx++) {
-        const originX = cx * clusterSize;
-        const originY = cy * clusterSize;
-        const width = Math.min(clusterSize, this.mapWidth - originX);
-        const height = Math.min(clusterSize, this.mapHeight - originY);
-        const cluster = new Cluster(clusterId, originX, originY, width, height, this.map);
-        this.clusters.push(cluster);
-        this.clusterGrid[cx][cy] = clusterId;
-        this.nodesByCluster.set(clusterId, []);
-        clusterId++;
-      }
-    }
-  }
-  /**
-   * @zh 检测入口并创建抽象节点
-   * @en Detect entrances and create abstract nodes
-   */
-  buildEntrances() {
-    const clusterSize = this.config.clusterSize;
-    for (let cy = 0; cy < this.clustersY; cy++) {
-      for (let cx = 0; cx < this.clustersX; cx++) {
-        const clusterId = this.clusterGrid[cx][cy];
-        if (clusterId === null) continue;
-        const cluster1 = this.clusters[clusterId];
-        if (cx < this.clustersX - 1) {
-          const cluster2Id = this.clusterGrid[cx + 1][cy];
-          if (cluster2Id !== null) {
-            const cluster2 = this.clusters[cluster2Id];
-            this.detectAndCreateEntrances(cluster1, cluster2, "vertical");
-          }
-        }
-        if (cy < this.clustersY - 1) {
-          const cluster2Id = this.clusterGrid[cx][cy + 1];
-          if (cluster2Id !== null) {
-            const cluster2 = this.clusters[cluster2Id];
-            this.detectAndCreateEntrances(cluster1, cluster2, "horizontal");
-          }
-        }
-      }
-    }
-  }
-  /**
-   * @zh 检测并创建两个相邻集群之间的入口
-   * @en Detect and create entrances between two adjacent clusters
-   */
-  detectAndCreateEntrances(cluster1, cluster2, boundaryDirection) {
-    const spans = this.detectEntranceSpans(cluster1, cluster2, boundaryDirection);
-    for (const span of spans) {
-      this.createEntranceNodes(cluster1, cluster2, span, boundaryDirection);
-    }
-  }
-  /**
-   * @zh 检测边界上的连续可通行区间
-   * @en Detect continuous walkable spans on boundary
-   */
-  detectEntranceSpans(cluster1, cluster2, boundaryDirection) {
-    const spans = [];
-    if (boundaryDirection === "vertical") {
-      const x1 = cluster1.originX + cluster1.width - 1;
-      const x2 = cluster2.originX;
-      const startY = Math.max(cluster1.originY, cluster2.originY);
-      const endY = Math.min(cluster1.originY + cluster1.height, cluster2.originY + cluster2.height);
-      let spanStart = null;
-      for (let y = startY; y < endY; y++) {
-        const walkable1 = this.map.isWalkable(x1, y);
-        const walkable2 = this.map.isWalkable(x2, y);
-        if (walkable1 && walkable2) {
-          if (spanStart === null) {
-            spanStart = y;
-          }
-        } else {
-          if (spanStart !== null) {
-            spans.push({
-              start: spanStart,
-              end: y - 1
-            });
-            spanStart = null;
-          }
-        }
-      }
-      if (spanStart !== null) {
-        spans.push({
-          start: spanStart,
-          end: endY - 1
-        });
-      }
-    } else {
-      const y1 = cluster1.originY + cluster1.height - 1;
-      const y2 = cluster2.originY;
-      const startX = Math.max(cluster1.originX, cluster2.originX);
-      const endX = Math.min(cluster1.originX + cluster1.width, cluster2.originX + cluster2.width);
-      let spanStart = null;
-      for (let x = startX; x < endX; x++) {
-        const walkable1 = this.map.isWalkable(x, y1);
-        const walkable2 = this.map.isWalkable(x, y2);
-        if (walkable1 && walkable2) {
-          if (spanStart === null) {
-            spanStart = x;
-          }
-        } else {
-          if (spanStart !== null) {
-            spans.push({
-              start: spanStart,
-              end: x - 1
-            });
-            spanStart = null;
-          }
-        }
-      }
-      if (spanStart !== null) {
-        spans.push({
-          start: spanStart,
-          end: endX - 1
-        });
+  forEachNeighbor(node, callback) {
+    const { x, y } = node.position;
+    const directions = this.options.allowDiagonal ? DIRECTIONS_8 : DIRECTIONS_4;
+    for (let i = 0; i < directions.length; i++) {
+      const dir = directions[i];
+      const nx = x + dir.dx;
+      const ny = y + dir.dy;
+      if (nx < 0 || nx >= this.width || ny < 0 || ny >= this.height) {
+        continue;
       }
-    }
-    return spans;
-  }
-  /**
-   * @zh 为入口区间创建抽象节点
-   * @en Create abstract nodes for entrance span
-   */
-  createEntranceNodes(cluster1, cluster2, span, boundaryDirection) {
-    const spanLength = span.end - span.start + 1;
-    const maxWidth = this.config.maxEntranceWidth;
-    const strategy = this.config.entranceStrategy;
-    const positions = [];
-    if (spanLength <= maxWidth) {
-      positions.push(Math.floor((span.start + span.end) / 2));
-    } else {
-      const numNodes = Math.ceil(spanLength / maxWidth);
-      const spacing = spanLength / numNodes;
-      for (let i = 0; i < numNodes; i++) {
-        const pos = Math.floor(span.start + spacing * (i + 0.5));
-        positions.push(Math.min(pos, span.end));
+      const neighbor = this.nodes[ny][nx];
+      if (!neighbor.walkable) {
+        continue;
       }
-      if (strategy === "end") {
-        if (!positions.includes(span.start)) {
-          positions.unshift(span.start);
-        }
-        if (!positions.includes(span.end)) {
-          positions.push(span.end);
+      if (this.options.avoidCorners && dir.dx !== 0 && dir.dy !== 0) {
+        const hNode = this.nodes[y][x + dir.dx];
+        const vNode = this.nodes[y + dir.dy][x];
+        if (!hNode.walkable || !vNode.walkable) {
+          continue;
         }
       }
-    }
-    for (const pos of positions) {
-      let p1, p2;
-      if (boundaryDirection === "vertical") {
-        p1 = {
-          x: cluster1.originX + cluster1.width - 1,
-          y: pos
-        };
-        p2 = {
-          x: cluster2.originX,
-          y: pos
-        };
-      } else {
-        p1 = {
-          x: pos,
-          y: cluster1.originY + cluster1.height - 1
-        };
-        p2 = {
-          x: pos,
-          y: cluster2.originY
-        };
-      }
-      const node1 = this.createAbstractNode(p1, cluster1);
-      const node2 = this.createAbstractNode(p2, cluster2);
-      const interCost = 1;
-      node1.edges.push({
-        targetNodeId: node2.id,
-        cost: interCost,
-        isInterEdge: true,
-        innerPath: null
-      });
-      node2.edges.push({
-        targetNodeId: node1.id,
-        cost: interCost,
-        isInterEdge: true,
-        innerPath: null
-      });
-      this.entranceCount++;
-    }
-  }
-  /**
-   * @zh 创建抽象节点
-   * @en Create abstract node
-   */
-  createAbstractNode(position, cluster) {
-    const concreteId = position.y * this.mapWidth + position.x;
-    for (const nodeId of cluster.nodeIds) {
-      const existing = this.abstractNodes.get(nodeId);
-      if (existing && existing.concreteNodeId === concreteId) {
-        return existing;
+      if (callback(neighbor) === false) {
+        return;
       }
     }
-    const node = {
-      id: this.nextNodeId++,
-      position: {
-        x: position.x,
-        y: position.y
-      },
-      clusterId: cluster.id,
-      concreteNodeId: concreteId,
-      edges: []
-    };
-    this.abstractNodes.set(node.id, node);
-    cluster.addNodeId(node.id);
-    const clusterNodes = this.nodesByCluster.get(cluster.id);
-    if (clusterNodes) {
-      clusterNodes.push(node.id);
-    }
-    return node;
-  }
-  /**
-   * @zh 构建所有集群的 intra-edges
-   * @en Build intra-edges for all clusters
-   */
-  buildIntraEdges() {
-    for (const cluster of this.clusters) {
-      this.buildClusterIntraEdges(cluster);
-    }
   }
   /**
-   * @zh 构建单个集群的 intra-edges
-   * @en Build intra-edges for single cluster
+   * @zh 计算启发式距离
+   * @en Calculate heuristic distance
    */
-  buildClusterIntraEdges(cluster) {
-    const nodeIds = cluster.nodeIds;
-    if (nodeIds.length < 2) return;
-    if (this.config.lazyIntraEdges) {
-      this.buildLazyIntraEdges(cluster);
-    } else {
-      this.buildEagerIntraEdges(cluster);
-    }
-  }
-  /**
-   * @zh 延迟构建 intra-edges（只用启发式距离）
-   * @en Build lazy intra-edges (using heuristic distance only)
-   */
-  buildLazyIntraEdges(cluster) {
-    const nodeIds = cluster.nodeIds;
-    for (let i = 0; i < nodeIds.length; i++) {
-      for (let j = i + 1; j < nodeIds.length; j++) {
-        const node1 = this.abstractNodes.get(nodeIds[i]);
-        const node2 = this.abstractNodes.get(nodeIds[j]);
-        const heuristicCost = this.heuristic(node1.position, node2.position);
-        node1.edges.push({
-          targetNodeId: node2.id,
-          cost: heuristicCost,
-          isInterEdge: false,
-          innerPath: null
-          // 标记为未计算
-        });
-        node2.edges.push({
-          targetNodeId: node1.id,
-          cost: heuristicCost,
-          isInterEdge: false,
-          innerPath: null
-        });
-      }
-    }
-  }
-  /**
-   * @zh 立即构建 intra-edges（计算真实路径）
-   * @en Build eager intra-edges (compute actual paths)
-   */
-  buildEagerIntraEdges(cluster) {
-    const nodeIds = cluster.nodeIds;
-    const subPathfinder = new AStarPathfinder(cluster.subMap);
-    for (let i = 0; i < nodeIds.length; i++) {
-      for (let j = i + 1; j < nodeIds.length; j++) {
-        const node1 = this.abstractNodes.get(nodeIds[i]);
-        const node2 = this.abstractNodes.get(nodeIds[j]);
-        const local1 = cluster.subMap.globalToLocal(node1.position.x, node1.position.y);
-        const local2 = cluster.subMap.globalToLocal(node2.position.x, node2.position.y);
-        const result = subPathfinder.findPath(local1.x, local1.y, local2.x, local2.y);
-        if (result.found && result.path.length > 0) {
-          const globalPath = result.path.map((p) => {
-            const global = cluster.subMap.localToGlobal(p.x, p.y);
-            return global.y * this.mapWidth + global.x;
-          });
-          if (this.config.cacheInternalPaths) {
-            cluster.setCache(node1.id, node2.id, result.cost, globalPath);
-            cluster.setCache(node2.id, node1.id, result.cost, [
-              ...globalPath
-            ].reverse());
-          }
-          node1.edges.push({
-            targetNodeId: node2.id,
-            cost: result.cost,
-            isInterEdge: false,
-            innerPath: this.config.cacheInternalPaths ? globalPath : null
-          });
-          node2.edges.push({
-            targetNodeId: node1.id,
-            cost: result.cost,
-            isInterEdge: false,
-            innerPath: this.config.cacheInternalPaths ? [
-              ...globalPath
-            ].reverse() : null
-          });
-        }
-      }
-    }
-  }
-  /**
-   * @zh 按需计算 intra-edge 的真实路径
-   * @en Compute actual path for intra-edge on demand
-   */
-  computeIntraEdgePath(fromNode, toNode, edge) {
-    const cluster = this.clusters[fromNode.clusterId];
-    if (!cluster) return null;
-    const cachedPath = cluster.getCachedPath(fromNode.id, toNode.id);
-    const cachedCost = cluster.getCachedDistance(fromNode.id, toNode.id);
-    if (cachedPath && cachedCost !== void 0) {
-      edge.cost = cachedCost;
-      edge.innerPath = cachedPath;
-      return {
-        cost: cachedCost,
-        path: cachedPath
-      };
-    }
-    const subPathfinder = new AStarPathfinder(cluster.subMap);
-    const local1 = cluster.subMap.globalToLocal(fromNode.position.x, fromNode.position.y);
-    const local2 = cluster.subMap.globalToLocal(toNode.position.x, toNode.position.y);
-    const result = subPathfinder.findPath(local1.x, local1.y, local2.x, local2.y);
-    if (result.found && result.path.length > 0) {
-      const globalPath = result.path.map((p) => {
-        const global = cluster.subMap.localToGlobal(p.x, p.y);
-        return global.y * this.mapWidth + global.x;
-      });
-      if (this.config.cacheInternalPaths) {
-        cluster.setCache(fromNode.id, toNode.id, result.cost, globalPath);
-        cluster.setCache(toNode.id, fromNode.id, result.cost, [
-          ...globalPath
-        ].reverse());
-      }
-      edge.cost = result.cost;
-      edge.innerPath = globalPath;
-      const reverseEdge = toNode.edges.find((e) => e.targetNodeId === fromNode.id);
-      if (reverseEdge) {
-        reverseEdge.cost = result.cost;
-        reverseEdge.innerPath = [
-          ...globalPath
-        ].reverse();
-      }
-      return {
-        cost: result.cost,
-        path: globalPath
-      };
-    }
-    return null;
+  heuristic(a, b) {
+    return this.options.heuristic(a, b);
   }
-  // =========================================================================
-  // 搜索方法 | Search Methods
-  // =========================================================================
   /**
-   * @zh 获取指定位置的集群
-   * @en Get cluster at position
+   * @zh 计算移动代价
+   * @en Calculate movement cost
    */
-  getClusterAt(x, y) {
-    const cx = Math.floor(x / this.config.clusterSize);
-    const cy = Math.floor(y / this.config.clusterSize);
-    if (cx < 0 || cx >= this.clustersX || cy < 0 || cy >= this.clustersY) {
-      return null;
-    }
-    const clusterId = this.clusterGrid[cx]?.[cy];
-    if (clusterId === null || clusterId === void 0) {
-      return null;
-    }
-    return this.clusters[clusterId] || null;
-  }
-  /**
-   * @zh 获取受影响的集群
-   * @en Get affected clusters
-   */
-  getAffectedClusters(minX, minY, maxX, maxY) {
-    const affected = [];
-    const clusterSize = this.config.clusterSize;
-    const minCX = Math.floor(minX / clusterSize);
-    const maxCX = Math.floor(maxX / clusterSize);
-    const minCY = Math.floor(minY / clusterSize);
-    const maxCY = Math.floor(maxY / clusterSize);
-    for (let cy = minCY; cy <= maxCY; cy++) {
-      for (let cx = minCX; cx <= maxCX; cx++) {
-        if (cx >= 0 && cx < this.clustersX && cy >= 0 && cy < this.clustersY) {
-          const clusterId = this.clusterGrid[cx]?.[cy];
-          if (clusterId !== null && clusterId !== void 0) {
-            affected.push(this.clusters[clusterId]);
-          }
-        }
-      }
+  getMovementCost(from, to) {
+    const dx = Math.abs(from.position.x - to.position.x);
+    const dy = Math.abs(from.position.y - to.position.y);
+    if (dx !== 0 && dy !== 0) {
+      return to.cost * this.options.diagonalCost;
     }
-    return affected;
+    return to.cost;
   }
   /**
-   * @zh 插入临时节点
-   * @en Insert temporary node
+   * @zh 从二维数组加载地图
+   * @en Load map from 2D array
+   *
+   * @param data - @zh 0=可通行，非0=不可通行 @en 0=walkable, non-0=blocked
    */
-  insertTempNode(x, y, cluster) {
-    const concreteId = y * this.mapWidth + x;
-    for (const nodeId of cluster.nodeIds) {
-      const existing = this.abstractNodes.get(nodeId);
-      if (existing && existing.concreteNodeId === concreteId) {
-        return existing;
-      }
-    }
-    const tempNode = {
-      id: this.nextNodeId++,
-      position: {
-        x,
-        y
-      },
-      clusterId: cluster.id,
-      concreteNodeId: concreteId,
-      edges: []
-    };
-    this.abstractNodes.set(tempNode.id, tempNode);
-    cluster.addNodeId(tempNode.id);
-    const subPathfinder = new AStarPathfinder(cluster.subMap);
-    const localPos = cluster.subMap.globalToLocal(x, y);
-    for (const existingNodeId of cluster.nodeIds) {
-      if (existingNodeId === tempNode.id) continue;
-      const existingNode = this.abstractNodes.get(existingNodeId);
-      if (!existingNode) continue;
-      const targetLocalPos = cluster.subMap.globalToLocal(existingNode.position.x, existingNode.position.y);
-      const result = subPathfinder.findPath(localPos.x, localPos.y, targetLocalPos.x, targetLocalPos.y);
-      if (result.found && result.path.length > 0) {
-        const globalPath = result.path.map((p) => {
-          const global = cluster.subMap.localToGlobal(p.x, p.y);
-          return global.y * this.mapWidth + global.x;
-        });
-        tempNode.edges.push({
-          targetNodeId: existingNode.id,
-          cost: result.cost,
-          isInterEdge: false,
-          innerPath: globalPath
-        });
-        existingNode.edges.push({
-          targetNodeId: tempNode.id,
-          cost: result.cost,
-          isInterEdge: false,
-          innerPath: [
-            ...globalPath
-          ].reverse()
-        });
+  loadFromArray(data) {
+    for (let y = 0; y < Math.min(data.length, this.height); y++) {
+      for (let x = 0; x < Math.min(data[y].length, this.width); x++) {
+        this.nodes[y][x].walkable = data[y][x] === 0;
       }
     }
-    return tempNode;
   }
   /**
-   * @zh 移除临时节点
-   * @en Remove temporary node
+   * @zh 从字符串加载地图
+   * @en Load map from string
+   *
+   * @param str - @zh 地图字符串，'.'=可通行，'#'=障碍 @en Map string, '.'=walkable, '#'=blocked
    */
-  removeTempNode(node, cluster) {
-    for (const existingNodeId of cluster.nodeIds) {
-      if (existingNodeId === node.id) continue;
-      const existingNode = this.abstractNodes.get(existingNodeId);
-      if (existingNode) {
-        existingNode.edges = existingNode.edges.filter((e) => e.targetNodeId !== node.id);
+  loadFromString(str) {
+    const lines = str.trim().split("\n");
+    for (let y = 0; y < Math.min(lines.length, this.height); y++) {
+      const line = lines[y];
+      for (let x = 0; x < Math.min(line.length, this.width); x++) {
+        this.nodes[y][x].walkable = line[x] !== "#";
       }
     }
-    cluster.removeNodeId(node.id);
-    this.abstractNodes.delete(node.id);
   }
   /**
-   * @zh 在抽象图上进行 A* 搜索
-   * @en Perform A* search on abstract graph
+   * @zh 导出为字符串
+   * @en Export to string
    */
-  abstractSearch(startNode, endNode, opts) {
-    const openList = new IndexedBinaryHeap((a, b) => a.f - b.f);
-    const nodeMap = /* @__PURE__ */ new Map();
-    const endPosition = endNode.position;
-    const h = this.heuristic(startNode.position, endPosition) * opts.heuristicWeight;
-    const startSearchNode = {
-      node: startNode,
-      g: 0,
-      h,
-      f: h,
-      parent: null,
-      closed: false,
-      opened: true,
-      heapIndex: -1
-    };
-    openList.push(startSearchNode);
-    nodeMap.set(startNode.id, startSearchNode);
-    let nodesSearched = 0;
-    while (!openList.isEmpty && nodesSearched < opts.maxNodes) {
-      const current = openList.pop();
-      current.closed = true;
-      nodesSearched++;
-      if (current.node.id === endNode.id) {
-        return this.reconstructPath(current);
-      }
-      for (const edge of current.node.edges) {
-        let neighbor = nodeMap.get(edge.targetNodeId);
-        if (!neighbor) {
-          const neighborNode = this.abstractNodes.get(edge.targetNodeId);
-          if (!neighborNode) continue;
-          const nh = this.heuristic(neighborNode.position, endPosition) * opts.heuristicWeight;
-          neighbor = {
-            node: neighborNode,
-            g: Infinity,
-            h: nh,
-            f: Infinity,
-            parent: null,
-            closed: false,
-            opened: false,
-            heapIndex: -1
-          };
-          nodeMap.set(edge.targetNodeId, neighbor);
-        }
-        if (neighbor.closed) continue;
-        const tentativeG = current.g + edge.cost;
-        if (!neighbor.opened) {
-          neighbor.g = tentativeG;
-          neighbor.f = tentativeG + neighbor.h;
-          neighbor.parent = current;
-          neighbor.opened = true;
-          openList.push(neighbor);
-        } else if (tentativeG < neighbor.g) {
-          neighbor.g = tentativeG;
-          neighbor.f = tentativeG + neighbor.h;
-          neighbor.parent = current;
-          openList.update(neighbor);
-        }
+  toString() {
+    let result = "";
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        result += this.nodes[y][x].walkable ? "." : "#";
       }
+      result += "\n";
     }
-    return null;
-  }
-  /**
-   * @zh 重建抽象路径
-   * @en Reconstruct abstract path
-   */
-  reconstructPath(endNode) {
-    const path = [];
-    let current = endNode;
-    while (current) {
-      path.unshift(current.node);
-      current = current.parent;
-    }
-    return path;
+    return result;
   }
   /**
-   * @zh 细化抽象路径为具体路径
-   * @en Refine abstract path to concrete path
+   * @zh 重置所有节点为可通行
+   * @en Reset all nodes to walkable
    */
-  refinePath(abstractPath, startX, startY, endX, endY, opts) {
-    if (abstractPath.length === 0) {
-      return EMPTY_PATH_RESULT;
-    }
-    const fullPath = [];
-    let totalCost = 0;
-    let nodesSearched = abstractPath.length;
-    for (let i = 0; i < abstractPath.length - 1; i++) {
-      const fromNode = abstractPath[i];
-      const toNode = abstractPath[i + 1];
-      const edge = fromNode.edges.find((e) => e.targetNodeId === toNode.id);
-      if (!edge) {
-        const segResult = this.findLocalPath(fromNode.position.x, fromNode.position.y, toNode.position.x, toNode.position.y, opts);
-        if (segResult.found) {
-          this.appendPath(fullPath, segResult.path);
-          totalCost += segResult.cost;
-          nodesSearched += segResult.nodesSearched;
-        }
-      } else if (edge.isInterEdge) {
-        if (fullPath.length === 0 || fullPath[fullPath.length - 1].x !== fromNode.position.x || fullPath[fullPath.length - 1].y !== fromNode.position.y) {
-          fullPath.push({
-            x: fromNode.position.x,
-            y: fromNode.position.y
-          });
-        }
-        fullPath.push({
-          x: toNode.position.x,
-          y: toNode.position.y
-        });
-        totalCost += edge.cost;
-      } else if (edge.innerPath && edge.innerPath.length > 0) {
-        const concretePath = edge.innerPath.map((id) => ({
-          x: id % this.mapWidth,
-          y: Math.floor(id / this.mapWidth)
-        }));
-        this.appendPath(fullPath, concretePath);
-        totalCost += edge.cost;
-      } else {
-        const computed = this.computeIntraEdgePath(fromNode, toNode, edge);
-        if (computed && computed.path.length > 0) {
-          const concretePath = computed.path.map((id) => ({
-            x: id % this.mapWidth,
-            y: Math.floor(id / this.mapWidth)
-          }));
-          this.appendPath(fullPath, concretePath);
-          totalCost += computed.cost;
-        } else {
-          const segResult = this.findLocalPath(fromNode.position.x, fromNode.position.y, toNode.position.x, toNode.position.y, opts);
-          if (segResult.found) {
-            this.appendPath(fullPath, segResult.path);
-            totalCost += segResult.cost;
-            nodesSearched += segResult.nodesSearched;
-          }
-        }
-      }
-    }
-    if (fullPath.length > 0 && (fullPath[0].x !== startX || fullPath[0].y !== startY)) {
-      const firstPoint = fullPath[0];
-      if (Math.abs(firstPoint.x - startX) <= 1 && Math.abs(firstPoint.y - startY) <= 1) {
-        fullPath.unshift({
-          x: startX,
-          y: startY
-        });
-      } else {
-        const segResult = this.findLocalPath(startX, startY, firstPoint.x, firstPoint.y, opts);
-        if (segResult.found) {
-          fullPath.splice(0, 0, ...segResult.path.slice(0, -1));
-          totalCost += segResult.cost;
-        }
-      }
-    }
-    if (fullPath.length > 0) {
-      const lastPoint = fullPath[fullPath.length - 1];
-      if (lastPoint.x !== endX || lastPoint.y !== endY) {
-        if (Math.abs(lastPoint.x - endX) <= 1 && Math.abs(lastPoint.y - endY) <= 1) {
-          fullPath.push({
-            x: endX,
-            y: endY
-          });
-        } else {
-          const segResult = this.findLocalPath(lastPoint.x, lastPoint.y, endX, endY, opts);
-          if (segResult.found) {
-            fullPath.push(...segResult.path.slice(1));
-            totalCost += segResult.cost;
-          }
-        }
+  reset() {
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        this.nodes[y][x].walkable = true;
+        this.nodes[y][x].cost = 1;
       }
     }
-    return {
-      found: fullPath.length > 0,
-      path: fullPath,
-      cost: totalCost,
-      nodesSearched
-    };
   }
   /**
-   * @zh 追加路径（避免重复点）
-   * @en Append path (avoid duplicate points)
+   * @zh 设置矩形区域的通行性
+   * @en Set walkability for a rectangle region
    */
-  appendPath(fullPath, segment) {
-    if (segment.length === 0) return;
-    let startIdx = 0;
-    if (fullPath.length > 0) {
-      const last = fullPath[fullPath.length - 1];
-      if (last.x === segment[0].x && last.y === segment[0].y) {
-        startIdx = 1;
+  setRectWalkable(x, y, width, height, walkable) {
+    for (let dy = 0; dy < height; dy++) {
+      for (let dx = 0; dx < width; dx++) {
+        this.setWalkable(x + dx, y + dy, walkable);
       }
     }
-    for (let i = startIdx; i < segment.length; i++) {
-      fullPath.push({
-        x: segment[i].x,
-        y: segment[i].y
-      });
-    }
-  }
-  /**
-   * @zh 局部寻路
-   * @en Local pathfinding
-   */
-  findLocalPath(startX, startY, endX, endY, opts) {
-    return this.localPathfinder.findPath(startX, startY, endX, endY, opts);
-  }
-  /**
-   * @zh 启发式函数（Octile 距离）
-   * @en Heuristic function (Octile distance)
-   */
-  heuristic(a, b) {
-    const dx = Math.abs(a.x - b.x);
-    const dy = Math.abs(a.y - b.y);
-    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
   }
 };
-__name(_HPAPathfinder, "HPAPathfinder");
-var HPAPathfinder = _HPAPathfinder;
-function createHPAPathfinder(map, config) {
-  return new HPAPathfinder(map, config);
+__name(_GridMap, "GridMap");
+var GridMap = _GridMap;
+function createGridMap(width, height, options) {
+  return new GridMap(width, height, options);
 }
-__name(createHPAPathfinder, "createHPAPathfinder");
+__name(createGridMap, "createGridMap");
 
 // src/navmesh/NavMesh.ts
-var _a5;
-var NavMeshNode = (_a5 = class {
+var _a3;
+var NavMeshNode = (_a3 = class {
   constructor(polygon) {
     __publicField(this, "id");
     __publicField(this, "position");
@@ -2528,12 +1242,17 @@ var NavMeshNode = (_a5 = class {
     this.walkable = true;
     this.polygon = polygon;
   }
-}, __name(_a5, "NavMeshNode"), _a5);
+}, __name(_a3, "NavMeshNode"), _a3);
 var _NavMesh = class _NavMesh {
   constructor() {
     __publicField(this, "polygons", /* @__PURE__ */ new Map());
     __publicField(this, "nodes", /* @__PURE__ */ new Map());
     __publicField(this, "nextId", 0);
+    // @zh 动态障碍物支持
+    // @en Dynamic obstacle support
+    __publicField(this, "obstacles", /* @__PURE__ */ new Map());
+    __publicField(this, "nextObstacleId", 0);
+    __publicField(this, "disabledPolygons", /* @__PURE__ */ new Set());
   }
   /**
    * @zh 添加导航多边形
@@ -2741,7 +1460,7 @@ var _NavMesh = class _NavMesh {
     }
     const start = createPoint(startX, startY);
     const end = createPoint(endX, endY);
-    const pointPath = this.funnelPath(start, end, polygonPath.polygons);
+    const pointPath = this.funnelPath(start, end, polygonPath.polygons, opts.agentRadius);
     return {
       found: true,
       path: pointPath,
@@ -2752,8 +1471,13 @@ var _NavMesh = class _NavMesh {
   /**
    * @zh 在多边形图上寻路
    * @en Find path on polygon graph
+   *
+   * @param start - @zh 起始多边形 @en Start polygon
+   * @param end - @zh 目标多边形 @en End polygon
+   * @param opts - @zh 寻路选项 @en Pathfinding options
+   * @param checkObstacles - @zh 是否检查障碍物 @en Whether to check obstacles
    */
-  findPolygonPath(start, end, opts) {
+  findPolygonPath(start, end, opts, checkObstacles = false) {
     const openList = new BinaryHeap((a, b) => a.f - b.f);
     const closed = /* @__PURE__ */ new Set();
     const states = /* @__PURE__ */ new Map();
@@ -2787,6 +1511,9 @@ var _NavMesh = class _NavMesh {
         if (closed.has(neighborId)) {
           continue;
         }
+        if (checkObstacles && this.isPolygonBlocked(neighborId)) {
+          continue;
+        }
         const neighborPolygon = this.polygons.get(neighborId);
         if (!neighborPolygon) {
           continue;
@@ -2817,10 +1544,15 @@ var _NavMesh = class _NavMesh {
     };
   }
   /**
-   * @zh 使用漏斗算法优化路径
-   * @en Optimize path using funnel algorithm
+   * @zh 使用漏斗算法优化路径（支持代理半径）
+   * @en Optimize path using funnel algorithm (supports agent radius)
+   *
+   * @param start - @zh 起点 @en Start point
+   * @param end - @zh 终点 @en End point
+   * @param polygons - @zh 多边形路径 @en Polygon path
+   * @param agentRadius - @zh 代理半径 @en Agent radius
    */
-  funnelPath(start, end, polygons) {
+  funnelPath(start, end, polygons, agentRadius = 0) {
     if (polygons.length <= 1) {
       return [
         start,
@@ -2831,7 +1563,22 @@ var _NavMesh = class _NavMesh {
     for (let i = 0; i < polygons.length - 1; i++) {
       const portal = polygons[i].portals.get(polygons[i + 1].id);
       if (portal) {
-        portals.push(portal);
+        if (agentRadius > 0) {
+          const shrunk = this.shrinkPortal(portal.left, portal.right, agentRadius);
+          portals.push({
+            left: shrunk.left,
+            right: shrunk.right,
+            originalLeft: portal.left,
+            originalRight: portal.right
+          });
+        } else {
+          portals.push({
+            left: portal.left,
+            right: portal.right,
+            originalLeft: portal.left,
+            originalRight: portal.right
+          });
+        }
       }
     }
     if (portals.length === 0) {
@@ -2844,35 +1591,50 @@ var _NavMesh = class _NavMesh {
       start
     ];
     let apex = start;
+    let apexOriginal = start;
     let leftIndex = 0;
     let rightIndex = 0;
     let left = portals[0].left;
     let right = portals[0].right;
+    let leftOriginal = portals[0].originalLeft;
+    let rightOriginal = portals[0].originalRight;
     for (let i = 1; i <= portals.length; i++) {
       const nextLeft = i < portals.length ? portals[i].left : end;
       const nextRight = i < portals.length ? portals[i].right : end;
       if (this.triArea2(apex, right, nextRight) <= 0) {
-        if (apex === right || this.triArea2(apex, left, nextRight) > 0) {
+        if (this.pointsEqual(apex, right) || this.triArea2(apex, left, nextRight) > 0) {
           right = nextRight;
           rightIndex = i;
+          if (i < portals.length) {
+            rightOriginal = portals[i].originalRight;
+          }
         } else {
-          path.push(left);
+          const turnPoint = agentRadius > 0 ? this.offsetTurningPoint(apexOriginal, leftOriginal, left, agentRadius, "left") : left;
+          path.push(turnPoint);
           apex = left;
+          apexOriginal = leftOriginal;
           leftIndex = rightIndex = leftIndex;
           left = right = apex;
+          leftOriginal = rightOriginal = apexOriginal;
           i = leftIndex;
           continue;
         }
       }
       if (this.triArea2(apex, left, nextLeft) >= 0) {
-        if (apex === left || this.triArea2(apex, right, nextLeft) < 0) {
+        if (this.pointsEqual(apex, left) || this.triArea2(apex, right, nextLeft) < 0) {
           left = nextLeft;
           leftIndex = i;
+          if (i < portals.length) {
+            leftOriginal = portals[i].originalLeft;
+          }
         } else {
-          path.push(right);
+          const turnPoint = agentRadius > 0 ? this.offsetTurningPoint(apexOriginal, rightOriginal, right, agentRadius, "right") : right;
+          path.push(turnPoint);
           apex = right;
+          apexOriginal = rightOriginal;
           leftIndex = rightIndex = rightIndex;
           left = right = apex;
+          leftOriginal = rightOriginal = apexOriginal;
           i = rightIndex;
           continue;
         }
@@ -2881,6 +1643,63 @@ var _NavMesh = class _NavMesh {
     path.push(end);
     return path;
   }
+  /**
+   * @zh 收缩 portal（将两端点向内移动 agentRadius）
+   * @en Shrink portal (move endpoints inward by agentRadius)
+   */
+  shrinkPortal(left, right, radius) {
+    const dx = right.x - left.x;
+    const dy = right.y - left.y;
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len <= radius * 2) {
+      const cx = (left.x + right.x) / 2;
+      const cy = (left.y + right.y) / 2;
+      return {
+        left: createPoint(cx, cy),
+        right: createPoint(cx, cy)
+      };
+    }
+    const nx = dx / len;
+    const ny = dy / len;
+    return {
+      left: createPoint(left.x + nx * radius, left.y + ny * radius),
+      right: createPoint(right.x - nx * radius, right.y - ny * radius)
+    };
+  }
+  /**
+   * @zh 偏移拐点以保持与角落的距离
+   * @en Offset turning point to maintain distance from corner
+   *
+   * @param prevApex - @zh 上一个顶点 @en Previous apex
+   * @param cornerOriginal - @zh 原始角落位置 @en Original corner position
+   * @param cornerShrunk - @zh 收缩后的角落位置 @en Shrunk corner position
+   * @param radius - @zh 代理半径 @en Agent radius
+   * @param side - @zh 转向侧 ('left' 或 'right') @en Turn side ('left' or 'right')
+   */
+  offsetTurningPoint(prevApex, cornerOriginal, cornerShrunk, radius, side) {
+    const dx = cornerOriginal.x - prevApex.x;
+    const dy = cornerOriginal.y - prevApex.y;
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len < 1e-4) {
+      return cornerShrunk;
+    }
+    let perpX, perpY;
+    if (side === "left") {
+      perpX = dy / len;
+      perpY = -dx / len;
+    } else {
+      perpX = -dy / len;
+      perpY = dx / len;
+    }
+    return createPoint(cornerShrunk.x + perpX * radius, cornerShrunk.y + perpY * radius);
+  }
+  /**
+   * @zh 检查两点是否相等
+   * @en Check if two points are equal
+   */
+  pointsEqual(a, b) {
+    return Math.abs(a.x - b.x) < 1e-4 && Math.abs(a.y - b.y) < 1e-4;
+  }
   /**
    * @zh 计算三角形面积的两倍（用于判断点的相对位置）
    * @en Calculate twice the triangle area (for point relative position)
@@ -2899,6 +1718,416 @@ var _NavMesh = class _NavMesh {
     }
     return length;
   }
+  // =========================================================================
+  // 动态障碍物管理 | Dynamic Obstacle Management
+  // =========================================================================
+  /**
+   * @zh 添加圆形障碍物
+   * @en Add circular obstacle
+   *
+   * @param x - @zh 中心 X @en Center X
+   * @param y - @zh 中心 Y @en Center Y
+   * @param radius - @zh 半径 @en Radius
+   * @returns @zh 障碍物 ID @en Obstacle ID
+   */
+  addCircleObstacle(x, y, radius) {
+    const id = this.nextObstacleId++;
+    this.obstacles.set(id, {
+      id,
+      type: "circle",
+      enabled: true,
+      position: createPoint(x, y),
+      radius
+    });
+    return id;
+  }
+  /**
+   * @zh 添加矩形障碍物
+   * @en Add rectangular obstacle
+   *
+   * @param x - @zh 中心 X @en Center X
+   * @param y - @zh 中心 Y @en Center Y
+   * @param halfWidth - @zh 半宽 @en Half width
+   * @param halfHeight - @zh 半高 @en Half height
+   * @returns @zh 障碍物 ID @en Obstacle ID
+   */
+  addRectObstacle(x, y, halfWidth, halfHeight) {
+    const id = this.nextObstacleId++;
+    this.obstacles.set(id, {
+      id,
+      type: "rect",
+      enabled: true,
+      position: createPoint(x, y),
+      halfWidth,
+      halfHeight
+    });
+    return id;
+  }
+  /**
+   * @zh 添加多边形障碍物
+   * @en Add polygon obstacle
+   *
+   * @param vertices - @zh 顶点列表 @en Vertex list
+   * @returns @zh 障碍物 ID @en Obstacle ID
+   */
+  addPolygonObstacle(vertices) {
+    const id = this.nextObstacleId++;
+    const center = this.calculateCenter(vertices);
+    this.obstacles.set(id, {
+      id,
+      type: "polygon",
+      enabled: true,
+      position: center,
+      vertices
+    });
+    return id;
+  }
+  /**
+   * @zh 移除障碍物
+   * @en Remove obstacle
+   */
+  removeObstacle(obstacleId) {
+    return this.obstacles.delete(obstacleId);
+  }
+  /**
+   * @zh 启用/禁用障碍物
+   * @en Enable/disable obstacle
+   */
+  setObstacleEnabled(obstacleId, enabled) {
+    const obstacle = this.obstacles.get(obstacleId);
+    if (obstacle) {
+      obstacle.enabled = enabled;
+    }
+  }
+  /**
+   * @zh 更新障碍物位置
+   * @en Update obstacle position
+   */
+  updateObstaclePosition(obstacleId, x, y) {
+    const obstacle = this.obstacles.get(obstacleId);
+    if (obstacle) {
+      obstacle.position = createPoint(x, y);
+    }
+  }
+  /**
+   * @zh 获取所有障碍物
+   * @en Get all obstacles
+   */
+  getObstacles() {
+    return Array.from(this.obstacles.values());
+  }
+  /**
+   * @zh 获取启用的障碍物
+   * @en Get enabled obstacles
+   */
+  getEnabledObstacles() {
+    return Array.from(this.obstacles.values()).filter((o) => o.enabled);
+  }
+  /**
+   * @zh 清除所有障碍物
+   * @en Clear all obstacles
+   */
+  clearObstacles() {
+    this.obstacles.clear();
+    this.nextObstacleId = 0;
+  }
+  // =========================================================================
+  // 多边形禁用管理 | Polygon Disable Management
+  // =========================================================================
+  /**
+   * @zh 禁用多边形
+   * @en Disable polygon
+   */
+  disablePolygon(polygonId) {
+    this.disabledPolygons.add(polygonId);
+  }
+  /**
+   * @zh 启用多边形
+   * @en Enable polygon
+   */
+  enablePolygon(polygonId) {
+    this.disabledPolygons.delete(polygonId);
+  }
+  /**
+   * @zh 检查多边形是否被禁用
+   * @en Check if polygon is disabled
+   */
+  isPolygonDisabled(polygonId) {
+    return this.disabledPolygons.has(polygonId);
+  }
+  /**
+   * @zh 禁用包含指定点的多边形
+   * @en Disable polygon containing specified point
+   */
+  disablePolygonAt(x, y) {
+    const polygon = this.findPolygonAt(x, y);
+    if (polygon) {
+      this.disablePolygon(polygon.id);
+      return polygon.id;
+    }
+    return null;
+  }
+  /**
+   * @zh 清除所有禁用的多边形
+   * @en Clear all disabled polygons
+   */
+  clearDisabledPolygons() {
+    this.disabledPolygons.clear();
+  }
+  /**
+   * @zh 获取被禁用的多边形 ID 列表
+   * @en Get list of disabled polygon IDs
+   */
+  getDisabledPolygons() {
+    return Array.from(this.disabledPolygons);
+  }
+  // =========================================================================
+  // 障碍物碰撞检测 | Obstacle Collision Detection
+  // =========================================================================
+  /**
+   * @zh 检查点是否在任何障碍物内
+   * @en Check if point is inside any obstacle
+   */
+  isPointInObstacle(x, y) {
+    for (const obstacle of this.obstacles.values()) {
+      if (!obstacle.enabled) continue;
+      if (this.isPointInSingleObstacle(x, y, obstacle)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * @zh 检查点是否在单个障碍物内
+   * @en Check if point is inside single obstacle
+   */
+  isPointInSingleObstacle(x, y, obstacle) {
+    switch (obstacle.type) {
+      case "circle": {
+        const dx = x - obstacle.position.x;
+        const dy = y - obstacle.position.y;
+        return dx * dx + dy * dy <= (obstacle.radius ?? 0) ** 2;
+      }
+      case "rect": {
+        const hw = obstacle.halfWidth ?? 0;
+        const hh = obstacle.halfHeight ?? 0;
+        return Math.abs(x - obstacle.position.x) <= hw && Math.abs(y - obstacle.position.y) <= hh;
+      }
+      case "polygon": {
+        if (!obstacle.vertices) return false;
+        return this.isPointInPolygon(x, y, obstacle.vertices);
+      }
+      default:
+        return false;
+    }
+  }
+  /**
+   * @zh 检查线段是否与任何障碍物相交
+   * @en Check if line segment intersects any obstacle
+   */
+  doesLineIntersectObstacle(x1, y1, x2, y2) {
+    for (const obstacle of this.obstacles.values()) {
+      if (!obstacle.enabled) continue;
+      if (this.doesLineIntersectSingleObstacle(x1, y1, x2, y2, obstacle)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * @zh 检查线段是否与单个障碍物相交
+   * @en Check if line segment intersects single obstacle
+   */
+  doesLineIntersectSingleObstacle(x1, y1, x2, y2, obstacle) {
+    switch (obstacle.type) {
+      case "circle": {
+        return this.lineIntersectsCircle(x1, y1, x2, y2, obstacle.position.x, obstacle.position.y, obstacle.radius ?? 0);
+      }
+      case "rect": {
+        const hw = obstacle.halfWidth ?? 0;
+        const hh = obstacle.halfHeight ?? 0;
+        const minX = obstacle.position.x - hw;
+        const maxX = obstacle.position.x + hw;
+        const minY = obstacle.position.y - hh;
+        const maxY = obstacle.position.y + hh;
+        return this.lineIntersectsRect(x1, y1, x2, y2, minX, minY, maxX, maxY);
+      }
+      case "polygon": {
+        if (!obstacle.vertices) return false;
+        return this.lineIntersectsPolygon(x1, y1, x2, y2, obstacle.vertices);
+      }
+      default:
+        return false;
+    }
+  }
+  /**
+   * @zh 线段与圆相交检测
+   * @en Line segment circle intersection
+   */
+  lineIntersectsCircle(x1, y1, x2, y2, cx, cy, r) {
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const fx = x1 - cx;
+    const fy = y1 - cy;
+    const a = dx * dx + dy * dy;
+    const b = 2 * (fx * dx + fy * dy);
+    const c = fx * fx + fy * fy - r * r;
+    let discriminant = b * b - 4 * a * c;
+    if (discriminant < 0) return false;
+    discriminant = Math.sqrt(discriminant);
+    const t1 = (-b - discriminant) / (2 * a);
+    const t2 = (-b + discriminant) / (2 * a);
+    return t1 >= 0 && t1 <= 1 || t2 >= 0 && t2 <= 1 || t1 < 0 && t2 > 1;
+  }
+  /**
+   * @zh 线段与矩形相交检测
+   * @en Line segment rectangle intersection
+   */
+  lineIntersectsRect(x1, y1, x2, y2, minX, minY, maxX, maxY) {
+    if (x1 >= minX && x1 <= maxX && y1 >= minY && y1 <= maxY || x2 >= minX && x2 <= maxX && y2 >= minY && y2 <= maxY) {
+      return true;
+    }
+    return this.lineSegmentsIntersect(x1, y1, x2, y2, minX, minY, maxX, minY) || this.lineSegmentsIntersect(x1, y1, x2, y2, maxX, minY, maxX, maxY) || this.lineSegmentsIntersect(x1, y1, x2, y2, maxX, maxY, minX, maxY) || this.lineSegmentsIntersect(x1, y1, x2, y2, minX, maxY, minX, minY);
+  }
+  /**
+   * @zh 线段与多边形相交检测
+   * @en Line segment polygon intersection
+   */
+  lineIntersectsPolygon(x1, y1, x2, y2, vertices) {
+    if (this.isPointInPolygon(x1, y1, vertices) || this.isPointInPolygon(x2, y2, vertices)) {
+      return true;
+    }
+    for (let i = 0; i < vertices.length; i++) {
+      const j = (i + 1) % vertices.length;
+      if (this.lineSegmentsIntersect(x1, y1, x2, y2, vertices[i].x, vertices[i].y, vertices[j].x, vertices[j].y)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * @zh 两线段相交检测
+   * @en Two line segments intersection
+   */
+  lineSegmentsIntersect(x1, y1, x2, y2, x3, y3, x4, y4) {
+    const d1 = this.direction(x3, y3, x4, y4, x1, y1);
+    const d2 = this.direction(x3, y3, x4, y4, x2, y2);
+    const d3 = this.direction(x1, y1, x2, y2, x3, y3);
+    const d4 = this.direction(x1, y1, x2, y2, x4, y4);
+    if ((d1 > 0 && d2 < 0 || d1 < 0 && d2 > 0) && (d3 > 0 && d4 < 0 || d3 < 0 && d4 > 0)) {
+      return true;
+    }
+    const epsilon = 1e-4;
+    if (Math.abs(d1) < epsilon && this.onSegment(x3, y3, x4, y4, x1, y1)) return true;
+    if (Math.abs(d2) < epsilon && this.onSegment(x3, y3, x4, y4, x2, y2)) return true;
+    if (Math.abs(d3) < epsilon && this.onSegment(x1, y1, x2, y2, x3, y3)) return true;
+    if (Math.abs(d4) < epsilon && this.onSegment(x1, y1, x2, y2, x4, y4)) return true;
+    return false;
+  }
+  direction(x1, y1, x2, y2, x3, y3) {
+    return (x3 - x1) * (y2 - y1) - (y3 - y1) * (x2 - x1);
+  }
+  onSegment(x1, y1, x2, y2, x3, y3) {
+    return Math.min(x1, x2) <= x3 && x3 <= Math.max(x1, x2) && Math.min(y1, y2) <= y3 && y3 <= Math.max(y1, y2);
+  }
+  // =========================================================================
+  // 障碍物感知寻路 | Obstacle-Aware Pathfinding
+  // =========================================================================
+  /**
+   * @zh 检查多边形是否被障碍物阻挡
+   * @en Check if polygon is blocked by obstacle
+   *
+   * @zh 检查以下条件：
+   * @en Checks the following conditions:
+   * - @zh 多边形是否被禁用 @en Whether polygon is disabled
+   * - @zh 多边形中心是否在障碍物内 @en Whether polygon center is inside obstacle
+   * - @zh 多边形任意顶点是否在障碍物内 @en Whether any polygon vertex is inside obstacle
+   * - @zh 多边形任意边是否与障碍物相交 @en Whether any polygon edge intersects obstacle
+   */
+  isPolygonBlocked(polygonId) {
+    if (this.disabledPolygons.has(polygonId)) {
+      return true;
+    }
+    const polygon = this.polygons.get(polygonId);
+    if (!polygon) return false;
+    if (this.isPointInObstacle(polygon.center.x, polygon.center.y)) {
+      return true;
+    }
+    for (const vertex of polygon.vertices) {
+      if (this.isPointInObstacle(vertex.x, vertex.y)) {
+        return true;
+      }
+    }
+    const vertices = polygon.vertices;
+    for (let i = 0; i < vertices.length; i++) {
+      const v1 = vertices[i];
+      const v2 = vertices[(i + 1) % vertices.length];
+      if (this.doesLineIntersectObstacle(v1.x, v1.y, v2.x, v2.y)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * @zh 在导航网格上寻路（考虑障碍物）
+   * @en Find path on navigation mesh (considering obstacles)
+   *
+   * @zh 此方法在规划阶段就考虑障碍物，自动绕过被阻挡的多边形
+   * @en This method considers obstacles during planning, automatically avoiding blocked polygons
+   *
+   * @zh 与 findPath 不同，此方法会：
+   * @en Unlike findPath, this method will:
+   * - @zh 在 A* 搜索中跳过被障碍物阻挡的多边形
+   * - @en Skip obstacle-blocked polygons during A* search
+   * - @zh 验证起点和终点不在障碍物内
+   * - @en Verify start and end points are not inside obstacles
+   */
+  findPathWithObstacles(startX, startY, endX, endY, options) {
+    const opts = {
+      ...DEFAULT_PATHFINDING_OPTIONS,
+      ...options
+    };
+    if (this.isPointInObstacle(startX, startY) || this.isPointInObstacle(endX, endY)) {
+      return EMPTY_PATH_RESULT;
+    }
+    const startPolygon = this.findPolygonAt(startX, startY);
+    const endPolygon = this.findPolygonAt(endX, endY);
+    if (!startPolygon || !endPolygon) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (this.isPolygonBlocked(startPolygon.id) || this.isPolygonBlocked(endPolygon.id)) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (startPolygon.id === endPolygon.id) {
+      const start2 = createPoint(startX, startY);
+      const end2 = createPoint(endX, endY);
+      if (this.doesLineIntersectObstacle(startX, startY, endX, endY)) {
+        return EMPTY_PATH_RESULT;
+      }
+      return {
+        found: true,
+        path: [
+          start2,
+          end2
+        ],
+        cost: euclideanDistance(start2, end2),
+        nodesSearched: 1
+      };
+    }
+    const polygonPath = this.findPolygonPath(startPolygon, endPolygon, opts, true);
+    if (!polygonPath.found) {
+      return EMPTY_PATH_RESULT;
+    }
+    const start = createPoint(startX, startY);
+    const end = createPoint(endX, endY);
+    const pointPath = this.funnelPath(start, end, polygonPath.polygons, opts.agentRadius);
+    return {
+      found: true,
+      path: pointPath,
+      cost: this.calculatePathLength(pointPath),
+      nodesSearched: polygonPath.nodesSearched
+    };
+  }
   /**
    * @zh 清空导航网格
    * @en Clear navigation mesh
@@ -2906,7 +2135,10 @@ var _NavMesh = class _NavMesh {
   clear() {
     this.polygons.clear();
     this.nodes.clear();
+    this.obstacles.clear();
+    this.disabledPolygons.clear();
     this.nextId = 0;
+    this.nextObstacleId = 0;
   }
   /**
    * @zh 获取所有多边形
@@ -2922,6 +2154,13 @@ var _NavMesh = class _NavMesh {
   get polygonCount() {
     return this.polygons.size;
   }
+  /**
+   * @zh 获取障碍物数量
+   * @en Get obstacle count
+   */
+  get obstacleCount() {
+    return this.obstacles.size;
+  }
 };
 __name(_NavMesh, "NavMesh");
 var NavMesh = _NavMesh;
@@ -2929,56 +2168,431 @@ function createNavMesh() {
   return new NavMesh();
 }
 __name(createNavMesh, "createNavMesh");
+
+// src/smoothing/PathSmoother.ts
+function bresenhamLineOfSight(x1, y1, x2, y2, map) {
+  let ix1 = Math.floor(x1);
+  let iy1 = Math.floor(y1);
+  const ix2 = Math.floor(x2);
+  const iy2 = Math.floor(y2);
+  const dx = Math.abs(ix2 - ix1);
+  const dy = Math.abs(iy2 - iy1);
+  const sx = ix1 < ix2 ? 1 : -1;
+  const sy = iy1 < iy2 ? 1 : -1;
+  let err = dx - dy;
+  while (true) {
+    if (!map.isWalkable(ix1, iy1)) {
+      return false;
+    }
+    if (ix1 === ix2 && iy1 === iy2) {
+      break;
+    }
+    const e2 = 2 * err;
+    if (e2 > -dy) {
+      err -= dy;
+      ix1 += sx;
+    }
+    if (e2 < dx) {
+      err += dx;
+      iy1 += sy;
+    }
+  }
+  return true;
+}
+__name(bresenhamLineOfSight, "bresenhamLineOfSight");
+function raycastLineOfSight(x1, y1, x2, y2, map, stepSize = 0.5) {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  if (distance === 0) {
+    return map.isWalkable(Math.floor(x1), Math.floor(y1));
+  }
+  const steps = Math.ceil(distance / stepSize);
+  const stepX = dx / steps;
+  const stepY = dy / steps;
+  let x = x1;
+  let y = y1;
+  for (let i = 0; i <= steps; i++) {
+    if (!map.isWalkable(Math.floor(x), Math.floor(y))) {
+      return false;
+    }
+    x += stepX;
+    y += stepY;
+  }
+  return true;
+}
+__name(raycastLineOfSight, "raycastLineOfSight");
+var _LineOfSightSmoother = class _LineOfSightSmoother {
+  constructor(lineOfSight = bresenhamLineOfSight) {
+    __publicField(this, "lineOfSight");
+    this.lineOfSight = lineOfSight;
+  }
+  smooth(path, map) {
+    if (path.length <= 2) {
+      return [
+        ...path
+      ];
+    }
+    const result = [
+      path[0]
+    ];
+    let current = 0;
+    while (current < path.length - 1) {
+      let furthest = current + 1;
+      for (let i = path.length - 1; i > current + 1; i--) {
+        if (this.lineOfSight(path[current].x, path[current].y, path[i].x, path[i].y, map)) {
+          furthest = i;
+          break;
+        }
+      }
+      result.push(path[furthest]);
+      current = furthest;
+    }
+    return result;
+  }
+};
+__name(_LineOfSightSmoother, "LineOfSightSmoother");
+var LineOfSightSmoother = _LineOfSightSmoother;
+var _CatmullRomSmoother = class _CatmullRomSmoother {
+  /**
+   * @param segments - @zh 每段之间的插值点数 @en Number of interpolation points per segment
+   * @param tension - @zh 张力 (0-1) @en Tension (0-1)
+   */
+  constructor(segments = 5, tension = 0.5) {
+    __publicField(this, "segments");
+    __publicField(this, "tension");
+    this.segments = segments;
+    this.tension = tension;
+  }
+  smooth(path, _map) {
+    if (path.length <= 2) {
+      return [
+        ...path
+      ];
+    }
+    const result = [];
+    const points = [
+      path[0],
+      ...path,
+      path[path.length - 1]
+    ];
+    for (let i = 1; i < points.length - 2; i++) {
+      const p0 = points[i - 1];
+      const p1 = points[i];
+      const p2 = points[i + 1];
+      const p3 = points[i + 2];
+      for (let j = 0; j < this.segments; j++) {
+        const t = j / this.segments;
+        const point = this.interpolate(p0, p1, p2, p3, t);
+        result.push(point);
+      }
+    }
+    result.push(path[path.length - 1]);
+    return result;
+  }
+  /**
+   * @zh Catmull-Rom 插值
+   * @en Catmull-Rom interpolation
+   */
+  interpolate(p0, p1, p2, p3, t) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const tension = this.tension;
+    const x = 0.5 * (2 * p1.x + (-p0.x + p2.x) * t * tension + (2 * p0.x - 5 * p1.x + 4 * p2.x - p3.x) * t2 * tension + (-p0.x + 3 * p1.x - 3 * p2.x + p3.x) * t3 * tension);
+    const y = 0.5 * (2 * p1.y + (-p0.y + p2.y) * t * tension + (2 * p0.y - 5 * p1.y + 4 * p2.y - p3.y) * t2 * tension + (-p0.y + 3 * p1.y - 3 * p2.y + p3.y) * t3 * tension);
+    return createPoint(x, y);
+  }
+};
+__name(_CatmullRomSmoother, "CatmullRomSmoother");
+var CatmullRomSmoother = _CatmullRomSmoother;
+var _CombinedSmoother = class _CombinedSmoother {
+  constructor(curveSegments = 5, tension = 0.5) {
+    __publicField(this, "simplifier");
+    __publicField(this, "curveSmoother");
+    this.simplifier = new LineOfSightSmoother();
+    this.curveSmoother = new CatmullRomSmoother(curveSegments, tension);
+  }
+  smooth(path, map) {
+    const simplified = this.simplifier.smooth(path, map);
+    return this.curveSmoother.smooth(simplified, map);
+  }
+};
+__name(_CombinedSmoother, "CombinedSmoother");
+var CombinedSmoother = _CombinedSmoother;
+function createLineOfSightSmoother(lineOfSight) {
+  return new LineOfSightSmoother(lineOfSight);
+}
+__name(createLineOfSightSmoother, "createLineOfSightSmoother");
+function createCatmullRomSmoother(segments, tension) {
+  return new CatmullRomSmoother(segments, tension);
+}
+__name(createCatmullRomSmoother, "createCatmullRomSmoother");
+function createCombinedSmoother(curveSegments, tension) {
+  return new CombinedSmoother(curveSegments, tension);
+}
+__name(createCombinedSmoother, "createCombinedSmoother");
+
+// src/smoothing/RadiusAwarePathSmoother.ts
+var DEFAULT_CONFIG = {
+  safetyMargin: 0.1,
+  sampleDirections: 8,
+  maxOffsetAttempts: 8,
+  processCorners: true
+};
+var _RadiusAwarePathSmoother = class _RadiusAwarePathSmoother {
+  constructor(config) {
+    __publicField(this, "config");
+    __publicField(this, "sampleAngles");
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config
+    };
+    this.sampleAngles = [];
+    const step = Math.PI * 2 / this.config.sampleDirections;
+    for (let i = 0; i < this.config.sampleDirections; i++) {
+      this.sampleAngles.push(i * step);
+    }
+  }
+  /**
+   * @zh 平滑路径，确保与障碍物保持安全距离
+   * @en Smooth path, ensuring safe distance from obstacles
+   *
+   * @param path - @zh 原始路径 @en Original path
+   * @param map - @zh 地图 @en Map
+   * @returns @zh 处理后的安全路径 @en Processed safe path
+   */
+  smooth(path, map) {
+    if (path.length <= 1) {
+      return [
+        ...path
+      ];
+    }
+    const result = [];
+    const clearance = this.config.agentRadius + this.config.safetyMargin;
+    for (let i = 0; i < path.length; i++) {
+      const point = path[i];
+      const isCorner = this.config.processCorners && i > 0 && i < path.length - 1;
+      let safePoint;
+      if (isCorner) {
+        const prev = path[i - 1];
+        const next = path[i + 1];
+        safePoint = this.offsetCornerPoint(point, prev, next, clearance, map);
+      } else {
+        safePoint = this.offsetPointFromObstacles(point, clearance, map);
+      }
+      result.push(safePoint);
+    }
+    return result;
+  }
+  /**
+   * @zh 将点从障碍物偏移
+   * @en Offset point away from obstacles
+   */
+  offsetPointFromObstacles(point, clearance, map) {
+    const obstacleDirections = this.detectNearbyObstacles(point, clearance, map);
+    if (obstacleDirections.length === 0) {
+      return point;
+    }
+    let avgDirX = 0;
+    let avgDirY = 0;
+    for (const dir of obstacleDirections) {
+      avgDirX += dir.x;
+      avgDirY += dir.y;
+    }
+    const len = Math.sqrt(avgDirX * avgDirX + avgDirY * avgDirY);
+    if (len < 1e-4) {
+      return point;
+    }
+    const offsetDirX = -avgDirX / len;
+    const offsetDirY = -avgDirY / len;
+    for (let attempt = 1; attempt <= this.config.maxOffsetAttempts; attempt++) {
+      const offsetDist = clearance * attempt / this.config.maxOffsetAttempts;
+      const newX = point.x + offsetDirX * offsetDist;
+      const newY = point.y + offsetDirY * offsetDist;
+      if (map.isWalkable(Math.floor(newX), Math.floor(newY))) {
+        const newObstacles = this.detectNearbyObstacles(createPoint(newX, newY), clearance, map);
+        if (newObstacles.length === 0) {
+          return createPoint(newX, newY);
+        }
+      }
+    }
+    return point;
+  }
+  /**
+   * @zh 偏移拐点（角落）
+   * @en Offset corner point
+   */
+  offsetCornerPoint(corner, prev, next, clearance, map) {
+    const inDirX = corner.x - prev.x;
+    const inDirY = corner.y - prev.y;
+    const inLen = Math.sqrt(inDirX * inDirX + inDirY * inDirY);
+    const outDirX = next.x - corner.x;
+    const outDirY = next.y - corner.y;
+    const outLen = Math.sqrt(outDirX * outDirX + outDirY * outDirY);
+    if (inLen < 1e-4 || outLen < 1e-4) {
+      return this.offsetPointFromObstacles(corner, clearance, map);
+    }
+    const inNormX = inDirX / inLen;
+    const inNormY = inDirY / inLen;
+    const outNormX = outDirX / outLen;
+    const outNormY = outDirY / outLen;
+    const bisectX = inNormX - outNormX;
+    const bisectY = inNormY - outNormY;
+    const bisectLen = Math.sqrt(bisectX * bisectX + bisectY * bisectY);
+    if (bisectLen < 1e-4) {
+      return this.offsetPointFromObstacles(corner, clearance, map);
+    }
+    const bisectNormX = bisectX / bisectLen;
+    const bisectNormY = bisectY / bisectLen;
+    const dotProduct = inNormX * outNormX + inNormY * outNormY;
+    const angle = Math.acos(Math.max(-1, Math.min(1, dotProduct)));
+    const halfAngle = angle / 2;
+    const sinHalfAngle = Math.sin(halfAngle);
+    if (sinHalfAngle < 0.1) {
+      return this.offsetPointFromObstacles(corner, clearance, map);
+    }
+    const offsetDist = clearance / sinHalfAngle;
+    const maxOffset = clearance * 3;
+    const actualOffset = Math.min(offsetDist, maxOffset);
+    const newX = corner.x + bisectNormX * actualOffset;
+    const newY = corner.y + bisectNormY * actualOffset;
+    if (map.isWalkable(Math.floor(newX), Math.floor(newY))) {
+      return createPoint(newX, newY);
+    }
+    const altX = corner.x - bisectNormX * actualOffset;
+    const altY = corner.y - bisectNormY * actualOffset;
+    if (map.isWalkable(Math.floor(altX), Math.floor(altY))) {
+      return createPoint(altX, altY);
+    }
+    return this.offsetPointFromObstacles(corner, clearance, map);
+  }
+  /**
+   * @zh 检测附近的障碍物方向
+   * @en Detect nearby obstacle directions
+   */
+  detectNearbyObstacles(point, clearance, map) {
+    const obstacles = [];
+    for (const angle of this.sampleAngles) {
+      const dirX = Math.cos(angle);
+      const dirY = Math.sin(angle);
+      const sampleX = point.x + dirX * clearance;
+      const sampleY = point.y + dirY * clearance;
+      if (!map.isWalkable(Math.floor(sampleX), Math.floor(sampleY))) {
+        obstacles.push(createPoint(dirX, dirY));
+      }
+    }
+    return obstacles;
+  }
+};
+__name(_RadiusAwarePathSmoother, "RadiusAwarePathSmoother");
+var RadiusAwarePathSmoother = _RadiusAwarePathSmoother;
+var _CombinedRadiusAwareSmoother = class _CombinedRadiusAwareSmoother {
+  constructor(baseSmoother, config) {
+    __publicField(this, "baseSmoother");
+    __publicField(this, "radiusAwareSmoother");
+    this.baseSmoother = baseSmoother;
+    this.radiusAwareSmoother = new RadiusAwarePathSmoother(config);
+  }
+  smooth(path, map) {
+    const smoothed = this.baseSmoother.smooth(path, map);
+    return this.radiusAwareSmoother.smooth(smoothed, map);
+  }
+};
+__name(_CombinedRadiusAwareSmoother, "CombinedRadiusAwareSmoother");
+var CombinedRadiusAwareSmoother = _CombinedRadiusAwareSmoother;
+function createRadiusAwareSmoother(agentRadius, options) {
+  return new RadiusAwarePathSmoother({
+    agentRadius,
+    ...options
+  });
+}
+__name(createRadiusAwareSmoother, "createRadiusAwareSmoother");
+function createCombinedRadiusAwareSmoother(baseSmoother, agentRadius, options) {
+  return new CombinedRadiusAwareSmoother(baseSmoother, {
+    agentRadius,
+    ...options
+  });
+}
+__name(createCombinedRadiusAwareSmoother, "createCombinedRadiusAwareSmoother");
 export {
   AStarPathfinder,
   BinaryHeap,
   CatmullRomSmoother,
+  CollisionResolver,
+  CollisionResolverAdapter,
+  CombinedRadiusAwareSmoother,
   CombinedSmoother,
   DEFAULT_AGENT_PARAMS,
+  DEFAULT_COLLISION_CONFIG,
+  DEFAULT_FLOW_CONTROLLER_CONFIG,
   DEFAULT_GRID_OPTIONS,
   DEFAULT_HPA_CONFIG,
   DEFAULT_ORCA_CONFIG,
+  DEFAULT_ORCA_PARAMS,
   DEFAULT_PATHFINDING_OPTIONS,
   DEFAULT_PATH_CACHE_CONFIG,
   DEFAULT_REPLANNING_CONFIG,
   DIRECTIONS_4,
   DIRECTIONS_8,
+  EMPTY_COLLISION,
+  EMPTY_COLLISION_RESULT,
   EMPTY_PATH_RESULT,
+  EMPTY_PLAN_RESULT,
   EMPTY_PROGRESS,
+  FlowController,
   GridMap,
   GridNode,
   GridPathfinder,
+  GridPathfinderAdapter,
   HPAPathfinder,
   IncrementalAStarPathfinder,
+  IncrementalGridPathPlannerAdapter,
   IndexedBinaryHeap,
   JPSPathfinder,
   KDTree,
   LineOfSightSmoother,
   NavMesh,
+  NavMeshPathPlannerAdapter,
+  ORCALocalAvoidanceAdapter,
   ORCASolver,
   ObstacleChangeManager,
+  PassPermission,
   PathCache,
+  PathPlanState,
   PathValidator,
   PathfindingState,
+  RadiusAwarePathSmoother,
   bresenhamLineOfSight,
   chebyshevDistance,
   createAStarPathfinder,
+  createAStarPlanner,
   createCatmullRomSmoother,
+  createCollisionResolver,
+  createCombinedRadiusAwareSmoother,
   createCombinedSmoother,
+  createDefaultCollisionResolver,
+  createFlowController,
   createGridMap,
   createGridPathfinder,
   createHPAPathfinder,
+  createHPAPlanner,
   createIncrementalAStarPathfinder,
+  createIncrementalAStarPlanner,
   createJPSPathfinder,
+  createJPSPlanner,
   createKDTree,
   createLineOfSightSmoother,
   createNavMesh,
+  createNavMeshPathPlanner,
+  createORCAAvoidance,
   createORCASolver,
   createObstacleChangeManager,
   createPathCache,
   createPathValidator,
   createPoint,
+  createRadiusAwareSmoother,
   euclideanDistance,
+  isIncrementalPlanner,
   manhattanDistance,
   octileDistance,
   raycastLineOfSight,