Animation Events

Unity's inbuilt Animation Event system works the same when using Animancer as without it. The Unity Manual explains how to set up events using the Animation Tab of a model's import settings or the Animation Window. To receive the events, you simply attach a script to the same object as the Animator component and the engine will look for a method in that script with whatever Function Name the event specifies.

It can be convenient to have your event listener script Interit from AnimancerComponent for organisational purposes (instead of having two separate components), but most events do not actually have any direct interaction with Animancer except for certain standard function names:

These standard functions were implemented in earlier versions of Animancer before v4.0 added Animancer Events but they were never particularly convenient to use so they may be removed in a future version. If you still find them useful, please see the Help and FAQ page for various contact methods you can use to provide feedback.

Function Name Category Parameters
"Play"
"PlayFromStart"
Control Object is the AnimationClip to play.
Int is the layerIndex.
"CrossFade"
"CrossFadeFromStart"
Control Object is the AnimationClip to play.
Float is the fadeDuration
Int is the layerIndex.
"Transition" Control Object is the ITransition to play.
Int is the layerIndex.
"Event" Simple All. The callback is given the whole AnimationEvent.
"End" End Float is the duration which AnimancerPlayable.GetFadeOutDuration returns if it is called during the OnEnd event.

You can see the definitions of these methods in the AnimatorController script (inside the #region Animation Events).

Note that any event with a string or AnimationEvent parameter will allocate some Garbage every time it is triggered, which can potentially cause performance issues.

Control Events

Control events call AnimancerComponent.Play with various different parameters as outlined in the table above.

Note that assigning the wrong type of Object will cause an InvalidCastException at runtime. Most of the control methods require an AnimationClip, but "Transition" requires something that implements ITransition such as a Transition Asset.

Simple Events

The SimpleEventReceiver component has an onEvent callback which is triggered by Animation Events using the function name "Event". This means you can start an animation then register a callback for when its event occurs. It will automatically assert that the AnimationClip actually has an event with that name (while in the Unity Editor).

The SimpleEventReceiver component mainly serves as an example of how you can implement your own events using the AnimationEventReceiver struct, but it could be useful in a simple game if you set up all of your animations with only one event each that uses "Event" as the Function name (Attack script uses the event to indicate the hit time, Walk script uses it to play footstep sounds, etc). The callback takes the triggering AnimationEvent as a parameter so you can access any of its values, including the AnimationClip that it comes from.

Using simple events in code is similar to using End Events, you simply access onEvent on the SimpleEventReceiver rather than the state:

[SerializeField]
private AnimancerComponent _Animancer;

[SerializeField]
private SimpleEventReceiver _EventReceiver;

...

var state = _Animancer.Play(clip);
state.Events.OnEnd = ...;
_EventReceiver.onEvent.Set(state, ...);

It is recommended that you always use Set instead of only setting the Callback to ensure that you only receive the callback from the state you specify. Otherwise events from an animation that is fading out might trigger a callback you just registered for a new animation that is fading in.

The Golf Events example demonstrates the use of this feature.

End Animation Events

Before Animancer v4.0, End Events did not allow you to specify a custom time so they always occured at the end of the animation. This is not always ideal for Cross Fading so it can be useful to trigger the event early to allow the fade to occur while the animation is approaching the end rather than while it is already frozen on its last frame. This can now be done by either setting the End Event to use whatever time you like which is usually much more convenient, but it can also be done by adding an Animation Event with the function name "End".

Such an event will not directly affect the animation. All it does is invoke the OnEnd callback you have registered, so if you have not registered one or if the one you have registered does not stop the animation (usually by starting a different one) then the current animation will continue playing and will still trigger the OnEnd callback when it ends normally.

The script triggering a Fade is usually responsible for determining the fadeDuration (whether by hard coding it or getting it from somewhere else), however when using End Animation Events it can be useful to have the event itself specify the fadeDuration. To allow this, you can simply have your OnEnd callback use the static AnimancerPlayable.GetFadeOutDuration method to get the value from Float parameter of the triggering event:

Value Effect
No Event GetFadeOutDuration takes a minDuration parameter which is used here.
Float <= 0 Use the entire remaining duration of the current animation.
Float > 0 Use the specified value.

The Golf Events example demonstrates the use of this feature.