From 6136a4d7f081273b1efb8e7fb040cd9e7b2435dd Mon Sep 17 00:00:00 2001 From: James Chen Date: Wed, 15 Jan 2025 09:38:04 +0800 Subject: [PATCH] [v3.8.6] [Tween] More override in tween modules and add `toString` method for all actions which will be easier for debugging. (#18181) * [v3.8.6] [Tween] More override in tween modules and add `toString` method for all actions which will be easier for debugging. Also add some `@mangle` jsDoc tag for some properties. --- cocos/tween/actions/action-instant.ts | 62 ++++-- cocos/tween/actions/action-interval.ts | 198 +++++++++++------- .../tween/actions/action-unknown-duration.ts | 16 +- cocos/tween/actions/action.ts | 4 + cocos/tween/tween-action.ts | 12 +- 5 files changed, 185 insertions(+), 107 deletions(-) diff --git a/cocos/tween/actions/action-instant.ts b/cocos/tween/actions/action-instant.ts index f0cbaf2bb60..c67b9dc5293 100644 --- a/cocos/tween/actions/action-instant.ts +++ b/cocos/tween/actions/action-instant.ts @@ -35,15 +35,15 @@ import type { Node } from '../../scene-graph'; * @extends FiniteTimeAction */ export abstract class ActionInstant extends FiniteTimeAction { - isDone (): boolean { + override isDone (): boolean { return true; } - step (_dt: number): void { + override step (_dt: number): void { this.update(1); } - update (_dt: number): void { + override update (_dt: number): void { // nothing } @@ -54,13 +54,13 @@ export abstract class ActionInstant extends FiniteTimeAction { * - The reversed action will be x of 100 move to 0. * @returns {Action} */ - reverse (): ActionInstant { + override reverse (): ActionInstant { return this.clone(); } abstract clone (): ActionInstant; - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } } @@ -71,7 +71,7 @@ export abstract class ActionInstant extends FiniteTimeAction { * @extends ActionInstant */ export class Show extends ActionInstant { - update (_dt: number): void { + override update (_dt: number): void { const target = this._getWorkerTarget(); if (!target) return; const _renderComps = target.getComponentsInChildren(Renderer); @@ -81,15 +81,19 @@ export class Show extends ActionInstant { } } - reverse (): Hide { + override reverse (): Hide { return new Hide(); } - clone (): Show { + override clone (): Show { const action = new Show(); action._id = this._id; return action; } + + override toString (): string { + return ''; + } } /** @@ -111,7 +115,7 @@ export function show (): Show { * @extends ActionInstant */ export class Hide extends ActionInstant { - update (_dt: number): void { + override update (_dt: number): void { const target = this._getWorkerTarget(); if (!target) return; const _renderComps = target.getComponentsInChildren(Renderer); @@ -121,15 +125,19 @@ export class Hide extends ActionInstant { } } - reverse (): Show { + override reverse (): Show { return new Show(); } - clone (): Hide { + override clone (): Hide { const action = new Hide(); action._id = this._id; return action; } + + override toString (): string { + return ''; + } } /** @@ -151,7 +159,7 @@ export function hide (): Hide { * @extends ActionInstant */ export class ToggleVisibility extends ActionInstant { - update (_dt: number): void { + override update (_dt: number): void { const target = this._getWorkerTarget(); if (!target) return; const _renderComps = target.getComponentsInChildren(Renderer); @@ -161,15 +169,19 @@ export class ToggleVisibility extends ActionInstant { } } - reverse (): ToggleVisibility { + override reverse (): ToggleVisibility { return new ToggleVisibility(); } - clone (): ToggleVisibility { + override clone (): ToggleVisibility { const action = new ToggleVisibility(); action._id = this._id; return action; } + + override toString (): string { + return ''; + } } /** @@ -203,7 +215,7 @@ export class RemoveSelf extends ActionInstant { if (isNeedCleanUp !== undefined) this.init(isNeedCleanUp); } - update (_dt: number): void { + override update (_dt: number): void { const target = this._getWorkerTarget(); if (!target) return; target.removeFromParent(); @@ -217,15 +229,19 @@ export class RemoveSelf extends ActionInstant { return true; } - reverse (): RemoveSelf { + override reverse (): RemoveSelf { return new RemoveSelf(this._isNeedCleanUp); } - clone (): RemoveSelf { + override clone (): RemoveSelf { const action = new RemoveSelf(this._isNeedCleanUp); action._id = this._id; return action; } + + override toString (): string { + return ''; + } } /** @@ -307,13 +323,13 @@ export class CallFunc extends ActionInstant { } } - update (_dt: number): void { + override update (_dt: number): void { this.execute(); } /* * Get selectorTarget. - * @return {object} + * @mangle */ getTargetCallback (): CallbackThis | undefined { return this._callbackThis; @@ -321,7 +337,7 @@ export class CallFunc extends ActionInstant { /* * Set selectorTarget. - * @param {object} sel + * @mangle */ setTargetCallback (sel: CallbackThis): void { if (sel !== this._callbackThis) { @@ -329,12 +345,16 @@ export class CallFunc extends ActionInstant { } } - clone (): CallFunc { + override clone (): CallFunc { const action = new CallFunc(); action._id = this._id; if (this._callback) action.initWithFunction(this._callback, this._callbackThis, this._data); return action; } + + override toString (): string { + return ``; + } } /** diff --git a/cocos/tween/actions/action-interval.ts b/cocos/tween/actions/action-interval.ts index 2a062583e3d..97a75ff3c58 100644 --- a/cocos/tween/actions/action-interval.ts +++ b/cocos/tween/actions/action-interval.ts @@ -32,25 +32,29 @@ import type { Tween, TweenUpdateCallback } from '../tween'; // Extra action for making a Sequence or Spawn when only adding one action to it. class DummyAction extends FiniteTimeAction { - clone (): DummyAction { + override clone (): DummyAction { return new DummyAction(); } - reverse (): DummyAction { + override reverse (): DummyAction { return this.clone(); } - update (time: number): void { + override update (time: number): void { // empty } - step (dt: number): void { + override step (dt: number): void { // empty } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } + + override toString (): string { + return `DummyAction`; + } } /** @@ -117,13 +121,17 @@ export abstract class ActionInterval extends FiniteTimeAction { return this._elapsed >= this._duration && !this.isUnknownDuration(); } + /** + * @mangle + * @engineInternal + */ _cloneDecoration (action: ActionInterval): void { action._speed = this._speed; } abstract clone (): ActionInterval; - step (dt: number): void { + override step (dt: number): void { if (this._paused || this._speed === 0) return; dt *= this._speed; if (this._firstTick) { @@ -193,16 +201,16 @@ export abstract class ActionInterval extends FiniteTimeAction { } } +function sequenceActionWithOneTwo (actionOne: FiniteTimeAction, actionTwo: FiniteTimeAction): Sequence { + const sequence = new Sequence(); + sequence.initWithTwoActions(actionOne, actionTwo); + return sequence; +} + /* * Runs actions sequentially, one after another. */ export class Sequence extends ActionInterval { - public static _actionOneTwo (actionOne: FiniteTimeAction, actionTwo: FiniteTimeAction): Sequence { - const sequence = new Sequence(); - sequence.initWithTwoActions(actionOne, actionTwo); - return sequence; - } - private _actions: FiniteTimeAction[] = []; private _split = 0; private _last = 0; @@ -235,18 +243,18 @@ export class Sequence extends ActionInterval { for (let i = 1; i < last; i++) { if (actions[i]) { action1 = prev; - prev = Sequence._actionOneTwo(action1, actions[i]); + prev = sequenceActionWithOneTwo(action1, actions[i]); } } this.initWithTwoActions(prev, actions[last]); } } - /* - * Initializes the action
- * @param {FiniteTimeAction} actionOne - * @param {FiniteTimeAction} actionTwo - * @return {Boolean} + /** + * Initializes the action + * @param actionOne the first action to run + * @param actionTwo the second action to run + * @return true if the action initializes properly, false otherwise. */ initWithTwoActions (actionOne?: FiniteTimeAction, actionTwo?: FiniteTimeAction): boolean { if (!actionOne || !actionTwo) { @@ -264,7 +272,7 @@ export class Sequence extends ActionInterval { return true; } - clone (): Sequence { + override clone (): Sequence { const action = new Sequence(); action._id = this._id; action._speed = this._speed; @@ -273,7 +281,7 @@ export class Sequence extends ActionInterval { return action; } - startWithTarget (target: T | null): void { + override startWithTarget (target: T | null): void { super.startWithTarget(target); if (this._actions.length === 0) { return; @@ -282,7 +290,7 @@ export class Sequence extends ActionInterval { this._last = -1; } - stop (): void { + override stop (): void { if (this._actions.length === 0) { return; } @@ -291,7 +299,7 @@ export class Sequence extends ActionInterval { super.stop(); } - update (t: number): void { + override update (t: number): void { const locActions = this._actions; if (locActions.length === 0) { return; @@ -348,13 +356,14 @@ export class Sequence extends ActionInterval { this._last = found; } - reverse (): Sequence { - const action: Sequence = Sequence._actionOneTwo(this._actions[1].reverse(), this._actions[0].reverse()); + override reverse (): Sequence { + const action: Sequence = sequenceActionWithOneTwo(this._actions[1].reverse(), this._actions[0].reverse()); this._cloneDecoration(action); action._reversed = true; return action; } + /** @mangle */ updateOwner (owner: Tween): void { if (this._actions.length < 2) { return; @@ -372,6 +381,7 @@ export class Sequence extends ActionInterval { } } + /** @mangle */ findAction (id: number): FiniteTimeAction | null { for (let i = 0, len = this._actions.length; i < len; ++i) { let action: FiniteTimeAction | null = this._actions[i]; @@ -389,7 +399,7 @@ export class Sequence extends ActionInterval { return null; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { if (this._actions.length === 0) return false; const one = this._actions[0]; @@ -401,6 +411,10 @@ export class Sequence extends ActionInterval { return two.isUnknownDuration(); } + + override toString (): string { + return ``; + } } /** @@ -473,7 +487,7 @@ export class Repeat extends ActionInterval { return false; } - clone (): Repeat { + override clone (): Repeat { const action = new Repeat(); action._id = this._id; action._speed = this._speed; @@ -484,19 +498,19 @@ export class Repeat extends ActionInterval { return action; } - startWithTarget (target: T | null): void { + override startWithTarget (target: T | null): void { this._total = 0; this._nextDt = (this._innerAction ? this._innerAction.getDurationScaled() : 0) / this._duration; super.startWithTarget(target); if (this._innerAction) this._innerAction.startWithTarget(target); } - stop (): void { + override stop (): void { if (this._innerAction) this._innerAction.stop(); super.stop(); } - update (dt: number): void { + override update (dt: number): void { const locInnerAction = this._innerAction; const locDuration = this._duration; const locTimes = this._times; @@ -538,11 +552,11 @@ export class Repeat extends ActionInterval { } } - isDone (): boolean { + override isDone (): boolean { return this._total === this._times; } - reverse (): Repeat { + override reverse (): Repeat { const actionArg = this._innerAction ? this._innerAction.reverse() : undefined; const action = new Repeat(actionArg, this._times); this._cloneDecoration(action); @@ -551,7 +565,8 @@ export class Repeat extends ActionInterval { /* * Set inner Action. - * @param {FiniteTimeAction} action + * @param action The inner action. + * @mangle */ setInnerAction (action: FiniteTimeAction): void { if (this._innerAction !== action) { @@ -561,16 +576,21 @@ export class Repeat extends ActionInterval { /* * Get inner Action. - * @return {FiniteTimeAction} + * @return The inner action. + * @mangle */ getInnerAction (): FiniteTimeAction | null { return this._innerAction; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { if (this._innerAction) { return this._innerAction.isUnknownDuration(); } return false; } + + override toString (): string { + return ``; + } } /** @@ -622,7 +642,7 @@ export class RepeatForever extends ActionInterval { return true; } - clone (): RepeatForever { + override clone (): RepeatForever { const action = new RepeatForever(); action._id = this._id; action._speed = this._speed; @@ -633,19 +653,19 @@ export class RepeatForever extends ActionInterval { return action; } - startWithTarget (target: T | null): void { + override startWithTarget (target: T | null): void { super.startWithTarget(target); if (this._innerAction) { this._innerAction.startWithTarget(target); } } - stop (): void { + override stop (): void { if (this._innerAction) this._innerAction.stop(); super.stop(); } - step (dt: number): void { + override step (dt: number): void { if (this._paused || this._speed === 0) return; const locInnerAction = this._innerAction; if (!locInnerAction) { @@ -663,15 +683,15 @@ export class RepeatForever extends ActionInterval { } } - update (_t: number): void { + override update (_t: number): void { logID(1007); // should never come here. } - isDone (): boolean { + override isDone (): boolean { return false; } - reverse (): RepeatForever { + override reverse (): RepeatForever { if (this._innerAction) { const action = new RepeatForever(this._innerAction.reverse()); this._cloneDecoration(action); @@ -682,7 +702,8 @@ export class RepeatForever extends ActionInterval { /* * Set inner action. - * @param {ActionInterval} action + * @param The inner action + * @mangle */ setInnerAction (action: ActionInterval | null): void { if (this._innerAction !== action) { @@ -692,16 +713,21 @@ export class RepeatForever extends ActionInterval { /* * Get inner action. - * @return {ActionInterval} + * @return The inner action + * @mangle */ getInnerAction (): ActionInterval | null { return this._innerAction; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { if (this._innerAction) { return this._innerAction.isUnknownDuration(); } return false; } + + override toString (): string { + return ``; + } } /** @@ -718,18 +744,18 @@ export function repeatForever (action?: ActionInterval): RepeatForever { return new RepeatForever(action); } +function spawnActionWithOneTwo (action1?: FiniteTimeAction, action2?: FiniteTimeAction): Spawn { + const spawn = new Spawn(); + spawn.initWithTwoActions(action1, action2); + return spawn; +} + /* * Spawn a new action immediately * @class Spawn * @extends ActionInterval */ export class Spawn extends ActionInterval { - private static _actionOneTwo (action1?: FiniteTimeAction, action2?: FiniteTimeAction): Spawn { - const spawn = new Spawn(); - spawn.initWithTwoActions(action1, action2); - return spawn; - } - private _one: FiniteTimeAction | null = null; private _two: FiniteTimeAction | null = null; private _finished = false; @@ -752,7 +778,7 @@ export class Spawn extends ActionInterval { for (let i = 1; i < last; i++) { if (actions[i]) { action1 = prev; - prev = Spawn._actionOneTwo(action1, actions[i]); + prev = spawnActionWithOneTwo(action1, actions[i]); } } this.initWithTwoActions(prev, actions[last]); @@ -780,9 +806,9 @@ export class Spawn extends ActionInterval { this._two = action2; if (d1 > d2) { - this._two = Sequence._actionOneTwo(action2, delayTime(d1 - d2)); + this._two = sequenceActionWithOneTwo(action2, delayTime(d1 - d2)); } else if (d1 < d2) { - this._one = Sequence._actionOneTwo(action1, delayTime(d2 - d1)); + this._one = sequenceActionWithOneTwo(action1, delayTime(d2 - d1)); } ret = true; @@ -790,7 +816,7 @@ export class Spawn extends ActionInterval { return ret; } - clone (): Spawn { + override clone (): Spawn { const action = new Spawn(); action._id = this._id; action._speed = this._speed; @@ -801,19 +827,19 @@ export class Spawn extends ActionInterval { return action; } - startWithTarget (target: T | null): void { + override startWithTarget (target: T | null): void { super.startWithTarget(target); if (this._one) this._one.startWithTarget(target); if (this._two) this._two.startWithTarget(target); } - stop (): void { + override stop (): void { if (this._one) this._one.stop(); if (this._two) this._two.stop(); super.stop(); } - update (t: number): void { + override update (t: number): void { if (this._one) { if (!this._finished || this._one.isUnknownDuration()) { this._one.update(t); @@ -832,15 +858,19 @@ export class Spawn extends ActionInterval { this._finished = t === 1; } - reverse (): Spawn { + override reverse (): Spawn { if (this._one && this._two) { - const action = Spawn._actionOneTwo(this._one.reverse(), this._two.reverse()); + const action = spawnActionWithOneTwo(this._one.reverse(), this._two.reverse()); this._cloneDecoration(action); return action; } return this; } + /** + * @mangle + * @engineInternal + */ updateOwner (owner: Tween): void { if (!this._one || !this._two) { return; @@ -856,6 +886,10 @@ export class Spawn extends ActionInterval { } } + /** + * @mangle + * @engineInternal + */ findAction (id: number): FiniteTimeAction | null { const one = this._one; const two = this._two; @@ -880,7 +914,7 @@ export class Spawn extends ActionInterval { return null; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { const one = this._one; const two = this._two; @@ -895,6 +929,10 @@ export class Spawn extends ActionInterval { } return false; } + + override toString (): string { + return ``; + } } /** @@ -918,15 +956,15 @@ export function spawn (actions: FiniteTimeAction[]): Spawn { * @extends ActionInterval */ class DelayTime extends ActionInterval { - update (_dt: number): void { /* empty */ } + override update (_dt: number): void { /* empty */ } - reverse (): DelayTime { + override reverse (): DelayTime { const action = new DelayTime(this._duration); this._cloneDecoration(action); return action; } - clone (): DelayTime { + override clone (): DelayTime { const action = new DelayTime(); action._id = this._id; action._speed = this._speed; @@ -935,9 +973,13 @@ class DelayTime extends ActionInterval { return action; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } + + override toString (): string { + return ``; + } } /** @@ -998,7 +1040,7 @@ export class ReverseTime extends ActionInterval { return false; } - clone (): ReverseTime { + override clone (): ReverseTime { const action = new ReverseTime(); action._id = this._id; action._speed = this._speed; @@ -1009,30 +1051,34 @@ export class ReverseTime extends ActionInterval { return action; } - startWithTarget (target: T | null): void { + override startWithTarget (target: T | null): void { super.startWithTarget(target); if (this._other) this._other.startWithTarget(target); } - update (dt: number): void { + override update (dt: number): void { if (this._other) this._other.update(1 - dt); } - reverse (): ActionInterval { + override reverse (): ActionInterval { if (this._other) { return this._other.clone(); } return this; } - stop (): void { + override stop (): void { if (this._other) this._other.stop(); super.stop(); } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } + + override toString (): string { + return ``; + } } /** @@ -1059,19 +1105,23 @@ export class ActionCustomUpdate extends Ac this._args = args; } - clone (): ActionCustomUpdate { + override clone (): ActionCustomUpdate { return new ActionCustomUpdate(this._duration, this._cb, this._args); } - update (ratio: number): void { + override update (ratio: number): void { this._cb(this.target as T, ratio, ...this._args); } - reverse (): ActionCustomUpdate { + override reverse (): ActionCustomUpdate { return this.clone(); } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } + + override toString (): string { + return ``; + } } diff --git a/cocos/tween/actions/action-unknown-duration.ts b/cocos/tween/actions/action-unknown-duration.ts index 4831a1b480c..2330c2576cc 100644 --- a/cocos/tween/actions/action-unknown-duration.ts +++ b/cocos/tween/actions/action-unknown-duration.ts @@ -37,28 +37,32 @@ export class ActionUnknownDuration extends this._args = args; } - clone (): ActionUnknownDuration { + override clone (): ActionUnknownDuration { return new ActionUnknownDuration(this._cb, this._args); } - reverse (): ActionUnknownDuration { + override reverse (): ActionUnknownDuration { return this.clone(); } - step (dt: number): void { + override step (dt: number): void { throw new Error('should never go here'); } - update (t: number): void { + override update (t: number): void { const dt: number = cclegacy.game.deltaTime; this._finished = this._cb(this.target as T, dt, ...this._args); } - isDone (): boolean { + override isDone (): boolean { return this._finished; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return !this.isDone(); } + + override toString (): string { + return ``; + } } diff --git a/cocos/tween/actions/action.ts b/cocos/tween/actions/action.ts index 1695bf6ed34..bcb2718e08e 100644 --- a/cocos/tween/actions/action.ts +++ b/cocos/tween/actions/action.ts @@ -57,6 +57,8 @@ export abstract class Action { /** * The tween who owns this action. + * @engineInternal + * @mangle */ public _owner: Tween | null = null; @@ -146,6 +148,8 @@ export abstract class Action { /** * Return the worker target of the current action applys on. + * @engineInternal + * @mangle * * Example 1: * ```ts diff --git a/cocos/tween/tween-action.ts b/cocos/tween/tween-action.ts index f549ffd58c0..6a4ceba276c 100644 --- a/cocos/tween/tween-action.ts +++ b/cocos/tween/tween-action.ts @@ -202,7 +202,7 @@ export class TweenAction extends ActionInterval { return !!this._opts.relative; } - clone (): TweenAction { + override clone (): TweenAction { const action = new TweenAction(this._duration, this._originProps, this._opts); action._reversed = this._reversed; action._owner = this._owner; @@ -211,7 +211,7 @@ export class TweenAction extends ActionInterval { return action; } - reverse (): TweenAction { + override reverse (): TweenAction { if (!this._opts.relative) { warnID(16382); return new TweenAction(0, {}); @@ -224,7 +224,7 @@ export class TweenAction extends ActionInterval { return action; } - startWithTarget (target: U | null): void { + override startWithTarget (target: U | null): void { const isEqual: TypeEquality = true; if (!isEqual) return; super.startWithTarget(target); @@ -340,7 +340,7 @@ export class TweenAction extends ActionInterval { if (this._opts.onStart) { this._opts.onStart(workerTarget); } } - stop (): void { + override stop (): void { const props = this._props; for (const name in props) { const prop = props[name]; @@ -354,7 +354,7 @@ export class TweenAction extends ActionInterval { super.stop(); } - update (t: number): void { + override update (t: number): void { const workerTarget = this._getWorkerTarget(); if (!workerTarget) return; @@ -414,7 +414,7 @@ export class TweenAction extends ActionInterval { return current = start + (end - start) * t; } - isUnknownDuration (): boolean { + override isUnknownDuration (): boolean { return false; } }