@cc-component/cc-pathfinding 1.0.5 → 1.0.8

package/assets/pathfinding/Interface.ts

@@ -59,8 +59,13 @@ declare global {
         export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number }): void
         /** 设置单位位置 */
         export function SetPosition(playerNode: Node, position: { row: number, col: number }): void
-        /** 让单位移动到目标格子 */
-        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void): void
+        /**
+         * 让单位移动到目标格子
+         * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
+         * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
+         * 与终点是否相同无关
+         */
+        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap?: boolean): void
         /** 取消移动 */
         export function CancelMove(playerNode: Node, preserveCurrent?: boolean): void
         /** 销毁移动控制器 */

package/assets/pathfinding/base/AStarPathfinder.ts

@@ -87,6 +87,14 @@ export class AStarPathfinder {
     /** 转向惩罚：极小值，只用于等长路径的平局消解，不影响步数最优性 */
     private static readonly TURN_PENALTY = 0.001;
 
+    /**
+     * 偏离直线惩罚：极小值，四方向模式下替代转向惩罚做平局消解。
+     * 四方向里所有单调路径步数相同，若按"拐弯最少"消解会得到先横到底再竖到底的直角路线；
+     * 改成按"偏离 start→target 直线的程度"消解，路线就会贴着对角线走成阶梯状。
+     * 单步惩罚上限 0.5 * 该值，远小于 1 步，不改变步数最优性。
+     */
+    private static readonly LINE_DEVIATION_PENALTY = 0.0001;
+
     constructor(private readonly grid: GridMap) { }
 
     /**
@@ -98,17 +106,18 @@ export class AStarPathfinder {
         if (!this.grid.isWithinBounds(start.row, start.col) || !this.grid.isWithinBounds(end.row, end.col)) {
             return [];
         }
-        return this.search(start, [end]);
+        return this.search(start, [end], end);
     }
 
     /**
      * 多目标 A*：一次搜索，命中 targets 中任意一个格子即返回。
      * A* 按真实路径长度扩展，所以第一个命中的目标一定是“实际走过去最近”的那个，
      * 比按直线距离逐个试 A* 更优，且只搜一次。
+     * lineTarget：仅用于四方向模式的平局消解（参考直线终点），不传则不启用。
      */
-    findPathToNearest(start: Cell, targets: Cell[]): Cell[] {
+    findPathToNearest(start: Cell, targets: Cell[], lineTarget?: Cell): Cell[] {
         const validTargets = targets.filter(t => this.grid.isWithinBounds(t.row, t.col));
-        return this.search(start, validTargets);
+        return this.search(start, validTargets, lineTarget);
     }
 
     /**
@@ -125,7 +134,7 @@ export class AStarPathfinder {
     findPathToNearby(start: Cell, target: Cell, maxDistance: number = 1): Cell[] {
         // 终点本身可站：优先直达，避免绕到终点旁边再折返
         if (this.grid.isWithinBounds(target.row, target.col) && !this.grid.isOccupied(target.row, target.col)) {
-            const direct = this.search(start, [target]);
+            const direct = this.search(start, [target], target);
             if (direct.length > 0) {
                 return direct;
             }
@@ -138,7 +147,7 @@ export class AStarPathfinder {
         while (radius <= maxRadius) {
             const availablePoints = this.grid.findAvailablePointsInRange(target.row, target.col, radius);
             if (availablePoints.length > 0) {
-                const path = this.findPathToNearest(start, availablePoints);
+                const path = this.findPathToNearest(start, availablePoints, target);
                 if (path.length > 0) {
                     return path;
                 }
@@ -157,15 +166,28 @@ export class AStarPathfinder {
      * A* 按 g + h 从小到大扩展，第一个出堆的目标必为真实路径最短的目标。
      *
      * 路径质量（平局消解）：步数相同的路径代价完全相等时，A* 会按入堆顺序
-     * 随机取一条，可能返回“之”字形等长路径。这里给 g 加一个极小的转向惩罚
-     * （TURN_PENALTY < 1 / 最大步数），不改变步数最优性，但保证步数相同时
-     * 优先选拐弯最少（最顺直）的那条。
+     * 随机取一条，可能返回“之”字形等长路径。这里给 g 加一个极小的附加代价
+     * （远小于 1 步），不改变步数最优性，只决定等长路径里选哪一条：
+     *  - 四方向：按偏离 start→lineTarget 直线的程度（LINE_DEVIATION_PENALTY），
+     *    路线贴着对角线走成阶梯状，避免“先横到底再竖到底”的直角路线
+     *  - 其他模式：按转向次数（TURN_PENALTY），优先拐弯最少（最顺直）的那条
      */
-    private search(start: Cell, targets: Cell[]): Cell[] {
+    private search(start: Cell, targets: Cell[], lineTarget?: Cell): Cell[] {
         if (targets.length === 0) {
             return [];
         }
 
+        // 四方向平局消解参考直线：start → lineTarget
+        let lineDRow = 0;
+        let lineDCol = 0;
+        let lineLenSq = 0;
+        if (lineTarget) {
+            lineDRow = lineTarget.row - start.row;
+            lineDCol = lineTarget.col - start.col;
+            lineLenSq = lineDRow * lineDRow + lineDCol * lineDCol;
+        }
+        const useLineDeviation = this.grid.useFourDirection && lineLenSq > 0;
+
         const targetKeys = new Set<string>();
         for (const t of targets) {
             targetKeys.add(`${t.row},${t.col}`);
@@ -230,11 +252,14 @@ export class AStarPathfinder {
                     continue;
                 }
 
-                // 步数代价 + 极小转向惩罚：延续父节点的行进方向记 1，
-                // 换方向记 1 + TURN_PENALTY。总惩罚远小于 1 步，
-                // 不改变步数最优性，只在等长路径中优先拐弯最少（最顺直）的
+                // 步数代价 + 极小附加代价（总附加远小于 1 步，不改变步数最优性，只用于平局消解）
                 let stepCost = 1;
-                if (current.parent) {
+                if (useLineDeviation) {
+                    // 偏离 start→lineTarget 直线越远，代价越高 → 等长路径里选最贴对角线的那条
+                    stepCost += AStarPathfinder.LINE_DEVIATION_PENALTY
+                        * this.getLineDeviation(newRow, newCol, start, lineDRow, lineDCol, lineLenSq);
+                } else if (current.parent) {
+                    // 延续父节点的行进方向记 1，换方向记 1 + TURN_PENALTY → 优先拐弯最少（最顺直）的
                     const keptDirection =
                         current.row - current.parent.row === dRow &&
                         current.col - current.parent.col === dCol;
@@ -261,4 +286,17 @@ export class AStarPathfinder {
         // 开放列表耗尽仍未命中任何目标：无可达路径
         return [];
     }
+
+    /**
+     * 格子到参考直线（from → from + (dRow, dCol)）的归一化偏离度。
+     * 用叉积 / |直线|² 表示，等价于垂直距离 / |直线|，值域 [0, 0.5]，
+     * 与地图尺寸无关，保证附加代价上限恒为 0.5 * LINE_DEVIATION_PENALTY。
+     */
+    private getLineDeviation(
+        row: number, col: number,
+        from: Cell, dRow: number, dCol: number, lenSq: number,
+    ): number {
+        const cross = Math.abs(dRow * (col - from.col) - dCol * (row - from.row));
+        return cross / lenSq;
+    }
 }

package/assets/pathfinding/base/AStarPathfinder.ts.meta

@@ -1,9 +1,9 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "c8b2e640-3f1d-42a7-b5e9-6d0f9a3c8e15",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "c8b2e640-3f1d-42a7-b5e9-6d0f9a3c8e15",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/Common.ts.meta

@@ -1,9 +1,9 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "149ef51b-697e-469e-8ba6-1feb40e9e2b6",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "149ef51b-697e-469e-8ba6-1feb40e9e2b6",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/GridMap.ts

@@ -1,314 +1,330 @@
-/**
- * 网格数据层（纯逻辑，不依赖任何 cc 视图，可独立单元测试）
- *
- * 职责：
- *  1. 边界 / 占用管理
- *  2. 方向规则（八方向 / 六方向蜂窝，蜂窝按行奇偶取对角）
- *  3. 距离计算（蜂窝步数 / 切比雪夫 / 曼哈顿）
- *  4. 范围查询（目标周围可站点等）
- *  5. 包围判断（四方向原逻辑 / 蜂窝逻辑）
- */
-
-/** 格子坐标 */
-export type Cell = { row: number; col: number };
-
-/** 格子的唯一 key："row,col" */
-export function cellKey(row: number, col: number): string {
-    return `${row},${col}`;
-}
-
-export class GridMap {
-
-    readonly rowCount: number;
-    readonly colCount: number;
-    /** 六方向模式：按蜂窝规则（左上/左/左下/右上/右/右下）移动、寻路、判包围 */
-    readonly useSixDirection: boolean;
-
-    /** 被占用格子的 key 集合 */
-    private readonly occupied: Set<string> = new Set();
-
-    constructor(rowCount: number, colCount: number, useSixDirection: boolean) {
-        this.rowCount = rowCount;
-        this.colCount = colCount;
-        this.useSixDirection = useSixDirection;
-    }
-
-    // ==================== 1. 边界 / 占用 ====================
-
-    /** 检查格子是否在地图范围内 */
-    isWithinBounds(row: number, col: number): boolean {
-        return row >= 0 && row < this.rowCount && col >= 0 && col < this.colCount;
-    }
-
-    isOccupied(row: number, col: number): boolean {
-        return this.occupied.has(cellKey(row, col));
-    }
-
-    occupy(row: number, col: number): void {
-        this.occupied.add(cellKey(row, col));
-    }
-
-    free(row: number, col: number): void {
-        this.occupied.delete(cellKey(row, col));
-    }
-
-    freeAll(): void {
-        this.occupied.clear();
-    }
-
-    /** 被占用格子的 key 集合（兼容旧接口 GetOccupyNodeNot） */
-    getOccupiedSet(): Set<string> {
-        return this.occupied;
-    }
-
-    // ==================== 2. 方向 / 距离 ====================
-
-    /**
-     * 六方向（蜂窝）模式下两格之间的步数距离
-     * 奇数行右移半格的交错布局（odd-r）：offset 转 cube 坐标
-     */
-    getHexDistance(row1: number, col1: number, row2: number, col2: number): number {
-        const x1 = col1 - (row1 - (row1 & 1)) / 2;
-        const z1 = row1;
-        const y1 = -x1 - z1;
-        const x2 = col2 - (row2 - (row2 & 1)) / 2;
-        const z2 = row2;
-        const y2 = -x2 - z2;
-        return Math.max(Math.abs(x1 - x2), Math.abs(y1 - y2), Math.abs(z1 - z2));
-    }
-
-    /** 切比雪夫距离（原逻辑的 getManhattanDistance，八方向攻击距离判定用） */
-    getChebyshevDistance(a: Cell, b: Cell): number {
-        const row = Math.abs(a.row - b.row);
-        const col = Math.abs(a.col - b.col);
-        return row > col ? row : col;
-    }
-
-    /** 曼哈顿距离（攻击位排序用） */
-    getManhattanDistance(a: Cell, b: Cell): number {
-        return Math.abs(a.row - b.row) + Math.abs(a.col - b.col);
-    }
-
-    /** 当前移动模式下不会高估的“步数距离”下界（A* 启发函数用，保证最优路径） */
-    getStepDistance(a: Cell, b: Cell): number {
-        if (this.useSixDirection) {
-            return this.getHexDistance(a.row, a.col, b.row, b.col);
-        }
-        return this.getChebyshevDistance(a, b);
-    }
-
-    /**
-     * 获取从 row 行出发的移动方向偏移
-     * 六方向模式：左上、左、左下、右上、右、右下（对角按行奇偶取）
-     * 八方向模式：上下左右 + 四个对角
-     */
-    getDirections(row: number): [number, number][] {
-        if (this.useSixDirection) {
-            const isEvenRow = row % 2 === 0;
-            return [
-                isEvenRow ? [-1, -1] : [-1, 0], // 左上
-                [0, -1],                        // 左
-                isEvenRow ? [1, -1] : [1, 0],   // 左下
-                isEvenRow ? [-1, 0] : [-1, 1],  // 右上
-                [0, 1],                         // 右
-                isEvenRow ? [1, 0] : [1, 1],    // 右下
-            ];
-        }
-        return [
-            [-1, 0],  // 上
-            [1, 0],   // 下
-            [0, -1],  // 左
-            [0, 1],   // 右
-            [-1, -1], // 左上
-            [-1, 1],  // 右上
-            [1, -1],  // 左下
-            [1, 1],   // 右下
-        ];
-    }
-
-    /** 判断两个格子是否相邻（按当前模式的移动规则） */
-    isNeighborCell(a: Cell, b: Cell): boolean {
-        return this.getDirections(a.row).some(([dr, dc]) =>
-            a.row + dr === b.row && a.col + dc === b.col
-        );
-    }
-
-    // ==================== 3. 范围查询 ====================
-
-    /**
-     * 查找目标周围 maxDistance 范围内、在地图内且未被占用的点。
-     *
-     * 注意：这里不能用 isClosedLoop 做提前返回——目标的“被包围”语义包含
-     * “目标自身被占用”，而那正是需要找攻击位的场景（终点被占用/敌人站在终点上）。
-     * 只按 边界 + 占用 过滤即可，范围内没有可站点时自然返回空数组，
-     * 由上层 findPathToNearby 继续扩大半径。
-     */
-    findAvailablePointsInRange(targetRow: number, targetCol: number, maxDistance: number): Cell[] {
-        const availablePoints: Cell[] = [];
-        const visited = new Set<string>();
-        // 遍历目标点周围 maxDistance 范围内的所有格子
-        for (let dRow = -maxDistance; dRow <= maxDistance; dRow++) {
-            for (let dCol = -maxDistance; dCol <= maxDistance; dCol++) {
-                const newRow = targetRow + dRow;
-                const newCol = targetCol + dCol;
-                // 跳过目标点本身
-                if (newRow === targetRow && newCol === targetCol) {
-                    continue;
-                }
-                // 六方向模式：只保留蜂窝距离 ≤ maxDistance 的格子（去掉正方形的四个角）
-                if (this.useSixDirection
-                    && this.getHexDistance(targetRow, targetCol, newRow, newCol) > maxDistance) {
-                    continue;
-                }
-                if (this.isWithinBounds(newRow, newCol) && !this.isOccupied(newRow, newCol)) {
-                    const key = cellKey(newRow, newCol);
-                    if (!visited.has(key)) {
-                        visited.add(key);
-                        availablePoints.push({ row: newRow, col: newCol });
-                    }
-                }
-            }
-        }
-        return availablePoints;
-    }
-
-    /** 目标周围 maxDistance 范围内的所有点（不判断占用，仅边界内） */
-    checkAvailableSurrounding(targetRow: number, targetCol: number, maxDistance: number): Cell[] {
-        const points: Cell[] = [];
-        for (let dRow = -maxDistance; dRow <= maxDistance; dRow++) {
-            for (let dCol = -maxDistance; dCol <= maxDistance; dCol++) {
-                const newRow = targetRow + dRow;
-                const newCol = targetCol + dCol;
-                // 跳过目标点本身
-                if (newRow === targetRow && newCol === targetCol) {
-                    continue;
-                }
-                if (this.isWithinBounds(newRow, newCol)) {
-                    points.push({ row: newRow, col: newCol });
-                }
-            }
-        }
-        return points;
-    }
-
-    // ==================== 4. 包围判断 ====================
-
-    /** 判断目标点是否被包围 */
-    isClosedLoop(targetRow: number, targetCol: number, maxDistance: number): boolean {
-        if (this.useSixDirection) {
-            return this.isClosedLoopSix(targetRow, targetCol, maxDistance);
-        }
-        return this.isClosedLoopFour(targetRow, targetCol, maxDistance);
-    }
-
-    /** 原有四方向逻辑：四个面全部被堵住才算被包围 */
-    private isClosedLoopFour(targetRow: number, targetCol: number, maxDistance: number): boolean {
-        const value = maxDistance;
-
-        const shang = [
-            { row: -value, col: -value },  // 左上
-            { row: -value, col: 0 },       // 上
-            { row: -value, col: value },   // 右上
-        ];
-        const zuo = [
-            { row: -value, col: -value },  // 左上
-            { row: 0, col: -value },       // 左
-            { row: value, col: -value },   // 左下
-        ];
-        const xia = [
-            { row: value, col: -value },   // 左下
-            { row: value, col: 0 },        // 下
-            { row: value, col: value },    // 右下
-        ];
-        const you = [
-            { row: -value, col: value },   // 右上
-            { row: 0, col: value },        // 右
-            { row: value, col: value },    // 右下
-        ];
-
-        let is_shang = false;
-        let is_zuo = false;
-        let is_xia = false;
-        let is_you = false;
-
-        let shang_model = this.isMan(targetRow, targetCol, shang, 0, 0);
-        is_shang = shang_model.is_man
-        if (!shang_model.is_man) {
-            shang_model = this.isMan(targetRow, targetCol, shang, -1, 0);
-            is_shang = shang_model.is_man_bounds
-        }
-
-        let zuo_model = this.isMan(targetRow, targetCol, zuo, 0, 0);
-        is_zuo = zuo_model.is_man
-        if (!zuo_model.is_man) {
-            zuo_model = this.isMan(targetRow, targetCol, zuo, 0, -1);
-            is_zuo = zuo_model.is_man_bounds
-        }
-
-        let xia_model = this.isMan(targetRow, targetCol, xia, 0, 0);
-        is_xia = xia_model.is_man
-        if (!xia_model.is_man) {
-            xia_model = this.isMan(targetRow, targetCol, xia, 1, 0);
-            is_xia = xia_model.is_man_bounds
-        }
-
-        let you_model = this.isMan(targetRow, targetCol, you, 0, 0);
-        is_you = you_model.is_man
-        if (!you_model.is_man) {
-            you_model = this.isMan(targetRow, targetCol, you, 0, 1);
-            is_you = you_model.is_man_bounds
-        }
-
-        // 四个面全部被堵住才算被包围
-        return is_shang && is_zuo && is_xia && is_you;
-    }
-
-    /**
-     * 六方向（蜂窝）模式的包围判断：
-     * 目标点周围蜂窝距离 maxDistance 以内（不含自身）的所有格子，
-     * 只要有一个既在地图内又没被占用，就没被包围；
-     * 全部被堵住（出界或被占用都算堵住）才算被包围。
-     */
-    private isClosedLoopSix(targetRow: number, targetCol: number, maxDistance: number): boolean {
-        // 目标点本身出界 / 被占用，也算“被围住”
-        if (!this.isWithinBounds(targetRow, targetCol) || this.isOccupied(targetRow, targetCol)) {
-            return true;
-        }
-        // 蜂窝范围一定落在这个正方形包围盒里，遍历后按蜂窝距离过滤即可
-        for (let row = targetRow - maxDistance; row <= targetRow + maxDistance; row++) {
-            for (let col = targetCol - maxDistance; col <= targetCol + maxDistance; col++) {
-                if (row === targetRow && col === targetCol) {
-                    continue;
-                }
-                if (this.getHexDistance(targetRow, targetCol, row, col) > maxDistance) {
-                    continue;
-                }
-                // 出界或被占用都算“堵住”；发现一个能站的空格就没被包围
-                if (this.isWithinBounds(row, col) && !this.isOccupied(row, col)) {
-                    return false;
-                }
-            }
-        }
-        return true;
-    }
-
-    /** 检查一组格子是否全部被占据（is_man）或全部出界（is_man_bounds），四方向包围判断用 */
-    private isMan(targetRow: number, targetCol: number, list: { row: number, col: number }[], row: number, col: number) {
-        let count = 0
-        let count_bounds = 0
-
-        for (const dir of list) {
-            const newRow = targetRow + dir.row + row;
-            const newCol = targetCol + dir.col + col;
-            // 出界算被占据
-            if (!this.isWithinBounds(newRow, newCol)) {
-                count++
-                count_bounds++
-            }
-            if (this.isOccupied(newRow, newCol)) {
-                count++
-            }
-        }
-        return { is_man_bounds: count_bounds === list.length, is_man: count === list.length }
-    }
-}
+/**
+ * 网格数据层（纯逻辑，不依赖任何 cc 视图，可独立单元测试）
+ *
+ * 职责：
+ *  1. 边界 / 占用管理
+ *  2. 方向规则（八方向 / 六方向蜂窝，蜂窝按行奇偶取对角）
+ *  3. 距离计算（蜂窝步数 / 切比雪夫 / 曼哈顿）
+ *  4. 范围查询（目标周围可站点等）
+ *  5. 包围判断（四方向原逻辑 / 蜂窝逻辑）
+ */
+
+/** 格子坐标 */
+export type Cell = { row: number; col: number };
+
+/** 格子的唯一 key："row,col" */
+export function cellKey(row: number, col: number): string {
+    return `${row},${col}`;
+}
+
+export class GridMap {
+
+    readonly rowCount: number;
+    readonly colCount: number;
+    /** 六方向模式：按蜂窝规则（左上/左/左下/右上/右/右下）移动、寻路、判包围 */
+    readonly useSixDirection: boolean;
+    /** 四方向模式：只能走 左/下/右/上（优先级高于六方向） */
+    readonly useFourDirection: boolean;
+
+    /** 被占用格子的 key 集合 */
+    private readonly occupied: Set<string> = new Set();
+
+    constructor(rowCount: number, colCount: number, useSixDirection: boolean, useFourDirection = false) {
+        this.rowCount = rowCount;
+        this.colCount = colCount;
+        this.useFourDirection = useFourDirection;
+        // 四方向优先级高于六方向：开启四方向后强制按方格规则处理
+        this.useSixDirection = useFourDirection ? false : useSixDirection;
+    }
+
+    // ==================== 1. 边界 / 占用 ====================
+
+    /** 检查格子是否在地图范围内 */
+    isWithinBounds(row: number, col: number): boolean {
+        return row >= 0 && row < this.rowCount && col >= 0 && col < this.colCount;
+    }
+
+    isOccupied(row: number, col: number): boolean {
+        return this.occupied.has(cellKey(row, col));
+    }
+
+    occupy(row: number, col: number): void {
+        this.occupied.add(cellKey(row, col));
+    }
+
+    free(row: number, col: number): void {
+        this.occupied.delete(cellKey(row, col));
+    }
+
+    freeAll(): void {
+        this.occupied.clear();
+    }
+
+    /** 被占用格子的 key 集合（兼容旧接口 GetOccupyNodeNot） */
+    getOccupiedSet(): Set<string> {
+        return this.occupied;
+    }
+
+    // ==================== 2. 方向 / 距离 ====================
+
+    /**
+     * 六方向（蜂窝）模式下两格之间的步数距离
+     * 奇数行右移半格的交错布局（odd-r）：offset 转 cube 坐标
+     */
+    getHexDistance(row1: number, col1: number, row2: number, col2: number): number {
+        const x1 = col1 - (row1 - (row1 & 1)) / 2;
+        const z1 = row1;
+        const y1 = -x1 - z1;
+        const x2 = col2 - (row2 - (row2 & 1)) / 2;
+        const z2 = row2;
+        const y2 = -x2 - z2;
+        return Math.max(Math.abs(x1 - x2), Math.abs(y1 - y2), Math.abs(z1 - z2));
+    }
+
+    /** 切比雪夫距离（原逻辑的 getManhattanDistance，八方向攻击距离判定用） */
+    getChebyshevDistance(a: Cell, b: Cell): number {
+        const row = Math.abs(a.row - b.row);
+        const col = Math.abs(a.col - b.col);
+        return row > col ? row : col;
+    }
+
+    /** 曼哈顿距离（攻击位排序用） */
+    getManhattanDistance(a: Cell, b: Cell): number {
+        return Math.abs(a.row - b.row) + Math.abs(a.col - b.col);
+    }
+
+    /** 当前移动模式下不会高估的“步数距离”下界（A* 启发函数用，保证最优路径） */
+    getStepDistance(a: Cell, b: Cell): number {
+        if (this.useFourDirection) {
+            return this.getManhattanDistance(a, b);
+        }
+        if (this.useSixDirection) {
+            return this.getHexDistance(a.row, a.col, b.row, b.col);
+        }
+        return this.getChebyshevDistance(a, b);
+    }
+
+    /**
+     * 获取从 row 行出发的移动方向偏移
+     * 四方向模式：左、下、右、上
+     * 六方向模式：左上、左、左下、右上、右、右下（对角按行奇偶取）
+     * 八方向模式（默认）：上下左右 + 四个对角
+     */
+    getDirections(row: number): [number, number][] {
+        if (this.useFourDirection) {
+            return [
+                [0, -1], // 左
+                [1, 0],  // 下
+                [0, 1],  // 右
+                [-1, 0], // 上
+            ];
+        }
+        if (this.useSixDirection) {
+            const isEvenRow = row % 2 === 0;
+            return [
+                isEvenRow ? [-1, -1] : [-1, 0], // 左上
+                [0, -1],                        // 左
+                isEvenRow ? [1, -1] : [1, 0],   // 左下
+                isEvenRow ? [-1, 0] : [-1, 1],  // 右上
+                [0, 1],                         // 右
+                isEvenRow ? [1, 0] : [1, 1],    // 右下
+            ];
+        }
+        return [
+            [-1, 0],  // 上
+            [1, 0],   // 下
+            [0, -1],  // 左
+            [0, 1],   // 右
+            [-1, -1], // 左上
+            [-1, 1],  // 右上
+            [1, -1],  // 左下
+            [1, 1],   // 右下
+        ];
+    }
+
+    /** 判断两个格子是否相邻（按当前模式的移动规则） */
+    isNeighborCell(a: Cell, b: Cell): boolean {
+        return this.getDirections(a.row).some(([dr, dc]) =>
+            a.row + dr === b.row && a.col + dc === b.col
+        );
+    }
+
+    // ==================== 3. 范围查询 ====================
+
+    /**
+     * 查找目标周围 maxDistance 范围内、在地图内且未被占用的点。
+     *
+     * 注意：这里不能用 isClosedLoop 做提前返回——目标的“被包围”语义包含
+     * “目标自身被占用”，而那正是需要找攻击位的场景（终点被占用/敌人站在终点上）。
+     * 只按 边界 + 占用 过滤即可，范围内没有可站点时自然返回空数组，
+     * 由上层 findPathToNearby 继续扩大半径。
+     */
+    findAvailablePointsInRange(targetRow: number, targetCol: number, maxDistance: number): Cell[] {
+        const availablePoints: Cell[] = [];
+        const visited = new Set<string>();
+        // 遍历目标点周围 maxDistance 范围内的所有格子
+        for (let dRow = -maxDistance; dRow <= maxDistance; dRow++) {
+            for (let dCol = -maxDistance; dCol <= maxDistance; dCol++) {
+                const newRow = targetRow + dRow;
+                const newCol = targetCol + dCol;
+                // 跳过目标点本身
+                if (newRow === targetRow && newCol === targetCol) {
+                    continue;
+                }
+                // 六方向模式：只保留蜂窝距离 ≤ maxDistance 的格子（去掉正方形的四个角）
+                if (this.useSixDirection
+                    && this.getHexDistance(targetRow, targetCol, newRow, newCol) > maxDistance) {
+                    continue;
+                }
+                if (this.isWithinBounds(newRow, newCol) && !this.isOccupied(newRow, newCol)) {
+                    const key = cellKey(newRow, newCol);
+                    if (!visited.has(key)) {
+                        visited.add(key);
+                        availablePoints.push({ row: newRow, col: newCol });
+                    }
+                }
+            }
+        }
+        return availablePoints;
+    }
+
+    /** 目标周围 maxDistance 范围内的所有点（不判断占用，仅边界内） */
+    checkAvailableSurrounding(targetRow: number, targetCol: number, maxDistance: number): Cell[] {
+        const points: Cell[] = [];
+        for (let dRow = -maxDistance; dRow <= maxDistance; dRow++) {
+            for (let dCol = -maxDistance; dCol <= maxDistance; dCol++) {
+                const newRow = targetRow + dRow;
+                const newCol = targetCol + dCol;
+                // 跳过目标点本身
+                if (newRow === targetRow && newCol === targetCol) {
+                    continue;
+                }
+                if (this.isWithinBounds(newRow, newCol)) {
+                    points.push({ row: newRow, col: newCol });
+                }
+            }
+        }
+        return points;
+    }
+
+    // ==================== 4. 包围判断 ====================
+
+    /** 判断目标点是否被包围 */
+    isClosedLoop(targetRow: number, targetCol: number, maxDistance: number): boolean {
+        if (this.useSixDirection) {
+            return this.isClosedLoopSix(targetRow, targetCol, maxDistance);
+        }
+        return this.isClosedLoopFour(targetRow, targetCol, maxDistance);
+    }
+
+    /** 原有四方向逻辑：四个面全部被堵住才算被包围 */
+    private isClosedLoopFour(targetRow: number, targetCol: number, maxDistance: number): boolean {
+        const value = maxDistance;
+
+        const shang = [
+            { row: -value, col: -value },  // 左上
+            { row: -value, col: 0 },       // 上
+            { row: -value, col: value },   // 右上
+        ];
+        const zuo = [
+            { row: -value, col: -value },  // 左上
+            { row: 0, col: -value },       // 左
+            { row: value, col: -value },   // 左下
+        ];
+        const xia = [
+            { row: value, col: -value },   // 左下
+            { row: value, col: 0 },        // 下
+            { row: value, col: value },    // 右下
+        ];
+        const you = [
+            { row: -value, col: value },   // 右上
+            { row: 0, col: value },        // 右
+            { row: value, col: value },    // 右下
+        ];
+
+        let is_shang = false;
+        let is_zuo = false;
+        let is_xia = false;
+        let is_you = false;
+
+        let shang_model = this.isMan(targetRow, targetCol, shang, 0, 0);
+        is_shang = shang_model.is_man
+        if (!shang_model.is_man) {
+            shang_model = this.isMan(targetRow, targetCol, shang, -1, 0);
+            is_shang = shang_model.is_man_bounds
+        }
+
+        let zuo_model = this.isMan(targetRow, targetCol, zuo, 0, 0);
+        is_zuo = zuo_model.is_man
+        if (!zuo_model.is_man) {
+            zuo_model = this.isMan(targetRow, targetCol, zuo, 0, -1);
+            is_zuo = zuo_model.is_man_bounds
+        }
+
+        let xia_model = this.isMan(targetRow, targetCol, xia, 0, 0);
+        is_xia = xia_model.is_man
+        if (!xia_model.is_man) {
+            xia_model = this.isMan(targetRow, targetCol, xia, 1, 0);
+            is_xia = xia_model.is_man_bounds
+        }
+
+        let you_model = this.isMan(targetRow, targetCol, you, 0, 0);
+        is_you = you_model.is_man
+        if (!you_model.is_man) {
+            you_model = this.isMan(targetRow, targetCol, you, 0, 1);
+            is_you = you_model.is_man_bounds
+        }
+
+        // 四个面全部被堵住才算被包围
+        return is_shang && is_zuo && is_xia && is_you;
+    }
+
+    /**
+     * 六方向（蜂窝）模式的包围判断：
+     * 目标点周围蜂窝距离 maxDistance 以内（不含自身）的所有格子，
+     * 只要有一个既在地图内又没被占用，就没被包围；
+     * 全部被堵住（出界或被占用都算堵住）才算被包围。
+     */
+    private isClosedLoopSix(targetRow: number, targetCol: number, maxDistance: number): boolean {
+        // 目标点本身出界 / 被占用，也算“被围住”
+        if (!this.isWithinBounds(targetRow, targetCol) || this.isOccupied(targetRow, targetCol)) {
+            return true;
+        }
+        // 蜂窝范围一定落在这个正方形包围盒里，遍历后按蜂窝距离过滤即可
+        for (let row = targetRow - maxDistance; row <= targetRow + maxDistance; row++) {
+            for (let col = targetCol - maxDistance; col <= targetCol + maxDistance; col++) {
+                if (row === targetRow && col === targetCol) {
+                    continue;
+                }
+                if (this.getHexDistance(targetRow, targetCol, row, col) > maxDistance) {
+                    continue;
+                }
+                // 出界或被占用都算“堵住”；发现一个能站的空格就没被包围
+                if (this.isWithinBounds(row, col) && !this.isOccupied(row, col)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+
+    /** 检查一组格子是否全部被占据（is_man）或全部出界（is_man_bounds），四方向包围判断用 */
+    private isMan(targetRow: number, targetCol: number, list: { row: number, col: number }[], row: number, col: number) {
+        let count = 0
+        let count_bounds = 0
+
+        for (const dir of list) {
+            const newRow = targetRow + dir.row + row;
+            const newCol = targetCol + dir.col + col;
+            // 出界算被占据
+            if (!this.isWithinBounds(newRow, newCol)) {
+                count++
+                count_bounds++
+            }
+            if (this.isOccupied(newRow, newCol)) {
+                count++
+            }
+        }
+        return { is_man_bounds: count_bounds === list.length, is_man: count === list.length }
+    }
+}

package/assets/pathfinding/base/GridMap.ts.meta

@@ -1,9 +1,9 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "5d3a8f21-7c4e-4b6a-9f2d-8e1c0a4b7d92",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "5d3a8f21-7c4e-4b6a-9f2d-8e1c0a4b7d92",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/GridMovementController.ts

@@ -16,6 +16,9 @@ export interface GridMovementOptions {
  * 负责把节点位置、临时占用、动画回调串起来，避免多个单位相互污染同一张地图状态。
  */
 export class GridMovementController {
+    /** 允许重叠的单位共用的共享令牌 */
+    private static readonly OVERLAP_TOKEN = 'overlap';
+
     private readonly movementVersions = new Map<Node, number>();
     private readonly movementOwners = new Map<Node, symbol>();
     private readonly movementRetryCallbacks = new Map<Node, () => void>();
@@ -51,23 +54,27 @@ export class GridMovementController {
      * 1. 先取消旧移动和重试。
      * 2. 计算路径，路径无效则延时重试。
      * 3. 成功后进入逐格动画。
+     *
+     * allowOverlap：为 true 时该单位进入"允许重叠"模式，
+     * 与其他同样开启该开关的单位可以走到同一格（互相穿过、不互相绕行、不互相等待），
+     * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
      */
-    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void): void {
+    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
         const start = this.getPosition(playerNode);
         if (start.row === target.row && start.col === target.col) {
             return;
         }
 
         this.cancel(playerNode, true);
-        const route = PathfindingModule.TracePath(start, target, attackDistance, openColor);
+        const route = this.traceRoute(start, target, attackDistance, openColor, allowOverlap, this.movementOwners.get(playerNode));
         if (!route || route.length === 0 || this.isPathBlocked(start, target, route, attackDistance)) {
-            this.retryPathfinding(playerNode, target, attackDistance, openColor, callBack);
+            this.retryPathfinding(playerNode, target, attackDistance, openColor, callBack, allowOverlap);
             return;
         }
 
         this.clearPathfindingRetry(playerNode);
         route.shift();
-        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack);
+        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack, allowOverlap);
     }
 
     /** 强制中止当前移动，可选择保留当前格子的临时占用。 */
@@ -114,14 +121,15 @@ export class GridMovementController {
      * 执行逐格移动。
      * 每次移动前会尝试保留下一格，失败说明被占用，就重新规划路径或延时重试。
      */
-    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void): void {
+    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
         const previousOwner = this.movementOwners.get(playerNode);
         if (previousOwner) {
             this.pathState.release(previousOwner);
         }
         const owner = Symbol(playerNode.name);
         this.movementOwners.set(playerNode, owner);
-        this.pathState.reserveCurrent(start, owner);
+        const shareToken = this.getShareToken(allowOverlap);
+        this.pathState.reserveCurrent(start, owner, shareToken);
         const version = this.bumpVersion(playerNode);
         let previous = start;
         let index = 0;
@@ -131,7 +139,7 @@ export class GridMovementController {
         const retry = () => {
             this.clearMovementRetry(playerNode);
             if (route.length === 0) {
-                const retryRoute = PathfindingModule.TracePath(previous, target, attackDistance, openColor);
+                const retryRoute = this.traceRoute(previous, target, attackDistance, openColor, allowOverlap, owner);
                 if (retryRoute.length <= 1) {
                     if (reachedAttackDistance()) {
                         moveNext();
@@ -166,10 +174,11 @@ export class GridMovementController {
 
             const next = route[index];
             // 只要下一格被占用，就不继续移动，重新规划路线，避免穿透同一格子。
-            if (!this.pathState.tryReserve(previous, next, owner)) {
+            // 同组（终点相同且开启重叠）的单位例外，允许踩到同一格上。
+            if (!this.pathState.tryReserve(previous, next, owner, shareToken)) {
                 this.pathState.release(owner);
                 PathfindingModule.OccupyNode(previous.row, previous.col, true);
-                const newRoute = PathfindingModule.TracePath(previous, target, attackDistance, openColor);
+                const newRoute = this.traceRoute(previous, target, attackDistance, openColor, allowOverlap, owner);
                 if (newRoute.length > 1) {
                     newRoute.shift();
                     route.splice(0, route.length, ...newRoute);
@@ -187,7 +196,7 @@ export class GridMovementController {
             tween(playerNode)
                 .to(this.moveDuration, { worldPosition: PathfindingModule.GetMapPosition(next.row, next.col) })
                 .call(() => {
-                    this.pathState.completeMove(previous, next, owner);
+                    this.pathState.completeMove(previous, next, owner, shareToken);
                     this.positions.set(playerNode, { row: next.row, col: next.col });
                     previous = next;
                     index++;
@@ -199,12 +208,35 @@ export class GridMovementController {
         moveNext();
     }
 
+    /**
+     * 寻路。开启重叠时，先把其他同样开启重叠的单位占住的格子临时释放，
+     * 让 A* 直接穿过它们而不是绕行；寻路结束立刻还原占用，
+     * 这样只放行"动态单位"，静态障碍依旧不可通行。
+     */
+    private traceRoute(start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, allowOverlap: boolean, owner?: symbol): Cell[] {
+        const shareToken = this.getShareToken(allowOverlap);
+        if (shareToken === null) {
+            return PathfindingModule.TracePath(start, target, attackDistance, openColor);
+        }
+
+        const sharedCells = this.pathState.getShareableCells(shareToken, owner);
+        sharedCells.forEach(cell => PathfindingModule.FreeNode(cell.row, cell.col));
+        const route = PathfindingModule.TracePath(start, target, attackDistance, openColor);
+        sharedCells.forEach(cell => PathfindingModule.OccupyNode(cell.row, cell.col, true));
+        return route;
+    }
+
+    /** 开启重叠的单位共用一个固定令牌：只要开关打开，彼此之间都允许同格 */
+    private getShareToken(allowOverlap: boolean): string | null {
+        return allowOverlap ? GridMovementController.OVERLAP_TOKEN : null;
+    }
+
     /** 路径规划失败时，做一次延迟重试，避免因为瞬时占用导致立刻失败。 */
-    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void): void {
+    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
         this.clearPathfindingRetry(playerNode);
         const retry = () => {
             this.clearPathfindingRetry(playerNode);
-            this.moveTo(playerNode, target, attackDistance, openColor, callBack);
+            this.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap);
         };
         this.movementRetryCallbacks.set(playerNode, retry);
         this.scheduler.scheduleOnce(retry, this.retryDelay);

package/assets/pathfinding/base/IMapData.ts.meta

@@ -1,9 +1,9 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "46edad01-0ea3-4d52-957f-edf0abfd3cae",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "46edad01-0ea3-4d52-957f-edf0abfd3cae",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/MapBoxView.ts

@@ -39,6 +39,9 @@ export class MapBoxView extends Component {
     /** 六方向模式：开启后按蜂窝规则（左上/左/左下/右上/右/右下）移动、寻路、判包围 */
     @property({ tooltip: '开启后按蜂窝(六方向)规则寻路：左上/左/左下/右上/右/右下' })
     useSixDirection = true
+    /** 四方向模式：开启后只能走 左/下/右/上（优先级高于六方向） */
+    @property({ tooltip: '开启后按四方向规则寻路：左/下/右/上（优先级高于六方向）' })
+    useFourDirection = false
 
     // ==================== 2. 内部数据 ====================
 
@@ -54,11 +57,16 @@ export class MapBoxView extends Component {
 
     protected onLoad(): void {
         this.content_tf = this.node.getComponent(UITransform);
-        this.grid = new GridMap(this.row, this.col, this.useSixDirection);
+        this.grid = new GridMap(this.row, this.col, this.useSixDirection, this.useFourDirection);
         this.pathfinder = new AStarPathfinder(this.grid);
         PathfindingModule.Init(this);
     }
 
+    /** 是否按蜂窝（六方向）布局：四方向优先级更高，开启后按普通方格布局 */
+    private get isHexLayout(): boolean {
+        return this.useSixDirection && !this.useFourDirection;
+    }
+
     onDestroy() {
         PathfindingModule.Destroy();
     }
@@ -94,8 +102,8 @@ export class MapBoxView extends Component {
                 mapItem.col = j
 
                 const pos = v3(
-                    this.item_width * j + space_x + (i % 2 === 1 ? (this.useSixDirection ? padding_left : 0) : 0) - start_x,
-                    -(this.item_height * i + space_y - (this.useSixDirection ? top : 0)) + start_y,
+                    this.item_width * j + space_x + (i % 2 === 1 ? (this.isHexLayout ? padding_left : 0) : 0) - start_x,
+                    -(this.item_height * i + space_y - (this.isHexLayout ? top : 0)) + start_y,
                     0);
 
 

package/assets/pathfinding/base/Mapitem.ts.meta

@@ -1,9 +1,9 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "760944a7-bf43-418a-ba1b-fc7ba7bf6958",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "760944a7-bf43-418a-ba1b-fc7ba7bf6958",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/PathGridStateManager.ts

@@ -6,26 +6,47 @@ export interface PathGridOccupancy {
     free(row: number, col: number): void;
 }
 
+/**
+ * 共享令牌：令牌相同且非 null 的单位允许站在同一格上（互相穿过）；
+ * null 表示独占，即默认行为（不允许任何单位与自己同格）。
+ */
+export type ShareToken = string | null;
+
 export class PathGridStateManager {
     private readonly temporaryCells = new Set<string>();
-    private readonly reservedCells = new Map<string, Set<symbol>>();
+    /** key -> (归属者 -> 共享令牌) */
+    private readonly reservedCells = new Map<string, Map<symbol, ShareToken>>();
 
     constructor(private readonly occupancy: PathGridOccupancy) {
     }
 
-    reserveCurrent(cell: Cell, owner: symbol): void {
+    reserveCurrent(cell: Cell, owner: symbol, shareToken: ShareToken = null): void {
         this.occupancy.occupy(cell.row, cell.col);
         this.temporaryCells.add(cellKey(cell.row, cell.col));
-        this.addReservation(cellKey(cell.row, cell.col), owner);
+        this.addReservation(cellKey(cell.row, cell.col), owner, shareToken);
     }
 
-    tryReserve(previous: Cell, next: Cell, owner: symbol): boolean {
+    /**
+     * 尝试保留下一格。
+     * 下一格已被别人占住时：只有双方共享令牌相同（同组）才放行，否则视为被堵。
+     */
+    tryReserve(previous: Cell, next: Cell, owner: symbol, shareToken: ShareToken = null): boolean {
         const nextKey = cellKey(next.row, next.col);
         const nextOwners = this.reservedCells.get(nextKey);
-        if (nextOwners && [...nextOwners].some((reservedOwner) => reservedOwner !== owner)) {
-            return false;
+        if (nextOwners) {
+            for (const [reservedOwner, reservedToken] of nextOwners) {
+                if (reservedOwner === owner) {
+                    continue;
+                }
+                if (shareToken === null || reservedToken !== shareToken) {
+                    return false;
+                }
+            }
         }
-        if (this.occupancy.isOccupied(next.row, next.col) && !nextOwners?.has(owner)) {
+        // 没有任何归属者却处于占用状态 = 静态障碍，任何单位都不能踩上去
+        if (this.occupancy.isOccupied(next.row, next.col)
+            && !nextOwners?.has(owner)
+            && !this.isShareable(nextOwners, shareToken)) {
             return false;
         }
 
@@ -33,15 +54,16 @@ export class PathGridStateManager {
         this.occupancy.occupy(next.row, next.col);
         this.temporaryCells.add(cellKey(previous.row, previous.col));
         this.temporaryCells.add(nextKey);
-        this.addReservation(cellKey(previous.row, previous.col), owner);
-        this.addReservation(nextKey, owner);
+        this.addReservation(cellKey(previous.row, previous.col), owner, shareToken);
+        this.addReservation(nextKey, owner, shareToken);
         return true;
     }
 
-    completeMove(previous: Cell, next: Cell, owner: symbol): void {
+    completeMove(previous: Cell, next: Cell, owner: symbol, shareToken: ShareToken = null): void {
         const previousKey = cellKey(previous.row, previous.col);
         if (this.removeReservation(previousKey, owner)) {
             this.temporaryCells.delete(previousKey);
+            // 还有同组单位站在原地时不释放占用
             if (!this.reservedCells.has(previousKey)) {
                 this.occupancy.free(previous.row, previous.col);
             }
@@ -49,7 +71,36 @@ export class PathGridStateManager {
 
         this.occupancy.occupy(next.row, next.col);
         this.temporaryCells.add(cellKey(next.row, next.col));
-        this.addReservation(cellKey(next.row, next.col), owner);
+        this.addReservation(cellKey(next.row, next.col), owner, shareToken);
+    }
+
+    /**
+     * 返回与 shareToken 同组、且不属于 excludeOwner 的单位已占用的格子。
+     * 供上层在寻路前临时释放，让 A* 不要把同组单位当成障碍绕行。
+     */
+    getShareableCells(shareToken: ShareToken, excludeOwner?: symbol): Cell[] {
+        if (shareToken === null) {
+            return [];
+        }
+        const cells: Cell[] = [];
+        for (const [key, owners] of this.reservedCells) {
+            let matched = false;
+            for (const [reservedOwner, reservedToken] of owners) {
+                if (excludeOwner && reservedOwner === excludeOwner) {
+                    continue;
+                }
+                if (reservedToken === shareToken) {
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched) {
+                continue;
+            }
+            const [row, col] = key.split(',').map(Number);
+            cells.push({ row, col });
+        }
+        return cells;
     }
 
     release(owner?: symbol): void {
@@ -72,13 +123,26 @@ export class PathGridStateManager {
         }
     }
 
-    private addReservation(key: string, owner: symbol): void {
+    private addReservation(key: string, owner: symbol, shareToken: ShareToken): void {
         let owners = this.reservedCells.get(key);
         if (!owners) {
-            owners = new Set<symbol>();
+            owners = new Map<symbol, ShareToken>();
             this.reservedCells.set(key, owners);
         }
-        owners.add(owner);
+        owners.set(owner, shareToken);
+    }
+
+    /** 该格上所有归属者的共享令牌都与 shareToken 一致（且非空）时，允许同格重叠 */
+    private isShareable(owners: Map<symbol, ShareToken> | undefined, shareToken: ShareToken): boolean {
+        if (shareToken === null || !owners || owners.size === 0) {
+            return false;
+        }
+        for (const reservedToken of owners.values()) {
+            if (reservedToken !== shareToken) {
+                return false;
+            }
+        }
+        return true;
     }
 
     private removeReservation(key: string, owner: symbol): boolean {

package/assets/pathfinding/base/PathfindingModule.ts

@@ -41,8 +41,14 @@ export class PathfindingModule {
         return this.movementController?.getPosition(playerNode) ?? { row: 0, col: 0 };
     }
 
-    static MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void): void {
-        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack);
+    /**
+     * 让单位移动到目标格子。
+     * allowOverlap：为 true 时该单位进入"允许重叠"模式，
+     * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
+     * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
+     */
+    static MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
+        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap);
     }
 
     static CancelMove(playerNode: Node, preserveCurrent = false): void {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cc-component/cc-pathfinding",
-    "version": "1.0.5",
+    "version": "1.0.8",
     "engine": ">=3.8.6",
     "description": "系统组件添加常用扩展方法",
     "main": "index.ts",