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

package/utils/JsViewVueWidget/JsvFreeMoveActor/SetCondition.ts

@@ -5,39 +5,43 @@
  * @Description: file content
  */
 
-import ActionRefObject from "./ActionRefObject";
 import CallbackManager from "./CallbackManager";
 import { ConditionSetBuilder, StateCmdBuilder, CmdPackBuilder } from "./ForgeTypeDefine"
-import { NexusNode } from "./NexusNode";
+import { NexusNode, GLOBAL_CUSTOM_NEXUS_DETAIL_TYPE } from "./NexusNode";
+import type { CommandPackType, ConditionPackType } from "./CmdTypes";
 
 type UNumber = undefined | number;
 
-const setChildCommnadPackList = (conditionSet: Object, callbackManager: CallbackManager, cmdPackList: Array<Object>) => {
+export const TranslateCondThenCmdPackList = (
+  callbackManager: CallbackManager, 
+  cmdPackList: Array<CommandPackType | Function>) => {
   for (let i = 0; i < cmdPackList.length; i++) {
     if (typeof cmdPackList[i] == "function") {
       // 将回调函数更换为对应CommandPack, 内容为 FireEcho 的 stateCommand
-      cmdPackList[i] = CmdPackBuilder.InitStateCmdPack(callbackManager.buildCallbackCmd(cmdPackList[i] as Function));
+      cmdPackList[i] = CmdPackBuilder.InitStateCmdPack(
+        callbackManager.buildCallbackCmd(cmdPackList[i] as Function));
     }
   }
-
-  // 将此cmdPackList设置给ConditionSet
-  ConditionSetBuilder.SetCmdPackList(conditionSet, cmdPackList);
 }
 
 type WallDirection = "left" | "right" | "top" | "bottom";
 
+/**
+ * condition().XXXXX 可用的API说明
+ * 标注"内部API"的API, 应用开发时一定!!不要使用, 因为后续版本可能调整导致失效
+ */
 class ConditionPackBuilder {
   public _Callbacks: CallbackManager;
   private _CommonInfo: Object;
   private _CommonInfoValid: boolean;
-  private _ContorlSlefNexus: NexusNode;
+  private _ContorlSelfNexus: NexusNode;
   private _BuildersFactory: any;
 
   constructor(callbackManager: CallbackManager, selfNexus: NexusNode, buildersFactory: any) {
     this._Callbacks = callbackManager;
     this._CommonInfo = ConditionSetBuilder.InitCommonInfo();
     this._CommonInfoValid = false;
-    this._ContorlSlefNexus = selfNexus;
+    this._ContorlSelfNexus = selfNexus;
     this._BuildersFactory = buildersFactory;
   }
 
@@ -58,12 +62,13 @@ class ConditionPackBuilder {
   /**
    * reachPosition
    * 获取 ReachPosition 的condition
-   * x或y已经处于，或者被越过时触发
+   * x或y已经处于，或者被越过时触发, 
+   * 此接口主要用于途径中途点的监听, 若要定义运动边界, 用positionWall/positionBox更合适
    * 
    * @param {double} xPosition 位置有效值，可以传入undefined来决定此值不设置
    * @param {double} yPosition 位置有效值，可以传入undefined来决定此值不设置
    */
-  reachPosition(xPosition: number | undefined, yPosition: number | undefined): Object | null {
+  reachPosition(xPosition: number | undefined, yPosition: number | undefined): CommandPackType | null {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
       return null;
@@ -74,23 +79,106 @@ class ConditionPackBuilder {
   }
 
   /**
-   * reachPosition
-   * 获取 ReachPosition 的condition
-   * x或y已经处于，或者被越过时触发
+   * onSpeedAcross
+   * 创建速度跨越阈值检测条件
+   * 当速度跨越给定阈值后触发
    * 
-   * @param {double} xPosition 位置有效值，可以传入undefined来决定此值不设置
-   * @param {double} yPosition 位置有效值，可以传入undefined来决定此值不设置
+   * 经典场景是检测抛物运动的拐点(定点), 
+   * 例如 condition().onSpeedAcross("y", 0).then([(ActorState)=>{}])
+   * 
+   * @param {string} xOrY "x"为x轴，"y"为y轴
+   * @param {number} speedVale 速度阈值
+   */
+  onSpeedAcross(xOrY:string, speedVale: number): CommandPackType | null {
+    // CommonInfo 只能使用一次，规避多次使用问题
+    if (!this._CheckCommonInfo()) {
+      return null;
+    }
+    this._CommonInfoValid = false;
+
+    let x_speed = undefined;
+    let y_speed = undefined;
+    if (xOrY == "x") {
+      x_speed = speedVale;
+    } else {
+      y_speed = speedVale;
+    }
+    
+    return this._BuildPack(ConditionSetBuilder.AcrossSpeed(x_speed, y_speed, this._CommonInfo));
+  }
+  
+  /**
+   * speedBoundary
+   * 创建速度阈值检测条件(单个阈值)
+   * 当速度超过给定阈值后触发
+   * 
+   * @param {string} boundName 边界名称，可以是 "x-min" | "x-max" | "y-min" | "y-max"
+   * @param {Object} speedSet 速度设置，可以是 {speed: number, limit: number}
+   */
+  speedBoundary(boundName: string, speedVale: number): CommandPackType | null {
+    let x_max_limit = boundName === "x-max" ? speedVale : undefined;
+    let x_min_limit = boundName === "x-min" ? speedVale : undefined;
+    let y_max_limit = boundName === "y-max" ? speedVale : undefined;
+    let y_min_limit = boundName === "y-min" ? speedVale : undefined;
+    return this.speedAllBoundary(x_min_limit, x_max_limit, y_min_limit, y_max_limit);
+  }
+
+  /**
+   * speedAllBoundary
+   * 创建速度所有阈值检测条件(x,y的max/min阈值，Max=上限，Min=下限)
+   * 当速度超过给定阈值后触发
+   * 
+   * @param {number} xMinLimit x轴下限阈值
+   * @param {number} xMaxLimit x轴上限阈值
+   * @param {number} yMinLimit y轴下限阈值
+   * @param {number} yMaxLimit y轴上限阈值
    */
-  wallPosition(direction: WallDirection, xPosition: UNumber, yPosition: UNumber): object | null {
+  speedAllBoundary(xMinLimit:number|undefined, xMaxLimit:number|undefined, yMinLimit:number|undefined, yMaxLimit:number|undefined): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
 
-    return this._BuildPack(ConditionSetBuilder.WallPosition(direction, xPosition, yPosition, this._CommonInfo));
+    return this._BuildPack(ConditionSetBuilder.SpeedAllBoundary(
+      xMaxLimit, xMinLimit, yMaxLimit, yMinLimit, this._CommonInfo));
+  }
+
+  /**
+   * positionWall/wallPosition
+   * 创建碰墙(单面)检测条件
+   * x或y已经处于，或者被越过时触发
+   * 
+   * 和reachPosition的最大区别是, 
+   * reach是有跨过行为才激活, 
+   * 而wall是初始位置已经超过wall时就会立刻激活
+   * 
+   * @param {string} direction 方向，可以是 "left" | "right" | "top" | "bottom", 标明初始wall位置相对运动物体的方位
+   * @param {double} position 位置有效值，direction为left/right时作用于x，direction为top/bottom时作用于y
+   */
+  positionWall(direction: WallDirection, position: UNumber): CommandPackType | null {
+    // 复用 box 逻辑: wall 等价于只启用一个边界的 box
+    const left = direction === "left" ? position : undefined;
+    const top = direction === "top" ? position : undefined;
+    const right = direction === "right" ? position : undefined;
+    const bottom = direction === "bottom" ? position : undefined;
+
+    return this.positionBox(left, top, right, bottom);
+  }
+  wallPosition(direction: WallDirection, position: UNumber): CommandPackType | null {
+    return this.positionWall(direction, position);
   }
 
-  boxPosition(left: UNumber, top: UNumber, right: UNumber, bottom: UNumber): any {
+  /**
+   * positionBox/boxPosition
+   * 创建碰墙(4面)检测条件
+   * 相当于用4面wallPosition组合起来的box(本物体一般处于box内, 一旦移到box外就激活)
+   * 
+   * @param {double} left 左边界位置有效值，可以传入undefined来表面此面无wallPosition
+   * @param {double} top 上边界位置有效值，可以传入undefined来表面此面无wallPosition
+   * @param {double} right 右边界位置有效值，可以传入undefined来表面此面无wallPosition
+   * @param {double} bottom 下边界位置有效值，可以传入undefined来表面此面无wallPosition
+   */
+  positionBox(left: UNumber, top: UNumber, right: UNumber, bottom: UNumber): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -98,8 +186,20 @@ class ConditionPackBuilder {
 
     return this._BuildPack(ConditionSetBuilder.BoxPosition(left, top, right, bottom, this._CommonInfo));
   }
+  boxPosition(left: UNumber, top: UNumber, right: UNumber, bottom: UNumber): CommandPackType | null {
+    return this.positionBox(left, top, right, bottom);
+  }
 
-  offsetPosition(left: UNumber, top: UNumber, right: UNumber, bottom: UNumber): object | null {
+  /**
+   * offsetPosition
+   * 当div运动了给定的偏移量后触发
+   * 
+   * @param {double} left 向左移动多少触发，为正整数
+   * @param {double} top 向上移动多少触发，为正整数
+   * @param {double} right 向右移动多少触发，为正整数
+   * @param {double} bottom 向下移动多少触发，为正整数
+   */
+  offsetPosition(left: UNumber, top: UNumber, right: UNumber, bottom: UNumber): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -108,7 +208,14 @@ class ConditionPackBuilder {
     return this._BuildPack(ConditionSetBuilder.OffsetPosition(left, top, right, bottom, this._CommonInfo));
   }
 
-  startMove(xEnable: boolean, yEnable: boolean) {
+  /**
+   * startMove
+   * 当FreeMove块开始移动时触发, 用于探测方块从静止到移动的过程
+   * 
+   * @param {boolean} xEnable x轴是否启用
+   * @param {boolean} yEnable y轴是否启用
+   */
+  startMove(xEnable: boolean, yEnable: boolean): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -121,31 +228,28 @@ class ConditionPackBuilder {
   }
 
   /**
-   * AcrossPosition
-   * 获取 AcrossPosition 的condition
-   * x或y被越过时触发
    * 
-   * @param {double} xPosition 位置有效值，可以传入undefined来决定此值不设置
-   * @param {double} yPosition 位置有效值，可以传入undefined来决定此值不设置
+   * onCustomNexus
+   * 响应由 state.fireCustomNexus 发起的event
+   * 是用户事件处理中激发预制命令集的手段
+   * 
+   * @param {NexusNode} nexusRecv 由 FreeMoveFunc.newNexus() 创建, 为通讯匹配的句柄, 类似电话号
    */
-  acrossPosition(xPosition: number | undefined, yPosition: number | undefined): Object | null {
-    // CommonInfo 只能使用一次，规避多次使用问题
-    if (!this._CheckCommonInfo()) {
-      return null;
-    }
-    this._CommonInfoValid = false;
-
-    return this._BuildPack(ConditionSetBuilder.AcrossPosition(xPosition, yPosition, this._CommonInfo));
+  onCustomNexus(nexusRecv: NexusNode): CommandPackType | null {
+    return this.onNexusEvent(nexusRecv, GLOBAL_CUSTOM_NEXUS_DETAIL_TYPE);
   }
 
   /**
+   * 内部API
+   * 
    * OnNexusEvent
-   * 响应 actRef 关联的 action 所发出的内部状态信息
+   * 响应由 state.fireNexusEvent 发起的event
+   * 是用户事件处理中激发预制命令集的手段
    * 
    * @param {NexusNode} nexusRecv 由 FreeMoveFunc.newNexus() 创建, 作为通讯句柄，类似电话号，被fireNexusEvent调用
    * @param {number} detailEventType 监听的事件类型, 类比与分机号，和fireNexusEvent发出的id约定, 自定义内容要求1000以上
    */
-  onNexusEvent(nexusRecv: NexusNode, detailEventType: number) {
+  onNexusEvent(nexusRecv: NexusNode, detailEventType: number): CommandPackType | null {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
       return null;
@@ -162,13 +266,15 @@ class ConditionPackBuilder {
   }
 
   /**
+   * 内部API
+   * 
    * OnHitBlock
    * 监听Actor关联的LayoutView与blocker碰撞的状态
    * 碰撞发生后，可以 State.revertWithHitBlock 将LayoutView返回到紧贴到碰撞点的状态
    * 
    * @param {number} blkGID 想监听的blocker集群的组ID, 例如所有的跳板横向碰撞面，或者所有的跳板边缘的纵向碰撞面, 0为无效值
    */
-  onHitBlock(blkGID: number) {
+  onHitBlock(blkGID: number): CommandPackType | null {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
       return null;
@@ -184,7 +290,7 @@ class ConditionPackBuilder {
    * 特别场景: onNextTick(0) 可用于充当前帧命令执行完毕的回调，相当于为命令执行完毕做一个callback
    * 
    */
-  onNextTick(tickGap: number = 1) {
+  onNextTick(tickGap: number = 1): CommandPackType | null {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
       return null;
@@ -198,7 +304,12 @@ class ConditionPackBuilder {
   }
 
   /** 指定的swapcount前才能执行 */
-  onSwapCount() {
+  /**
+   * 内部API
+   * 
+   * onSwapCount
+   */
+  onSwapCount(): CommandPackType | null {
     // CommonInfo 只能使用一次，规避多次使用问题
     if (!this._CheckCommonInfo()) {
       return null;
@@ -207,85 +318,146 @@ class ConditionPackBuilder {
     return this._BuildPack(ConditionSetBuilder.onSwapCount(0, this._CommonInfo));
   }
 
-  onDragStart() {
+  /**
+   * 内部API
+   * 
+   * onDragStart
+   * 当拖拽开始时触发
+   */
+  onDragStart(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
 
-    return this._BuildPack(ConditionSetBuilder.OnDragStart(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnDragStart(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onDragEnd() {
+  /**
+   * 内部API
+   */
+  onDragEnd(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnDragEnd(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnDragEnd(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onTouchDown() {
+  /**
+   * 内部API
+   */
+  onTouchDown(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnTouchDown(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnTouchDown(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onTouchRelease() {
+  /**
+   * 内部API
+   */
+  onTouchRelease(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnTouchRelease(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnTouchRelease(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onFlingStart() {
+  /**
+   * 内部API
+   * 
+   * onFlingStart
+   * 当 fling 开始时触发
+   */
+  onFlingStart(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnFlingStart(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnFlingStart(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onFlingProgress() {
+  /**
+   * 内部API
+   * 
+   * onFlingProgress
+   * 当 fling 过程中触发
+   */
+  onFlingProgress(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnFlingProgress(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnFlingProgress(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onFlingEnd() {
+  /**
+   * 内部API
+   * 
+   * onFlingEnd
+   * 当 fling 结束时触发
+   */
+  onFlingEnd(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnFlingEnd(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnFlingEnd(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onFlingCancel() {
+  /**
+   * 内部API
+   * 
+   * onFlingCancel
+   * 当 fling 取消时触发
+   */
+  onFlingCancel(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnFlingCancel(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnFlingCancel(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
-  onFlingDrop() {
+  /**
+   * 内部API
+   * 
+   * onFlingDrop
+   * 当 fling 拖拽结束时触发
+   */
+  onFlingDrop(): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
     this._CommonInfoValid = false;
-    return this._BuildPack(ConditionSetBuilder.OnFlingDrop(this._CommonInfo, this._ContorlSlefNexus.token));
+    return this._BuildPack(ConditionSetBuilder.OnFlingDrop(this._CommonInfo, this._ContorlSelfNexus.token));
   }
 
   /**
+   * 内部API
+   * 
+   * onMouseWheelScrollProgress
+   * 当鼠标滚轮滚动时触发
+   */
+  onMouseWheelScrollProgress(): CommandPackType | null {
+    if (!this._CheckCommonInfo()) {
+      return null;
+    }
+    this._CommonInfoValid = false;
+    return this._BuildPack(ConditionSetBuilder.OnMouseWheelScrollProgress(this._CommonInfo, this._ContorlSelfNexus.token));
+  }
+
+  /**
+   * 内部API
+   * 
    * touchCount
    * 当touchDown时，Count会++，用于解决多次touchDown引发的时序问题
    * 当native的count计数等于给定的参数设定的count时，触发condition
    */
-  touchCount(count: number) {
+  touchCount(count: number): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -294,6 +466,8 @@ class ConditionPackBuilder {
   }
 
   /**
+   * 内部API
+   * 
    * onMovement
    * 当FreeMove块移动时，移动了给定的距离值后触发条件, 给定的距离值由sensitivity定义
    * 
@@ -303,7 +477,7 @@ class ConditionPackBuilder {
    */
   onMovement(xSensitivity: number,
     ySensitivity: number | undefined = undefined,
-    xyEnables: number | undefined = undefined) {
+    xyEnables: number | undefined = undefined): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -327,7 +501,13 @@ class ConditionPackBuilder {
       xSensitivity, ySensitivity, xyEnables));
   }
 
-  movementSync(nexusRef: NexusNode) {
+  /**
+   * 内部API
+   * 
+   * movementSync
+   * @param {NexusNode} nexusRef 用于同步运动的nexus节点
+   */
+  movementSync(nexusRef: NexusNode): CommandPackType | null {
     if (!this._CheckCommonInfo()) {
       return null;
     }
@@ -345,20 +525,21 @@ class ConditionPackBuilder {
     return true;
   }
 
-  _BuildPack(conditionSet: Object) {
+  _BuildPack(conditionSet: ConditionPackType): CommandPackType {
     let cmdPack = CmdPackBuilder.InitStateCmdPack(StateCmdBuilder.NewCondition(conditionSet));
 
     // 追加then处理
     let callbackManager = this._Callbacks;
-    cmdPack["then"] = (creatorOrArray: Function | Array<Object> | undefined) => {
+    cmdPack["then"] = (creatorOrArray: Function | Array<CommandPackType | Function> | undefined) => {
       if (creatorOrArray) {
-        let childCmdPackList: Array<Object>;
+        let childCmdPackList: Array<CommandPackType | Function>;
         if (typeof creatorOrArray == "function") {
           childCmdPackList = creatorOrArray(this._BuildersFactory);
         } else {
           childCmdPackList = creatorOrArray;
         }
-        setChildCommnadPackList(conditionSet, callbackManager, childCmdPackList);
+        TranslateCondThenCmdPackList(callbackManager, childCmdPackList);
+        ConditionSetBuilder.SetCmdPackList(conditionSet, childCmdPackList);
         return cmdPack;
       }
       return cmdPack;