@esengine/pathfinding 1.0.1

package/src/AI/Pathfinding/BreadthFirst/UnweightedGridGraph.ts

@@ -0,0 +1,81 @@
+import { IVector2, Vector2Utils } from '../../../Types/IVector2';
+import { IUnweightedGraph } from './IUnweightedGraph';
+import { BreadthFirstPathfinder } from './BreadthFirstPathfinder';
+
+/**
+ * 基本的无权网格图，用于广度优先搜索
+ * 适用于简单的网格寻路，如迷宫、推箱子等游戏
+ */
+export class UnweightedGridGraph implements IUnweightedGraph<IVector2> {
+    private static readonly CARDINAL_DIRS: IVector2[] = [
+        Vector2Utils.create(1, 0),
+        Vector2Utils.create(0, -1),
+        Vector2Utils.create(-1, 0),
+        Vector2Utils.create(0, 1)
+    ];
+
+    private static readonly COMPASS_DIRS: IVector2[] = [
+        Vector2Utils.create(1, 0),
+        Vector2Utils.create(1, -1),
+        Vector2Utils.create(0, -1),
+        Vector2Utils.create(-1, -1),
+        Vector2Utils.create(-1, 0),
+        Vector2Utils.create(-1, 1),
+        Vector2Utils.create(0, 1),
+        Vector2Utils.create(1, 1),
+    ];
+
+    public walls: IVector2[] = [];
+
+    private _width: number;
+    private _height: number;
+    private _dirs: IVector2[];
+    private _neighbors: IVector2[] = [];
+
+    constructor(width: number, height: number, allowDiagonalSearch: boolean = false) {
+        this._width = width;
+        this._height = height;
+        this._dirs = allowDiagonalSearch ? UnweightedGridGraph.COMPASS_DIRS : UnweightedGridGraph.CARDINAL_DIRS;
+    }
+
+    public isNodeInBounds(node: IVector2): boolean {
+        return 0 <= node.x && node.x < this._width && 0 <= node.y && node.y < this._height;
+    }
+
+    public isNodePassable(node: IVector2): boolean {
+        return !this.walls.find(wall => Vector2Utils.equals(wall, node));
+    }
+
+    public getNeighbors(node: IVector2): IVector2[] {
+        this._neighbors.length = 0;
+
+        for (const dir of this._dirs) {
+            const next = Vector2Utils.add(node, dir);
+            if (this.isNodeInBounds(next) && this.isNodePassable(next)) {
+                this._neighbors.push(next);
+            }
+        }
+
+        return this._neighbors;
+    }
+
+    /**
+     * 搜索路径的便捷方法
+     * @param start 起始位置
+     * @param goal 目标位置
+     * @returns 路径数组，如果没找到则返回空数组
+     */
+    public searchPath(start: IVector2, goal: IVector2): IVector2[] {
+        return BreadthFirstPathfinder.searchPath(this, start, goal);
+    }
+
+    /**
+     * 检查是否存在路径
+     * @param start 起始位置
+     * @param goal 目标位置
+     * @returns 是否存在路径
+     */
+    public hasPath(start: IVector2, goal: IVector2): boolean {
+        return BreadthFirstPathfinder.search(this, start, goal);
+    }
+}

package/src/Types/IVector2.ts

@@ -0,0 +1,102 @@
+/**
+ * 通用Vector2接口，兼容Cocos Creator和Laya引擎的Vector2类型
+ * 支持 cc.Vec2, Laya.Vector2 等
+ */
+export interface IVector2 {
+    x: number;
+    y: number;
+}
+
+/**
+ * 可比较的Vector2接口，用于路径查找算法
+ */
+export interface IComparableVector2 extends IVector2 {
+    /**
+     * 判断两个向量是否相等
+     */
+    equals?(other: IVector2): boolean;
+}
+
+/**
+ * Vector2工具类，提供通用的向量操作
+ */
+export class Vector2Utils {
+    // 哈希计算相关常量
+    private static readonly HASH_MULTIPLIER = 73856093;
+    private static readonly MAX_COORD = 32767;
+
+    /**
+     * 判断两个向量是否相等
+     */
+    static equals(a: IVector2, b: IVector2): boolean {
+        if ((a as IComparableVector2).equals) {
+            return (a as IComparableVector2).equals!(b);
+        }
+        return a.x === b.x && a.y === b.y;
+    }
+
+    /**
+     * 创建一个新的Vector2对象
+     */
+    static create(x: number, y: number): IVector2 {
+        return { x, y };
+    }
+
+    /**
+     * 复制Vector2
+     */
+    static clone(vector: IVector2): IVector2 {
+        return { x: vector.x, y: vector.y };
+    }
+
+    /**
+     * 向量加法
+     */
+    static add(a: IVector2, b: IVector2): IVector2 {
+        return { x: a.x + b.x, y: a.y + b.y };
+    }
+
+    /**
+     * 计算曼哈顿距离
+     */
+    static manhattanDistance(a: IVector2, b: IVector2): number {
+        return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+    }
+
+    /**
+     * 计算欧几里得距离
+     */
+    static distance(a: IVector2, b: IVector2): number {
+        const dx = a.x - b.x;
+        const dy = a.y - b.y;
+        return Math.sqrt(dx * dx + dy * dy);
+    }
+
+    /**
+     * 将Vector2转换为数值哈希键
+     * 使用位运算生成哈希值，支持坐标范围：-32767 到 32767
+     */
+    static toHash(vector: IVector2): number {
+        const x = (vector.x + this.MAX_COORD) | 0;
+        const y = (vector.y + this.MAX_COORD) | 0;
+        return (x << 16) | y;
+    }
+
+    /**
+     * 将Vector2转换为字符串键
+     * 用于需要字符串键的场景
+     */
+    static toKey(vector: IVector2): string {
+        return `${vector.x},${vector.y}`;
+    }
+
+    /**
+     * 从哈希值还原坐标
+     * 主要用于调试
+     */
+    static fromHash(hash: number): IVector2 {
+        const x = (hash >> 16) - this.MAX_COORD;
+        const y = (hash & 0xFFFF) - this.MAX_COORD;
+        return { x, y };
+    }
+} 

package/src/Utils/PriorityQueue.ts

@@ -0,0 +1,121 @@
+/**
+ * 优先队列实现
+ * 使用二叉堆数据结构，时间复杂度：插入O(log n)，删除O(log n)
+ */
+export interface IPriorityQueueNode {
+    priority: number;
+}
+
+export class PriorityQueue<T extends IPriorityQueueNode> {
+    private _heap: T[] = [];
+    private _size = 0;
+
+    /**
+     * 队列中元素的数量
+     */
+    get size(): number {
+        return this._size;
+    }
+
+    /**
+     * 队列是否为空
+     */
+    get isEmpty(): boolean {
+        return this._size === 0;
+    }
+
+    /**
+     * 清空队列
+     */
+    clear(): void {
+        this._heap.length = 0;
+        this._size = 0;
+    }
+
+    /**
+     * 入队
+     * @param item 要插入的元素
+     */
+    enqueue(item: T): void {
+        this._heap[this._size] = item;
+        this._bubbleUp(this._size);
+        this._size++;
+    }
+
+    /**
+     * 出队，返回优先级最高（值最小）的元素
+     */
+    dequeue(): T | undefined {
+        if (this._size === 0) {
+            return undefined;
+        }
+
+        const result = this._heap[0];
+        this._size--;
+        
+        if (this._size > 0) {
+            this._heap[0] = this._heap[this._size];
+            this._bubbleDown(0);
+        }
+
+        return result;
+    }
+
+    /**
+     * 查看队首元素但不移除
+     */
+    peek(): T | undefined {
+        return this._size > 0 ? this._heap[0] : undefined;
+    }
+
+    /**
+     * 向上冒泡
+     */
+    private _bubbleUp(index: number): void {
+        while (index > 0) {
+            const parentIndex = Math.floor((index - 1) / 2);
+            if (this._heap[index].priority >= this._heap[parentIndex].priority) {
+                break;
+            }
+            this._swap(index, parentIndex);
+            index = parentIndex;
+        }
+    }
+
+    /**
+     * 向下冒泡
+     */
+    private _bubbleDown(index: number): void {
+        while (true) {
+            let minIndex = index;
+            const leftChild = 2 * index + 1;
+            const rightChild = 2 * index + 2;
+
+            if (leftChild < this._size && 
+                this._heap[leftChild].priority < this._heap[minIndex].priority) {
+                minIndex = leftChild;
+            }
+
+            if (rightChild < this._size && 
+                this._heap[rightChild].priority < this._heap[minIndex].priority) {
+                minIndex = rightChild;
+            }
+
+            if (minIndex === index) {
+                break;
+            }
+
+            this._swap(index, minIndex);
+            index = minIndex;
+        }
+    }
+
+    /**
+     * 交换两个元素
+     */
+    private _swap(i: number, j: number): void {
+        const temp = this._heap[i];
+        this._heap[i] = this._heap[j];
+        this._heap[j] = temp;
+    }
+} 

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * 寻路算法库
+ */
+
+// 导出类型定义
+export { IVector2, IComparableVector2, Vector2Utils } from './Types/IVector2';
+
+// 导出工具类
+export { PriorityQueue, IPriorityQueueNode } from './Utils/PriorityQueue';
+
+// 导出A*算法相关
+export { IAstarGraph } from './AI/Pathfinding/AStar/IAstarGraph';
+export { AStarPathfinder } from './AI/Pathfinding/AStar/AStarPathfinder';
+export { AstarGridGraph } from './AI/Pathfinding/AStar/AstarGridGraph';
+
+// 导出广度优先算法相关
+export { IUnweightedGraph } from './AI/Pathfinding/BreadthFirst/IUnweightedGraph';
+export { BreadthFirstPathfinder } from './AI/Pathfinding/BreadthFirst/BreadthFirstPathfinder';
+export { UnweightedGraph } from './AI/Pathfinding/BreadthFirst/UnweightedGraph';
+export { UnweightedGridGraph } from './AI/Pathfinding/BreadthFirst/UnweightedGridGraph';
+
+// 使用示例和说明
+/**
+ * 使用示例：
+ * 
+ * // A*算法 - 适用于大部分游戏场景
+ * const astarGraph = new AstarGridGraph(10, 10);
+ * astarGraph.walls.push({ x: 5, y: 5 });
+ * const astarPath = astarGraph.searchPath({ x: 0, y: 0 }, { x: 9, y: 9 });
+ * 
+ * // 广度优先算法 - 适用于简单网格，保证最短路径
+ * const bfsGraph = new UnweightedGridGraph(10, 10);
+ * bfsGraph.walls.push({ x: 5, y: 5 });
+ * const bfsPath = bfsGraph.searchPath({ x: 0, y: 0 }, { x: 9, y: 9 });
+ * 
+ * // 自定义图结构
+ * const customGraph = new UnweightedGraph<IVector2>();
+ * customGraph.addEdgesForNode({ x: 0, y: 0 }, [{ x: 1, y: 0 }, { x: 0, y: 1 }]);
+ * 
+ * // 在Cocos Creator中使用
+ * // const start = cc.v2(0, 0);
+ * // const goal = cc.v2(9, 9);
+ * // const path = astarGraph.searchPath(start, goal);
+ * 
+ * // 在Laya中使用
+ * // const start = new Laya.Vector2(0, 0);
+ * // const goal = new Laya.Vector2(9, 9);
+ * // const path = astarGraph.searchPath(start, goal);
+ */ 

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "module": "es6",
+    "target": "es5",
+    "declaration": true,
+    "sourceMap": false,
+    "removeComments": true,
+    "outDir": "./bin",
+    "strict": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "lib": [
+      "es5",
+      "dom",
+      "es2015.promise",
+      "es6"
+    ]
+  },
+  "include": [
+    "src/index.ts",
+    "src/Types/**/*",
+    "src/Utils/**/*",
+    "src/AI/Pathfinding/AStar/**/*",
+    "src/AI/Pathfinding/BreadthFirst/**/*"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}