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.
|Events on looping animations are triggered on every loop.
|By default, playing a new animation will clear the events from the old animation.
|Various other minor details.
Events behave differently depending on whether the animation is looping or not:
|Once on the frame when the animation passes the specified time.
Every loop on the frame when the animation passes the specified time.
|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 Interruptions 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
AnimancerEvent.Sequence from that Transition.
Events will give it a spare
AnimancerEvent.Sequence from the
ObjectPool which you can then modify on the spot.
Events will refer directly to the
AnimancerEvent.Sequence owned by the Transition so any modifications you make will be retained when you play it again. This means modifications should generally only be performed once on startup rather than being repeated every time you play it.
new AnimancerEvent.Sequence() and assign it manually, then it will not be cleared or pooled.
|When you play something else, the
AnimancerEvent.Sequence will be removed from the state but since it is owned by the Transition it will not be cleared or given to the
This system has several other details worth mentioning:
- Events are triggered using the
AnimancerEvent.Invokemethod which sets the static
AnimancerEvent.CurrentStateproperties, 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 can be placed on Mixers or on their children depending on whether you want them to be triggered according to the weighted average
NormalizedTimeof the children or the
NormalizedTimeof a specific child. The Events section on that page gives more details.
- 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.