@cc-component/cc-pathfinding 1.0.8 → 1.1.0

package/assets/pathfinding/Interface.ts

@@ -57,15 +57,23 @@ declare global {
         //#region 移动控制
         /** 内部创建并绑定移动控制器 */
         export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number }): void
-        /** 设置单位位置 */
-        export function SetPosition(playerNode: Node, position: { row: number, col: number }): void
+        /**
+         * 设置单位位置
+         * @param useBottomPosition false（默认）用格子中心 GetMapPosition，
+         * true 用格子底部 GetMapModel(...).bottom_positon
+         */
+        export function SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition?: boolean): void
         /**
          * 让单位移动到目标格子
          * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
          * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
          * 与终点是否相同无关
+         * @param moveDuration 本次移动的"单格移动时长"，单位秒（越小越快）；
+         * 不传或传 <= 0 时使用 InitMovementController 配置的默认值
+         * @param useBottomPosition 节点对齐方式：false（默认）用格子中心 GetMapPosition，
+         * true 用格子底部 GetMapModel(...).bottom_positon
          */
-        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, useBottomPosition?: boolean): void
         /** 取消移动 */
         export function CancelMove(playerNode: Node, preserveCurrent?: boolean): void
         /** 销毁移动控制器 */

package/assets/pathfinding/base/GridMovementController.ts

@@ -1,4 +1,4 @@
-import { Component, Node, Tween, tween } from 'cc';
+import { Component, Node, Tween, tween, Vec3 } from 'cc';
 import { AttackDistance } from './Common';
 import { Cell } from './GridMap';
 import { PathGridStateManager } from './PathGridStateManager';
@@ -38,10 +38,13 @@ export class GridMovementController {
         });
     }
 
-    /** 设定单位当前格子，并同步到节点世界坐标。 */
-    setPosition(playerNode: Node, position: Cell): void {
+    /**
+     * 设定单位当前格子，并同步到节点世界坐标。
+     * useBottomPosition：false（默认）对齐格子中心，true 对齐格子底部。
+     */
+    setPosition(playerNode: Node, position: Cell, useBottomPosition = false): void {
         this.positions.set(playerNode, { row: position.row, col: position.col });
-        playerNode.worldPosition = PathfindingModule.GetMapPosition(position.row, position.col);
+        playerNode.worldPosition = this.resolveCellPosition(position, useBottomPosition);
     }
 
     /** 获取单位当前格子，未记录时返回默认起点。 */
@@ -58,8 +61,10 @@ export class GridMovementController {
      * allowOverlap：为 true 时该单位进入"允许重叠"模式，
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过、不互相绕行、不互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
+     * moveDuration：本次移动的"单格移动时长"，单位秒；不传或传非法值时用控制器的默认值。
+     * useBottomPosition：为 true 时节点对齐到格子底部（bottom_positon），否则对齐到格子中心（GetMapPosition）。
      */
-    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, useBottomPosition = false): void {
         const start = this.getPosition(playerNode);
         if (start.row === target.row && start.col === target.col) {
             return;
@@ -68,13 +73,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, useBottomPosition);
             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, useBottomPosition);
     }
 
     /** 强制中止当前移动，可选择保留当前格子的临时占用。 */
@@ -121,7 +126,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, useBottomPosition = false): void {
         const previousOwner = this.movementOwners.get(playerNode);
         if (previousOwner) {
             this.pathState.release(previousOwner);
@@ -130,6 +135,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 +201,7 @@ export class GridMovementController {
             }
 
             tween(playerNode)
-                .to(this.moveDuration, { worldPosition: PathfindingModule.GetMapPosition(next.row, next.col) })
+                .to(duration, { worldPosition: this.resolveCellPosition(next, useBottomPosition) })
                 .call(() => {
                     this.pathState.completeMove(previous, next, owner, shareToken);
                     this.positions.set(playerNode, { row: next.row, col: next.col });
@@ -231,12 +238,24 @@ export class GridMovementController {
         return allowOverlap ? GridMovementController.OVERLAP_TOKEN : null;
     }
 
+    /** 单格移动时长：未指定或非法时回退到控制器默认值（单位秒） */
+    private resolveMoveDuration(moveDuration?: number): number {
+        return (typeof moveDuration === 'number' && moveDuration > 0) ? moveDuration : this.moveDuration;
+    }
+
+    /** 节点落到格子上的坐标：底部对齐用 bottom_positon，否则用格子中心 */
+    private resolveCellPosition(cell: Cell, useBottomPosition: boolean): Vec3 {
+        return useBottomPosition
+            ? PathfindingModule.GetMapModel(cell.row, cell.col).bottom_positon
+            : PathfindingModule.GetMapPosition(cell.row, cell.col);
+    }
+
     /** 路径规划失败时，做一次延迟重试，避免因为瞬时占用导致立刻失败。 */
-    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, useBottomPosition = false): 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, useBottomPosition);
         };
         this.movementRetryCallbacks.set(playerNode, retry);
         this.scheduler.scheduleOnce(retry, this.retryDelay);

package/assets/pathfinding/base/PathfindingModule.ts

@@ -33,8 +33,12 @@ export class PathfindingModule {
         }
     }
 
-    static SetPosition(playerNode: Node, position: { row: number, col: number }): void {
-        this.movementController?.setPosition(playerNode, position);
+    /**
+     * 设置单位所在格子，并同步节点世界坐标。
+     * useBottomPosition：false（默认）用格子中心 GetMapPosition，true 用格子底部 bottom_positon。
+     */
+    static SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition = false): void {
+        this.movementController?.setPosition(playerNode, position, useBottomPosition);
     }
 
     static GetPosition(playerNode: Node): { row: number, col: number } {
@@ -46,9 +50,13 @@ export class PathfindingModule {
      * allowOverlap：为 true 时该单位进入"允许重叠"模式，
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
+     * moveDuration：本次移动的"单格移动时长"，单位秒（数字越小走得越快）。
+     * 不传或传 <= 0 时使用 InitMovementController 配置的默认值。
+     * useBottomPosition：节点对齐方式。false（默认）用格子中心 GetMapPosition，
+     * true 用格子底部 GetMapModel(...).bottom_positon（角色脚底踩在格子底边）。
      */
-    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, useBottomPosition = false): void {
+        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration, useBottomPosition);
     }
 
     static CancelMove(playerNode: Node, preserveCurrent = false): void {

package/package.json

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