@cc-component/cc-pathfinding 1.0.1

package/.cc-ex-component.md

@@ -0,0 +1,12 @@
+# 系统组件添加常用扩展方法
+
+## 前置条件
+[游戏引擎](https://www.cocos.com/en/creator-download)
+[开发框架](https://github.com/a1076559139/cocos-creator-frame-3d)
+
+## 使用案例
+```TS
+import {} from 'db://pkg/@gamex/cc-ex-component';
+
+...
+```

package/assets/pathfinding/Interface.ts

@@ -0,0 +1,73 @@
+import { Vec3 } from "cc";
+import { MapViewModel } from "./base/MapViewModel";
+import { AttackDistance } from "./base/Common";
+import { MapBoxView } from "./base/MapBoxView";
+import { Component } from "cc";
+import { Node } from "cc";
+
+declare module "cc" {
+
+}
+declare global {
+    namespace PathfindingModule {
+        /**开启日志打印 */
+        //export function Debug(enabled: boolean);
+        // 调用 A* 路径寻找，从 (1,1) 到 (5,5),attackDis: 攻击距离
+        export function TracePath(start: { row: number, col: number }, end: { row: number, col: number }, attackDis: AttackDistance, openColor?: boolean): { row: number, col: number }[]
+        // 占用某个节点
+        export function OccupyNode(row: number, col: number, openColor?: boolean)
+        // 判断节点是否被占用
+        export function IsOccupied(row: number, col: number): boolean
+        // 节点可以用
+        export function FreeNode(row: number, col: number)
+
+        // 获取指定行列位置的坐标
+        export function GetMapPosition(row: number, col: number): Vec3
+
+        // 获取指定位置的MapViewModel
+        export function CreateMapModel(row: number, col: number): MapViewModel
+        // 获取指定位置的MapViewModel
+        export function GetMapModel(row: number, col: number): MapViewModel
+        //获取所有的地图块
+        export function GetSeatModelList(): MapViewModel[][]
+        /*获取目标点周围最近的位置*/
+        export function CheckAvailableSurrounding(target: { row: number, col: number, dis: number })
+
+        /**在攻击距离内 */
+        export function IsAttackDistance(model1: MapViewModel, model2: MapViewModel, maxDistance: number): boolean
+
+        /**设置颜色 */
+        export function TargetColor(row, col, dis: number)
+
+        /**清除颜色所所有 */
+        export function ClearColor()
+        /**清除颜色-寻路路径 */
+        export function ClearColorPath()
+
+        /**初始化 */
+        export function Init(map_view: MapBoxView);
+        export function Destroy();
+        // 判断目标点是否被包围
+        export function IsClosedLoop(
+            targetRow: number,
+            targetCol: number, maxDistance: number
+        ): boolean;
+
+
+        //#region 移动控制
+        /** 内部创建并绑定移动控制器 */
+        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
+        /** 取消移动 */
+        export function CancelMove(playerNode: Node, preserveCurrent?: boolean): void
+        /** 销毁移动控制器 */
+        export function DestroyMovement(): void
+        /**开启或关闭所有高亮颜色 */
+        export function SetColorVisible(visible: boolean)
+    }
+}
+// // 必须在 game.init() 之前设置！
+//macro.ENABLE_TRANSPARENT_CANVAS = true;

package/assets/pathfinding/Interface.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "b295f1b0-6f95-4fef-af46-2cdb71f3cd40",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/pathfinding/base/AStarPathfinder.ts

@@ -0,0 +1,264 @@
+import { Cell, GridMap } from './GridMap';
+
+/** A* 寻路节点 */
+class PathNode {
+    constructor(
+        public row: number,
+        public col: number,
+        public g: number = 0,                 // 从起点到当前节点的实际代价
+        public h: number = 0,                 // 当前节点到终点的估计代价
+        public parent: PathNode | null = null // 父节点，用于回溯路径
+    ) { }
+
+    /** f = g + h，值越小越优先扩展 */
+    get f(): number {
+        return this.g + this.h;
+    }
+}
+
+/** 按 f 值组织的最小堆（开放列表，替代线性扫最小值） */
+class MinHeap {
+    private readonly data: PathNode[] = [];
+
+    get size(): number {
+        return this.data.length;
+    }
+
+    push(node: PathNode): void {
+        this.data.push(node);
+        this.siftUp(this.data.length - 1);
+    }
+
+    pop(): PathNode | undefined {
+        if (this.data.length === 0) {
+            return undefined;
+        }
+        const top = this.data[0];
+        const last = this.data.pop();
+        if (this.data.length > 0 && last) {
+            this.data[0] = last;
+            this.siftDown(0);
+        }
+        return top;
+    }
+
+    private siftUp(index: number): void {
+        while (index > 0) {
+            const parent = (index - 1) >> 1;
+            if (this.data[index].f >= this.data[parent].f) {
+                break;
+            }
+            [this.data[index], this.data[parent]] = [this.data[parent], this.data[index]];
+            index = parent;
+        }
+    }
+
+    private siftDown(index: number): void {
+        const n = this.data.length;
+        while (true) {
+            let smallest = index;
+            const left = index * 2 + 1;
+            const right = index * 2 + 2;
+            if (left < n && this.data[left].f < this.data[smallest].f) {
+                smallest = left;
+            }
+            if (right < n && this.data[right].f < this.data[smallest].f) {
+                smallest = right;
+            }
+            if (smallest === index) {
+                break;
+            }
+            [this.data[index], this.data[smallest]] = [this.data[smallest], this.data[index]];
+            index = smallest;
+        }
+    }
+}
+
+/**
+ * A* 寻路算法层（纯逻辑，只依赖 GridMap）
+ *
+ * - 方向规则由 GridMap.getDirections 决定（六方向蜂窝 / 八方向）
+ * - 被占用的格子不能通行；目标格子例外（目标常是敌人，需要走到它身边）
+ * - 支持多目标搜索：一次 A* 命中任意目标即返回，天然按真实路径长度(g)扩展，
+ *   保证返回的是“实际走过去最近”的目标
+ */
+export class AStarPathfinder {
+
+    /** 转向惩罚：极小值，只用于等长路径的平局消解，不影响步数最优性 */
+    private static readonly TURN_PENALTY = 0.001;
+
+    constructor(private readonly grid: GridMap) { }
+
+    /**
+     * A* 寻路：返回起点到终点的路径（含起终点），找不到返回空数组。
+     * 单目标场景，等价于 findPathToNearest(start, [end])。
+     */
+    findPath(start: Cell, end: Cell): Cell[] {
+        // 起点或终点不在地图内，直接失败
+        if (!this.grid.isWithinBounds(start.row, start.col) || !this.grid.isWithinBounds(end.row, end.col)) {
+            return [];
+        }
+        return this.search(start, [end]);
+    }
+
+    /**
+     * 多目标 A*：一次搜索，命中 targets 中任意一个格子即返回。
+     * A* 按真实路径长度扩展，所以第一个命中的目标一定是“实际走过去最近”的那个，
+     * 比按直线距离逐个试 A* 更优，且只搜一次。
+     */
+    findPathToNearest(start: Cell, targets: Cell[]): Cell[] {
+        const validTargets = targets.filter(t => this.grid.isWithinBounds(t.row, t.col));
+        return this.search(start, validTargets);
+    }
+
+    /**
+     * 找到“从 start 出发、能走到 target 身边”的路径：
+     * 优先直达，走不到再从小到大扩大搜索半径取最近可站点。
+     *
+     * 1. 终点本身可站（界内且未被占用）：先直达终点，路径最直最短
+     * 2. 终点被占用（敌人站在终点上）：直接走环圈，到身边最近点
+     * 3. 终点可站但不可达（被墙隔开）：直达失败后落回环圈搜索
+     * 4. 目标被围住：半径 1 全被占 → 扩到半径 2 取围墙外最近空格；
+     *    若这一圈空格全部不可达（被墙圈出的“口袋”），继续扩大半径，
+     *    直到出现可达点或超出地图（返回空数组 = 整个区域都到不了）
+     */
+    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]);
+            if (direct.length > 0) {
+                return direct;
+            }
+            // 直达不可达（被墙隔开），落回环圈搜索
+        }
+
+        const maxRadius = Math.max(this.grid.rowCount, this.grid.colCount);
+        let radius = Math.max(1, maxDistance);
+
+        while (radius <= maxRadius) {
+            const availablePoints = this.grid.findAvailablePointsInRange(target.row, target.col, radius);
+            if (availablePoints.length > 0) {
+                const path = this.findPathToNearest(start, availablePoints);
+                if (path.length > 0) {
+                    return path;
+                }
+                // 这一圈的空格都走不到，扩大半径再试
+            }
+            radius++;
+        }
+        return [];
+    }
+
+    /**
+     * A* 主循环（单目标/多目标共用）：
+     * 返回起点到第一个命中目标的路径（含起终点），无可达目标返回空数组。
+     *
+     * 最优性保证：启发函数取“到最近目标的步数距离下界”（可采纳且一致），
+     * A* 按 g + h 从小到大扩展，第一个出堆的目标必为真实路径最短的目标。
+     *
+     * 路径质量（平局消解）：步数相同的路径代价完全相等时，A* 会按入堆顺序
+     * 随机取一条，可能返回“之”字形等长路径。这里给 g 加一个极小的转向惩罚
+     * （TURN_PENALTY < 1 / 最大步数），不改变步数最优性，但保证步数相同时
+     * 优先选拐弯最少（最顺直）的那条。
+     */
+    private search(start: Cell, targets: Cell[]): Cell[] {
+        if (targets.length === 0) {
+            return [];
+        }
+
+        const targetKeys = new Set<string>();
+        for (const t of targets) {
+            targetKeys.add(`${t.row},${t.col}`);
+        }
+
+        // 起点本身就在目标集合里：路径只有自己
+        if (targetKeys.has(`${start.row},${start.col}`)) {
+            return [{ row: start.row, col: start.col }];
+        }
+
+        // 启发函数：到最近目标的步数距离下界（min 保持可采纳性）
+        const heuristic = (cell: Cell): number => {
+            let min = Infinity;
+            for (const t of targets) {
+                const d = this.grid.getStepDistance(cell, t);
+                if (d < min) {
+                    min = d;
+                }
+            }
+            return min;
+        };
+
+        // 开放列表：待扩展的节点（最小堆）
+        const openList = new MinHeap();
+        openList.push(new PathNode(start.row, start.col));
+        // 每个格子已发现的最小 g 值（用于去重，避免重复入队）
+        const bestG = new Map<string, number>();
+        // 闭合列表：已扩展完成的格子
+        const closed = new Set<string>();
+
+        while (openList.size > 0) {
+            // 1. 取出 f 值最小的节点
+            const current = openList.pop()!;
+            const curKey = `${current.row},${current.col}`;
+            if (closed.has(curKey)) {
+                continue;
+            }
+            closed.add(curKey);
+
+            // 2. 命中任意目标，回溯出完整路径
+            if (targetKeys.has(curKey)) {
+                const path: Cell[] = [];
+                let node: PathNode | null = current;
+                while (node !== null) {
+                    path.unshift({ row: node.row, col: node.col });
+                    node = node.parent;
+                }
+                return path;
+            }
+
+            // 3. 扩展邻居
+            for (const [dRow, dCol] of this.grid.getDirections(current.row)) {
+                const newRow = current.row + dRow;
+                const newCol = current.col + dCol;
+                const key = `${newRow},${newCol}`;
+
+                if (!this.grid.isWithinBounds(newRow, newCol) || closed.has(key)) {
+                    continue;
+                }
+                // 被占用的格子不能走（目标格子例外）
+                if (this.grid.isOccupied(newRow, newCol) && !targetKeys.has(key)) {
+                    continue;
+                }
+
+                // 步数代价 + 极小转向惩罚：延续父节点的行进方向记 1，
+                // 换方向记 1 + TURN_PENALTY。总惩罚远小于 1 步，
+                // 不改变步数最优性，只在等长路径中优先拐弯最少（最顺直）的
+                let stepCost = 1;
+                if (current.parent) {
+                    const keptDirection =
+                        current.row - current.parent.row === dRow &&
+                        current.col - current.parent.col === dCol;
+                    if (!keptDirection) {
+                        stepCost += AStarPathfinder.TURN_PENALTY;
+                    }
+                }
+                const g = current.g + stepCost;
+                // 已经用更短的路径到达过该格子，跳过
+                if (bestG.has(key) && bestG.get(key)! <= g) {
+                    continue;
+                }
+                bestG.set(key, g);
+
+                openList.push(new PathNode(
+                    newRow, newCol,
+                    g,
+                    heuristic({ row: newRow, col: newCol }),
+                    current
+                ));
+            }
+        }
+
+        // 开放列表耗尽仍未命中任何目标：无可达路径
+        return [];
+    }
+}

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

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