AnimationEvent
Thank you for helping us improve the quality of Unity Documentation. Although we cannot accept all submissions, we do read each suggested change from our users and will make updates where applicable.
Submission failed
For some reason your suggested change could not be submitted. Please <a>try again</a> in a few minutes. And thank you for taking the time to help us improve the quality of Unity Documentation.
Description
AnimationEvent lets you call a script function similar to SendMessage as part of playing back an animation.
Animation events support functions that take zero or one parameter. The parameter can be a float, an int, a string, an object reference, or an AnimationEvent.
A more detailed example below shows a more complex way of creating an animation. In this script example the Animator component is accessed and a Clip from it obtained. (This clip was set up in the Animation window.) The clip lasts for 2 seconds. An AnimationEvent is created, and has parameters set. The parameters include the function PrintEvent() which will handle the event. The event is then added to the clip. This all happens in Start() . Once the game has launched the event is called after 1.3s and then repeats every 2s.
Using Animation Events
Use Animation Events to call functions at specific points in the timeline. These functions can be in any script attached to the GameObject.
The function called by an Animation Event also has the option to take one parameter. The parameter can be a float , string , int , or object reference, or an AnimationEvent object. The AnimationEvent object has member variables that allow a float, string, integer and object reference to be passed into the function all at once, along with other information about the Event that triggered the function call.
To add an Animation Event to a clip at the current playhead position, click the Event button. To add an Animation event to any point in the Animation, double-click the Event line at the point where you want the Event to be triggered. Once added, you can drag the mouse to reposition the Event. To delete an Event, select it and press the Delete key, or right-click on it and select Delete Event.
Animation Events are shown in the Event Line. Add a new Animation Event by double-clicking the Event Line or by using the Event button.
When you add an Event, the Inspector A Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary Window displays several fields. These fields allow you to specify the name of the function you want to call, and the value of the parameter you want to pass to it.
The Animation Event Inspector Window
The Events added to a clip are shown as markers in the Event line. Hold the mouse over a marker to show a tooltip with the function name and parameter value.
You can select and manipulate multiple Events in the timeline.
To select multiple Events in the timeline, hold the Shift key and select Event markers one by one to add them to your selection. You can also drag a selection box across them; click and drag within the Event marker area, like this:
Example
This example demonstrates how to add Animation Events to a simple GameObject. When all the steps are followed, the Cube animates forwards and backwards along the x-axis during Play mode, and the Event message is displayed in the console every 1 second at the 0.8 second time.
The example requires a small script with the function PrintEvent() . This function prints a debug message which includes a string (“called at:”) and the time:
Create a script file with this example code and place it in your Project folder (right-click inside the Project window in Unity and select Create > C# Script, then copy and paste the above code example into the file and save it).
In Unity, create a Cube GameObject (menu: GameObject The fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary > 3D Object A 3D GameObject such as a cube, terrain or ragdoll. More info
See in Glossary > Cube). To add your new script file to it, drag and drop it from the Project window into the Inspector window.
Select the Cube and then open the Animation window (menu: Window > Animation > Animation or use ctrl+6). Set a Position curve for the x coordinate.
Animation window
Next, set the animation for the x coordinate to increase to around 0.4 and then back to zero over 1 second, then create an Animation Event at approximately 0.8 seconds. Press Play to run the animation.
Unity Animation Event Explained
The title should have been: Death of an Enemy. I was writing about how I made my enemy die under the blows of my character, when I decided to make some research, to improve a little my work.
In search of gold, I found diamonds.
I was planning to make the enemies die after reaching 0 health. By die, I mean that the enemy would stop any activity, trigger a death animation and then, after a while, it would be removed from the scene.
Animation Events and Script
Depending on the game, at some point in the animation, the character needs some interaction.
When a running character makes a jump, it may get dirty or a swinging sword may hit a monster.
In this page, you will learn how to use the animation event function to interact with the script.
(C # script included.)
In the Animation Properties UI, click the Animation Events button to open a dialog that registers an animation event.
You can see the description of the animation event dialog changed in AnyPortrait v1.4.0 at the bottom of the page.
Adding an Animation Event and associating them with a Script
(1) Click the Add Event button to add a new event.
(2) Set the name of the event and enter the frame to be called.
The name of the event is linked with the script, so remember the name at that time.
I created it here as SampleAnimEvent .
When an animation event is added, you can see that an event marker has been added to that location in the timeline GUI.
Bake and go to the scene.
Create a script to be associated with the event.
(1) Create a GameObject to contain the script. (It does not have to be a new one; it can be anything GameObject that contains the script.)
(2) Create and add a MonoBehaviour script.
Write the following code:
Remember that the animation event you created above is named SampleAnimEvent .
using UnityEngine;
public class AnimEventListener : MonoBehaviour
<
void Start() < >
void SampleAnimEvent()
<
Debug .Log( «Sample Anim Event» );
>
>
As you can see in the code above, we call a function with the same name as the created animation event.
Therefore, animation events and scripts must have the same name and the same arguments.
When you select a character, the apPortrait properties are displayed in the Inspector.
To allow the script to receive events, set the GameObject that contains the script you just created into the Event Listener.
When you run the game, an event occurs, and you can see in the console window that the script takes it and prints the log.
Adding a Parameter to an animation event
You can add a parameter to an animation event.
At this time, the parameter is called as an argument of the function.
(1) Press the Add Parameter button to add the parameter.
(2) Select the parameter type and (3) enter the value to be transferred.
(The types that can be passed as parameters are Bool, Int, Float, Vector2, String.)
using UnityEngine;
public class AnimEventListener : MonoBehaviour
<
void Start() < >
void SampleAnimEvent( float floatValue)
<
Debug .Log( «Sample Anim Event — » + floatValue);
>
>
Modify the function to receive the parameters.
Declare a parameter for the variable type.
When you run the game, you can see that the value of the parameter is passed.
Making Animation Events call continuously on multiple frames
Sometimes you need to fire an event continuously over a certain frame instead of raising an event in one frame.
(1) Change the Call Method from Once to Continuous.
(2) Set Start Frame and End Frame respectively.
(3) Two parameter values can be specified.
Each value is called by the Start Frame and the End Frame. In between, the value interpolated linearly is passed to the script.
(String type is not interpolated, so this function is not supported.)
Continuous type animation events are represented by markers of different colors. The starting point is blue and the ending point is green.
If you run the game after bake, you will see that the interpolated value is called every frame.
Create an animation event with two or more parameters
You can also create animation events with multiple parameters.
Each parameter can have a different type.
The above screen is a screen with three parameters, Integer, Float, and Vector2 respectively.
(I create a new animation event, named MultipleParamAnimEvent.)
using UnityEngine;
public class AnimEventListener : MonoBehaviour
<
void Start() < >
void MultipleParamAnimEvent( object [] multipleParams)
<
int intParam = ( int )multipleParams[0];
float floatParam = ( float )multipleParams[1];
Vector2 vector2Param = ( Vector2 )multipleParams[2];
Debug .Log( «Multiple Param Anim Event» );
Debug .Log( «Param 1 : » + intParam);
Debug .Log( «Param 2 : » + floatParam);
Debug .Log( «Param 3 : » + vector2Param);
>
>
Only one argument of the object array type is used as a function parameter, not three arguments.
This array contains the parameters in the order you defined them in the editor.
Variables can be referenced via type casting.
When you run the game, you will see that three parameters are passed to the script.
Animated Events in the improved Inspector
Through the inspector (Related page) updated in AnyPortrait v1.3.4, you can quickly check animation events.
It is also possible to copy animation events into a script, or change the method they are called.
When you select a character with an animated event in the Unity scene, a screen like the one above will appear in the inspector.
(1) The animation call method can be selected from Send Message and Callback. The method used is Send Message.
(2) A listener object to receive and process animation events. (The location of this item that existed at the top of the existing Inspector has been changed.)
(3) Animation event list. You can check the event name and parameters.
(4) Copy the animation event to the clipboard. The copied form is processed so that it can be pasted into a C# script.
(5) Copy all animation events to the clipboard.
Let’s use the added function «Copy animation events to clipboard».
First, press the copy button in (4) or (5).
If you open the script editor and paste it, the code that matches the names and formats of the animation events is added as shown above.
You will now be able to avoid the unnecessary effort of memorizing and writing animation events.
Another feature added in v1.3.4 is the Callback method.
If the existing Send Message uses Unity Send Message, this is similar to Unity Event, which specifies a function directly.
It not only improves performance, but also has the advantage of not having to set the same name of the function to receive the event.
(We didn’t actually use Unity Event, but we developed it almost similarly so that users can use it like Unity Event.)
(1) Let’s change Event Method to Callback.
The original Event Listener disappears, and the UI is changed to be able to assign the call targets for each event.
(1) Press the + button.
(2) An item that can set event listeners and callback functions is added.
(1) Allocate a Monobehaviour object that will receive events from the scene.
(2) If you click the blank on the right, a list of functions that can receive events appears. Choose the appropriate function.
If more than one Monobehaviour component is added to one GameObject, the listener can be replaced through the function list.
(1) In the same way, you can set one event to be received by multiple listeners or multiple functions at the same time.
(2) To delete an item, press the — button.
When designating a callback function, if there is no function that matches the event type (number, type, order of parameters), nothing appears in the list as above.
Either way, you can make your script receive animation events and run.
Try the method that works for you!
Improved Animation Event Markers
An option to set the color of event markers has been added to easily distinguish events on the timeline.
(1) Select an animation event.
(2) Let’s change the value of Marker Color.
(1) You can see that the color of the animation event marker icon has changed in the timeline UI.
(2) You can see which color has been set in the event list.
In addition, the marker of the Continuous type event has been improved to appear more intuitively in the timeline UI.
Animation Event Presets
When an animation event with the same name is called in multiple animations, it would be handy to have the ability to save it for reuse.
AnyPortrait v1.4.0 has added the ability to save animation events as presets and utilize them.
(1) The left side of the animation event dialog shows the current animation event list and the properties of the selected event as before.
(2) The newly added Animation Event Presets appear on the right side of the dialog box.
(1) Select the animation event you want to save.
(2) Press the Save as Preset button.
(1) The selected event has been added to the animation event preset list.
(2) When you select a preset, the properties of the preset are displayed.
(3) If you want to delete the selected preset, click the Remove Event Preset button.
This feature can be used for the same animation as well as other animations.
Let’s add an event to another animation using the saved preset.
(1) Select another animation.
(2) Move the time slider to the position where you want to add the event.
(3) Click the Animation Events button.
(1) Click the Add Event button.
(2) Select the added event.
(3) Select the preset you want to apply.
(4) Press the Apply Selected Preset button.
(5) Check the message and click the Apply button.
You can see that the animation event information saved as a preset is copied and applied.
Fix invalid event names
Animation events will be called from scripts, so they should be named according to scripting conventions where possible.
— The name must be a combination of Alphabets, numbers, and underscore («_»), and spaces are not allowed.
— Blank Name is not allowed.
— «Overloading» is not allowed when the call method is «Send Message«. That is, there must not be more than one event with the same name with different parameter combinations.
If the name of the event is invalid, you can use a function that automatically corrects the name.
(1) The name of the above animation event is «Sample Event Name (!)». By convention, this name is invalid because it contains special characters and spaces.
(2) A message appears explaining why the name of the event is invalid.
(3) If you click the Fix now button, the name is automatically corrected. (However, if there is no valid character, it will not be modified.)
Assign the event listener easily in Callback
The advantage of calling animation events in the Callback method is that you can set up multiple event listeners.
However, it is cumbersome to assign each event listener for every event.
Let’s use a feature that makes this easy.
(1) A character created with AnyPortrait and a GameObject that will act as Event Listener are placed in the scene.
(2) The event call method is set to «Callback«.
(3) Assign GameObject as Event Listener to Target of «Assign Listener to All Events«.
(4) Press the Assign button.
As shown above, you can see that an event listener is commonly assigned to all events.
Now all we need to do is set functions for the event.
Validate callback functions
When assigning a function to be called by an event in «Callback» method, the function cannot be called in the following cases.
— When the event listener does not exist
— When the function with the saved name is not in the event listener
— When a function with a saved name is an «Overloading» function
Fortunately, invalid callback functions do not cause fatal errors during the game.
However, you won’t be able to test that the set events are valid by running the game every time.
Let’s use the function to automatically delete invalid events.
Let’s assume the event listener has the following callback function defined:
private void OnAnimEvent_A ()
private void OnAnimEvent_A ( float floatValue )
Two functions are «Overloading» with the same name but different parameters.
According to the callback rules, these functions are invalid.
(1) Event listeners and functions including the above code are set. An invalid function («OnAnimEvent_A») is also set, but hard to verify whether it is valid.
(2) Click the Validate Events button.
When validation is performed, invalid functions are automatically deleted as above.