@cc-component/cc-pathfinding 1.0.4 → 1.0.7

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.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,314 @@
-/**
- * 网格数据层（纯逻辑，不依赖任何 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;
+
+    /** 被占用格子的 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 }
+    }
+}

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

@@ -341,7 +341,7 @@ export class MapBoxView extends Component {
         this.seat_model_list.forEach(list => {
             list.forEach(item => {
                 if (!this.grid.isOccupied(item.row, item.col)) {
-                    item.node_chose_sp.node.active = visible;
+                    // item.node_chose_sp.node.active = visible;
                     if (!visible) {
                         item.node_chose_sp.color = Color.WHITE;
                     }

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.4",
+    "version": "1.0.7",
     "engine": ">=3.8.6",
     "description": "系统组件添加常用扩展方法",
     "main": "index.ts",