@cc-component/cc-pathfinding 1.1.3 → 1.1.4

package/assets/pathfinding/Interface.ts

@@ -78,6 +78,19 @@ declare global {
         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 时该单位进入"允许重叠"模式，

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;
 }
@@ -27,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;
@@ -43,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>();
@@ -64,6 +86,13 @@ export class GridMovementController {
     /** 正在播放的那一格的"重放"入口，用于改速度时立即生效 */
     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 = {}) {
         // 允许外部按场景调整重试间隔和动画时长，默认值保持兼容。
@@ -99,6 +128,48 @@ export class GridMovementController {
         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(
@@ -181,6 +252,9 @@ 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);
@@ -270,8 +344,21 @@ export class GridMovementController {
             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 })
+                .to(stepDuration() * ratio, { worldPosition: to }, toOptions)
                 .call(() => {
                     stepping = false;
                     this.pathState.completeMove(previous, next, owner, shareToken);

package/assets/pathfinding/base/PathfindingModule.ts

@@ -56,6 +56,26 @@ export class PathfindingModule {
         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;

package/package.json

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