@shijiu/jsview-vue 2.3.0 → 2.3.728-alpha.0

package/utils/JsViewVueWidget/JsvFreeMoveActor/ForgeTypeDefine.ts

@@ -34,6 +34,8 @@ const FreeMoveAnimClass: any = Forge.FreeMoveAnimation;
 // Run function
 const RunFreeMoveCmdPacks: Function = Forge.AnimFireCommand.RunFreeMoveCmdPacks;
 
+const FireGlobalNexus: Function = Forge.AnimFireCommand.FireGlobalNexus;
+
 const FinishRenderBreak: Function = Forge.sRenderBridge.FinishRenderBreak.bind(Forge.sRenderBridge);
 
 export {
@@ -45,5 +47,6 @@ export {
     CmdPackBuilder,
     FreeMoveAnimClass,
     RunFreeMoveCmdPacks,
+    FireGlobalNexus,
     FinishRenderBreak
 }

package/utils/JsViewVueWidget/JsvFreeMoveActor/{FreeMoveActor.vue → JsvFreeMoveActor.vue}

@@ -14,6 +14,10 @@
  *              .action()  单一运动指令，新指令发生时会冲掉旧指令  
  *              .condition()  条件设置，有时间维度，X/Y维度
  *              .state()  状态调整指令
+            用于解决需要在动画运动过程中随时暂停, 又能原地重新启动运动的场景。
+            暂停和重启运动通过发出nexus来实现, 具体参考 @file://./ActorControl.ts 中的"定制命令集的work flow"
+
+            也用于解决复杂的诸如 抛物线 + 触底反弹 + 空中二段跳的场景
  *
  *      props说明:
  *          class: String, 等同于div的class设置(目前未实装，后续支持...)
@@ -23,7 +27,7 @@
  *          sizeMode: Boolean, 从控制div左上角坐标的模式改为改为通过div矩形宽高
  *                    (指令控制右下角坐标，实现对[0,0]->[右下角x,y]的矩形的宽高调整，另外，不支持负坐标)
  *      expose说明:
- *          control: Object 控制器句柄，具体参考 ActorControl
+ *          control: ActorControl ActorControl实例，详细使用规则见 @file://./ActorControl.ts
 -->
 <script setup>
 import ActControl from "./ActorControl.ts";

package/utils/JsViewVueWidget/JsvFreeMoveActor/NexusNode.ts

@@ -1,4 +1,4 @@
-
+import { FireGlobalNexus } from "./ForgeTypeDefine"
 let sNexusIdGen = 0x4000_0000; // 预留0为无效值
 
 //js端预留的id范围为 0x40000000-0x7FFFFFFF
@@ -15,7 +15,15 @@ function newNexus(): NexusNode {
     return new NexusNode();
 }
 
+function fireGlobalNexus(NexusNode: NexusNode) {
+    FireGlobalNexus(NexusNode.token, GLOBAL_CUSTOM_NEXUS_DETAIL_TYPE);
+}
+
+const GLOBAL_CUSTOM_NEXUS_DETAIL_TYPE = 1001;
+
 export {
     NexusNode,
-    newNexus
+    GLOBAL_CUSTOM_NEXUS_DETAIL_TYPE,
+    newNexus,
+    fireGlobalNexus
 }

package/utils/JsViewVueWidget/JsvFreeMoveActor/SetAction.ts

@@ -9,96 +9,85 @@ import { ConditionSetBuilder, StateCmdBuilder, CmdPackBuilder, ActionCmdBuilder
 import { ActEventDefine } from "./ForgeTypeDefine"
 import { GroupType_ActionAssoc } from "./ForgeTypeDefine"
 import CallbackManager from "./CallbackManager";
-import ActionRefObject from "./ActionRefObject";
 import ActorState from "./ActorState";
 import { NexusNode } from "./NexusNode";
+import type { CommandPackType, CommandType } from "./CmdTypes";
+import { TranslateCondThenCmdPackList } from "./SetCondition";
 
 const ConditionCmdCreator = (
-  builderThis: ActorPackBuilder,
   setCondFunc: Function, // 条件创建处理
-  acts: Array<Object> | null, // 条件达成后的命令列表
+  acts: Array<CommandPackType | Function | null> | null, // 条件达成后的命令列表
   isFinal: boolean,  // 用于进行结束时清理临时condition
-  callback: Function | null  // 达到条件后的callback
-) => {
+) : CommandType => {
   let commonInfo = ConditionSetBuilder.InitCommonInfo();
   ConditionSetBuilder.UpdateCommonInfo(commonInfo, GroupType_ActionAssoc);
 
   // 创建位置条件
   let conditionSet: Object = setCondFunc(commonInfo);;
 
-  let conditionSubCmds: Array<Object> = acts ? acts : [];
-
-  // 设置达到条件后的callback
-  if (callback) {
-    // callback接受参数为({xPos, yPos, xSpd, ySpd, xAcc, yAcc})
-    conditionSubCmds.push(builderThis._CallbackManager.buildCallbackCmd(callback));
-  }
+  let conditionSubCmds: Array<CommandPackType | Function | null> = acts ? acts : [];
 
   if (isFinal) {
     // 结束时清理临时condition
-    conditionSubCmds.push(StateCmdBuilder.DelActionAssocCondition());
+    conditionSubCmds.push(CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.DelActionAssocCondition()));
   }
 
   // 挂载设置好的Sub command list
   if (conditionSubCmds.length > 0) {
-    ConditionSetBuilder.SetCmdList(conditionSet, conditionSubCmds);
+    ConditionSetBuilder.SetCmdPackList(conditionSet, conditionSubCmds);
   }
 
   return StateCmdBuilder.NewCondition(conditionSet);
 }
 
 const ActOnNexusEvent = (
-  builderThis: ActorPackBuilder,
   nexusId: number,
   eventType: number,
-  acts: Array<Object> | null,
-  isFinal: boolean,
-  callback: Function): Object => {
-  return ConditionCmdCreator(builderThis, (commonInfo: Object) => {
+  acts: Array<CommandPackType | Function | null> | null,
+  isFinal: boolean): CommandType => {
+  return ConditionCmdCreator((commonInfo: Object) => {
     return ConditionSetBuilder.OnNexusEvent(nexusId, eventType, commonInfo);
-  }, acts, isFinal, callback)
+  }, acts, isFinal)
 }
 
 const ActOnReachPosition = (
-  builderThis: ActorPackBuilder,
   xPos: number | undefined,
   yPos: number | undefined,
-  acts: Array<Object> | null,
+  acts: Array<CommandPackType | Function | null> | null,
   isFinal: boolean,
-  callback: Function | null
-): Object => {
-  return ConditionCmdCreator(builderThis, (commonInfo: Object) => {
+): CommandType => {
+  return ConditionCmdCreator((commonInfo: Object) => {
     return ConditionSetBuilder.ReachPosition(xPos, yPos, commonInfo);
-  }, acts, isFinal, callback);
+  }, acts, isFinal);
 }
 
 const ActOnGetToSpeed = (
-  builderThis: ActorPackBuilder,
   xSpeed: number | undefined,
   ySpeed: number | undefined,
-  acts: Array<Object> | null,
+  acts: Array<CommandPackType | Function | null> | null,
   isFinal: boolean,
-  callback: Function | null
-): Object => {
-  return ConditionCmdCreator(builderThis, (commonInfo: Object): Object => {
+): CommandType => {
+  return ConditionCmdCreator((commonInfo: Object): Object => {
     return ConditionSetBuilder.ReachSpeed(xSpeed, ySpeed, commonInfo);
-  }, acts, isFinal, callback);
+  }, acts, isFinal);
 }
 
 const ActOnGetAcrossSpeed = (
-  builderThis: ActorPackBuilder,
   xSpeed: number | undefined,
   ySpeed: number | undefined,
-  acts: Array<Object> | null,
+  acts: Array<CommandPackType | Function | null> | null,
   isFinal: boolean,
-  callback: Function | null
-): Object => {
-  return ConditionCmdCreator(builderThis, (commonInfo: Object): Object => {
+): CommandType => {
+  return ConditionCmdCreator((commonInfo: Object): Object => {
     return ConditionSetBuilder.AcrossSpeed(xSpeed, ySpeed, commonInfo);
-  }, acts, isFinal, callback);
+  }, acts, isFinal);
 }
 
-class ActorPackBuilder {
+/**
+ * action().XXXXX 可用的API说明
+ * 标注"内部API"的API, 应用开发时一定!!不要使用, 因为后续版本可能调整导致失效
+ */
+class ActionPackBuilder {
   public _CallbackManager: CallbackManager;
   private _ActionTokenGen: number;
 
@@ -106,7 +95,7 @@ class ActorPackBuilder {
   private _AccKeeps: number;
   private _NexusRecv: NexusNode | null;
   private _CommonInfoValid: boolean;
-  private _ContorlSlefNexus: NexusNode;
+  private _ContorlSelfNexus: NexusNode;
 
   constructor(callbackManager: CallbackManager, selfNexus: NexusNode) {
     this._CallbackManager = callbackManager;
@@ -118,7 +107,7 @@ class ActorPackBuilder {
     this._AccKeeps = 0;
     this._NexusRecv = null;
     this._CommonInfoValid = false;
-    this._ContorlSlefNexus = selfNexus;
+    this._ContorlSelfNexus = selfNexus;
   }
 
   isInUsing() {
@@ -192,7 +181,10 @@ class ActorPackBuilder {
    *                       undefined时，若edgeX设置, 则把edge作为运动目标，以另一轴速度反推此速度, 否则不改变该轴速度
    * @param {double} ySpeed 运行速度，使用时会自动取绝对值，单位(pixel/帧)
    *                       undefined时，若targetY设置, 则把edge作为运动目标，以另一轴速度反推此速度, 否则不改变该轴速度
-   * @param {function} endCallback 参数(x, y) 运动到目标位置后的回调函数, x或者y达到后即回调，以先到为准，回报当前Actor的相对于原始位置的x,y
+   * @param {function | Array} endCallback 
+   *                        function: js消息通知(异步), 参数(x, y) 运动到目标位置后的回调函数, x或者y达到后即回调，以先到为准，
+   *                               回报当前Actor的相对于原始位置的x,y
+   *                        Array: 命令集
    * @return CommandPack(放入run或者then的CmdPackList队列)
    */
   public moveTo(
@@ -200,7 +192,7 @@ class ActorPackBuilder {
     edgeY: number | undefined,
     xSpeed: number | undefined,
     ySpeed: number | undefined,
-    endCallback: Function | null = null
+    endCallback: Function | Array<CommandPackType | Function> | null = null
   ) {
     if (!this._BasicPreProcess("moveTo")) {
       return;
@@ -221,18 +213,27 @@ class ActorPackBuilder {
     // 设置运动速度
     cmdList.push(ActionCmdBuilder.SetArrowSpeed(edgeX, edgeY, xSpeed, ySpeed));
 
+    // 统一 callback 入参：既支持 function，也支持 then 命令数组
+    let endCallbackCmdPackList = this._BuildCallbackCmdPackList(
+      endCallback,
+      (callback: Function, actorState: ActorState) => {
+        callback?.(actorState.xPos, actorState.yPos);
+      }
+    );
+
     // 设置达到目标位置的condition
     cmdList.push(
       ActOnReachPosition(
-        this,
         edgeX, edgeY,
-        [ActionCmdBuilder.StopMovingExact(),
-        this._NexusRecv ? StateCmdBuilder.FireNexusEvent(ActEventDefine.ActFinish, this._NexusRecv.token) : null
+        [
+          CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.AlignPosition()), 
+          CmdPackBuilder.InitStateCmdPack(ActionCmdBuilder.StopMoving()), // 不改keeps的action = state
+          this._NexusRecv ? 
+            CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.FireNexusEvent(ActEventDefine.ActFinish, this._NexusRecv.token)) 
+              : null,
+          endCallbackCmdPackList
         ],
         true,
-        endCallback ? (actorState: ActorState) => {
-          endCallback?.(actorState.xPos, actorState.yPos);
-        } : null
       )
     );
 
@@ -248,13 +249,15 @@ class ActorPackBuilder {
    *      xSpeed      (double) 带符号整数，符号表示方向，标识运动的运行速度，单位(pixel/帧), 可设undefined代表不改变该轴速度
    *      ySpeed      (double) 带符号整数，符号表示方向，标识运动的运行速度，单位(pixel/帧), 可设undefined代表不改变该轴速度
    *      spreadFrame    (int) 选填，正整数, 变速需要经历帧数, 若为立即变速，则设置为0，或者不再设置(undefined)
-   *      finishCallback (Function(xSpeed, ySpeed)) 选填，达到目标速度后的回调，当costTime不为0时有效
+   *      finishCallback (Function(xSpeed, ySpeed) | Array) 选填，达到目标速度后的处理，当costTime不为0时有效
+   *                              Function: js消息通知(异步), 回调参数为(xSpeed, ySpeed)
+   *                              Array: 命令集(会按 then 链路进行翻译处理)
    */
   altSpeed(
     xSpeed: number | undefined,
     ySpeed: number | undefined,
     spreadFrame: number | undefined,
-    finishCallback: Function | null = null
+    finishCallback: Function | Array<CommandPackType | Function> | null = null
   ) {
     if (!this._BasicPreProcess("altSpeed")) {
       return;
@@ -275,18 +278,26 @@ class ActorPackBuilder {
       // 均匀变速逻辑
       cmdList.push(ActionCmdBuilder.AltSpeed(xSpeed, ySpeed, spreadFrame));
 
+      // finishCallback 可传 function 或命令数组
+      let finishCallbackCmdPackList = this._BuildCallbackCmdPackList(
+        finishCallback,
+        (callback: Function, actorState: ActorState) => {
+          callback?.(actorState.xSpd, actorState.ySpd);
+        }
+      );
+
       // 创建结束ConditionSet
       cmdList.push(
         ActOnGetToSpeed(
-          this,
           xSpeed, ySpeed,
-          [ActionCmdBuilder.ResetAcc(0, 0),
-          this._NexusRecv ? StateCmdBuilder.FireNexusEvent(ActEventDefine.ActFinish, this._NexusRecv.token) : null
+          [
+            CmdPackBuilder.InitStateCmdPack(ActionCmdBuilder.SetAccel(0, 0)),
+            this._NexusRecv ? 
+              CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.FireNexusEvent(ActEventDefine.ActFinish, this._NexusRecv.token)) 
+                : null,
+            finishCallbackCmdPackList
           ],
           true, // isFinal
-          finishCallback ? (actorState: ActorState) => {
-            finishCallback(actorState.xSpd, actorState.ySpd);
-          } : null
         )
       )
 
@@ -299,14 +310,19 @@ class ActorPackBuilder {
    * 参数说明:
    *      targetX      (int) 带符号整数，目标运动终点位置，如果设置为undefined，标识不以此轴为终点
    *      targetY      (int) 带符号整数，目标运动终点位置，如果设置为undefined，标识不以此轴为终点
-   *      finishCallback  (Function(x,y)) 运动到目标位置后的回调函数, x或者y达到后即回调，以先到为准，回报当前Actor的相对于原始位置的x,y
-   *      rejectedCallback  (Function()) 当前速度无法达到target位置时，回调此函数，然后放弃改变任何速度和加速度
+   *      finishCallback  (Function(x,y) | Array) 运动到目标位置后的处理, x或者y达到后即触发，以先到为准，回报当前Actor相对于原始位置的x,y
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(推荐用于动作链路编排)
+   *      rejectedCallback  (Function() | Array) 当前速度无法达到target位置时的处理，然后放弃改变任何速度和加速度
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(推荐用于动作链路编排)
+   *      onFinishCommands (Array) 当执行完成的命令集, 对nexus响应的active/deactive调整放这里
    */
   brakeToPosition(
     targetX: number | undefined,
     targetY: number | undefined,
-    finishCallback: Function | null = null,
-    rejectedCallback: Function | null = null
+    finishCallback: Function | Array<CommandPackType | Function> | null = null,
+    rejectedCallback: Function | Array<CommandPackType | Function> | null = null,
   ) {
     // brakeToPosition 的设计
     // 1. 由native根据当前的速度值和目标位置，计算出正好能停止到目标点的减速度
@@ -317,7 +333,7 @@ class ActorPackBuilder {
     if (!this._NexusRecv) {
       // 此动作的结束由native来判断和决定
       // 要跟踪native的 ActFinish 事件
-      this._NexusRecv = this._ContorlSlefNexus;
+      this._NexusRecv = this._ContorlSelfNexus;
     }
 
     if (!this._BasicPreProcess("brakeToPosition")) {
@@ -334,31 +350,43 @@ class ActorPackBuilder {
     // 通过targetX和targetY以及内部当前的 xSpeed 和 ySpeed 状态，计算 xAcc 和 yAcc, 使运动接近目标位置时停止
     cmdList.push(ActionCmdBuilder.BrakeToPos(targetX, targetY));
 
+    // 结束回调统一走 _BuildCallbackCmdPackList，避免各接口重复包装逻辑
+    let finishCallbackCmdPackList = this._BuildCallbackCmdPackList(
+      finishCallback,
+      (callback: Function, actorState: ActorState) => {
+        callback?.(actorState.xPos, actorState.yPos);
+      }
+    );
+
+    // reject 回调同样支持 function/命令数组两种形态
+    let rejectedCallbackCmdPackList = this._BuildCallbackCmdPackList(
+      rejectedCallback,
+      (callback: Function) => {
+        callback?.();
+      }
+    );
+
     // 创建结束ConditionSet(ActFinish)
     cmdList.push(
       ActOnNexusEvent(
-        this,
         this._NexusRecv.token,
         ActEventDefine.ActFinish,
-        null,
-        true,
-        (actorState: ActorState) => {
-          finishCallback?.(actorState.xPos, actorState.yPos);
-        }
+        [
+          ...((finishCallbackCmdPackList || []) as Array<CommandPackType | Function | null>)
+        ],
+        true, // isFinal
       )
     );
 
     // 创建结束ConditionSet(ActReject)
     cmdList.push(
       ActOnNexusEvent(
-        this,
         this._NexusRecv.token,
         ActEventDefine.ActReject,
-        null,
-        true,
-        () => {
-          rejectedCallback?.();
-        }
+        [
+          ...((rejectedCallbackCmdPackList || []) as Array<CommandPackType | Function | null>)
+        ],
+        true
       )
     );
 
@@ -388,6 +416,28 @@ class ActorPackBuilder {
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
+  /*
+   * scaleSpeed 
+   * 按比例调整当前运行速度, 特别用于condition触发时，对当前render端速度具体值未知场景, 进行相对调整，立刻生效
+   * 
+   * 参数说明:
+   *      scaleX    (double) x 速度缩放比例, 可为负数, -1代表转向, 可以传入undefined来决定此值不设置
+   *      scaleY    (double) y 速度缩放比例, 可为负数, -1代表转向, 可以传入undefined来决定此值不设置
+   */
+  scaleSpeed(
+    scaleX: number | undefined,
+    scaleY: number | undefined,
+  ) {
+    if (!this._BasicPreProcess("scaleSpeed")) {
+      return;
+    }
+
+    let cmdList: Array<Object> = [];
+    cmdList.push(ActionCmdBuilder.ScaleSpeed(scaleX, scaleY));
+
+    return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
+  }
+
   /*
    * setSpeed 
    * 调整运行速度，立刻生效
@@ -395,12 +445,18 @@ class ActorPackBuilder {
    * 参数说明:
    *      spdX      (double) x 速度有效值，可正可负, 每帧的posX移动量, 可以传入undefined来决定此值不设置
    *      spdY      (double) y 速度有效值，可正可负, 每帧的posY移动量, 可以传入undefined来决定此值不设置
+   *      onRevertX (Function | Array) x速度过零反向时的处理
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(会按 then 链路进行翻译处理)
+   *      onRevertY (Function | Array) y速度过零反向时的处理
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(会按 then 链路进行翻译处理)
    */
   setAccel(
     accelX: number | undefined,
     accelY: number | undefined,
-    onRevertX: Function | null = null,
-    onRevertY: Function | null = null
+    onRevertX: Function | Array<CommandPackType | Function> | null = null,
+    onRevertY: Function | Array<CommandPackType | Function> | null = null
   ) {
     if (!this._BasicPreProcess("setAccel")) {
       return;
@@ -420,7 +476,7 @@ class ActorPackBuilder {
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
-  /*
+  /**
    * setSpdAndAccel 
    * 同时设置速度和加速度，并提供拐点回调(用于抛物线处理)
    * 
@@ -429,16 +485,20 @@ class ActorPackBuilder {
    *      spdY      (double) y 速度有效值，可正可负, 每帧的posY移动量, 可以传入undefined来决定此值不设置
    *      accelX    (double) 加速度有效值，可正可负，每帧spdX的调整量，可以传入undefined来决定此值不设置
    *      accelY    (double) 加速度有效值，可正可负，每帧spdY的调整量，可以传入undefined来决定此值不设置
-   *      onRevertX (function) x速度开始反向运动时，进行回调(例如抛物到达顶点)
-   *      onRevertY (function) y速度开始反向运动时，进行回调(例如抛物到达顶点)
+   *      onRevertX (Function | Array) x速度开始反向运动时的处理(例如抛物到达顶点)
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(会按 then 链路进行翻译处理)
+   *      onRevertY (Function | Array) y速度开始反向运动时的处理(例如抛物到达顶点)
+   *                              Function: js消息通知(异步), 不要把新的run需求放这里, 会导致时机控制不准
+   *                              Array: 命令集(会按 then 链路进行翻译处理)
    */
   setSpdAndAccel(
     spdX: number | undefined,
     spdY: number | undefined,
     accelX: number | undefined,
     accelY: number | undefined,
-    onRevertX: Function | null = null,
-    onRevertY: Function | null = null
+    onRevertX: Function | Array<CommandPackType | Function> | null = null,
+    onRevertY: Function | Array<CommandPackType | Function> | null = null
   ) {
     if (!this._BasicPreProcess("setSpdAndAccel")) {
       return;
@@ -461,10 +521,12 @@ class ActorPackBuilder {
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
-  /*
+  /**
    * stopMoving
    * 停止运动
-   *      isExact (boolean) 设置为true时, 如果在positionCondition中会按照condition的位置进行精准停止
+   *      isExact (boolean) 设置为true时, 
+   *          如果在positionCondition中会按照condition的位置进行精准停止
+   *          从而解决在condition.then中停止时,停止的位置因为上帧的drawX/Y + speedX/Y并不是完全和condition不吻合,而希望吻合的问题
    */
   stopMoving(
     isExact: boolean = true
@@ -474,21 +536,43 @@ class ActorPackBuilder {
     }
 
     let cmdList: Array<Object> = [];
-    cmdList.push(isExact ? ActionCmdBuilder.StopMovingExact() : ActionCmdBuilder.StopMoving());
+    if (isExact) {
+      cmdList.push(StateCmdBuilder.AlignPosition());
+    }
+    cmdList.push(ActionCmdBuilder.StopMoving());
+
+    return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
+  }
+
+  /**
+   * alignSpeed
+   * 在condition().then()中使用, 只在speed相关的condition中才会响应
+   * 用condition的速度设定值,来校准speed值, 相当于用condition的speed值来进行 action().setSpeed()
+   * 以解决加速对速度进行改变后，速度值已经超过了condition中设定的阈值时, 想纠正回来的场景
+   * 
+   * 标准的停止加速度但保持速度的方法为: action(FreeMoveDef.KeepFlags.XY, 0).alignSpeed()
+   * 即通过action()构建的第二个参数把加速度清除
+   */
+  alignSpeed() {
+    if (!this._BasicPreProcess("alignSpeed")) {
+      return;
+    }
 
+    let cmdList: Array<Object> = [];
+    cmdList.push(ActionCmdBuilder.alignSpeed());
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
   /**
    * ackMovementSync
-   * 只能放在 movementSync 的then中，用于将Sync同步信息按比例转化成
+   * 只能放在 movementSync 的then中，用于将Sync同步信息按比例转化成自身的freeMoveDiv的位置值
    * (注意): 如果触发链条上有自己发出的信息，则将不再产生动作，规避循环触发
    * 
    * @param {int} horizontalStart  横向运动识别区域的0%对应位置, 可以为负
    * @param {int} horizontalEnd  横向运动识别区域的100%对应位置, 可以为负，可以小于start
    * @param {int} verticalStart  纵向运动识别区域的0%对应位置, 可以为负
    * @param {int} verticalEnd  纵向运动识别区域的100%对应位置, 可以为负，可以小于end
-   * @param {int} xyEnable  x,y是否都触发, 0b01对应x, 0b10对应y, 可以或运算在一起
+   * @param {int} xyEnable  x,y是否都触发, 使用FreeMoveDef.KeepFlags设置x,y,或者xy
    * @param {int} syncType 换算公式: 
    *                        1: 正比公式:selfPercent = givenPercent  
    *                        2: 反比公式:selfPercent = (1 - givenPercent)
@@ -513,12 +597,26 @@ class ActorPackBuilder {
   }
 
   _BuildAccelOnPole(
-    builderThis: ActorPackBuilder,
+    builderThis: ActionPackBuilder,
     cmdList: Array<Object>,
     nexusRecv: NexusNode | null,
-    onRevertX: Function | null,
-    onRevertY: Function | null
+    onRevertX: Function | Array<CommandPackType | Function> | null,
+    onRevertY: Function | Array<CommandPackType | Function> | null
   ) {
+    // 拐点回调，支持函数或命令数组
+    let onRevertXCmdPackList = this._BuildCallbackCmdPackList(
+      onRevertX,
+      (callback: Function) => {
+        callback?.();
+      }
+    );
+    let onRevertYCmdPackList = this._BuildCallbackCmdPackList(
+      onRevertY,
+      (callback: Function) => {
+        callback?.();
+      }
+    );
+
     if (nexusRecv || onRevertX || onRevertY) {
       // RefObj: 外界可能希望了解速度拐点的ActEvent
       // onRevertX || onRevertY: 通过callback希望了解速度拐点信息
@@ -526,31 +624,56 @@ class ActorPackBuilder {
       // X轴拐点检测 newCondition
       cmdList.push(
         ActOnGetAcrossSpeed(
-          builderThis,
           0, undefined,
-          [nexusRecv ? StateCmdBuilder.FireNexusEvent(ActEventDefine.SpeedRevertX, nexusRecv.token) : null],
+          [
+            nexusRecv ? CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.FireNexusEvent(ActEventDefine.SpeedRevertX, nexusRecv.token)) : null,
+            ...((onRevertXCmdPackList || []) as Array<CommandPackType | Function | null>)
+          ],
           false, // isFinal
-          onRevertX ? () => {
-            onRevertX();
-          } : null
         )
       )
 
       // Y轴拐点检测 newCondition
       cmdList.push(
         ActOnGetAcrossSpeed(
-          builderThis,
           undefined, 0,
-          [nexusRecv ? StateCmdBuilder.FireNexusEvent(ActEventDefine.SpeedRevertY, nexusRecv.token) : null],
+          [
+            nexusRecv ? CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.FireNexusEvent(ActEventDefine.SpeedRevertY, nexusRecv.token)) : null,
+            ...((onRevertYCmdPackList || []) as Array<CommandPackType | Function | null>)
+          ],
           false, // isFinal
-          onRevertY ? () => {
-            onRevertY();
-          } : null
         )
       )
     }
   }
 
+  private _BuildCallbackCmdPackList(
+    callback: Function | Array<CommandPackType | Function> | null,
+    callbackInvoker?: (callback: Function, actorState: ActorState) => void,
+  ): Array<CommandPackType | Function | null> | null {
+    if (!callback) {
+      return null;
+    }
+    if (Array.isArray(callback)) {
+      // then 场景里的函数需要先翻译成内部 callbackCmd
+      TranslateCondThenCmdPackList(this._CallbackManager, callback);
+      return callback;
+    }
+    if (typeof callback === "function") {
+      // 纯函数回调统一包装成 callbackCmd，便于放入 command list
+      return [CmdPackBuilder.InitStateCmdPack(this._CallbackManager.buildCallbackCmd(
+        (actorState: ActorState) => {
+          if (callbackInvoker) {
+            callbackInvoker(callback, actorState);
+          } else {
+            callback?.(actorState);
+          }
+        }
+      ))];
+    }
+    return null;
+  }
+
   _BasicPreProcess(procName: string) {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
@@ -571,4 +694,4 @@ class ActorPackBuilder {
   }
 }
 
-export default ActorPackBuilder;
+export default ActionPackBuilder;