Animation events provide a way to call a customized function or perform an action at a specific time in an animation clip.
This allows interaction between animations and scripts, and is useful when performing actions at the exact timing of an animation.
Adding Events to Object Animation
The following example adds an animation event to an animated object.
This structure outputs information to the console log whenever an event is executed by adding an Up event and a Down event to the animation that repeats up and down.
- Select GameObject > 3D Object > Cube to create a cube in the scene.
- Select the created cube and add an Animator component by clicking the Add Component button in the Inspector panel.
- Apply the cube Animator Controller to the added Animator.
- Apply the cube animation clip to the entry of the cube Animator Controller so that the cube animation can be played when the scene is played.
Please refer to the following guide for Animator registration and animation clip editing.
Unity Animation Event Guide
https://docs.unity3d.com/kr/current/Manual/script-AnimationWindowEvent.html
Unity Learn Animation Tutorial
https://learn.unity.com/tutorial/may-18-animation?language=en#
- Add the following properties to the cube animation clip.
- There is a key frame of Position (x: 0, y:0, z:0) in the 0 second, 2 second section of the cube's animation clip.
- There is a key frame of Position (x: 0, y:1, z:0) in the 1 second section of the cube's animation clip.
(1) Register an Animation Event in the 1-second section of the animation clip of the cube.
- Function : Invoke
- String : Up
(2) Register an Animation Event in the 2-second section of the animation clip of the cube.
- Function : Invoke
- String : Down
Tips
- When writing animation events through C# in Unity, write the function name in Function.
- However, in order to call an animation event in Typescript, Invoke must be written in Funtion and the function name must be written in String, the argument value.
- Create Project > Create > ZEPETO > TypeScript and rename it to ObjectAnimationController.
- Write a sample script as below.
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
export default class ObjectAnimationController extends ZepetoScriptBehaviour {
public Up() {
console.log(`Cube is Up`);
}
public Down(){
console.log(`Cube is Down`);
}
}
- If you press the play button to run it, you can see the console log output while the animation of the cube is played.
Play footstep sounds using animation events on local characters.
In order to add animation events to the Animator of ZEPETO's character, the event must be added at runtime, when the character is created.
The following example applies an event to a specific Animation Clip of the local player Animator at runtime, and plays a footstep sound when the event fires.
- Create a FootStepController script that will be applied to the local player's animator object. FootStepController is responsible for adding animation events to Animator.
- Create Project > Create > ZEPETO > TypeScript and rename it to FootStepController.
- Write the script as below.
import { AnimationEvent, Animator, AudioClip, AudioSource } from 'UnityEngine';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
export default class FootStepController extends ZepetoScriptBehaviour {
// Sound used for footstep effects
public footStepSound: AudioClip;
// Audio source for playing footstep sound
private _zepetoAudio: AudioSource;
// Adds animation events to trigger footstep sounds
public AddAnimationEvent() {
// Get the Animator component attached to this GameObject
const anim = this.GetComponent<Animator>();
// Check if the Animator component exists
if (anim != null) {
// Create the AudioSource for footstep sounds
this.SetAudio();
// Specify the times in animation clips when footstep sounds should play
const runSoundEventTimes = [0.1, 0.6];
// Add animation events to the specified animation clip
this.AddAnimationClipEvent(anim, "move_walk", runSoundEventTimes);
}
}
// Sets up the AudioSource for playing footstep sounds
private SetAudio() {
// Create and configure the AudioSource component
this._zepetoAudio = this.gameObject.AddComponent<AudioSource>();
this._zepetoAudio.clip = this.footStepSound;
}
// Activates footstep sounds
public ActivateFootSteps() {
// Output a log message indicating that footstep sounds are playing
console.log("FootSteps!");
// Play the footstep sound using the configured AudioSource
this._zepetoAudio.Play();
}
// Adds animation events to a specified animation clip
private AddAnimationClipEvent(anim: Animator, clipName: string, eventTimes: number[]) {
// Initialize the index of the animation clip
let animationClipIndex: number;
// Get all animation clips from the runtimeAnimatorController
const clips = anim.runtimeAnimatorController.animationClips;
// Find the index of the specified animation clip
for (let i = 0; i < clips.length; i++) {
if (clips[i].name == clipName) {
animationClipIndex = i;
}
}
// Iterate through the specified event times
eventTimes.forEach(eventTime => {
// Create a new AnimationEvent for the footstep sound trigger
const newEvent: AnimationEvent = new AnimationEvent();
newEvent.time = eventTime;
newEvent.functionName = "Invoke";
newEvent.stringParameter = "ActivateFootSteps";
// Add the new AnimationEvent to the animation clip
clips[animationClipIndex].AddEvent(newEvent);
});
}
}
-
script description
- FootStepController adds an animation event and plays a footstep sound effect when that event occurs.
- SetAudio() adds an AudioSource component to apply the footstep sound to the object.
- AddAnimationClipEvent() adds an animation event to the specified animation clip. You must put the following elements as argument values.
- Animator for local player
- Animation clip name to which the event is applied
- An array of animation times to apply the event to
-
In the newEvent registered with AddAnimationClipEvent(), the following items are set.
(1) newEvent.time : The animation time when the event fires. A value of 0 is the beginning of the full length, and a value of 1 is the end of the full length.
(2) newEvent.functionName : The name of the function the event fires. In Typescript, it should be typed as "Invoke".
(3) newEvent.stringParameter : The parameter value set to the function when the event executes the function. Typescript lists the function name to be executed.
- When an event occurs, ActivateFootSteps() is executed and footstep sounds are played.
- Now create a FootStepManager that adds a FootStepController component to the local player's Animator object when the local player is created at runtime.
- Project > Create > ZEPETO > TypeScript and rename it to FootStepManager.
- Write the script as below.
import { SpawnInfo, ZepetoPlayers } from 'ZEPETO.Character.Controller'
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import FootStepController from './FootStepController'
import { WorldService } from 'ZEPETO.World'
import { AudioClip } from 'UnityEngine';
export default class FootStepManager extends ZepetoScriptBehaviour {
// Sound to be played for footsteps
public footStepSound: AudioClip;
Start() {
// Event listener when the local player is added
ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
// Access the Zepeto character of the local player
const zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;
// Attach the FootStepController script to the ZepetoAnimator's GameObject
const footStepController = zepetoCharacter.ZepetoAnimator.gameObject.AddComponent<FootStepController>();
// Set the footStepSound for the FootStepController
footStepController.footStepSound = this.footStepSound;
// Add animation events to trigger footsteps
footStepController.AddAnimationEvent();
});
}
}
- script description
- After the FootStepManager detects that a local player is being added, it attaches the FootStepController script to the player's ZepetoAnimator's GameObject.
- FootStepController is responsible for adding animation events that play footstep sounds.
Tips
- The script of the function executed by the animation event of the Animator must be identically applied to the object to which the corresponding Animator component is applied.
- So you need to find ZepetoAnimator.gameObject and apply the FootStepController script as AddComponent.
- Apply footstep sound to footStepSound of FootStepManager.
- If you press the Play button to run it, you can see that the sound is played according to the steps of the local player whenever they walk.
Tips
- ZEPETO Basic Animator's Walk State consists of several animation blends and states.
- Since the example applies sound only to the move_walk state, you can customize AddAnimationClipEvent() and input it directly to states such as fast walking and running.
- When sound is applied to multiple Animation States, footstep sounds may overlap due to animation blend. To solve this, write an additional conditional statement so that the corresponding sound is played when AnimationEvent.animatorClipInfo.weight is 0.5.
Known-Issue
- When implemented following the development guide style, the following error message may appear, but there should be no problem with execution.
