@cc-component/cc-pathfinding 1.1.5 → 1.1.6

package/assets/pathfinding/Interface.ts

@@ -65,6 +65,12 @@ declare global {
          * 传 { 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

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

package/assets/pathfinding/base/GridMovementController.ts

@@ -118,6 +118,8 @@ export class GridMovementController {
     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 = {}) {
         // 允许外部按场景调整重试间隔和动画时长，默认值保持兼容。
@@ -182,6 +184,7 @@ export class GridMovementController {
      * 传 { handler } → 完全交给外部处理层级（内部只做脏标记与每帧合并）。
      */
     setDepthSort(enabled: boolean, setting?: DepthSortSetting): void {
+        this.depthSortOrder = this.resolveDepthSortOrder(setting);
         if (!enabled) {
             this.depthSorter = null;
             this.depthSortHandler = null;
@@ -197,6 +200,53 @@ export class GridMovementController {
         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

package/assets/pathfinding/base/PathfindingModule.ts

@@ -66,6 +66,17 @@ 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 越小越靠前）

package/package.json

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