Animation component
Animation components control the playback of animations.
Animation components are added to nodes in exactly the same way as other components:
import { AnimationComponent, Node } from "cc";
function (node: Node) {
const animationComponent = node.addComponent(AnimationComponent);
}
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 component 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(AnimationComponent);
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 { AnimationComponent, Component } from "cc";
class MyScript extends Component {
constructor() {
}
public start() {
const animationComponent = this.node.getComponent(AnimationComponent);
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
.