Using animation events

14min
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.
﻿
﻿
1) 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#﻿
﻿
2) 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
﻿
﻿
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.
﻿
3) Create Project > Create > ZEPETO > TypeScript and rename it to ObjectAnimationController.
Write a sample script as below.
ObjectAnimationController.ts
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`);
    }
}
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`);
    }
}
﻿
4) 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.
1) 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.
FootStepController.ts
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);
        });
    }
}
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.
﻿
﻿
2) 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.
FootStepManager.ts
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();

        });
    }

}
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.
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.
﻿
3) Apply footstep sound to footStepSound of FootStepManager.
﻿
﻿
4) 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.
﻿
﻿
Updated 10 Oct 2024
Did this page help you?
Quarter View Example
Measuring your character's height