@cc-component/cc-pathfinding 1.0.9 → 1.1.1

package/assets/pathfinding/Interface.ts

@@ -4,6 +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";
 
 declare module "cc" {
 
@@ -56,9 +57,18 @@ declare global {
 
         //#region 移动控制
         /** 内部创建并绑定移动控制器 */
-        export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number }): void
-        /** 设置单位位置 */
-        export function SetPosition(playerNode: Node, position: { row: number, col: number }): void
+        export function InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory }): void
+        /**
+         * 注入自定义 tween 实现（比如换成项目自己的动画系统）
+         * @param factory 传 null 或从未调用时，自动使用 cc 自带 tween
+         */
+        export function SetTweenFactory(factory: GridTweenFactory | null): void
+        /**
+         * 设置单位位置
+         * @param useBottomPosition false（默认）用格子中心 GetMapPosition，
+         * true 用格子底部 GetMapModel(...).bottom_positon
+         */
+        export function SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition?: boolean): void
         /**
          * 让单位移动到目标格子
          * @param allowOverlap 为 true 时该单位进入"允许重叠"模式，
@@ -66,8 +76,10 @@ declare global {
          * 与终点是否相同无关
          * @param moveDuration 本次移动的"单格移动时长"，单位秒（越小越快）；
          * 不传或传 <= 0 时使用 InitMovementController 配置的默认值
+         * @param useBottomPosition 节点对齐方式：false（默认）用格子中心 GetMapPosition，
+         * true 用格子底部 GetMapModel(...).bottom_positon
          */
-        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap?: boolean, moveDuration?: number): void
+        export function MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap?: boolean, moveDuration?: number, useBottomPosition?: boolean): void
         /** 取消移动 */
         export function CancelMove(playerNode: Node, preserveCurrent?: boolean): void
         /** 销毁移动控制器 */

package/assets/pathfinding/base/GridMovementController.ts

@@ -1,14 +1,34 @@
-import { Component, Node, Tween, tween } from 'cc';
+import { Component, Node, Tween, tween, Vec3 } from 'cc';
 import { AttackDistance } from './Common';
 import { Cell } from './GridMap';
 import { PathGridStateManager } from './PathGridStateManager';
 import { PathfindingModule } from './PathfindingModule';
 
+/** 外部 tween 对象需要满足的最小接口（与 cc.Tween 用法一致） */
+export interface GridTween {
+    to(duration: number, props: object): GridTween;
+    call(callback: () => void): GridTween;
+    start(): GridTween;
+}
+
+/**
+ * tween 工厂：外部注入后，移动控制器用它创建/停止 tween。
+ * 未注入（null）时自动使用 cc 自带的 tween。
+ */
+export interface GridTweenFactory {
+    /** 创建一个绑定在 target 上的 tween */
+    tween(target: Node): GridTween;
+    /** 停止 target 上的所有 tween */
+    stopAllByTarget(target: Node): void;
+}
+
 export interface GridMovementOptions {
     /** 每次重试前的等待时间，单位秒 */
     retryDelay?: number;
     /** 单格移动动画时长，单位秒 */
     moveDuration?: number;
+    /** 自定义 tween 实现，不传则用 cc 自带 tween */
+    tweenFactory?: GridTweenFactory;
 }
 
 /**
@@ -23,14 +43,22 @@ export class GridMovementController {
     private readonly movementOwners = new Map<Node, symbol>();
     private readonly movementRetryCallbacks = new Map<Node, () => void>();
     private readonly positions = new Map<Node, Cell>();
+    /** 未注入外部实现时使用的系统 tween */
+    private static readonly SYSTEM_TWEEN_FACTORY: GridTweenFactory = {
+        tween: (target: Node) => tween(target),
+        stopAllByTarget: (target: Node) => Tween.stopAllByTarget(target),
+    };
+
     private readonly retryDelay: number;
     private readonly moveDuration: number;
     private readonly pathState: PathGridStateManager;
+    private customTweenFactory: GridTweenFactory | null;
 
     constructor(private readonly scheduler: Component, options: GridMovementOptions = {}) {
         // 允许外部按场景调整重试间隔和动画时长，默认值保持兼容。
         this.retryDelay = options.retryDelay ?? 1;
         this.moveDuration = options.moveDuration ?? 0.5;
+        this.customTweenFactory = options.tweenFactory ?? null;
         this.pathState = new PathGridStateManager({
             isOccupied: (row, col) => PathfindingModule.IsOccupied(row, col),
             occupy: (row, col) => PathfindingModule.OccupyNode(row, col, true),
@@ -38,10 +66,23 @@ export class GridMovementController {
         });
     }
 
-    /** 设定单位当前格子，并同步到节点世界坐标。 */
-    setPosition(playerNode: Node, position: Cell): void {
+    /** 注入自定义 tween 实现，传 null 恢复使用 cc 自带 tween */
+    setTweenFactory(factory: GridTweenFactory | null): void {
+        this.customTweenFactory = factory ?? null;
+    }
+
+    /** 外部注入优先，取不到就回退到 cc 自带 tween */
+    private get tweenFactory(): GridTweenFactory {
+        return this.customTweenFactory ?? GridMovementController.SYSTEM_TWEEN_FACTORY;
+    }
+
+    /**
+     * 设定单位当前格子，并同步到节点世界坐标。
+     * useBottomPosition：false（默认）对齐格子中心，true 对齐格子底部。
+     */
+    setPosition(playerNode: Node, position: Cell, useBottomPosition = false): void {
         this.positions.set(playerNode, { row: position.row, col: position.col });
-        playerNode.worldPosition = PathfindingModule.GetMapPosition(position.row, position.col);
+        playerNode.worldPosition = this.resolveCellPosition(position, useBottomPosition);
     }
 
     /** 获取单位当前格子，未记录时返回默认起点。 */
@@ -59,8 +100,9 @@ export class GridMovementController {
      * 与其他同样开启该开关的单位可以走到同一格（互相穿过、不互相绕行、不互相等待），
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
      * moveDuration：本次移动的"单格移动时长"，单位秒；不传或传非法值时用控制器的默认值。
+     * useBottomPosition：为 true 时节点对齐到格子底部（bottom_positon），否则对齐到格子中心（GetMapPosition）。
      */
-    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
+    moveTo(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number, useBottomPosition = false): void {
         const start = this.getPosition(playerNode);
         if (start.row === target.row && start.col === target.col) {
             return;
@@ -69,18 +111,18 @@ export class GridMovementController {
         this.cancel(playerNode, true);
         const route = this.traceRoute(start, target, attackDistance, openColor, allowOverlap, this.movementOwners.get(playerNode));
         if (!route || route.length === 0 || this.isPathBlocked(start, target, route, attackDistance)) {
-            this.retryPathfinding(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
+            this.retryPathfinding(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration, useBottomPosition);
             return;
         }
 
         this.clearPathfindingRetry(playerNode);
         route.shift();
-        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
+        this.startMovement(playerNode, route, start, target, attackDistance, openColor, callBack, allowOverlap, moveDuration, useBottomPosition);
     }
 
     /** 强制中止当前移动，可选择保留当前格子的临时占用。 */
     cancel(playerNode: Node, preserveCurrent = false): void {
-        Tween.stopAllByTarget(playerNode);
+        this.tweenFactory.stopAllByTarget(playerNode);
         this.clearPathfindingRetry(playerNode);
         this.clearMovementRetry(playerNode);
 
@@ -106,7 +148,7 @@ export class GridMovementController {
         this.movementVersions.clear();
         this.movementOwners.forEach((owner, playerNode) => {
             this.pathState.release(owner);
-            Tween.stopAllByTarget(playerNode);
+            this.tweenFactory.stopAllByTarget(playerNode);
         });
         this.movementOwners.clear();
 
@@ -122,7 +164,7 @@ export class GridMovementController {
      * 执行逐格移动。
      * 每次移动前会尝试保留下一格，失败说明被占用，就重新规划路径或延时重试。
      */
-    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
+    private startMovement(playerNode: Node, route: Cell[], start: Cell, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number, useBottomPosition = false): void {
         const previousOwner = this.movementOwners.get(playerNode);
         if (previousOwner) {
             this.pathState.release(previousOwner);
@@ -196,8 +238,8 @@ export class GridMovementController {
                 return;
             }
 
-            tween(playerNode)
-                .to(duration, { worldPosition: PathfindingModule.GetMapPosition(next.row, next.col) })
+            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 });
@@ -239,12 +281,19 @@ export class GridMovementController {
         return (typeof moveDuration === 'number' && moveDuration > 0) ? moveDuration : this.moveDuration;
     }
 
+    /** 节点落到格子上的坐标：底部对齐用 bottom_positon，否则用格子中心 */
+    private resolveCellPosition(cell: Cell, useBottomPosition: boolean): Vec3 {
+        return useBottomPosition
+            ? PathfindingModule.GetMapModel(cell.row, cell.col).bottom_positon
+            : PathfindingModule.GetMapPosition(cell.row, cell.col);
+    }
+
     /** 路径规划失败时，做一次延迟重试，避免因为瞬时占用导致立刻失败。 */
-    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
+    private retryPathfinding(playerNode: Node, target: Cell, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number, useBottomPosition = false): void {
         this.clearPathfindingRetry(playerNode);
         const retry = () => {
             this.clearPathfindingRetry(playerNode);
-            this.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
+            this.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration, useBottomPosition);
         };
         this.movementRetryCallbacks.set(playerNode, retry);
         this.scheduler.scheduleOnce(retry, this.retryDelay);

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 } from './GridMovementController';
+import { GridMovementController, GridTweenFactory } from './GridMovementController';
 const { ccclass, property } = _decorator;
 
 @ccclass('PathfindingModule')
@@ -27,14 +27,26 @@ export class PathfindingModule {
         this.movementController = controller;
     }
 
-    static InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number }): void {
+    static InitMovementController(scheduler: Component, options?: { retryDelay?: number; moveDuration?: number; tweenFactory?: GridTweenFactory }): void {
         if (!this.movementController) {
             this.movementController = new GridMovementController(scheduler, options);
         }
     }
 
-    static SetPosition(playerNode: Node, position: { row: number, col: number }): void {
-        this.movementController?.setPosition(playerNode, position);
+    /**
+     * 注入自定义 tween 实现（比如换成项目自己的动画系统）。
+     * 传 null 或从未调用时，自动使用 cc 自带 tween。
+     */
+    static SetTweenFactory(factory: GridTweenFactory | null): void {
+        this.movementController?.setTweenFactory(factory);
+    }
+
+    /**
+     * 设置单位所在格子，并同步节点世界坐标。
+     * useBottomPosition：false（默认）用格子中心 GetMapPosition，true 用格子底部 bottom_positon。
+     */
+    static SetPosition(playerNode: Node, position: { row: number, col: number }, useBottomPosition = false): void {
+        this.movementController?.setPosition(playerNode, position, useBottomPosition);
     }
 
     static GetPosition(playerNode: Node): { row: number, col: number } {
@@ -48,9 +60,11 @@ export class PathfindingModule {
      * 与终点是否相同无关；未开启的单位之间、以及开启与未开启之间仍保持互斥。
      * moveDuration：本次移动的"单格移动时长"，单位秒（数字越小走得越快）。
      * 不传或传 <= 0 时使用 InitMovementController 配置的默认值。
+     * useBottomPosition：节点对齐方式。false（默认）用格子中心 GetMapPosition，
+     * true 用格子底部 GetMapModel(...).bottom_positon（角色脚底踩在格子底边）。
      */
-    static MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number): void {
-        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration);
+    static MoveTo(playerNode: Node, target: { row: number, col: number }, attackDistance: AttackDistance, openColor: boolean, callBack?: () => void, allowOverlap = false, moveDuration?: number, useBottomPosition = false): void {
+        this.movementController?.moveTo(playerNode, target, attackDistance, openColor, callBack, allowOverlap, moveDuration, useBottomPosition);
     }
 
     static CancelMove(playerNode: Node, preserveCurrent = false): void {

package/package.json

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