@cc-component/cc-pathfinding 1.1.4 → 1.1.6

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,20 @@ 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
+        /**
+         * 一次性给一批节点设置层级（初始化、批量改完位置后调用一次）
+         * @param getOrder 排序键，键越大越靠前显示；不传则用 SetDepthSort 设过的键，
+         * 都没设过默认按世界坐标 y（y 越小越靠前）
+         */
+        export function SetNodesLayer(nodes: Node[], getOrder?: (node: Node) => number): void
         /**
          * 注入自定义 tween 实现（比如换成项目自己的动画系统）
          * @param factory 传 null 或从未调用时，自动使用 cc 自带 tween

package/assets/pathfinding/base/DepthSorter.ts

@@ -12,11 +12,14 @@ import { Node } from 'cc';
  */
 export class DepthSorter {
 
+    /** 默认排序键：y 越小（画面越靠下）越靠前显示 */
+    static readonly DEFAULT_ORDER = (node: Node): number => -node.worldPosition.y;
+
     /**
      * @param getOrder 排序键：键越大越靠前显示（siblingIndex 越大，越后绘制、盖在上面）。
-     * 常见写法：(node) => -node.worldPosition.y —— y 越小（画面越靠下）越靠前。
+     * 默认按世界坐标 y：(node) => -node.worldPosition.y
      */
-    constructor(private readonly getOrder: (node: Node) => number) { }
+    constructor(readonly getOrder: (node: Node) => number = DepthSorter.DEFAULT_ORDER) { }
 
     /**
      * 把节点调整到正确的层级位置。位置已经正确时不做任何操作。

package/assets/pathfinding/base/GridMovementController.ts

@@ -1,5 +1,6 @@
 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';
@@ -47,6 +48,21 @@ export type MovementUpdateHandler = (playerNode: Node, worldPosition: Vec3) => v
  */
 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;
@@ -54,6 +70,11 @@ export interface GridMovementOptions {
     moveDuration?: number;
     /** 自定义 tween 实现，不传则用 cc 自带 tween */
     tweenFactory?: GridTweenFactory;
+    /**
+     * 是否开启内置深度排序：移动中的单位每帧自动调整层级（只调整动过的节点）。
+     * 默认 false。排序键可通过 SetDepthSort 自定义。
+     */
+    depthSort?: boolean;
 }
 
 /**
@@ -93,12 +114,21 @@ export class GridMovementController {
     /** 本帧坐标发生变化的单位，合并回调后清空 */
     private readonly dirtyNodes = new Set<Node>();
     private frameFlushScheduled = false;
+    /** 内置深度排序器，开启后每帧自动调整动过的单位层级 */
+    private depthSorter: DepthSorter | null = null;
+    /** 外部深度排序处理器，设置后内置排序不生效 */
+    private depthSortHandler: ((nodes: Node[]) => void) | null = null;
+    /** 当前排序键：SetNodesLayer 在没有显式传 getOrder 时用它 */
+    private depthSortOrder: (node: Node) => number = DepthSorter.DEFAULT_ORDER;
 
     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),
@@ -147,6 +177,84 @@ export class GridMovementController {
         }
     }
 
+    /**
+     * 开启 / 关闭深度排序。
+     * @param setting 不传 → 内置插入式排序 + 默认键（世界坐标 y，越小越靠前）；
+     * 传 (node) => number → 内置排序 + 自定义键；
+     * 传 { handler } → 完全交给外部处理层级（内部只做脏标记与每帧合并）。
+     */
+    setDepthSort(enabled: boolean, setting?: DepthSortSetting): void {
+        this.depthSortOrder = this.resolveDepthSortOrder(setting);
+        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);
+    }
+
+    /** 取出排序键：函数直接用，配置对象取 getOrder，都没有就用默认（世界坐标 y） */
+    private resolveDepthSortOrder(setting?: DepthSortSetting): (node: Node) => number {
+        if (typeof setting === 'function') {
+            return setting;
+        }
+        return setting?.getOrder ?? DepthSorter.DEFAULT_ORDER;
+    }
+
+    /**
+     * 一次性给一批节点设置层级（初始化、批量改动位置后调用）。
+     * 按父节点分组，只在这些节点当前占据的"槽位"之间按排序键重排，
+     * 不会打乱父节点下其它子节点（比如地图格子）的顺序。
+     */
+    setNodesLayer(nodes: Node[], getOrder?: (node: Node) => number): void {
+        if (!nodes || nodes.length === 0) {
+            return;
+        }
+        const order = getOrder ?? this.depthSortOrder;
+
+        // 按父节点分组，跳过无效 / 无父节点的
+        const groups = new Map<Node, Node[]>();
+        for (const node of nodes) {
+            if (!node?.isValid || !node.parent) {
+                continue;
+            }
+            const list = groups.get(node.parent);
+            if (list) {
+                list.push(node);
+            } else {
+                groups.set(node.parent, [node]);
+            }
+        }
+
+        groups.forEach((list) => {
+            // 槽位 = 这批节点当前的 siblingIndex（升序），重排只发生在这些槽位之间
+            const slots = list.map(node => node.getSiblingIndex()).sort((a, b) => a - b);
+            // 排序键升序：键越小 index 越小（越靠后绘制）
+            list.sort((a, b) => order(a) - order(b));
+            // 按槽位从小到大写入，避免先写大下标导致后续位置错乱
+            for (let i = 0; i < list.length; i++) {
+                if (list[i].getSiblingIndex() !== slots[i]) {
+                    list[i].setSiblingIndex(slots[i]);
+                }
+            }
+        });
+    }
+
+    /** 是否需要在 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);
@@ -159,15 +267,16 @@ export class GridMovementController {
 
     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);
+        // 深度排序：有外部处理器就交给外部，否则用内置插入式排序
+        if (this.depthSortHandler) {
+            this.depthSortHandler(nodes);
+        } else {
+            this.depthSorter?.updateAll(nodes);
+        }
+        this.movementFrameHandler?.(nodes);
     };
 
     /** 获取某个单位当前实际生效的单格移动时长（秒） */
@@ -346,11 +455,11 @@ export class GridMovementController {
             stepping = true;
             // 有外部监听时才挂每帧回调；批量监听只做脏标记（一次 Set.add），排序等重活每帧合并一次
             const updateHandler = this.movementUpdateHandler;
-            const needOnUpdate = updateHandler !== null || this.movementFrameHandler !== null;
+            const needOnUpdate = this.needsFrameUpdate();
             const toOptions: GridTweenOption | undefined = needOnUpdate
                 ? {
                     onUpdate: () => {
-                        if (this.movementFrameHandler) {
+                        if (this.movementFrameHandler || this.depthSorter || this.depthSortHandler) {
                             this.markDirty(playerNode);
                         }
                         updateHandler?.(playerNode, playerNode.getWorldPosition(GridMovementController.TMP_POSITION));

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);
         }
@@ -66,6 +66,30 @@ export class PathfindingModule {
         this.movementController?.setMovementUpdateHandler(handler);
     }
 
+    /**
+     * 一次性给一批节点设置层级（初始化、批量改完位置后调用一次即可）。
+     * 按父节点分组，只在这些节点当前占据的槽位之间按排序键重排，
+     * 不会打乱父节点下其它子节点（比如地图格子）的顺序。
+     * @param getOrder 排序键，键越大越靠前显示；不传则用 SetDepthSort 设过的键，
+     * 都没设过默认按世界坐标 y（y 越小越靠前）
+     */
+    static SetNodesLayer(nodes: Node[], getOrder?: (node: Node) => number): void {
+        this.movementController?.setNodesLayer(nodes, getOrder);
+    }
+
+    /**
+     * 开启 / 关闭深度排序（三种用法）：
+     * 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);
+    }
+
     /**
      * 批量监听"移动过程中位置更新"（推荐，多个单位时用它）：
      * 无论多少个单位在移动，每帧只回调一次，参数是本帧坐标发生变化的单位数组。

package/package.json

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