AnyPortrait > Manual > Animation Events and Script
Animation Events and Script
1.4.5
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
1.3.4
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
1.4.0
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
1.4.0
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.
Add an event by preset in the current frame directly
1.4.5
You can shorten the steps of creating events and applying presets.
Let's select a frame and create an event with a preset applied at once.
(1) Move the time slider to the location where the event will be created.
(2) Select a preset.
(3) Pressing the Add Event by Preset button creates an event with the preset applied to the frame.
Assign a category of presets
1.4.5
When there are too many event presets, it becomes difficult to find the preset you need each time from the list.
In this case, using "Category", presets with similar purposes can be grouped and managed.
(1) Select a preset.
(2) Let's change the Category property.
Currently, there is no registered category, so select "+ New Category.." to register a new category.
Set the name of the new category.
Let's apply the created categories to other presets.
(1) Select another preset.
(2) Select the Category property and you will see that the category you just created has been added.
(1) You can change the category at the top of the preset list.
If you select a category other than Everything, only the presets of that category are displayed in the list.
If there are no presets with a specific category, the category is automatically deleted.
Fix invalid event names
1.4.1
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
1.4.1
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
1.4.1
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 () { Debug.Log("Event A"); }
private void OnAnimEvent_A ( float floatValue ) { Debug.Log("Event A (Overloaded)"); }
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.