The Events page compares the differences between Unity's inbuilt Animation Events and Animancer Events, but there are several other important details about the way the system works.
|Looping||Events on looping animations are triggered on every loop.|
|Clear Automatically||By default, playing a new animation will clear the events from the old animation.|
|Other Details||Various other minor details.|
Events behave differently depending on whether the animation is looping or not:
|Non-Looping||Once on the frame when the animation passes the specified time.|
Every loop on the frame when the animation passes the specified time.
|End Events||On every frame when the animation has passed the specified time, regardless of whether the animation is looping or not.|
Stop automatically clears the events of all states unless
AnimancerState.AutomaticallyClearEvents is set to false. This ensures that you do not have to worry whether or not other scripts have used the same animation previously. Each script that plays an animation takes responsibility for managing what it expects to happen without worrying about the expectations of other scripts.
For example, if a character has an Attack animation which wants to return to Idle when it finishes but the character gets hit by an enemy in the middle of the Attack, the character will now want to play the Flinch animation and return to Idle after that instead. At that point, we no longer care about the end of the Attack animation. If we want to attack again, we just play the animation and register the callback again. But if the character has a special skill that lets them perform an attack combo which happens to include the same Attack animation followed by several others in sequence, it will not want that animation to still have the old End Event that returns to Idle.
That said, enforcing rules for which animations/actions are allowed to interrupt each other is often very important so that topic is covered in the Interrupt Management example.
The way that events are cleared differs slightly depending on how a state was played:
|Without a Transition, the state will have no events by default.||When playing a Transition, the state will be given the
||When you play something else, the
This system has several other details worth mentioning:
- Events are triggered using the
AnimancerEvent.Invokemethod which sets the static
AnimancerEvent.CurrentState, allowing anything to access the details of the event and the state that triggered it before being cleared immediately afterwards. The Event Utilities example demonstrates some ways those properties can be used.
- Changing the
NormalizedTime) prevents that state from triggering any more events during that frame. If you want events between the old and new time to be triggered, you can use
AnimancerState.Eventssequence can not be modified by its own events (i.e. you can't use an event to add another event to the state that triggered it).
- Animancer Events work with Mixers. Blend Trees will trigger Animation Events on all of the
AnimationClips they contain, but this allows events to be placed on the
MixerStateitself so they get triggered according to the weighted average normalized time of the mixed states.
- They also technically work with Controller States, though they are tied to the overall
ControllerStateand do not check what the Animator Controller is doing internally so attempting to use them might not give the intended result.
- If you want to run custom code as part of the animation update, you can implement
IUpdatablein your own scripts.