Controlling Animation with Scripts

Animation Component

The Animation Component manages a set of animation states that control the play, pause, resume, stop, switch, etc. of each animation. The Animation Component creates a corresponding Animation State object for each Animation Clip. The Animation State is used to control the Animation Clips that need to be used on the object.

In the Animation Component, Animation States are identified by name, and the default name of each animation state is the name of its Animation Clip.

Adding an Animation Component to a node in a script is done in the following way:

  1. import { Animation, Node } from 'cc';
  3. function (node: Node) {
  4.     const animationComponent = node.addComponent(Animation);
  5. }

Playing and switching animations

Playing animations

The Animation Component controls the playback of the specified animation via the play() API, e.g:

  1. // Play the animation state 'idle'
  2. animationComponent.play('idle');
  4. // Specify that the 'idle' animation will be played from 1s onwards
  5. animationComponent.play('idle', 1);

If no specific animation is specified and defaultClip is set when using play to play an animation, the defaultClip animation will be played. If the playOnLoad of the Animation Component is also set to true, the Animation Component will automatically play the contents of defaultClip on the first run.

  1. // The defaultClip animation will be played if the defaultClip is set without specifying the animation to be played
  2. animationComponent.play();

Switching animation

When using the play interface to play an animation, if there are other animations playing at the same time, the other animations will be stopped immediately. This switch is very abrupt, and in some cases we want the switch to be a “fade in and fade out” effect, use crossFade() to smoothly complete the switch within the specified period. For example:

  1. // Play the animation state 'walk'
  2. animationComponent.play('walk');
  4. /* ... */
  6. // Smoothly switch from walk to run animation in 0.3 seconds
  7. animationComponent.crossFade('run', 0.3);

This fade-in and fade-out mechanism of crossFade() makes it possible for more than one Animation State to be playing at the same moment. Therefore, the Animation Component has no concept of the current animation.

Even so, the Animation Component provides pause(), resume(), and stop() methods that pause, resume, and stop all the animation states being played while also pausing, resuming, and stopping the animation switching.

For more details about the control interface related to the Animation Component, please refer to the Class Animation.

Animation State

The Animation Component only provides some simple control functions, which are mostly sufficient and easy to use, but for more animation information and animation control interfaces, review the Animation State documentation.

Frame Events

The Animation panel supports visual editing of event frames, or frame events can be added directly to the script.

The events of an AnimationClip contain all the frame events of this animation, each with the following properties:

  1. {
  2.     frame: number;
  3.     func: string;
  4.     params: any[];
  5. }
  • frame: the point in time when the event will be triggered, in seconds. For example, 0.618 means the event will be triggered when the animation reaches the 0.618th second. For the conversion between timeline scale units, please refer to the Scale Unit Display of the Timeline documentation.
  • func: indicates the name of the function that will be called back when the event is triggered. When the event is triggered, the animation system will search all the components in the animation root node, if there is a component that implements the function specified in func of the animation event, it will call it and pass in the parameters in params.

For example, if an event frame is added at 0.5s of the animation timeline:

keyframe

The code implemented in the script is as follows:

  1. {
  2.     frame: 0.5;
  3.     func: 'onTrigger';
  4.     params: [ 0 ];
  5. }

Example

The following code indicates that the default Animation Clip of the Animation Component of the node where the MyScript script component is located will call the onTriggered() method of the MyScript component when it reaches the 0.5 second mark and pass the parameter 0.

  1. import { Animation, Component } from 'cc';
  2. class MyScript extends Component {
  3.     constructor() {
  5.     }
  7.     public start() {
  8.         const animationComponent = this.node.getComponent(Animation);
  9.         if (animationComponent && animationComponent.defaultClip) {
  10.             const { defaultClip } = animationComponent;
  11.             defaultClip.events.push({
  12.                 frame: 0.5, // Triggers the event on the 0.5 second
  13.                 func: 'onTriggered', // The name of the function to call when the event is triggered
  14.                 params: [ 0 ], // Parameters passed to `func`
  15.             });
  16.             defaultClip.updateEventDatas();
  17.         }
  18.     }
  20.     public onTriggered(arg: number) {
  21.         console.log('I am triggered!');
  22.     }
  23. }

Animation Events

In addition to the callbacks provided by the frame events in the Animation panel, the animation system also provides a way to call back animation events. The currently supported callback events include:

  • play: triggered when playback starts
  • stop: triggered when playback is stopped
  • pause: triggered when playback is paused
  • resume: triggered when playback is resumed
  • lastframe: if the animation loop is greater than 1, triggered when the animation reaches the last frame.
  • finished: trigger when the animation is finished.

For more details, please refer to the Animation.EventType API.