Tweening

In order to be fully compatible with and maintain the experience of the Cocos Creator v2.x easing system, all the Cocos Creator v2.x functions are transplanted in Cocos Creator 3.0.

Note: action has been abandoned, please use tween.

Note: there is no longer a dependency on tween.js. If you use the relevant features of tween.js, please adapt.

Note: the onStart, onUpdate, onComplete callbacks were added to the optional attributes of to and by.

The difference from the previous tween.js is mainly optional attributes, explained as follows:

  • The value definition of easing has been changed (compatibility is done here).
  • In addition to easing, onStart, onUpdate, onComplete, other properties are not supported yet (checked here, the console will have a corresponding warning).

Example

  1. import { _decorator, Component, Vec3, tween } from 'cc';
  2. @ccclass("tween-test")
  3. export class tweentest extends Component {
  4. private _pos: Vec3 = new Vec3(0, 0, 0);
  5. start () {
  6. /** Easing _pos */
  7. tween(this._pos)
  8. .to(3, new Vec3(10, 10, 10), { easing: 'bounceInOut' })
  9. .to(3, new Vec3(0, 0, 0), { easing: 'elasticOut' })
  10. .union()
  11. .repeat(2) // 执行 2 次
  12. .start();
  13. /** Easing Node, here will ease the Node's position property */
  14. tween(this.node)
  15. .to(3, { position: new Vec3(10, 10, 10) }, { easing: 'bounceInOut' })
  16. .to(3, { position: new Vec3(0, 0, 0) }, { easing: 'elasticOut' })
  17. .union()
  18. .repeat(2) // execute 2 times
  19. .start();
  20. }
  21. }

Precautions

repeat semantics

Previously, the semantics of repeat was repeated several times. In order to fully maintain the design of Cocos Creator 2D, repeat is executed several times, that is, repeat(1) stands for one execution.

Restrictions

In-order to reduce the frequency of updating the Node Transform information, Node maintains a dirty state. Only when an interface that may change the Node Transform information is called, will dirty be set to the state that needs to be updated.

Note: the current interface has certain restrictions, for example position obtained through this.node.position is a generic Vec3.

When this code this.node.position.x = 1 is executed, only the getter of position is executed, and the setter of position is not executed. Since dirty is not updated, it will cause the Transform information of the nodes used during rendering not to be updated.

Such calls are not supported, but the use of setPosition or position is encouraged. Example:

  1. let _pos = new Vec3(0, 1, 0);
  2. this.node.position = _pos; // here will pass the position setter
  3. this.node.setPosition(_pos); // here will setPosition through interface

The right way of easing

In the new Tween module, you can obtain properties with getter and setter, such as the position property of node (in the simple example above). During the easing process, the corresponding interface will be carried out, making setting changes to ensure that dirty is updated normally.

Note: pay attention to stop the corresponding slow motion when switching scenes.

Tween interface introduction

InterfaceExplanation
toAdd an interval action that calculates the absolute value of the property
byAdd an interval action to calculate the relative value of the property
setAdd a momentary action that sets the target property directly
delayAdd an instant action of delay time
callAdd an instant action of call callback
targetAdd a instant action to directly set the slow-motion target
unionPackage the easing action of the context into one
thenInsert a Tween into the easing queue
repeatExecution several times (previously repeated several times, if using, please adapt)
repeatForeverAlways repeat execution
sequenceAdd a sequential slow motion
parallelAdd a simultaneous easing
startStart slow motion
stopStop slow motion
cloneClone Easing
showTo enable rendering on the node chain, the slowing target needs to be Node
hideDisable rendering on the node chain, the slowing target needs to be Node
removeSelfMove the node out of the scene tree, the slowing target needs to be Node

Optional attributes of to and by

The definition is as follows:

  1. interface ITweenOption {
  2. easing?: TweenEasing | ((k: number) => number);
  3. progress?: (start: number, end: number, current: number, ratio: number) => number;
  4. onStart?: (target: object) => {};
  5. onUpdate?: (target: object, ratio: number) => {};
  6. onComplete?: (target: object) => {};
  7. }

The difference with Cocos Creator 2D is the addition of properties such as onStart, onUpdate, and onComplete. These properties are callback functions, which will be passed into the easing target when called.

In addition, an additional value of the current easing will be passed in when onUpdate is called, and the range is (0-1).

Example of using callback

Taking onUpdate as an example, the following code eases a position, and then setting it to multiple objects in onUpdate, this demonstrates batch easing.

  1. import { Node, tween, Vec3 } from 'cc';
  2. const nodeArray: Node[] = []; // Replace here with your node array
  3. const tweenTargetVec3 = new Vec3();
  4. tween(tweenTargetVec3)
  5. .by(1, new Vec3(1, 1, 1), {
  6. 'onUpdate': (target: Vec3, ratio: number) => {
  7. for (let i = 0; i < nodeArray.length; i++)
  8. nodeArray[i].worldPosition = target;
  9. }
  10. });

Automatic destruction

In Cocos Creator 3.0, when the easing target is Node, it will listen to its destruction event for automatic destruction of the easing. This calls the target method and also automatically updates the listener.

Note: related test cases are located on GitHub.

Note: please refer to Using the Tween System documentation.