@cc-component/cc-pathfinding 1.1.3 → 1.1.5

package/assets/pathfinding/Interface.ts

@@ -4,7 +4,7 @@ import { AttackDistance } from "./base/Common";
 import { MapBoxView } from "./base/MapBoxView";
 import { Component } from "cc";
 import { Node } from "cc";
-import { GridTweenFactory } from "./base/GridMovementController";
+import { DepthSortOptions, GridTweenFactory } from "./base/GridMovementController";
 
 declare module "cc" {
 
@@ -57,7 +57,14 @@ declare global {
 
         //#region 移动控制
         /** 内部创建并绑定移动控制器 */
-        export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory }): void
+        export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory; depthSort?: boolean }): void
+        /**
+         * 开启 / 关闭深度排序
+         * @param setting 不传 → 内置插入式排序（默认按世界坐标 y，越小越靠前）；
+         * 传 (node) => number → 内置排序 + 自定义排序键；
+         * 传 { handler: (nodes) => void } → 完全交给外部处理层级（一帧只回调一次）
+         */
+        export function SetDepthSort(enabled: boolean, setting?: ((node: Node) => number) | DepthSortOptions): void
         /**
          * 注入自定义 tween 实现（比如换成项目自己的动画系统）
          * @param factory 传 null 或从未调用时，自动使用 cc 自带 tween
@@ -78,6 +85,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,71 @@
+import { Node } from 'cc';
+
+/**
+ * 增量深度排序器（配合移动中的位置更新回调使用）。
+ *
+ * 为什么不用全量排序：上百个单位每帧对 parent.children 做一次 sort + 逐个 setSiblingIndex，
+ * 开销是 O(N log N) 且会打乱整个 children 数组；而实际每帧真正需要挪动的往往只有少数几个节点。
+ *
+ * 这里的做法是"插入式调整"：只对动过的节点，与相邻兄弟逐个比较并交换，
+ * 直到它落在正确位置。大多数帧只需要 0~1 次 setSiblingIndex，
+ * 单次开销 O(移动的位数)，与单位总数无关。
+ */
+export class DepthSorter {
+
+    /** 默认排序键：y 越小（画面越靠下）越靠前显示 */
+    static readonly DEFAULT_ORDER = (node: Node): number => -node.worldPosition.y;
+
+    /**
+     * @param getOrder 排序键：键越大越靠前显示（siblingIndex 越大，越后绘制、盖在上面）。
+     * 默认按世界坐标 y：(node) => -node.worldPosition.y
+     */
+    constructor(private readonly getOrder: (node: Node) => number = DepthSorter.DEFAULT_ORDER) { }
+
+    /**
+     * 把节点调整到正确的层级位置。位置已经正确时不做任何操作。
+     * @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

@@ -1,12 +1,19 @@
 import { Component, Node, Tween, tween, Vec3 } from 'cc';
 import { AttackDistance } from './Common';
+import { DepthSorter } from './DepthSorter';
 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 +34,35 @@ 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;
+
+/**
+ * 深度排序配置。两种用法二选一（handler 优先）：
+ *  - getOrder：交给内置插入式排序，只传排序键，最省事；
+ *  - handler：完全交给外部处理层级，内部只负责"脏标记 + 每帧合并成一次回调"。
+ */
+export interface DepthSortOptions {
+    /** 内置插入式排序的排序键：键越大越靠前显示（siblingIndex 越大） */
+    getOrder?: (node: Node) => number;
+    /** 外部处理器：每帧一次，参数是本帧坐标发生变化的单位 */
+    handler?: (nodes: Node[]) => void;
+}
+
+/** 直接传一个排序键函数，等价于 { getOrder } */
+export type DepthSortSetting = ((node: Node) => number) | DepthSortOptions;
+
 export interface GridMovementOptions {
     /** 每次重试前的等待时间，单位秒 */
     retryDelay?: number;
@@ -34,6 +70,11 @@ export interface GridMovementOptions {
     moveDuration?: number;
     /** 自定义 tween 实现，不传则用 cc 自带 tween */
     tweenFactory?: GridTweenFactory;
+    /**
+     * 是否开启内置深度排序：移动中的单位每帧自动调整层级（只调整动过的节点）。
+     * 默认 false。排序键可通过 SetDepthSort 自定义。
+     */
+    depthSort?: boolean;
 }
 
 /**
@@ -43,6 +84,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,12 +107,26 @@ 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;
+    /** 内置深度排序器，开启后每帧自动调整动过的单位层级 */
+    private depthSorter: DepthSorter | null = null;
+    /** 外部深度排序处理器，设置后内置排序不生效 */
+    private depthSortHandler: ((nodes: Node[]) => void) | null = null;
 
     constructor(private readonly scheduler: Component, options: GridMovementOptions = {}) {
         // 允许外部按场景调整重试间隔和动画时长，默认值保持兼容。
         this.retryDelay = options.retryDelay ?? 1;
         this.moveDuration = options.moveDuration ?? 0.5;
         this.customTweenFactory = options.tweenFactory ?? null;
+        if (options.depthSort) {
+            this.setDepthSort(true);
+        }
         this.pathState = new PathGridStateManager({
             isOccupied: (row, col) => PathfindingModule.IsOccupied(row, col),
             occupy: (row, col) => PathfindingModule.OccupyNode(row, col, true),
@@ -99,6 +156,79 @@ 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();
+        }
+    }
+
+    /**
+     * 开启 / 关闭深度排序。
+     * @param setting 不传 → 内置插入式排序 + 默认键（世界坐标 y，越小越靠前）；
+     * 传 (node) => number → 内置排序 + 自定义键；
+     * 传 { handler } → 完全交给外部处理层级（内部只做脏标记与每帧合并）。
+     */
+    setDepthSort(enabled: boolean, setting?: DepthSortSetting): void {
+        if (!enabled) {
+            this.depthSorter = null;
+            this.depthSortHandler = null;
+            return;
+        }
+        if (typeof setting === 'function') {
+            this.depthSorter = new DepthSorter(setting);
+            this.depthSortHandler = null;
+            return;
+        }
+        this.depthSortHandler = setting?.handler ?? null;
+        // 有外部处理器时内置排序不生效，避免两套逻辑重复跑
+        this.depthSorter = this.depthSortHandler ? null : new DepthSorter(setting?.getOrder);
+    }
+
+    /** 是否需要在 tween 上挂每帧回调（外部监听 或 深度排序） */
+    private needsFrameUpdate(): boolean {
+        return this.movementUpdateHandler !== null
+            || this.movementFrameHandler !== null
+            || this.depthSorter !== null
+            || this.depthSortHandler !== null;
+    }
+
+    /** 脏标记：只记录"动过"，真正的回调合并到下一帧统一触发一次 */
+    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 nodes: Node[] = [];
+        this.dirtyNodes.forEach(node => nodes.push(node));
+        this.dirtyNodes.clear();
+        // 深度排序：有外部处理器就交给外部，否则用内置插入式排序
+        if (this.depthSortHandler) {
+            this.depthSortHandler(nodes);
+        } else {
+            this.depthSorter?.updateAll(nodes);
+        }
+        this.movementFrameHandler?.(nodes);
+    };
+
     /** 获取某个单位当前实际生效的单格移动时长（秒） */
     getMoveDuration(playerNode: Node): number {
         return this.resolveMoveDuration(
@@ -181,6 +311,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 +403,21 @@ export class GridMovementController {
             const ratio = total > 0 ? Math.min(1, remain / total) : 1;
 
             stepping = true;
+            // 有外部监听时才挂每帧回调；批量监听只做脏标记（一次 Set.add），排序等重活每帧合并一次
+            const updateHandler = this.movementUpdateHandler;
+            const needOnUpdate = this.needsFrameUpdate();
+            const toOptions: GridTweenOption | undefined = needOnUpdate
+                ? {
+                    onUpdate: () => {
+                        if (this.movementFrameHandler || this.depthSorter || this.depthSortHandler) {
+                            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

@@ -4,7 +4,7 @@ import { Vec3 } from 'cc';
 import { MapViewModel } from './MapViewModel';
 import { Color } from 'cc';
 import { AttackDistance } from './Common';
-import { GridMovementController, GridTweenFactory } from './GridMovementController';
+import { DepthSortOptions, GridMovementController, GridTweenFactory } from './GridMovementController';
 const { ccclass, property } = _decorator;
 
 @ccclass('PathfindingModule')
@@ -27,7 +27,7 @@ export class PathfindingModule {
         this.movementController = controller;
     }
 
-    static InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory }): void {
+    static InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory; depthSort?: boolean }): void {
         if (!this.movementController) {
             this.movementController = new GridMovementController(scheduler, options);
         }
@@ -56,6 +56,39 @@ 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);
+    }
+
+    /**
+     * 开启 / 关闭深度排序（三种用法）：
+     * 1. SetDepthSort(true) → 内置插入式排序，默认按世界坐标 y（y 越小越靠前）
+     * 2. SetDepthSort(true, (node) => -node.worldPosition.y) → 内置排序 + 自定义排序键
+     * 3. SetDepthSort(true, { handler: (nodes) => {...} }) → 完全交给外部处理层级，
+     *    内部只负责脏标记并把一帧内的多次变化合并成一次回调（nodes 是本帧动过的单位）
+     *
+     * 传 false 关闭。内置排序只调整本帧动过的节点，不做全量排序，单位再多也是 O(移动位数)。
+     */
+    static SetDepthSort(enabled: boolean, setting?: ((node: Node) => number) | DepthSortOptions): void {
+        this.movementController?.setDepthSort(enabled, setting);
+    }
+
+    /**
+     * 批量监听"移动过程中位置更新"（推荐，多个单位时用它）：
+     * 无论多少个单位在移动，每帧只回调一次，参数是本帧坐标发生变化的单位数组。
+     * 单位越多收益越大：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.5",
     "engine": ">=3.8.6",
     "description": "系统组件添加常用扩展方法",
     "main": "index.ts",