@esengine/pathfinding 1.0.3 → 1.0.7

package/README.md

@@ -13,6 +13,8 @@
 - **引擎兼容**：支持Cocos Creator和Laya引擎
 - **TypeScript**：完整的类型定义
 - **高性能**：对象池优化，减少GC压力
+- **稳定可靠**：87.39%测试覆盖率，14个测试用例验证
+- **类型安全**：严格的TypeScript类型检查
 
 ## 安装
 
@@ -37,7 +39,7 @@ npm install @esengine/pathfinding
 ### 基本使用
 
 ```typescript
-import { AstarGridGraph, Vector2Utils } from '@esengine/pathfinding';
+import { AStarPathfinder, AstarGridGraph, Vector2Utils } from '@esengine/pathfinding';
 
 // 创建20x20的网格
 const graph = new AstarGridGraph(20, 20);
@@ -52,9 +54,18 @@ graph.addWeightedNode(Vector2Utils.create(5, 5));
 // 搜索路径
 const start = Vector2Utils.create(0, 0);
 const goal = Vector2Utils.create(19, 19);
+
+// 方法1：使用图对象的便捷方法
 const path = graph.searchPath(start, goal);
 
+// 方法2：使用静态方法（更灵活）
+const path2 = AStarPathfinder.searchPath(graph, start, goal);
+
+// 检查路径是否存在（不返回具体路径）
+const hasPath = AStarPathfinder.hasPath(graph, start, goal);
+
 console.log('路径:', path);
+console.log('路径存在:', hasPath);
 ```
 
 ### 广度优先搜索
@@ -134,6 +145,32 @@ export class PathfindingManager {
 
 ## API文档
 
+### AStarPathfinder
+
+A*算法核心实现（静态方法）。
+
+```typescript
+// 搜索完整路径
+AStarPathfinder.searchPath<T>(graph: IAstarGraph<T>, start: T, goal: T): T[]
+
+// 检查路径是否存在
+AStarPathfinder.hasPath<T>(graph: IAstarGraph<T>, start: T, goal: T): boolean
+
+// 底层搜索方法（返回节点对象）
+AStarPathfinder.search<T>(graph: IAstarGraph<T>, start: T, goal: T): {
+    found: boolean;
+    goalNode?: AStarNode;
+    openSetNodes?: AStarNode[];
+}
+
+// 对象池管理
+AStarPathfinder.clearPool(): void                    // 清理对象池
+AStarPathfinder.getPoolStats(): {                    // 获取池统计信息
+    poolSize: number;
+    maxPoolSize: number;
+}
+```
+
 ### AstarGridGraph
 
 A*算法网格图实现。
@@ -148,13 +185,19 @@ graph.defaultWeight: number          // 默认移动成本（默认1）
 graph.weightedNodeWeight: number     // 加权节点成本（默认5）
 
 // 方法
-graph.searchPath(start, goal): IVector2[]  // 搜索完整路径
-graph.search(start, goal): boolean         // 检查是否存在路径
+graph.searchPath(start, goal): IVector2[]  // 搜索完整路径（便捷方法）
+graph.isNodePassable(node): boolean        // 检查节点是否可通行
+graph.isNodeInBounds(node): boolean        // 检查节点是否在边界内
 graph.addWall(wall): void                  // 添加单个障碍物
 graph.addWalls(walls): void                // 批量添加障碍物
 graph.clearWalls(): void                   // 清空障碍物
 graph.addWeightedNode(node): void          // 添加加权节点
 graph.clearWeightedNodes(): void           // 清空加权节点
+
+// IAstarGraph接口方法
+graph.getNeighbors(node): IVector2[]       // 获取邻居节点
+graph.cost(from, to): number               // 计算移动成本
+graph.heuristic(node, goal): number        // 计算启发式距离
 ```
 
 ### UnweightedGridGraph
@@ -193,31 +236,67 @@ Vector2Utils.distance(a, b)                  // 欧几里得距离
 ### 塔防游戏
 
 ```typescript
+import { AStarPathfinder, AstarGridGraph } from '@esengine/pathfinding';
+
 // 敌人寻路到基地
 const graph = new AstarGridGraph(mapWidth, mapHeight);
 towers.forEach(tower => graph.addWall(tower.position));
-const path = graph.searchPath(spawnPoint, basePosition);
+
+// 检查是否有路径（性能更好）
+if (AStarPathfinder.hasPath(graph, spawnPoint, basePosition)) {
+    const path = AStarPathfinder.searchPath(graph, spawnPoint, basePosition);
+    enemy.followPath(path);
+}
 ```
 
 ### RPG游戏
 
 ```typescript
+import { AStarPathfinder, AstarGridGraph } from '@esengine/pathfinding';
+
 // 角色移动寻路，设置不同地形权重
 const graph = new AstarGridGraph(mapWidth, mapHeight);
 swampTiles.forEach(tile => graph.addWeightedNode(tile));
 graph.weightedNodeWeight = 3; // 沼泽地移动慢
-const path = graph.searchPath(playerPos, targetPos);
+
+const path = AStarPathfinder.searchPath(graph, playerPos, targetPos);
+if (path.length > 0) {
+    player.moveTo(path);
+}
 ```
 
 ### 迷宫游戏
 
 ```typescript
+import { UnweightedGridGraph } from '@esengine/pathfinding';
+
 // 简单迷宫寻路
 const graph = new UnweightedGridGraph(mazeWidth, mazeHeight);
 walls.forEach(wall => graph.walls.push(wall));
 const path = graph.searchPath(startPos, exitPos);
 ```
 
+### 性能优化示例
+
+```typescript
+import { AStarPathfinder } from '@esengine/pathfinding';
+
+// 在游戏结束时清理对象池
+function onGameEnd() {
+    AStarPathfinder.clearPool();
+}
+
+// 监控内存使用
+function checkMemoryUsage() {
+    const stats = AStarPathfinder.getPoolStats();
+    console.log(`对象池使用: ${stats.poolSize}/${stats.maxPoolSize}`);
+
+    if (stats.poolSize > stats.maxPoolSize * 0.8) {
+        console.warn('对象池使用率较高，考虑优化');
+    }
+}
+```
+
 ## 文件结构
 
 ```
@@ -238,13 +317,42 @@ bin/
 # 安装依赖
 npm install
 
+# 运行测试
+npm test
+
+# 测试覆盖率
+npm run test:coverage
+
+# 类型检查
+npm run type-check
+
+# 代码检查
+npm run lint
+
 # 构建
 npm run build
 
-# 清理构建目录
-gulp clean
+# 完整CI检查
+npm run ci
 ```
 
+## 质量保证
+
+- ✅ **14个测试用例**覆盖主要功能
+- ✅ **87.39%代码覆盖率**
+- ✅ **TypeScript严格模式**
+- ✅ **ESLint代码规范**
+- ✅ **CI自动化测试**
+
+### 测试覆盖范围
+
+- 基础路径查找功能
+- 边界情况处理（起点=终点、超出边界、障碍物上）
+- 错误情况处理（无路径、不可达）
+- 性能和稳定性（大网格、多次搜索）
+- 对象池内存管理
+- 路径质量验证
+
 ## 许可证
 
 MIT License

package/dist/pathfinding.cjs

@@ -1,5 +1,5 @@
 /**
- * @esengine/pathfinding v1.0.3
+ * @esengine/pathfinding v1.0.7
  * 高性能寻路算法库 - 支持A*、广度优先等算法，适用于Cocos Creator、Laya等游戏引擎
  * 
  * @author yhh

package/dist/pathfinding.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/pathfinding v1.0.3
+ * @esengine/pathfinding v1.0.7
  * TypeScript definitions
  */
 interface IVector2 {

package/dist/pathfinding.js

@@ -1,5 +1,5 @@
 /**
- * @esengine/pathfinding v1.0.3
+ * @esengine/pathfinding v1.0.7
  * 高性能寻路算法库 - 支持A*、广度优先等算法，适用于Cocos Creator、Laya等游戏引擎
  * 
  * @author yhh

package/dist/pathfinding.mjs

@@ -1,5 +1,5 @@
 /**
- * @esengine/pathfinding v1.0.3
+ * @esengine/pathfinding v1.0.7
  * 高性能寻路算法库 - 支持A*、广度优先等算法，适用于Cocos Creator、Laya等游戏引擎
  * 
  * @author yhh

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@esengine/pathfinding",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "寻路算法库，支持A*、广度优先等算法，适用于Cocos Creator、Laya等游戏引擎",
   "main": "dist/pathfinding.cjs",
   "module": "dist/pathfinding.mjs",
   "types": "dist/pathfinding.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/pathfinding.mjs",
+      "default": "./dist/pathfinding.cjs"
+    }
+  },
   "files": [
     "dist/**/*",
     "README.md",