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

package/utils/JsViewVueWidget/JsvDomRenderer/index.ts

@@ -0,0 +1 @@
+export { default as JsvDomRenderer } from "./JsvDomRenderer"

package/utils/JsViewVueWidget/JsvDragBox/JsvDragBox.vue

@@ -75,6 +75,7 @@ let vOnDragStart = null;
 let vOnDragRelease = null;
 
 function initDragBox() {
+  // 定制dragBox的活动区域
   cController.run((cmds) => [
     cmds.state().removeConditionByGroup(cWallConditionGroup),
     cmds
@@ -109,6 +110,7 @@ function setSensor(callback, sensitivity) {
       cmds.state().removeConditionByGroup(cSensorConditionGroup),
     ]);
     if (callback != null) {
+      // 设置运动过程位置信息的回调
       cController.run((cmds) => [
         cmds
           .condition(cSensorConditionGroup, true)
@@ -131,6 +133,7 @@ function moveTo(left, top) {
     );
     return;
   }
+  // 接受moveTo坐标，主动移动到指定位置
   cController.run((cmds) => [cmds.action().teleportTo(left, top)]);
 }
 
@@ -144,6 +147,9 @@ onMounted(() => {
   }
   let divView = rMainDiv.value.jsvGetProxyView();
   cController.bindForgeView(divView, true);
+  // TOUCH_RECV_MOVE_BIT 激活跟随触控位置移动
+  // TOUCH_RECV_FIRST_START 激活首次触摸开始的事件, 让condistion.onDragStart生效
+  // TOUCH_RECV_LAST_END 激活最后一次触摸结束的事件, 让condistion.onTouchRelease生效
   divView.DragEnables?.(
     ForgeConst.DragFlags.TOUCH_RECV_MOVE_BIT |
       // (cEnableFling ? ForgeConst.DragFlags.TOUCH_RECV_FLING_BIT : 0) |
@@ -157,9 +163,12 @@ onMounted(() => {
     typeof props.dragRect.left == "number" ? props.dragRect.left : 0;
   let initTop = typeof props.dragRect.top == "number" ? props.dragRect.top : 0;
   if (initLeft != 0 || initTop != 0) {
+    // 将dragBox移动到初始位置
     cController.run((cmds) => [cmds.action().teleportTo(initLeft, initTop)]);
   }
 
+  // 注册 onDragStart 和 onTouchRelease 回调
+  // 制作初始的onSensor回调，敏感度默认为10
   cController.run((cmds) => [
     cmds
       .condition(undefined, true)
@@ -189,7 +198,7 @@ onMounted(() => {
       ]),
     cmds
       .condition(cSensorConditionGroup, true)
-      .onMovement(10) // 默认设置x或y移动超过10时才触发回调，以此减少回调的频次，规避js的性能影响
+      .onMovement(vSensitivity) // 默认设置x或y移动超过10时才触发回调，以此减少回调的频次，规避js的性能影响
       .then([onSensor]),
   ]);
 });

package/utils/JsViewVueWidget/JsvEnableRenderBreak.vue

@@ -1,3 +1,9 @@
+<!--
+ * @file 
+ *
+ * 此组件目前并不建议应用端使用，目前没有非常合适的应用场景
+-->
+
 <script setup>
 import { RENDER_ITEM_BREAK_KEY } from "../JsViewEngineWidget/WidgetCommon";
 import { shallowRef } from "vue";

package/utils/JsViewVueWidget/JsvFlexCell/JsvFlexDiv.vue

@@ -69,12 +69,18 @@ let SizeHeight = shallowRef(undefined);
 let onSizeCallback = (x, y, width, height) => {
   SizeX.value = x;
   SizeY.value = y;
-  SizeWidth.value = width;
-  SizeHeight.value = height;
 
-  if (width != 0 && height != 0) {
-    // 忽略0尺寸这个中间过程的回调
-    props.onSized?.(width, height);
+  let origin_width = SizeWidth.value;
+  let origin_height = SizeHeight.value; 
+
+  if (origin_width != width || origin_height != height) {
+    SizeWidth.value = width;
+    SizeHeight.value = height;
+
+    if (width != 0 && height != 0) {
+      // 忽略0尺寸这个中间过程的回调
+      props.onSized?.(width, height);
+    }
   }
 };
 let containerRef = shallowRef(null);

package/utils/JsViewVueWidget/JsvFlexCell/JsvFullScrAdjust.vue

@@ -145,7 +145,9 @@ defineExpose({
         transform: rScaleSet,
       }"
     >
-      <slot />
+      <div data-jsv-vw-as-bound-anchor="true">
+        <slot />
+      </div>
     </div>
   </jsv-screen-flex>
 </template>

package/utils/JsViewVueWidget/JsvFlexCell/JsvScreenFlex.vue

@@ -18,6 +18,8 @@
  *          askSize: boolean  设置会跟进flex的尺寸变化，设置后可通过getWidth/getHeight拿到尺寸，但会降低性能
  *          onSized: Function(width:number, height:number) 
                 比askSize更进一步，可以通过回调知道尺寸变化后的时机，回调参数(width, height)为flex后的尺寸*          background: {string} (选填)背景图案 可选值: 绝对路径url|url(相对路径url)|#FFFFFF|rbga(255,0,0,1.0)
+            background: {string} (选填)背景图片url或者背景颜色 可选值: #FFFFFF|rbga(255,0,0,1.0)
+                                背景图会被按照objectFit:cover的形式显示
  *
  *      expose说明:
  *          getWidth():  当askSize或者onSize生效时，获取元素的宽度
@@ -85,7 +87,7 @@ watchEffect(() => {
       const texture_manager = ForgeHandles.TextureManager;
       if (
         vTextureStringCache.trim().startsWith("#") ||
-        vTextureStringCache.trim().startsWith("rgba")
+        vTextureStringCache.trim().startsWith("rgb")
       ) {
         texture_setting = new Forge.TextureSetting(
           ForgeTextureApis.GetColorTexture(texture_manager, vTextureStringCache)

package/utils/JsViewVueWidget/JsvFragShaderView/JsvFragShaderView.vue

@@ -12,6 +12,7 @@
  *           @prop {Array}      uniforms       uniform参数, [{ name: string, value: number }]
  *           @prop {Array}      textures       texture参数, [{ name: string, resource: string }]
  *           @prop {() => void} onStart        动画开始回调
+ *           @prop {boolean}    reverseAnimate 是否反向动画
  *           @prop {(int,boolean) => void} onEnd
  *                                动画结束回调,
  *                                返回值1号 int: 回到参数为动画的序列号，和startAnim的返回值匹配
@@ -65,6 +66,10 @@ const rProps = defineProps({
     type: Boolean,
     default: false,
   },
+  reverseAnimate: {
+    type: Boolean,
+    default: false,
+  },
   shaderStr: {
     type: String,
     required: true,
@@ -83,13 +88,16 @@ const rProps = defineProps({
   onStart: {
     type: Function,
   },
+  // 是否已经在外部保证其加载性了
+  loadComfirmed: {
+    type: Boolean,
+    default: false,
+  },
 });
 
 // 激活引擎中的功能支持
 JsvUseFeature("JsvFragShaderView", FeatureNames.CustomFragShader);
 
-console.log("LudlDebug using JsvFragShaderView...");
-
 let rAnimRunning = shallowRef(false); // 动画是否在执行，画面只在动画进行时进行显示
 let vPreloadHandler = null;
 let vPreloadDone = false;
@@ -133,9 +141,9 @@ if (rProps.textures) {
       });
       preload_textures.push(new JsvTextureLoadTool.ItemSet(image_url));
     }
-
-    // 对图片进行预加载，等所有图片预加载完成后才能开始动画，以确保动画的完整性
-
+  }
+  // 对图片进行预加载，等所有图片预加载完成后才能开始动画，以确保动画的完整性
+  if (!rProps.loadComfirmed) {
     vPreloadHandler = JsvTextureLoadTool.preload(preload_textures, () => {
       vPreloadDone = true;
 
@@ -154,6 +162,12 @@ if (rProps.textures) {
         vStartingPromise.resolve();
       }
     }
+  } else {
+    // 已经确认加载性, 不再做preload
+    vPreloadDone = true;
+    if (vStartingPromise != null) {
+      vStartingPromise.resolve();
+    }
   }
 }
 
@@ -178,7 +192,7 @@ function clearStartAnimTimeout() {
   }
 }
 
-const startAnim = (alt_duration, on_timeout_func) => {
+const startAnim = (alt_duration, on_timeout_func, reverse = false) => {
   vStartingPromise = null; // 重置promise回执处理
   rAnimRunning.value = false;
   vStartToken++;
@@ -223,7 +237,9 @@ const startAnim = (alt_duration, on_timeout_func) => {
 
       if (duration > 0) {
         let shaderAnimation = new Forge.ShaderAnimation(duration, null);
-        shaderAnimation.Enable(0x1); // ReleaseAfterEndCallback
+        shaderAnimation.Enable(
+          0x1 | (reverse ? Forge.AnimationEnable.Reverse : 0)
+        ); // ReleaseAfterEndCallback
         shaderAnimation.SetAnimationListener(
           new Forge.AnimationListener(
             null /* animation的onStart目前不调用 */,
@@ -263,7 +279,7 @@ const stopAnim = () => {
 
 onMounted(() => {
   if (rProps.autoplay) {
-    startAnim(rProps.duration);
+    startAnim(rProps.duration, undefined, rProps.reverseAnimate);
   }
 });
 

package/utils/JsViewVueWidget/JsvFreeMoveActor/ActorControl.ts

@@ -4,11 +4,87 @@
  * @LastEditors: donglin.lu@qcast.cn
  * @Description: file content
  */
+
+/*
+ * ActorControl
+ * 对 JsvFreeMoveActorDiv 进行控制
+ * 
+ * 开发者通过 ActorControl 的实例, 来对 JsvFreeMoveActorDiv 进行控制, 思路:
+ * 拿到ActorControl实例后, 通过 run(cmdPackList) 讲编排好的指令集一次性组织好, 送到render进行执行,
+ * 执行过程中，除了condition触发的(ActorState)=>{} 类型的回调外, 其余动画处理都不会与js端进行交互。
+ * 
+ * 进行动画设计时, 尽量避免 (ActorState)=>{} 回调中再调用 ActorControl.run(...)的模式, 以规避js性能低的问题影响到动画的流畅性。
+ * 比较好的设计模式是, ActorControl.run(...) 几乎都是界面初始化或者用户输入时进行(例如focusBlock的onKeyDown),
+ * 而 (ActorState)=>{} 回调中, 最好只放置辅助用户输入判断的状态的更新, 以及 state().updateBaseOffset(...) 这种对dom元素进行重新定位的场景。
+ * dom元素重新定位也一般只用于动画结束,要永久保留动画后的位置的场景。
+ * 
+ * cmdPackList: 
+ *     由 action(), state(), condition() 组成的指令集
+ *     在condition().xxxx.then() 中, 多一种指令类型 (actorState)=>{}, 用于对接此condition触发后, 讲actor信息同步给js
+ * 
+ * ------------------------------------------------------------
+ * 以下是 JsvFreeMoveActorDiv 中坐标概念说明:
+ * 
+ * JsvFreeMoveActorDiv 的基准坐标: baseX, baseY
+ * 此坐标不会被直接记录, 在组件内部以 baseOffsetX, baseOffsetY 记录, 初始值为(0, 0)
+ * baseX = -baseOffsetX
+ * baseY = -baseOffsetY
+ * 主要用于解决div的style.top, style.left改变前后, condition设置的条件中的坐标不会发生偏移。
+ * 具体思路是: condition创建时, 会记录当时的 baseOffset 坐标, 进行判断的时候将其条件中设定的x和y以当时记录的baseOffset转成baseX和baseY坐标,
+ * 而与之进行比较的 drawX 和 drawY, 也通过最新的baseOffset转成baseX和baseY坐标, 然后再进行比较。
+ * baseOffset的变更, 发生在本div的style.top, style.left进行改变时, 开发者会通过 state().updateBaseOffset(
+ *     newStyle.top - originStyle.top, 
+ *     newStyle.left - originStyle.left) 主动同步信息到控制系统。
+ * 
+ * JsvFreeMoveActorDiv 的绘制坐标: drawX, drawY
+ * 
+ * JsvFreeMoveActorDiv 的最终屏幕坐标:
+ * x = 父dom节点的屏幕坐标x + 本div的style.left + drawX;
+ * y = 父dom节点的屏幕坐标y + 本div的style.top + drawY;
+ * 
+ * ------------------------------------------------------------
+ * 每个JsvFreeMoveActorDiv内部状态变量分为8个:
+ * drawX: 参考上述坐标说明, 每帧会被SpeedX调整, 也可通过 action() 或者 state() 直接改变
+ * drawY: 参考上述坐标说明, 每帧会被SpeedY调整, 也可通过 action() 或者 state() 直接改变
+ * baseOffsetX: 参考上述坐标说明, 改变方式只有 state().updateBaseOffset(...)
+ * baseOffsetY: 参考上述坐标说明, 改变方式只有 state().updateBaseOffset(...)
+ * SpeedX: 帧间运行后，对drawX的增量, 只能通过 action() 改变
+ * SpeedY: 帧间运行后，对drawY的增量, 只能通过 action() 改变
+ * AccelerationX: 帧间运行后，对SpeedX的增量, 只能通过 action() 改变
+ * AccelerationY: 帧间运行后，对SpeedY的增量, 只能通过 action() 改变
+ * 
+ * ------------------------------------------------------------
+ * 请仔细阅读action和state的注释说明, 了解action和state的区别
+ * 
+ * ------------------------------------------------------------
+ * 为具体业务定制命令集的work flow:
+ * 1. 确认初始运动位置, 速度和初速度, 位置通过 state.setStartPos设置, 速度和加速度通过action设置(X和Y分开设计, 比如抛物线)
+ * 2. 定义运动边界和运动边界后的行为, 通常的运动边界行为为: 停止, 回弹(X方向和Y方向分开设计)
+ * 3. 定义运动中的突变控制, 通过 nexus -> 命令集 的方式设置, 即:
+ *    通过 let nexusRecv = FreeMoveApis.newNexus() 创建nexusRecv
+ *    然后通过 condition().onCustomNexus(nexusRecv) 定义响应后的控制命令集
+ *    再在用户输入处理(如按键响应回调)中用 FreeMoveApis.fireCustomNexus(nexusRecv) 来激发对应的condition。
+ *        如有需要也可在condition().then的命令集中用 state.fireCustomNexus(nexusRecv) 来激发对应的condition。
+ *    nexus激发的condition.then的命令集中建议使用相对数值调整的api(action/state):
+ *      a. 位置的相对数值调整api: state.setStartOffsetPos
+ *      b. 速度的相对数值调整api: action.scaleSpeed
+ *      c. 加速度目前没有随时间变化而变化的场景, 所以暂时没有相对数值调整的api
+ * 4. 中途点规划:
+ *    中途点规划为通过condition设置position或者speed的中途点的js回调, 例如:
+ *      a. Position超过了某个位置(通常使用reachPosition)
+ *      b. Speed达到拐点(抛物线)
+ *    在这类js回调中, 主要进行清理不在需要的中途点condition, 创建新的中途点condition, 并引进中途点的状态, 可以重新定制nexus的行为。
+ *    比如滚动轴比较长并且数据可以动态追加的场景: 建议中途点的规划可以覆盖大概200ms时间对应的物体能运动的范围
+ * 5. 命令集在run之后就定型了, 代码里面的响应式变量是不会响应更新的, 所以对于condition触发后CustomNexus对应的命令集要更换的场景,
+ *    在创建CustomNexus时, 用condition的specName或者group进行分类,预制所有种类的命令集, 
+ *    在触发命令集要更换的condition().then中通过 activeCondition 激活对应命令集, deactiveCondition 关闭其他命令集
+ *    
+ */
+
 import ConditionPackBuilder from "./SetCondition";
 import ActionPackBuilder from "./SetAction"
 import StatePackBuilder from "./SetState";
 import CallbackManager from "./CallbackManager";
-import ActionRefObject from "./ActionRefObject";
 import { RunFreeMoveCmdPacks, FreeMoveAnimClass, FinishRenderBreak } from "./ForgeTypeDefine"
 import { NexusNode, newNexus } from "./NexusNode";
 
@@ -16,6 +92,19 @@ interface CmdListCreator {
   (builders: BuilderFactory): Array<Object>;
 }
 
+interface ConditionConfig {
+  group?: number;
+  multiTimes?: boolean;
+  specName?: string | null;
+  shoudRenderBreak?: boolean;
+}
+
+interface ActionConfig {
+  xySpeedKeeps?: number;
+  xyAccKeeps?: number;
+  nexusRecv?: NexusNode | null;
+}
+
 class BuilderFactory {
   private _SharedQuickConditionPackBuilder: ConditionPackBuilder;
   private _SharedQuickActionPackBuilder: ActionPackBuilder;
@@ -36,67 +125,167 @@ class BuilderFactory {
 
   /**
    * Condition
-   * 获取创建 ConditionPack 的工厂对象
+   * 获取创建 Condition指令 的工厂对象
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.condition(...).条件指令(...).then([  // 条件指令: 例如 wallPosition()
+   *       cmds.condition(...).其他条件指令(...),  // 其他condition创建
+   *       (actorState)=>{
+   *         // 条件满足时预设的指令集
+   *         console.log(
+   *           "condition triggered",
+   *           actorState.xPos, actorState.yPos,
+   *           actorState.xSpd, actorState.ySpd,
+   *           actorState.xAcc, actorState.yAcc);
+   *       },
+   *       ...  // 其他command
+   *     ]),
+   *     ...  // 其他command
+   *   ]);
+   * 
    * ConditionPack对应支持 .then(cmdPackList), 可传入同 Run 的处理队列
-   * 可用方法见 ./SetCondition.js
-   * @param {int} group 可选参数，默认为0, 有效值为0~3, 对应默认组, 1组, 2组, 3组, 便于remove时，按组进行清理
+   * cmdPackList中是新的由 action(), state(), condition(), (actorState)=>{} 组成的指令集
+   * 其中(actorState)=>{} 是 condition().xxxx.then() 中独有的指令类型, 用于对接此condition触发后, 进行js端的回调
+   * actorState {
+   *   xPos: number, // 当前drawX的值
+   *   yPos: number, // 当前drawY的值
+   *   xSpd: number, // 当前SpeedX的值
+   *   ySpd: number, // 当前SpeedY的值
+   *   xAcc: number, // 当前AccelerationX的值
+   *   yAcc: number, // 当前AccelerationY的值
+   * }
+   * 
+   * 创建condition时, 会记录当时的 baseOffset 坐标, 其设定值在进行比较时会转换成baseX和baseY坐标, 然后进行比较
+   * 所以不同担心div的style.top, style.left改变后, condition设置的条件中的坐标会发生偏移导致需要重新设置
+   * 比如: wallPosition(), boxPosition() 这种要常驻的condition
+   * 
+   * boxPosition 用法示例(边界框与背景div尺寸一致):
+   *   // div1 背景: (0, 0) -> (400, 400)
+   *   cmds.condition({ multiTimes: true })
+   *     .boxPosition(0, 0, 400, 400)
+   *     .then([cmds.action().stopMoving(true)]);
+   * 
+   *   // div2 背景: (0, 0) -> (200, 200)
+   *   cmds.condition({ multiTimes: true })
+   *     .boxPosition(0, 0, 200, 200)
+   *     .then([cmds.action().stopMoving(true)]);
+   * 
+   * condition创建时, 可以用group和specName进行归类, 以便于后续按需清理, 例如: 
+   * wallPosition()在一启动的时候有, 后续就没有了, 而还有其他condition存在, 不能使用state().clearConditions()全清理
+   * 
+   * action指令内部也可能自己创建一些associated condition, 这些condition会被action执行完成后自动回收, 不需要通过state指令主动清理
+   * 
+   * 可用方法见 @file://./SetCondition.ts 的 ConditionPackBuilder 类
+   * @param {int | ConditionConfig} configOrGroup 可选参数，默认为0, 有效值为0~3, 对应默认组, 1组, 2组, 3组, 便于remove时，按组进行清理, 单个Anim中唯一, Anim之间可重名
+   *                                     也可以传入一个Object, 包含 group, multiTimes, specName, shoudRenderBreak 四个属性
    * @param {boolean} multiTimes 可选参数，默认为false, 是否要多次执行, 
    *                      若为单次, 当group未设定时自动作废，当group设定时，不作废但改为deactive状态
-   * @param {string} specName 可选参数，默认null, 命名condition, 用于指定名字进行active/deactive动作的场景
+   * @param {string} specName 可选参数，默认null, 命名condition, 单个Anim中唯一, Anim之间可重名, 用于指定名字进行active/deactive动作的场景
    * @param {boolean} shoudRenderBreak 可选参数，默认false, 关联的回调是否会发起RenderBreak
-   * @return {ConditionPackBuilder} ConditionPack 的工厂对象
+   * @return {ConditionPackBuilder} Condition指令的工厂对象
    */
   condition(
-    group: number = 0,
-    multiTimes: boolean = false,
-    specName: string | null = null,
-    shoudRenderBreak: boolean = false
+    configOrGroup?: ConditionConfig | number,
+    multiTimes?: boolean,
+    specName?: string | null,
+    shoudRenderBreak?: boolean
   ): ConditionPackBuilder {
+    let _group: number = 0;
+    let _multiTimes: boolean = false;
+    let _specName: string | null = null;
+    let _shoudRenderBreak: boolean = false;
+
+    if (typeof configOrGroup === 'object') {
+      _group = (configOrGroup as ConditionConfig).group || 0;
+      _multiTimes = (configOrGroup as ConditionConfig).multiTimes || false;
+      _specName = (configOrGroup as ConditionConfig).specName || null;
+      _shoudRenderBreak = (configOrGroup as ConditionConfig).shoudRenderBreak || false;
+    } else {
+      _group = configOrGroup ?? 0;
+      _multiTimes = multiTimes ?? false;
+      _specName = specName ?? null;
+      _shoudRenderBreak = shoudRenderBreak ?? false;
+    }
+
     // 注意: 不支持获取condition后，多次复制
     let builder: ConditionPackBuilder = this._SharedQuickConditionPackBuilder;
     if (builder.isInUsing()) {
       // 用于加速的builder被占用了，为了防止状态问题，使用新建builder
       builder = new ConditionPackBuilder(this._Callbacks, this._SelfNexusRecv, this);
     }
-    builder.updateCommandInfo(group, multiTimes, specName, shoudRenderBreak);
+    builder.updateCommandInfo(_group, _multiTimes, _specName, _shoudRenderBreak);
     return builder;
   }
 
   /**
    * Action
-   * 获取创建 ActionPack 的工厂对象
-   * 注意: ActionPack 是指会改变 speed 或 accelerate 并自动生成子condition的指令，
-   * 每个新的Action会覆盖掉前一次的Action设置，包括其关联的condition，
-   * 以及上一个action中的回调，以及上一个action中规划中的ActionEvent
-   * 可用方法见 ./SetAction.js
+   * 获取创建 Action指令 的工厂对象
    * 
-   * @param {int} xySpeedKeeps xy轴上的速度是否保持(与新Action不冲突的才会被保留)，
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.action(...).动作指令(...),  // 动作指令: 例如 teleportOffset()
+   *     ...  // 其他command
+   *   ]);
+   * 
+   * Action主要是改变speed和accelerate的值，在Action指令中还包含一些综合指令, 例如:
+   *    brakeToPosition: 通过内部创建一些associated condition来实现减速并停止到目标位置
+   *    setSpdAndAccel: 同时设置速度和加速度，并提供拐点回调(用于抛物线处理)
+   * 
+   * Action有个重要个规则: 一个FreeMoveActor中, 一个时间只会激活一条Action指令,
+   * 当下一条Action指令激活时, 会默认自动重置因为上一条Action而改变的SpeedX/Y(重置为0), AccelerationX/Y(重置为0), 以及其associated condition
+   * 但也可以进行主动保持, 通过 xySpeedKeeps 和 xyAccKeeps 参数控制
+   * 
+   * 可用方法见 @file://./SetAction.ts 的 ActionPackBuilder 类
+   * 
+   * @param {int | ActionConfig} configOrSpeedKeeps xy轴上的速度是否保持(与新Action不冲突的才会被保留)，
    *                           x轴保持为1, y轴保持为2，可"与或"让两个轴都保持
+   *                           也可以传入一个Object, 包含 xySpeedKeeps, xyAccKeeps, nexusRecv 三个属性
    * @param {int} xyAccKeeps xy轴上的加速度是否保持(与新Action不冲突的才会被保留)，
    *                         x轴保持为1, y轴保持为2，可"与或"让两个轴都保持
    * @param {NexusNode} nexusRecv 此动作发出的 nexusEvent 的接受者
-   * @return {ActionPackBuilder} ActionPack 的工厂对象
+   * @return {ActionPackBuilder} Action指令的工厂对象
    */
   action(
-    xySpeedKeeps: number = 0,
-    xyAccKeeps: number = 0,
-    nexusRecv: NexusNode | null = null
+    configOrSpeedKeeps?: ActionConfig | number,
+    xyAccKeeps?: number,
+    nexusRecv?: NexusNode
   ): ActionPackBuilder {
+    let _xySpeedKeeps: number = 0;
+    let _xyAccKeeps: number = 0;
+    let _nexusRecv: NexusNode | null = null;
+
+    if (typeof configOrSpeedKeeps === 'object') {
+      _xySpeedKeeps = (configOrSpeedKeeps as ActionConfig).xySpeedKeeps || 0;
+      _xyAccKeeps = (configOrSpeedKeeps as ActionConfig).xyAccKeeps || 0;
+      _nexusRecv = (configOrSpeedKeeps as ActionConfig).nexusRecv || null;
+    } else {
+      _xySpeedKeeps = configOrSpeedKeeps ?? 0;
+      _xyAccKeeps = xyAccKeeps ?? 0;
+      _nexusRecv = nexusRecv ?? null;
+    }
+
     let builder: ActionPackBuilder = this._SharedQuickActionPackBuilder;
     if (builder.isInUsing()) {
       // 用于加速的builder被占用了，为了防止状态问题，使用新建builder
       builder = new ActionPackBuilder(this._Callbacks, this._SelfNexusRecv);
     }
-    builder.updateCommonInfo(xySpeedKeeps, xyAccKeeps, nexusRecv);
+    builder.updateCommonInfo(_xySpeedKeeps, _xyAccKeeps, _nexusRecv);
     return builder;
   }
 
   /**
    * State
-   * 获取创建 StatePack 的工厂对象
+   * 获取创建 State指令 的工厂对象
+   * 
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.state(...).状态指令(...),  // 状态指令: 例如 clearConditions()
+   *     ...  // 其他command
+   *   ]);
+   * 
    * 在下一帧运行前的设置值，例如清理condition, 或者在下一帧运动的前调整启动运动的位置
-   * 可用方法见 ./SetState.js
-   * @return {StatePackBuilder} StatePack 的工厂对象
+   * 可用方法见 @file://./SetState.ts 的 StatePackBuilder 类
+   * @return {StatePackBuilder} State指令的工厂对象
    */
   state(): StatePackBuilder {
     return this._StatePackBuilder;
@@ -122,6 +311,11 @@ class ActorControl {
     this._Builders = new BuilderFactory(this, this._Callbacks, this._SelfNexusRecv);
   }
 
+  /**
+   * 内部API
+   * 
+   * asSizeMode
+   */
   asSizeMode() {
     if (this._BindAnim != null) {
       console.error("error: asSizeMode should call before bindForgeView");
@@ -134,6 +328,15 @@ class ActorControl {
   //   return this._BindAnim?.AnimNativeId;
   // }
 
+  /**
+   * 内部API
+   * 
+   * bindForgeView
+   * 为普通的div创建ActorControl控制
+   * 
+   * @param {any} bindView forgeView实例
+   * @param {boolean} instantActive 是否立即激活动画
+   */
   bindForgeView(bindView: any, instantActive: boolean) {
     this._BindView = bindView;
 
@@ -143,7 +346,26 @@ class ActorControl {
   }
 
   /**
-   * run 执行编排好的intent集合
+   * run 创建并执行编排好的指令队列
+   * 
+   * 用法为
+   * actorControl.run((cmds)=>[ // 指令队列
+   *   cmds.state(...).状态指令(...),
+   *   cmds.action(...).动作指令(...),
+   *   cmds.condition(...).条件指令(...).then([
+   *     // 条件满足时预设的指令集队列
+   *     cmds.condition(...).其他条件指令(...),
+   *     (actorState)=>{
+   *       console.log(
+   *         "condition triggered",
+   *         actorState.xPos, actorState.yPos,
+   *         actorState.xSpd, actorState.ySpd,
+   *         actorState.xAcc, actorState.yAcc);
+   *     },
+   *     ...
+   *   ]),
+   *   ...
+   * ]);
    *
    * @param {CmdListCreator} commandsCreator 
    *                         命令指令队列创建回调
@@ -176,11 +398,21 @@ class ActorControl {
     RunFreeMoveCmdPacks(this._BindView, cmdPackList);
   }
 
+  /**
+   * 内部API
+   * 
+   * getBindedAnim
+   */
   getBindedAnim() {
     this._EnsureAnim();
     return this._BindAnim;
   }
 
+  /**
+   * 内部API
+   * 
+   * getBindedView
+   */
   getBindedView() {
     this._EnsureAnim();
     return this._BindView;
@@ -190,6 +422,9 @@ class ActorControl {
    * addCondCycleListener
    * 追加 cond cycle listener，可以根据start和end来进行callback时序排序
    * 
+   * 应对场景为, 在condition的 (ActorState)=>{} 回调中, 
+   * 当一帧中condition的多个回调发生时(可能复数的condition被触发,也可能是一个condition有多个回调), 协调这些回调的处理逻辑的场景
+   * 
    * @param {Function} startCycleCallback   开始执行一帧的js回调(condition的callback)
    * @param {Function} endCycleCallback  执行一帧的js回调完毕
    */
@@ -209,6 +444,13 @@ class ActorControl {
     }
   }
 
+  /**
+   * removeCondCycleListener
+   * 移除由 addCondCycleListener 加入的回调
+   * 
+   * @param {Function} startCycleCallback   开始执行一帧的js回调(condition的callback)
+   * @param {Function} endCycleCallback  执行一帧的js回调完毕
+   */
   removeCondCycleListener(startCycleCallback: Function, endCycleCallback: Function) {
     if (startCycleCallback && this._CondCycleStartList) {
       for (let i = 0; i < this._CondCycleStartList.length; i++) {
@@ -232,6 +474,7 @@ class ActorControl {
     // 遇到layout后仍然会因为新broadcast有动作时，一帧中可能会有多次回调
     let retJsonObject: any = JSON.parse(retJson);
     let echoRetList: Array<any> = retJsonObject["retList"];
+    delete retJsonObject["retList"]; // 删除retList, 避免回调中读取
     if (echoRetList) {
       if (this._CondCycleStartList && this._CondCycleStartList.length > 0) {
         for (let startCb of this._CondCycleStartList) {

package/utils/JsViewVueWidget/JsvFreeMoveActor/CallbackManager.ts

@@ -6,6 +6,7 @@
  */
 
 import { StateCmdBuilder } from "./ForgeTypeDefine"
+import type { CommandType } from "./CmdTypes";
 
 class CallbackInfo {
   public funcRef!: Function; // 回调函数
@@ -68,7 +69,7 @@ class CallbackManager {
     }
   }
 
-  public buildCallbackCmd(func: Function): Object {
+  public buildCallbackCmd(func: Function): CommandType {
     let funcIdStr = this.addCallback(func, true);
     return StateCmdBuilder.FireEcho(funcIdStr); // 以funcIdStr 作为echoToken
   }

package/utils/JsViewVueWidget/JsvFreeMoveActor/CmdTypes.ts

@@ -0,0 +1,24 @@
+
+
+// Action或者State的命令包格式
+export interface CommandType {
+    typ: number;  // type, 命令类型
+    set?: {
+    };    // 命令的参数
+}
+
+// Condition的命令包格式
+export interface ConditionPackType {
+    subt: number,   // condition type
+    react?: number, // sub react type
+
+    cmds?: Array<CommandType>,  // command list 对应  ConditionSetBuilder.AppendSubCmd 或者 SetCmdList
+    cmdPacks?: Array<CommandPackType>,  // Command pack list 对应 ConditionSetBuilder.SetCmdPackList
+}
+
+export interface CommandPackType {
+    t: number,  // Command Pack type: Action / State
+    cmd?: CommandType,  // State的单个 command   
+    cmds?: Array<CommandType> | null,  // Command list  
+    then?: Function;
+}