animation-component.md

Animation component

Animation components control the playback of animations.

Animation components are added to nodes in exactly the same way as other components:

import { Animation, Node } from "cc";

function (node: Node) {
    const animationComponent = node.addComponent(Animation);
}

The animation component manages a set of animation clips. Before the animation component begins, it creates a corresponding animation state object for each animation clip. The animation state controls the playback process of an animation clip at a node, and an animation clip can be used by multiple animation states at the same time.

In an animation component, the animation state is identified by name. The default name of each animation state is the name of its animation clip.

Playing and switching animations

play() causes the __animation componen__t to start playing the specified animation:

animationComponent.play('idle'); // play animation state 'idle'

When playing, the old animation will be stopped immediately, this switch is very abrupt. In some cases, we want this switch to fade in and out. The crossFade() method can be used to achieve this. crossFade() will complete the switch smoothly within the specified period:

animationComponent.play('walk');

/* ... */

// When you need to switch to running animation
animationComponent.crossFade('run', 0.3); // Smoothly switch from walking animation to running animation in 0.3 seconds

The crossFade() fade-in and fade-out mechanism makes it possible for more than one animation state to play at the same time. Therefore, the animation component has no concept of the current animation.

The animation component still provides pause(), resume() and stop() methods. These calls pause, continue, and stop all animation states that are playing, however, they also pause, resume, and stop switching animations.

Animation State

Sometimes it is necessary to perform other operations on the animation state, for example, to set its speed.

You can get the animation state through getState():

const animationComponent = node.getComponent(Animation);
animationComponent.clips = [ idleClip, runClip ];

// Get the status of `idleClip`
const idleState = animationComponent.getState(idleClip.name);

You can set the speed of the animation playback:

animationComponent.getState('idle').speed = 2.0; // Play standby animation at double speed

The animation state also provides play(), pause(), resume() and stop(). These control common playback functions. When these common playback controls cannot meet your requirements, it is also possible to manipulate the playback of the animation state in a custom way.

Default animation

When the animation component's playOnLoad is true, it will automatically play the default animation clip, defaultClip, the first time it runs.

Frame events

You can add events for each time point of the animation.

The events of an AnimationClip contains all event descriptions for the animation, and each event description has the following properties:

{
    frame: number;
    func: string;
    params: any[];
}

frame represents the time point at which the event was triggered, in seconds. For example, 0.618 means that the event will be triggered when the animation reaches 0.618 seconds.

func represents the method name that is called back when the event is triggered. When the event is triggered, a search for a method named func on all components of the current node, once found, it is called with params passed to it. Example:

import { Animation, Component } from "cc";
class MyScript extends Component {
    constructor() {

    }

    public start() {
        const animationComponent = this.node.getComponent(Animation);
        if (animationComponent && animationComponent.defaultClip) {
            const { defaultClip } = animationComponent;
            defaultClip.events.push({
                frame: 0.5, // trigger event on the 0.5 second
                func: 'onTriggered', // name of event to be called
                params: [0], // parameters passed to `func`
            });
            defaultClip.updateEventDatas();
        }
    }

    public onTriggered(arg: number) {
        console.log(`I'm triggered!`);
    }
}

The above code indicates that the default animation clip of the animation component at the node where the MyScript component is located. At the 0.5th second, it will call the test() method of the MyScript component and pass the parameter 0.