Skip to content

AnimationStateMachine Class

Lightweight code-driven animation state machine. Evaluates transitions each frame and calls Play(string, bool) automatically.

public class AnimationStateMachine : System.IDisposable

Inheritance System.Object → AnimationStateMachine

Implements System.IDisposable

Remarks

Transitions are evaluated in descending Priority order. Within the same priority, they fire in the order they were added. The first passing condition wins.

Non-looping clips block outgoing transitions until they finish unless CanInterrupt is true.

StateTimer only advances while IsPlaying is true, so pausing the animator also freezes the dwell clock.

AnyState transitions are evaluated after all regular transitions for the current state.

If the default state is a non-looping clip, it restarts every time it completes with no matching transition. To suppress this, add an explicit on-complete transition from it to itself with a condition that returns false, or use a looping clip as the default.

Fields
StateHistoryCapacity Maximum number of state names retained in StateHistory.
Properties
AnyTransitions Read-only view of all AnyState transitions, in evaluation order.
CurrentState Gets the name of the currently active animation, or null if none.
HasDefaultState Returns true when a default state has been configured.
IsDisposed Gets whether this instance has been disposed. Useful for external lifetime guards when a reference to the state machine outlives its owning entity or component.
IsEnabled When false, transition evaluation is suspended each frame — the animator keeps playing its current clip normally but no automatic transitions fire and the default-state kickoff is skipped. ForceState(string, bool) and ForceStop(bool) still work regardless of this flag. Defaults to true.
PreviousState Gets the animation that was active before the current one, or null.
StateHistory Chronological log of the last StateHistoryCapacity state names entered. Index 0 is oldest. Cleared by ClearStateHistory().
StateTimer Gets the elapsed time in seconds the current state has been active. Only advances while IsPlaying is true, so pausing the animator also freezes this timer. Resets whenever a new animation starts (including via direct Play(string, bool) calls).
TransitionCount Gets the total number of registered transitions (regular + AnyState).
Transitions Read-only view of all regular (source-specific) transitions, in evaluation order.
Methods
AddAnyOnCompleteTransition(string, Func<bool>, float, int, bool) Adds a transition that fires automatically when any non-looping clip reaches its natural end. Returns the created AnimationTransition handle for targeted removal.
AddAnyTransition(string, Func<bool>, bool, float, float, float, int, bool) Adds a transition that can fire from any currently playing animation. Returns the created AnimationTransition handle for targeted removal.
AddAnyTriggerTransition(string, AnimationParameters, string, bool, float, float, float, int, bool) Adds an AnyState transition to to that fires when the named trigger is armed, consuming it safely via OnFired. Returns the created AnimationTransition handle for targeted removal.
AddOnCompleteTransition(string, string, Func<bool>, float, int, bool) Adds a transition that fires automatically when the non-looping clip named from reaches its natural end. Returns the created AnimationTransition handle for targeted removal.
AddOnCompleteTriggerTransition(string, string, AnimationParameters, string, float, int, bool) Adds an on-complete transition from from to to that additionally requires the named trigger to be armed, consuming it safely on fire. Returns the created AnimationTransition handle for targeted removal.
AddTransition(string, string, Func<bool>, bool, float, float, float, int, bool) Adds a transition from one named animation to another. Returns the created AnimationTransition handle for targeted removal.
AddTriggerTransition(string, string, AnimationParameters, string, bool, float, float, float, int, bool) Adds a transition from from to to that fires when the named trigger is armed, consuming it via OnFired. Returns the created AnimationTransition handle for targeted removal.
CanTransitionTo(string) Returns true if a transition to targetState is eligible based on loop-block rules, MinStateDuration, and MinNormalizedTime. Conditions and on-complete transitions are not evaluated.
CaptureSnapshot() Captures the current runtime state into an immutable AnimationStateMachineSnapshot. Use with RestoreSnapshot(AnimationStateMachineSnapshot) for save/load and rollback systems. Registered transitions, callbacks, and state history are not included.
ClearStateHistory() Clears the StateHistory log.
ClearTransitions() Removes all regular and AnyState transitions.
ForceState(string, bool) Imperatively drives the state machine to the named animation.
ForceStateDirect(AnimationClip, bool) Imperatively drives the state machine to play a clip instance directly, without requiring it to be pre-registered on the animator.
ForceStateDirectQueued(AnimationClip) Queues a clip instance to play directly after the current non-looping clip finishes, or immediately if nothing is playing. The clip does not need to be pre-registered.
ForceStateDirectQueuedWithCrossFade(AnimationClip, float) Queues a clip instance to play directly with a cross-fade after the current non-looping clip finishes, or immediately if nothing is playing. The clip does not need to be pre-registered.
ForceStateDirectWithCrossFade(AnimationClip, float, bool) Imperatively drives the state machine to play a clip instance directly with a cross-fade, without requiring it to be pre-registered on the animator.
ForceStateFromFrame(string, int, bool) Imperatively drives the state machine to the named animation beginning at a specific frame.
ForceStateFromFrameWithCrossFade(string, int, float, bool) Imperatively drives the state machine to the named animation beginning at a specific frame, with a cross-fade over fadeDuration seconds.
ForceStateFromNormalizedTime(string, float, bool) Imperatively drives the state machine to the named animation beginning at a normalised time.
ForceStateFromNormalizedTimeWithCrossFade(string, float, float, bool) Imperatively drives the state machine to the named animation beginning at a normalised time, with a cross-fade over fadeDuration seconds.
ForceStateQueued(string) Queues the named animation to play after the current non-looping clip finishes, or immediately if nothing is playing.
ForceStateQueuedWithCrossFade(string, float) Queues the named animation to play with a cross-fade after the current non-looping clip finishes, or immediately if nothing is playing.
ForceStateWithCrossFade(string, float, bool) Imperatively drives the state machine to the named animation with a cross-fade.
ForceStop(bool) Imperatively stops the animator and clears the active state, firing OnStateChanged with the previous state name and null as the new state. The state timer is reset and Stop(bool) is called with fireCallbacks.
GetAvailableTransitions() Returns the names of all destination states reachable via non-complete transitions from the active state (including AnyState transitions). Conditions are not evaluated.
IsInState(string) Returns true when the currently active animation matches stateName.
OnStateEnter(string, Action<string>) Registers a callback to invoke whenever the named state is entered. The callback receives the name of the previous state (or null if this is the first state entered). Multiple callbacks per state are supported; each call appends to the subscription list. Use RemoveStateEnterCallback(string, Action<string>) with the exact delegate to remove a specific subscription.
OnStateExit(string, Action<string>) Registers a callback to invoke whenever the named state is exited. The callback receives the name of the state being entered next, or null when the animator is stopped rather than transitioning to another state. Multiple callbacks per state are supported.
RemoveAnyOnCompleteTransition(string) Removes all AnyState on-complete transitions targeting the given animation.
RemoveAnyTransitions(string) Removes all AnyState condition-based transitions targeting the given animation.
RemoveOnCompleteTransitions(string, string) Removes all on-complete transitions from from to to.
RemoveStateEnterCallback(string) Removes all enter callbacks registered for stateName. Returns true if any were registered.
RemoveStateEnterCallback(string, Action<string>) Removes a specific enter callback previously registered for stateName. Returns true if the exact delegate was found and removed.
RemoveStateExitCallback(string) Removes all exit callbacks registered for stateName. Returns true if any were registered.
RemoveStateExitCallback(string, Action<string>) Removes a specific exit callback previously registered for stateName. Returns true if the exact delegate was found and removed.
RemoveTransition(AnimationTransition) Removes the specific transition instance obtained from an Add* call.
RemoveTransitions(string, string) Removes all condition-based (non-on-complete) transitions from from that target to. When from is null, removes matching AnyState transitions instead.
ResetStateTimer() Resets StateTimer to zero without triggering a transition.
RestoreSnapshot(AnimationStateMachineSnapshot) Restores runtime state from a previously captured AnimationStateMachineSnapshot. Does not fire OnStateChanged, OnStateEnter(string, Action<string>), or OnStateExit(string, Action<string>). Pair with RestorePlaybackSnapshot(AnimatorPlaybackSnapshot) to perform a full animation restore.
SetDefaultState(string) Sets the animation that plays automatically when the animator has no active animation, or when a non-looping clip finishes and no transition fires. Pass null to clear the default state.
Update(float) Evaluates all transitions and fires the first valid one. Called automatically by AnimationSystem each tick. No-op when IsEnabled is false.
ValidateTransitions() Checks that every From and To name in all registered transitions (and the default state) refers to a clip that has actually been added to the underlying animator. Returns a list of human-readable issue strings. An empty list means everything is valid.
Events
OnStateChanged Raised whenever the active state changes — both via automatic transitions, ForceState(string, bool), and direct Play(string, bool) calls. Provides the previous state name (or null) and the new state name (or null when the animator is stopped via ForceStop(bool)).