@cc-component/cc-pathfinding 1.1.2 → 1.1.3

package/assets/pathfinding/Interface.ts

@@ -69,13 +69,22 @@ declare global {
          * true 用格子底部 GetMapModel(...).bottom_positon
          */
         export function SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition?: boolean): void
+        /**
+         * 运行中设置单位移动速度（单格移动时长，秒，越小越快），立即生效：
+         * 正在播放的那一格按新速度从当前位置继续走完，不跳变
+         * @param moveDuration 传 <= 0 清除该单位设置，按以下顺序回退：
+         * 1) 本次 MoveTo 传入的 moveDuration；2) MoveTo 没传，才用 InitMovementController 配置的默认值
+         */
+        export function SetMoveDuration(playerNode: Node, moveDuration: number): void
+        /** 获取单位当前的单格移动时长（秒） */
+        export function GetMoveDuration(playerNode: Node): number
         /**
          * 让单位移动到目标格子
          * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
          * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
          * 与终点是否相同无关
-         * @param moveDuration 本次移动的"单格移动时长"，单位秒（越小越快）；
-         * 不传或传 <= 0 时使用 InitMovementController 配置的默认值
+         * @param moveDuration 单格移动时长，单位秒（越小越快）；传了会同时更新该单位的速度设置，
+         * 不传时沿用 SetMoveDuration 设过的速度，都没设过才用 InitMovementController 配置的默认值
          * @param useBottomPosition 节点对齐方式：false（默认）用格子中心 GetMapPosition，
          * true 用格子底部 GetMapModel(...).bottom_positon
          */

package/assets/pathfinding/base/GridMovementController.ts

@@ -14,6 +14,11 @@ export interface GridTween {
 /**
  * tween 工厂：外部注入后，移动控制器用它创建/停止 tween。
  * 未注入（null）时自动使用 cc 自带的 tween。
+ *
+ * 注意：工厂本身是长期复用的（控制器只持有一个），但每移动一格都会调用一次 tween(target)。
+ * 是否复用 tween 实例由实现决定：
+ *  - cc 自带 Tween 不能复用（start 后内部动作会累积，官方也警告不要复用实例），必须每次新建；
+ *  - 自定义实现若支持复用，可以缓存一个实例并在 to() 时自行重置后返回同一个对象。
  */
 export interface GridTweenFactory {
     /** 创建一个绑定在 target 上的 tween */
@@ -52,6 +57,12 @@ export class GridMovementController {
     private readonly retryDelay: number;
     private readonly moveDuration: number;
     private readonly pathState: PathGridStateManager;
+    /** SetMoveDuration 设置的"单位速度"（持久），优先级最高 */
+    private readonly unitMoveDurations = new Map<Node, number>();
+    /** 本次 MoveTo 传入的 moveDuration，SetMoveDuration 清除后回退到这里 */
+    private readonly callMoveDurations = new Map<Node, number>();
+    /** 正在播放的那一格的"重放"入口，用于改速度时立即生效 */
+    private readonly activeStepReplayers = new Map<Node, () => void>();
     private customTweenFactory: GridTweenFactory | null;
 
     constructor(private readonly scheduler: Component, options: GridMovementOptions = {}) {
@@ -71,6 +82,30 @@ export class GridMovementController {
         this.customTweenFactory = factory ?? null;
     }
 
+    /**
+     * 运行中设置某个单位的移动速度（单格移动时长，单位秒，越小越快），立即生效：
+     * 已经保存的旧速度会被替换，并且正在播放的那一格会按新速度从当前位置继续走，不会跳变。
+     *
+     * 传非法值（<= 0 / 非数字）则清除该单位的设置，按下面顺序回退：
+     *   1. 本次 PathfindingModule.MoveTo 传入的 moveDuration
+     *   2. 都没有才用 InitMovementController 配置的默认 moveDuration
+     */
+    setMoveDuration(playerNode: Node, moveDuration: number): void {
+        if (typeof moveDuration === 'number' && moveDuration > 0) {
+            this.unitMoveDurations.set(playerNode, moveDuration);
+        } else {
+            this.unitMoveDurations.delete(playerNode);
+        }
+        this.activeStepReplayers.get(playerNode)?.();
+    }
+
+    /** 获取某个单位当前实际生效的单格移动时长（秒） */
+    getMoveDuration(playerNode: Node): number {
+        return this.resolveMoveDuration(
+            this.unitMoveDurations.get(playerNode) ?? this.callMoveDurations.get(playerNode),
+        );
+    }
+
     /** 外部注入优先，取不到就回退到 cc 自带 tween */
     private get tweenFactory(): GridTweenFactory {
         return this.customTweenFactory ?? GridMovementController.SYSTEM_TWEEN_FACTORY;
@@ -125,6 +160,7 @@ export class GridMovementController {
         this.tweenFactory.stopAllByTarget(playerNode);
         this.clearPathfindingRetry(playerNode);
         this.clearMovementRetry(playerNode);
+        this.activeStepReplayers.delete(playerNode);
 
         const owner = this.movementOwners.get(playerNode);
         if (owner) {
@@ -151,6 +187,9 @@ export class GridMovementController {
             this.tweenFactory.stopAllByTarget(playerNode);
         });
         this.movementOwners.clear();
+        this.activeStepReplayers.clear();
+        this.unitMoveDurations.clear();
+        this.callMoveDurations.clear();
 
         for (const playerNode of this.movementRetryCallbacks.keys()) {
             this.clearPathfindingRetry(playerNode);
@@ -173,11 +212,21 @@ export class GridMovementController {
         this.movementOwners.set(playerNode, owner);
         const shareToken = this.getShareToken(allowOverlap);
         this.pathState.reserveCurrent(start, owner, shareToken);
-        // 单格移动时长：本次指定优先，否则用控制器默认值
-        const duration = this.resolveMoveDuration(moveDuration);
+        // 本次移动显式指定了时长就以它为准（覆盖之前 SetMoveDuration 的设置）；
+        // 没指定就清掉本次记录，回退到"单位设置 → 控制器默认"
+        if (typeof moveDuration === 'number' && moveDuration > 0) {
+            this.unitMoveDurations.delete(playerNode);
+            this.callMoveDurations.set(playerNode, moveDuration);
+        } else {
+            this.callMoveDurations.delete(playerNode);
+        }
+        // 单格移动时长：每次播放时实时读取，保证 SetMoveDuration 改完立即生效
+        // 优先级：SetMoveDuration 设置值 → MoveTo 传入值 → 控制器默认值
+        const stepDuration = () => this.getMoveDuration(playerNode);
         const version = this.bumpVersion(playerNode);
         let previous = start;
         let index = 0;
+        let stepping = false;
 
         const reachedAttackDistance = () => this.isAttackDistance(previous, target, attackDistance);
         // 当前格子/目标格子无法继续前进时，重新尝试路径计算或等待下一轮继续。
@@ -202,6 +251,45 @@ export class GridMovementController {
 
         const scheduleRetry = () => this.scheduleMovementRetry(playerNode, retry);
 
+        /**
+         * 播放"当前格 → 下一格"这一段。
+         * 中途改速度时会被原样重放：从节点当前所在位置接着走向同一个目标格，
+         * 时长按剩余距离折算，不会跳变，也不会出现"剩 10% 路程却走满一整格时间"。
+         */
+        const runStep = (stopRunning = false) => {
+            if (version !== this.movementVersions.get(playerNode)) {
+                return;
+            }
+            if (stopRunning) {
+                this.tweenFactory.stopAllByTarget(playerNode);
+            }
+            const next = route[index];
+            const to = this.resolveCellPosition(next, useBottomPosition);
+            const total = Vec3.distance(this.resolveCellPosition(previous, useBottomPosition), to);
+            const remain = Vec3.distance(playerNode.worldPosition, to);
+            const ratio = total > 0 ? Math.min(1, remain / total) : 1;
+
+            stepping = true;
+            this.tweenFactory.tween(playerNode)
+                .to(stepDuration() * ratio, { worldPosition: to })
+                .call(() => {
+                    stepping = false;
+                    this.pathState.completeMove(previous, next, owner, shareToken);
+                    this.positions.set(playerNode, { row: next.row, col: next.col });
+                    previous = next;
+                    index++;
+                    moveNext();
+                })
+                .start();
+        };
+
+        // 供 setMoveDuration 立即生效：只有真的有一步在播放时才重放
+        this.activeStepReplayers.set(playerNode, () => {
+            if (stepping) {
+                runStep(true);
+            }
+        });
+
         const moveNext = () => {
             if (version !== this.movementVersions.get(playerNode)) {
                 return;
@@ -213,6 +301,7 @@ export class GridMovementController {
                     return;
                 }
                 this.clearMovementRetry(playerNode);
+                this.activeStepReplayers.delete(playerNode);
                 callBack?.();
                 return;
             }
@@ -229,6 +318,7 @@ export class GridMovementController {
                     route.splice(0, route.length, ...newRoute);
                     index = 0;
                 } else if (reachedAttackDistance()) {
+                    this.activeStepReplayers.delete(playerNode);
                     callBack?.();
                     return;
                 } else {
@@ -238,16 +328,7 @@ export class GridMovementController {
                 return;
             }
 
-            this.tweenFactory.tween(playerNode)
-                .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 });
-                    previous = next;
-                    index++;
-                    moveNext();
-                })
-                .start();
+            runStep();
         };
 
         moveNext();

package/assets/pathfinding/base/PathfindingModule.ts

@@ -45,6 +45,22 @@ export class PathfindingModule {
      * 设置单位所在格子，并同步节点世界坐标。
      * useBottomPosition：false（默认）用格子中心 GetMapPosition，true 用格子底部 bottom_positon。
      */
+    /**
+     * 运行中设置单位移动速度（单格移动时长，单位秒，越小越快），立即生效：
+     * 正在播放的那一格会按新速度从当前位置继续走完，不会跳变；后续格子也用新速度。
+     * 传 <= 0 则清除该单位的速度设置，按以下顺序回退：
+     *   1. 本次 PathfindingModule.MoveTo 传入的 moveDuration
+     *   2. MoveTo 也没传，才用 InitMovementController 配置的默认 moveDuration
+     */
+    static SetMoveDuration(playerNode: Node, moveDuration: number): void {
+        this.movementController?.setMoveDuration(playerNode, moveDuration);
+    }
+
+    /** 获取单位当前的单格移动时长（秒） */
+    static GetMoveDuration(playerNode: Node): number {
+        return this.movementController?.getMoveDuration(playerNode) ?? 0;
+    }
+
     static SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition = false): void {
         this.movementController?.setPosition(playerNode, position, useBottomPosition);
     }
@@ -58,8 +74,8 @@ export class PathfindingModule {
      * allowOverlap：为 true 时该单位进入"允许重叠"模式，
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
-     * moveDuration：本次移动的"单格移动时长"，单位秒（数字越小走得越快）。
-     * 不传或传 <= 0 时使用 InitMovementController 配置的默认值。
+     * moveDuration：单格移动时长，单位秒（数字越小走得越快）。传了就同时更新该单位的速度设置；
+     * 不传时沿用 SetMoveDuration 设过的速度，都没设过才用 InitMovementController 配置的默认值。
      * useBottomPosition：节点对齐方式。false（默认）用格子中心 GetMapPosition，
      * true 用格子底部 GetMapModel(...).bottom_positon（角色脚底踩在格子底边）。
      */

package/package.json

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