Add Tween.bindNodeState to mark whether tween's lifecycle needs to associate with node target 's state. (#18565)

This commit is contained in:
James Chen
2025-04-08 16:42:17 +08:00
committed by GitHub
parent 155a7bfa4d
commit 0c65d3e0ce
3 changed files with 120 additions and 7 deletions
+7 -6
View File
@@ -124,12 +124,8 @@ export class ActionManager {
* 如果目标不存在,将为这一目标创建一个新的实例,并将动作添加进去。<br/>
* 当目标状态的 paused 为 true,动作将不会被执行
*
* @method addAction
* @param {Action} action
* @param {object} target
* @param {Boolean} paused
*/
addAction<T> (action: Action | null, target: T, paused: boolean): void {
addAction<T> (action: Action | null, target: T, paused: boolean, isBindNodeState: boolean = true): void {
if (!action || !target) {
errorID(1000);
return;
@@ -146,8 +142,13 @@ export class ActionManager {
element.actions = [];
}
if (element.actions.length === 0 && target instanceof Node) {
const registerNodeEvent = isBindNodeState && element.actions.length === 0 && target instanceof Node;
if (registerNodeEvent) {
this._registerNodeEvent(target);
if (!target.active) {
element.paused = true; // if the target is not active, we need to pause the action
}
}
// update target due to the same UUID is allowed for different scenarios
+19 -1
View File
@@ -106,11 +106,29 @@ export class Tween<T extends object = any> {
private _target: T | null = null;
private _tag = ActionEnum.TAG_INVALID;
private _timeScale = 1;
private _isBindNodeState = true; // The default value is true which is compatible with Creator 2.x. See 'bindNodeState' method.
constructor (target?: T | null) {
this._target = target === undefined ? null : target;
}
/**
* @en Set whether to bind the current tween's lifecycle with node target's state. (Supported from v3.8.7)
* If set it to true :
* - When the node is activated, the tween will automatically resume.
* - When the node is deactivated, the tween will automatically pause.
* - When the node is destroyed, the tween will automatically be destroyed.
* @zh 设置当前缓动是否需要关联节点状态。如果设置为真,那么节点被激活,缓动会被自动恢复,节点被禁用,缓动会被自动暂停,节点销毁后,缓动会被自动销毁。 (从 v3.8.7 开始支持)
* @param isBindNodeState @en Whether to associate node state for the current tween. @zh 关联节点状态。
* @return @en The instance itself for easier chaining. @zh 返回该实例本身,以便于链式调用。
* @note @en If not set, the default value is true which is compatible with Creator 2.x. If only works on the tween with Node target.
* @zh 如果此接口未被调用,为兼容 Creator 2.x,其默认值为 true 。此方法只针对 Node 目标的 tween 有效。
*/
bindNodeState (isBindNodeState: boolean): Tween<T> {
this._isBindNodeState = isBindNodeState;
return this;
}
/**
* @en Sets tween tag
* @zh 设置缓动的标签
@@ -323,7 +341,7 @@ export class Tween<T extends object = any> {
final.setSpeed(this._timeScale);
final.setStartTime(time);
final.setPaused(false); // If a tween was paused, starting the tween again should clear the 'paused' flag for the final action.
getActionManager().addAction(final, this._target, false);
getActionManager().addAction(final, this._target, false, this._isBindNodeState);
} else {
warnID(16393);
}
+94
View File
@@ -5004,3 +5004,97 @@ test('parallel with set action', function () {
director.unregisterSystem(sys);
});
test('bindNodeState(true) default test', function () {
const sys = new TweenSystem();
(TweenSystem.instance as any) = sys;
director.registerSystem(TweenSystem.ID, sys, System.Priority.MEDIUM);
const scene = new Scene('test');
director.runSceneImmediate(scene);
const node = new Node();
scene.addChild(node);
node.active = false;
tween(node)
.by(1, { position: v3(1, 1, 1) })
.start();
runFrames(1); // start
runFrames(60);
expect(node.position.equals(v3(0, 0, 0))).toBeTruthy();
node.active = true;
runFrames(1); // start
runFrames(60);
expect(node.position.equals(v3(1, 1, 1))).toBeTruthy();
director.unregisterSystem(sys);
});
test('bindNodeState(true) test', function () {
const sys = new TweenSystem();
(TweenSystem.instance as any) = sys;
director.registerSystem(TweenSystem.ID, sys, System.Priority.MEDIUM);
const scene = new Scene('test');
director.runSceneImmediate(scene);
const node = new Node();
scene.addChild(node);
node.active = false;
tween(node)
.bindNodeState(true)
.by(1, { position: v3(1, 1, 1) })
.start();
runFrames(1); // start
runFrames(60);
expect(node.position.equals(v3(0, 0, 0))).toBeTruthy();
node.active = true;
runFrames(1); // start
runFrames(60);
expect(node.position.equals(v3(1, 1, 1))).toBeTruthy();
director.unregisterSystem(sys);
});
test('bindNodeState(false) test', function () {
const sys = new TweenSystem();
(TweenSystem.instance as any) = sys;
director.registerSystem(TweenSystem.ID, sys, System.Priority.MEDIUM);
const scene = new Scene('test');
director.runSceneImmediate(scene);
const node = new Node();
scene.addChild(node);
node.active = false;
tween(node)
.bindNodeState(false)
.by(2, { position: v3(2, 2, 2) })
.start();
runFrames(1); // start
runFrames(60);
expect(node.position.equals(v3(1, 1, 1))).toBeTruthy();
node.active = true;
runFrames(60);
expect(node.position.equals(v3(2, 2, 2))).toBeTruthy();
director.unregisterSystem(sys);
});