@cc-component/cc-pathfinding 1.0.7 → 1.0.9

package/assets/pathfinding/Interface.ts

@@ -64,8 +64,10 @@ declare global {
          * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
          * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
          * 与终点是否相同无关
+         * @param moveDuration 本次移动的"单格移动时长"，单位秒（越小越快）；
+         * 不传或传 <= 0 时使用 InitMovementController 配置的默认值
          */
-        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap?: boolean): void
+        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap?: boolean, moveDuration?: number): 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/GridMap.ts

@@ -23,14 +23,18 @@ export class GridMap {
     readonly colCount: number;
     /** 六方向模式：按蜂窝规则（左上/左/左下/右上/右/右下）移动、寻路、判包围 */
     readonly useSixDirection: boolean;
+    /** 四方向模式：只能走 左/下/右/上（优先级高于六方向） */
+    readonly useFourDirection: boolean;
 
     /** 被占用格子的 key 集合 */
     private readonly occupied: Set<string> = new Set();
 
-    constructor(rowCount: number, colCount: number, useSixDirection: boolean) {
+    constructor(rowCount: number, colCount: number, useSixDirection: boolean, useFourDirection = false) {
         this.rowCount = rowCount;
         this.colCount = colCount;
-        this.useSixDirection = useSixDirection;
+        this.useFourDirection = useFourDirection;
+        // 四方向优先级高于六方向：开启四方向后强制按方格规则处理
+        this.useSixDirection = useFourDirection ? false : useSixDirection;
     }
 
     // ==================== 1. 边界 / 占用 ====================
@@ -91,6 +95,9 @@ export class GridMap {
 
     /** 当前移动模式下不会高估的“步数距离”下界（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);
         }
@@ -99,10 +106,19 @@ export class GridMap {
 
     /**
      * 获取从 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 [

package/assets/pathfinding/base/GridMovementController.ts

@@ -58,8 +58,9 @@ export class GridMovementController {
      * allowOverlap：为 true 时该单位进入"允许重叠"模式，
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过、不互相绕行、不互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
+     * moveDuration：本次移动的"单格移动时长"，单位秒；不传或传非法值时用控制器的默认值。
      */
-    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
+    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
         const start = this.getPosition(playerNode);
         if (start.row === target.row && start.col === target.col) {
             return;
@@ -68,13 +69,13 @@ export class GridMovementController {
         this.cancel(playerNode, true);
         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, allowOverlap);
+            this.retryPathfinding(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
             return;
         }
 
         this.clearPathfindingRetry(playerNode);
         route.shift();
-        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack, allowOverlap);
+        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
     }
 
     /** 强制中止当前移动，可选择保留当前格子的临时占用。 */
@@ -121,7 +122,7 @@ export class GridMovementController {
      * 执行逐格移动。
      * 每次移动前会尝试保留下一格，失败说明被占用，就重新规划路径或延时重试。
      */
-    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
+    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
         const previousOwner = this.movementOwners.get(playerNode);
         if (previousOwner) {
             this.pathState.release(previousOwner);
@@ -130,6 +131,8 @@ export class GridMovementController {
         this.movementOwners.set(playerNode, owner);
         const shareToken = this.getShareToken(allowOverlap);
         this.pathState.reserveCurrent(start, owner, shareToken);
+        // 单格移动时长：本次指定优先，否则用控制器默认值
+        const duration = this.resolveMoveDuration(moveDuration);
         const version = this.bumpVersion(playerNode);
         let previous = start;
         let index = 0;
@@ -194,7 +197,7 @@ export class GridMovementController {
             }
 
             tween(playerNode)
-                .to(this.moveDuration, { worldPosition: PathfindingModule.GetMapPosition(next.row, next.col) })
+                .to(duration, { worldPosition: PathfindingModule.GetMapPosition(next.row, next.col) })
                 .call(() => {
                     this.pathState.completeMove(previous, next, owner, shareToken);
                     this.positions.set(playerNode, { row: next.row, col: next.col });
@@ -231,12 +234,17 @@ export class GridMovementController {
         return allowOverlap ? GridMovementController.OVERLAP_TOKEN : null;
     }
 
+    /** 单格移动时长：未指定或非法时回退到控制器默认值（单位秒） */
+    private resolveMoveDuration(moveDuration?: number): number {
+        return (typeof moveDuration === 'number' && moveDuration > 0) ? moveDuration : this.moveDuration;
+    }
+
     /** 路径规划失败时，做一次延迟重试，避免因为瞬时占用导致立刻失败。 */
-    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false): void {
+    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
         this.clearPathfindingRetry(playerNode);
         const retry = () => {
             this.clearPathfindingRetry(playerNode);
-            this.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap);
+            this.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
         };
         this.movementRetryCallbacks.set(playerNode, retry);
         this.scheduler.scheduleOnce(retry, this.retryDelay);

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/PathfindingModule.ts

@@ -46,9 +46,11 @@ export class PathfindingModule {
      * allowOverlap：为 true 时该单位进入"允许重叠"模式，
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
+     * moveDuration：本次移动的"单格移动时长"，单位秒（数字越小走得越快）。
+     * 不传或传 <= 0 时使用 InitMovementController 配置的默认值。
      */
-    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 MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
+        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
     }
 
     static CancelMove(playerNode: Node, preserveCurrent = false): void {

package/package.json

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