[Feature] Add timeScale and pause()/resume() to cc.Tween

cocos/tween/actions/action-interval.ts

@@ -25,8 +25,8 @@
  THE SOFTWARE.
 */
 
-import { FiniteTimeAction, Action } from './action';
-import { macro, logID, errorID } from '../../core';
+import { errorID, logID, macro } from '../../core';
+import { Action, FiniteTimeAction } from './action';
 import { ActionInstant } from './action-instant';
 
 /**
@@ -50,16 +50,23 @@
 export class ActionInterval extends FiniteTimeAction {
     protected MAX_VALUE = 2;
     protected _elapsed = 0;
-    protected _firstTick = false;
+
+    // eslint-disable-next-line @typescript-eslint/ban-types
     protected _easeList: Function[] = [];
+
     protected _speed = 1;
     protected _repeatForever = false;
     _repeatMethod = false; // Compatible with repeat class, Discard after can be deleted
     protected _speedMethod = false; // Compatible with repeat class, Discard after can be deleted
 
+    // for pausing the action
+    paused = false;
+    // for time scale
+    timeScale = 1;
+
     constructor (d?: number) {
         super();
-        if (d !== undefined && !isNaN(d)) {
+        if (d !== undefined && !Number.isNaN(d)) {
             this.initWithDuration(d);
         }
     }
@@ -82,8 +89,10 @@
         // prevent division by 0
         // This comparison could be in step:, but it might decrease the performance
         // by 3% in heavy based action games.
-        this._elapsed = 0;
-        this._firstTick = true;
+
+        // _elapsed = -1 means it's the first tick
+        this._elapsed = -1;
+
         return true;
     }
 
@@ -128,7 +137,7 @@
     easing (easeObj: any): ActionInterval {
         if (this._easeList) this._easeList.length = 0;
         else this._easeList = [];
         for (let i = 0; i < arguments.length; i++) this._easeList.push(arguments[i]);
         return this;
     }
 
@@ -142,16 +151,20 @@
     }
 
     step (dt: number): void {
-        if (this._firstTick) {
-            this._firstTick = false;
+        // _elapsed = -1 means it's the first tick
+        if (this._elapsed === -1) {
             this._elapsed = 0;
-        } else this._elapsed += dt;
+        } else if (this.paused) {
+            return;
+        } else {
+            this._elapsed += dt * this.timeScale;
+        }
 
         // this.update((1 > (this._elapsed / this._duration)) ? this._elapsed / this._duration : 1);
         // this.update(Math.max(0, Math.min(1, this._elapsed / Math.max(this._duration, cc.macro.FLT_EPSILON))));
         let t = this._elapsed / (this._duration > 0.0000001192092896 ? this._duration : 0.0000001192092896);
-        t = (t < 1 ? t : 1);
-        this.update(t > 0 ? t : 0);
+        t = t > 0 ? (t < 1 ? t : 1) : 0;
+        this.update(t);
 
         // Compatible with repeat class, Discard after can be deleted (this._repeatMethod)
         if (this._repeatMethod && this._timesForRepeat > 1 && this.isDone()) {
@@ -169,8 +182,8 @@
 
     startWithTarget (target: any): void {
         Action.prototype.startWithTarget.call(this, target);
-        this._elapsed = 0;
-        this._firstTick = true;
+        // _elapsed = -1 means it's the first tick
+        this._elapsed = -1;
     }
 
     reverse (): ActionInterval {
@@ -256,7 +269,7 @@
      */
     repeat (times: number): ActionInterval {
         times = Math.round(times);
-        if (isNaN(times) || times < 1) {
+        if (Number.isNaN(times) || times < 1) {
             logID(1014);
             return this;
         }
@@ -285,7 +298,7 @@
  * Runs actions sequentially, one after another.
  */
 export class Sequence extends ActionInterval {
-    static _actionOneTwo = function (actionOne: ActionInterval, actionTwo: ActionInterval): Sequence {
+    static _actionOneTwo (actionOne: ActionInterval, actionTwo: ActionInterval): Sequence {
         const sequence = new Sequence();
         sequence.initWithTwoActions(actionOne, actionTwo);
         return sequence;
@@ -323,7 +336,7 @@
             for (let i = 1; i < last; i++) {
                 if (paramArray[i]) {
                     action1 = prev;
                     prev = Sequence._actionOneTwo(action1, paramArray[i]);
                 }
             }
             this.initWithTwoActions(prev, paramArray[last]);
@@ -346,7 +359,7 @@
         durationOne *= actionOne._repeatMethod ? actionOne._timesForRepeat : 1;
         durationTwo *= actionTwo._repeatMethod ? actionTwo._timesForRepeat : 1;
         const d = durationOne + durationTwo;
         this.initWithDuration(d);
 
         this._actions[0] = actionOne;
         this._actions[1] = actionTwo;
@@ -355,7 +368,7 @@
 
     clone (): any {
         const action = new Sequence();
         this._cloneDecoration(action as any);
         action.initWithTwoActions(this._actions[0].clone(), this._actions[1].clone());
         return action as any;
     }
@@ -378,7 +391,6 @@
         const locSplit = this._split;
         const locActions = this._actions;
         const locLast = this._last;
-        let actionFound: ActionInterval;
 
         dt = this._computeEaseTime(dt);
         if (dt < locSplit) {
@@ -411,7 +423,8 @@
             }
         }
 
-        actionFound = locActions[found];
+        const actionFound: ActionInterval = locActions[found];
+
         // Last action found and it is done.
         if (locLast === found && actionFound.isDone()) return;
 
@@ -438,8 +451,7 @@
  * The created action will run actions sequentially, one after another.
  * @zh 顺序执行动作，创建的动作将按顺序依次运行。
  * @method sequence
- * @param {FiniteTimeAction|FiniteTimeAction[]} actionOrActionArray
- * @param {FiniteTimeAction} ...tempArray
+ * @param {FiniteTimeAction[]} actionArray
  * @return {ActionInterval}
  * @example
  * import { sequence } from 'cc';
@@ -451,21 +463,20 @@
  * const seq = sequence(actArray);
  */
 // todo: It should be use new
-export function sequence (/* Multiple Arguments */tempArray: any): ActionInterval {
-    const paramArray = (tempArray instanceof Array) ? tempArray : arguments;
-    if (paramArray.length === 1) {
+export function sequence (actionArray: Action[]): ActionInterval | null {
+    if (actionArray.length === 1) {
         errorID(1019);
-        return null as any;
+        return null;
     }
-    const last = paramArray.length - 1;
-    if ((last >= 0) && (paramArray[last] == null)) logID(1015);
+    const last = actionArray.length - 1;
+    if ((last >= 0) && (actionArray[last] == null)) logID(1015);
 
-    let result: any = null;
+    let result: ActionInterval | null = null;
     if (last >= 0) {
-        result = paramArray[0];
+        result = actionArray[0] as ActionInterval;
         for (let i = 1; i <= last; i++) {
-            if (paramArray[i]) {
-                result = Sequence._actionOneTwo(result, paramArray[i]);
+            if (actionArray[i]) {
+                result = Sequence._actionOneTwo(result, actionArray[i] as ActionInterval);
             }
         }
     }
@@ -493,7 +504,7 @@
 
     constructor (action?: any, times?: any) {
         super();
         times !== undefined && this.initWithAction(action, times);
     }
 
     /*
@@ -635,7 +646,7 @@
 
     constructor (action?: ActionInterval) {
         super();
         action && this.initWithAction(action);
     }
 
     /*
@@ -666,7 +677,7 @@
 
     step (dt: any): void {
         const locInnerAction = this._innerAction!;
-        locInnerAction.step(dt);
+        locInnerAction.step(dt * this.timeScale);
         if (locInnerAction.isDone()) {
             // var diff = locInnerAction.getElapsed() - locInnerAction._duration;
             locInnerAction.startWithTarget(this.target);
@@ -727,7 +738,7 @@
  * @extends ActionInterval
  */
 export class Spawn extends ActionInterval {
-    static _actionOneTwo = function (action1: any, action2: any): Spawn {
+    static _actionOneTwo (action1: any, action2: any): Spawn {
         const pSpawn = new Spawn();
         pSpawn.initWithTwoActions(action1, action2);
         return pSpawn;
@@ -775,12 +786,12 @@
         const d1 = action1._duration;
         const d2 = action2._duration;
 
         if (this.initWithDuration(Math.max(d1, d2))) {
             this._one = action1;
             this._two = action2;
 
             if (d1 > d2) {
                 this._two = Sequence._actionOneTwo(action2, delayTime(d1 - d2));
             } else if (d1 < d2) {
                 this._one = Sequence._actionOneTwo(action1, delayTime(d2 - d1));
             }
@@ -835,15 +846,15 @@
  * const action = spawn(jumpBy(2, new Vec2(300, 0), 50, 4), rotateBy(2, 720));
  * todo: It should be the direct use new
  */
-export function spawn (/* Multiple Arguments */tempArray: any): FiniteTimeAction {
+export function spawn (/* Multiple Arguments */tempArray: any): FiniteTimeAction | null {
     const paramArray = (tempArray instanceof Array) ? tempArray : arguments;
     if (paramArray.length === 1) {
         errorID(1020);
-        return null as any;
+        return null;
     }
     if ((paramArray.length > 0) && (paramArray[paramArray.length - 1] == null)) logID(1015);
 
-    let prev = paramArray[0];
+    let prev: FiniteTimeAction = paramArray[0];
     for (let i = 1; i < paramArray.length; i++) {
         if (paramArray[i] != null) prev = Spawn._actionOneTwo(prev, paramArray[i]);
     }
@@ -905,7 +916,7 @@
 
     constructor (action?: any) {
         super();
         action && this.initWithAction(action);
     }
 
     /*

cocos/tween/tween.ts

@@ -22,15 +22,15 @@
  THE SOFTWARE.
 */
 
-import { TweenSystem } from './tween-system';
 import { warn } from '../core';
-import { ActionInterval, sequence, repeat, repeatForever, reverseTime, delayTime, spawn } from './actions/action-interval';
-import { removeSelf, show, hide, callFunc } from './actions/action-instant';
+import { legacyCC } from '../core/global-exports';
 import { Action, FiniteTimeAction } from './actions/action';
+import { callFunc, hide, removeSelf, show } from './actions/action-instant';
+import { ActionInterval, delayTime, repeat, repeatForever, reverseTime, sequence, spawn } from './actions/action-interval';
 import { ITweenOption } from './export-api';
-import { TweenAction } from './tween-action';
 import { SetAction } from './set-action';
-import { legacyCC } from '../core/global-exports';
+import { TweenAction } from './tween-action';
+import { TweenSystem } from './tween-system';
 
 // https://medium.com/dailyjs/typescript-create-a-condition-based-subset-types-9d902cea5b8c
 type FlagExcludedType<Base, Type> = { [Key in keyof Base]: Base[Key] extends Type ? never : Key };
@@ -60,6 +60,27 @@ export class Tween<T> {
     private _target: T | null = null;
     private _tag = Action.TAG_INVALID;
 
+    // for time scale
+    private _timeScale = 1;
+
+    /**
+     * !#en set/get time scale for tween
+     * !#zh 设置/读取 tween 的 time scale (时间缩放参数)
+     * @property timeScale
+     * @type {Number}
+     * @default 1
+     */
+    get timeScale (): number {
+        return this._timeScale;
+    }
+
+    set timeScale (value: number) {
+        this._timeScale = value;
+        if (this._finalAction) {
+            (this._finalAction as ActionInterval).timeScale = value;
+        }
+    }
+
     constructor (target?: T | null) {
         this._target = target === undefined ? null : target;
     }
@@ -138,6 +159,38 @@ export class Tween<T> {
         return this;
     }
 
+    /**
+     * !#en
+     * Pause this tween
+     * !#zh
+     * 暂停当前 tween
+     * @method pause
+     * @return {Tween}
+     * @typescript pause(): Tween<T>
+     */
+    pause (): Tween<T> {
+        if (this._finalAction) {
+            (this._finalAction as ActionInterval).paused = true;
+        }
+        return this;
+    }
+
+    /**
+     * !#en
+     * Resume this tween
+     * !#zh
+     * 从暂停状态恢复当前 tween
+     * @method resume
+     * @return {Tween}
+     * @typescript resume(): Tween<T>
+     */
+    resume (): Tween<T> {
+        if (this._finalAction) {
+            (this._finalAction as ActionInterval).paused = false;
+        }
+        return this;
+    }
+
     /**
      * @en
      * Clone a tween.
@@ -261,7 +314,7 @@ export class Tween<T> {
      */
     sequence (...args: Tween<T>[]): Tween<T> {
         const action = Tween._wrappedSequence(...args);
-        this._actions.push(action);
+        this._actions.push(action as Action);
         return this;
     }
 
@@ -275,7 +328,7 @@ export class Tween<T> {
      */
     parallel (...args: Tween<T>[]): Tween<T> {
         const action = Tween._wrappedParallel(...args);
-        this._actions.push(action);
+        this._actions.push(action as Action);
         return this;
     }
 
@@ -437,7 +490,7 @@ export class Tween<T> {
         if (actions.length === 1) {
             action = actions[0];
         } else {
-            action = sequence(actions);
+            action = sequence(actions) as Action;
         }
 
         return action;
@@ -449,7 +502,7 @@ export class Tween<T> {
 
     private static readonly _tmp_args: Tween<any>[] | Action[] = [];
 
-    private static _wrappedSequence (...args: Action[] | Tween<any>[]): ActionInterval {
+    private static _wrappedSequence (...args: Action[] | Tween<any>[]): ActionInterval | null {
         const tmp_args = Tween._tmp_args;
         tmp_args.length = 0;
         for (let l = args.length, i = 0; i < l; i++) {
@@ -459,10 +512,10 @@ export class Tween<T> {
             }
         }
 
-        return sequence.apply(sequence, tmp_args as any);
+        return sequence(tmp_args as Action[]);
     }
 
-    private static _wrappedParallel (...args: Action[] | Tween<any>[]): FiniteTimeAction {
+    private static _wrappedParallel (...args: Action[] | Tween<any>[]): FiniteTimeAction | null {
         const tmp_args = Tween._tmp_args;
         tmp_args.length = 0;
         for (let l = args.length, i = 0; i < l; i++) {