@cc-component/cc-pathfinding 1.1.2 → 1.1.4

package/assets/pathfinding/Interface.ts

@@ -69,13 +69,35 @@ 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
+        /**
+         * 监听移动过程中的位置更新：tween 每更新一次节点坐标就回调一次，
+         * 适合外部在这里刷新节点层级（按 y 做深度排序）
+         * @param handler (playerNode, worldPosition)，worldPosition 是复用的临时向量，仅在回调内有效；
+         * 传 null 取消监听
+         */
+        export function SetMovementUpdateHandler(handler: ((playerNode: Node, worldPosition: Vec3) => void) | null): void
+        /**
+         * 批量监听移动中的位置更新（多个单位时推荐）：无论多少个单位在移动，每帧只回调一次，
+         * 参数是本帧坐标发生变化的单位数组
+         * @param handler 传 null 取消监听；与 SetMovementUpdateHandler 二选一
+         */
+        export function SetMovementFrameHandler(handler: ((playerNodes: Node[]) => void) | null): void
         /**
          * 让单位移动到目标格子
          * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
          * 与其他同样开启该开关的单位可以走到同一格（互相穿过，不再互相绕行/互相等待），
          * 与终点是否相同无关
-         * @param moveDuration 本次移动的"单格移动时长"，单位秒（越小越快）；
-         * 不传或传 <= 0 时使用 InitMovementController 配置的默认值
+         * @param moveDuration 单格移动时长，单位秒（越小越快）；传了会同时更新该单位的速度设置，
+         * 不传时沿用 SetMoveDuration 设过的速度，都没设过才用 InitMovementController 配置的默认值
          * @param useBottomPosition 节点对齐方式：false（默认）用格子中心 GetMapPosition，
          * true 用格子底部 GetMapModel(...).bottom_positon
          */

package/assets/pathfinding/base/DepthSorter.ts

@@ -0,0 +1,68 @@
+import { Node } from 'cc';
+
+/**
+ * 增量深度排序器（配合移动中的位置更新回调使用）。
+ *
+ * 为什么不用全量排序：上百个单位每帧对 parent.children 做一次 sort + 逐个 setSiblingIndex，
+ * 开销是 O(N log N) 且会打乱整个 children 数组；而实际每帧真正需要挪动的往往只有少数几个节点。
+ *
+ * 这里的做法是"插入式调整"：只对动过的节点，与相邻兄弟逐个比较并交换，
+ * 直到它落在正确位置。大多数帧只需要 0~1 次 setSiblingIndex，
+ * 单次开销 O(移动的位数)，与单位总数无关。
+ */
+export class DepthSorter {
+
+    /**
+     * @param getOrder 排序键：键越大越靠前显示（siblingIndex 越大，越后绘制、盖在上面）。
+     * 常见写法：(node) => -node.worldPosition.y —— y 越小（画面越靠下）越靠前。
+     */
+    constructor(private readonly getOrder: (node: Node) => number) { }
+
+    /**
+     * 把节点调整到正确的层级位置。位置已经正确时不做任何操作。
+     * @returns 是否发生过调整
+     */
+    update(node: Node): boolean {
+        if (!node?.isValid) {
+            return false;
+        }
+        const parent = node.parent;
+        if (!parent) {
+            return false;
+        }
+
+        const order = this.getOrder(node);
+        const siblings = parent.children;
+        let index = node.getSiblingIndex();
+        const startIndex = index;
+
+        // 向前挪：前面的兄弟比自己更"靠前"，就往后再换（index 变大 = 后绘制 = 盖在上面）
+        while (index < siblings.length - 1) {
+            const nextSibling = siblings[index + 1];
+            if (nextSibling === node || this.getOrder(nextSibling) >= order) {
+                break;
+            }
+            node.setSiblingIndex(index + 1);
+            index++;
+        }
+
+        // 向后挪：后面的兄弟比自己更"靠后"，就往前换
+        while (index > 0) {
+            const prevSibling = siblings[index - 1];
+            if (prevSibling === node || this.getOrder(prevSibling) <= order) {
+                break;
+            }
+            node.setSiblingIndex(index - 1);
+            index--;
+        }
+
+        return index !== startIndex;
+    }
+
+    /** 批量调整：只对传入的（脏）节点做插入式调整 */
+    updateAll(nodes: Node[]): void {
+        for (const node of nodes) {
+            this.update(node);
+        }
+    }
+}

package/assets/pathfinding/base/GridMovementController.ts

@@ -4,9 +4,15 @@ import { Cell } from './GridMap';
 import { PathGridStateManager } from './PathGridStateManager';
 import { PathfindingModule } from './PathfindingModule';
 
+/** to() 的可选项（与 cc 的 ITweenOption 用法一致） */
+export interface GridTweenOption {
+    /** 每帧回调：tween 更新完目标属性后触发 */
+    onUpdate?: (target: Node) => void;
+}
+
 /** 外部 tween 对象需要满足的最小接口（与 cc.Tween 用法一致） */
 export interface GridTween {
-    to(duration: number, props: object): GridTween;
+    to(duration: number, props: object, opts?: GridTweenOption): GridTween;
     call(callback: () => void): GridTween;
     start(): GridTween;
 }
@@ -14,6 +20,11 @@ export interface GridTween {
 /**
  * tween 工厂：外部注入后，移动控制器用它创建/停止 tween。
  * 未注入（null）时自动使用 cc 自带的 tween。
+ *
+ * 注意：工厂本身是长期复用的（控制器只持有一个），但每移动一格都会调用一次 tween(target)。
+ * 是否复用 tween 实例由实现决定：
+ *  - cc 自带 Tween 不能复用（start 后内部动作会累积，官方也警告不要复用实例），必须每次新建；
+ *  - 自定义实现若支持复用，可以缓存一个实例并在 to() 时自行重置后返回同一个对象。
  */
 export interface GridTweenFactory {
     /** 创建一个绑定在 target 上的 tween */
@@ -22,6 +33,20 @@ export interface GridTweenFactory {
     stopAllByTarget(target: Node): void;
 }
 
+/**
+ * 移动过程中"位置更新"的回调。tween 每更新一次节点坐标就触发一次，
+ * 常用于外部刷新节点层级（按 y 做深度排序，越靠下越靠前显示）。
+ * @param worldPosition 复用同一个临时向量，只在本次回调内有效，不要保存引用
+ */
+export type MovementUpdateHandler = (playerNode: Node, worldPosition: Vec3) => void;
+
+/**
+ * 批量监听：多个单位同时移动时，每帧只回调一次，参数是"本帧坐标发生变化"的单位。
+ * 相比 MovementUpdateHandler（每个单位每帧各回调一次），把 N 次调用合并成 1 次，
+ * 排序等重活每帧只做一遍。单位越多收益越大。
+ */
+export type MovementFrameHandler = (playerNodes: Node[]) => void;
+
 export interface GridMovementOptions {
     /** 每次重试前的等待时间，单位秒 */
     retryDelay?: number;
@@ -38,6 +63,8 @@ export interface GridMovementOptions {
 export class GridMovementController {
     /** 允许重叠的单位共用的共享令牌 */
     private static readonly OVERLAP_TOKEN = 'overlap';
+    /** 位置更新回调里复用，避免每帧分配向量 */
+    private static readonly TMP_POSITION = new Vec3();
 
     private readonly movementVersions = new Map<Node, number>();
     private readonly movementOwners = new Map<Node, symbol>();
@@ -52,7 +79,20 @@ 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;
+    /** 移动中位置更新的外部回调（每单位每帧） */
+    private movementUpdateHandler: MovementUpdateHandler | null = null;
+    /** 移动中位置更新的外部回调（每帧合并一次） */
+    private movementFrameHandler: MovementFrameHandler | null = null;
+    /** 本帧坐标发生变化的单位，合并回调后清空 */
+    private readonly dirtyNodes = new Set<Node>();
+    private frameFlushScheduled = false;
 
     constructor(private readonly scheduler: Component, options: GridMovementOptions = {}) {
         // 允许外部按场景调整重试间隔和动画时长，默认值保持兼容。
@@ -71,6 +111,72 @@ 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)?.();
+    }
+
+    /**
+     * 设置"移动中位置更新"回调：tween 每更新一次节点坐标就触发一次，
+     * 外部可据此刷新节点层级（深度排序）。传 null 取消监听。
+     */
+    setMovementUpdateHandler(handler: MovementUpdateHandler | null): void {
+        this.movementUpdateHandler = handler ?? null;
+    }
+
+    /**
+     * 设置批量监听：多个单位同时移动时每帧只回调一次（参数是本帧动过的单位）。
+     * 传 null 取消监听。与 setMovementUpdateHandler 二选一即可，不要两个都设。
+     */
+    setMovementFrameHandler(handler: MovementFrameHandler | null): void {
+        this.movementFrameHandler = handler ?? null;
+        if (!this.movementFrameHandler) {
+            this.dirtyNodes.clear();
+        }
+    }
+
+    /** 脏标记：只记录"动过"，真正的回调合并到下一帧统一触发一次 */
+    private markDirty(playerNode: Node): void {
+        this.dirtyNodes.add(playerNode);
+        if (this.frameFlushScheduled) {
+            return;
+        }
+        this.frameFlushScheduled = true;
+        this.scheduler.scheduleOnce(this.flushMovementFrame, 0);
+    }
+
+    private readonly flushMovementFrame = (): void => {
+        this.frameFlushScheduled = false;
+        const handler = this.movementFrameHandler;
+        if (!handler) {
+            this.dirtyNodes.clear();
+            return;
+        }
+        const nodes: Node[] = [];
+        this.dirtyNodes.forEach(node => nodes.push(node));
+        this.dirtyNodes.clear();
+        handler(nodes);
+    };
+
+    /** 获取某个单位当前实际生效的单格移动时长（秒） */
+    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 +231,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) {
@@ -145,12 +252,18 @@ export class GridMovementController {
 
     /** 销毁控制器，并清理所有单位的动画、重试和格子占用状态。 */
     destroy(): void {
+        this.scheduler.unschedule(this.flushMovementFrame);
+        this.frameFlushScheduled = false;
+        this.dirtyNodes.clear();
         this.movementVersions.clear();
         this.movementOwners.forEach((owner, playerNode) => {
             this.pathState.release(owner);
             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 +286,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 +325,58 @@ 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;
+            // 有外部监听时才挂每帧回调；批量监听只做脏标记（一次 Set.add），排序等重活每帧合并一次
+            const updateHandler = this.movementUpdateHandler;
+            const needOnUpdate = updateHandler !== null || this.movementFrameHandler !== null;
+            const toOptions: GridTweenOption | undefined = needOnUpdate
+                ? {
+                    onUpdate: () => {
+                        if (this.movementFrameHandler) {
+                            this.markDirty(playerNode);
+                        }
+                        updateHandler?.(playerNode, playerNode.getWorldPosition(GridMovementController.TMP_POSITION));
+                    },
+                }
+                : undefined;
+            this.tweenFactory.tween(playerNode)
+                .to(stepDuration() * ratio, { worldPosition: to }, toOptions)
+                .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 +388,7 @@ export class GridMovementController {
                     return;
                 }
                 this.clearMovementRetry(playerNode);
+                this.activeStepReplayers.delete(playerNode);
                 callBack?.();
                 return;
             }
@@ -229,6 +405,7 @@ export class GridMovementController {
                     route.splice(0, route.length, ...newRoute);
                     index = 0;
                 } else if (reachedAttackDistance()) {
+                    this.activeStepReplayers.delete(playerNode);
                     callBack?.();
                     return;
                 } else {
@@ -238,16 +415,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,42 @@ 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);
+    }
+
+    /**
+     * 监听"移动过程中位置更新"：tween 每更新一次节点坐标就回调一次，
+     * 适合外部在这里刷新节点层级（按 y 做深度排序、越靠下越靠前显示）。
+     * 传 null 取消监听。
+     * @param handler (playerNode, worldPosition)，worldPosition 是复用的临时向量，仅在回调内有效
+     */
+    static SetMovementUpdateHandler(handler: ((playerNode: Node, worldPosition: Vec3) => void) | null): void {
+        this.movementController?.setMovementUpdateHandler(handler);
+    }
+
+    /**
+     * 批量监听"移动过程中位置更新"（推荐，多个单位时用它）：
+     * 无论多少个单位在移动，每帧只回调一次，参数是本帧坐标发生变化的单位数组。
+     * 单位越多收益越大：N 次回调 / N 次排序 收敛为 1 次。
+     * 传 null 取消监听。与 SetMovementUpdateHandler 二选一，不要两个都设。
+     */
+    static SetMovementFrameHandler(handler: ((playerNodes: Node[]) => void) | null): void {
+        this.movementController?.setMovementFrameHandler(handler);
+    }
+
+    /** 获取单位当前的单格移动时长（秒） */
+    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 +94,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.4",
     "engine": ">=3.8.6",
     "description": "系统组件添加常用扩展方法",
     "main": "index.ts",