AnimancerState Class

Summary

Base class for all states in an Animancer.AnimancerPlayable graph. Each state is a wrapper for a UnityEngine.Playables.Playable in the UnityEngine.Playables.PlayableGraph.

This class can be used as a custom yield instruction to wait until the animation either stops playing or reaches its end.
graph BT Type-->Base0["AnimancerNode"] click Base0 "/animancer/api/Animancer/AnimancerNode" Base0-->Base1["Key"] click Base1 "/animancer/api/Animancer/Key" Base1-->Base2["Object"] Type-.->Interface0["IKeyHolder"] click Interface0 "/animancer/api/Animancer/IKeyHolder" Type-.->Interface1["IEnumerable<AnimancerState>"] Type-.->Interface2["IEnumerator"] Type-.->Interface3["IPlayableWrapper"] click Interface3 "/animancer/api/Animancer/IPlayableWrapper" Type-.->Interface4["IAnimationClipCollection"] click Interface4 "/animancer/api/Animancer/IAnimationClipCollection" Type["AnimancerState"] class Type type-node Derived0["MixerState"]-->Type click Derived0 "/animancer/api/Animancer/MixerState" Derived1["ClipState"]-->Type click Derived1 "/animancer/api/Animancer/ClipState" Derived2["PlayableAssetState"]-->Type click Derived2 "/animancer/api/Animancer/PlayableAssetState" Derived3["ControllerState"]-->Type click Derived3 "/animancer/api/Animancer/ControllerState"

Syntax

public abstract class AnimancerState : AnimancerNode, IKeyHolder, IEnumerable<AnimancerState>, 
    IEnumerator, IPlayableWrapper, IAnimationClipCollection

Remarks

There are various different ways of getting a state:
  • Use one of the state's constructors. Generally the first parameter is a layer or mixer which will be used as the state's parent. If not specified, you will need to call SetParent manually. Also note than an AnimancerComponent can be implicitly cast to its first layer.
  • AnimancerController.CreateState creates a new ClipState. You can optionally specify a custom `key` to register it in the dictionary instead of the default (the `clip` itself).
  • AnimancerController.GetOrCreateState looks for an existing state registered with the specified `key` and only creates a new one if it doesn’t already exist.
  • AnimancerController.GetState returns an existing state registered with the specified `key` if there is one.
  • AnimancerController.TryGetState is similar but returns a bool to indicate success and returns the `state` as an out parameter.
  • AnimancerController.Play and CrossFade also return the state they play.

Note that when inheriting from this class, the Animancer.AnimancerNode._Playable field must be assigned in the constructor to avoid throwing System.ArgumentExceptions throughout the system.

Constructors

Name Summary
AnimancerState(AnimancerPlayable) Constructs a new Animancer.AnimancerState.

Fields

Name Constant Value Summary
Root
The Animancer.AnimancerPlayable at the root of the graph.
Inherited from AnimancerNode

Properties

Name Value Summary
ApplyAnimatorIK bool
Determines whether OnAnimatorIK(int layerIndex) will be called on the animated object. The initial value is determined by Animancer.AnimancerLayer.DefaultApplyAnimatorIK.

This is equivalent to the "IK Pass" toggle in Animator Controller layers, except that due to limitations in the Playables API the layerIndex will always be zero.

It requires Unity 2018.1 or newer, however 2018.3 or newer is recommended because a bug in earlier versions of the Playables API caused this value to only take effect while a state was at Animancer.AnimancerNode.Weight == 1 which meant that IK would not work while fading between animations.

Returns false and does nothing if this state does not support IK.
ApplyFootIK bool
Indicates whether this state is applying IK to the character's feet. The initial value is determined by Animancer.AnimancerLayer.DefaultApplyFootIK.

This is equivalent to the "Foot IK" toggle in Animator Controller states.

Returns false and does nothing if this state does not support IK.
AverageVelocity Vector3
The average velocity of the root motion caused by this state.
ChildCount int
The number of states using this node as their Animancer.AnimancerState.Parent.
Inherited from AnimancerNode
Clip AnimationClip
The UnityEngine.AnimationClip which this state plays (if any).
Duration float
The number of seconds the animation will take to play fully at its current Animancer.AnimancerNode.Speed.

Setting this value modifies the Animancer.AnimancerNode.Speed, not the Animancer.AnimancerState.Length. Animancer Lite does not allow this value to be changed in a runtime build.

For the time remaining from now until it reaches the end, use Animancer.AnimancerState.RemainingDuration instead.
EffectiveSpeed float
The Animancer.AnimancerNode.Speed of this node multiplied by the Animancer.AnimancerNode.Speed of each of its parents down the hierarchy (including the root Animancer.AnimancerPlayable) to determine the actual speed its output is being played at.
Inherited from AnimancerNode
EffectiveWeight float
The Animancer.AnimancerNode.Weight of this state multiplied by the Animancer.AnimancerNode.Weight of each of its parents down the hierarchy to determine how much this state affects the final output.
EventPoolCapacity int
The capacity of the internal list in the Animancer.ObjectPool`1 for Animancer.AnimancerState.EventRunner.
static
EventPoolCount int
The number of spare items in the Animancer.ObjectPool`1 for Animancer.AnimancerState.EventRunner.
static
Events AnimancerEvent.Sequence
A list of Animancer.AnimancerEvents that will occur while this state plays as well as one that specifically defines when this state ends.

Animancer Lite does not allow the use of events in a runtime build, except for Animancer.AnimancerEvent.Sequence.OnEnd.
FadeSpeed float
The speed at which this node is fading towards the Animancer.AnimancerNode.TargetWeight.
Inherited from AnimancerNode
HasEvents bool
Indicates whether this state currently has an Animancer.AnimancerEvent.Sequence (since accessing the Animancer.AnimancerState.Events would automatically get one from the Animancer.ObjectPool).
Index int
The index of the port this node is connected to on the parent's UnityEngine.Playables.Playable.

A negative value indicates that it is not assigned to a port.
Inherited from AnimancerNode
IsActive bool
Returns true if this state is playing and is at or fading towards a non-zero Animancer.AnimancerNode.Weight.
IsLooping bool
Indicates whether this state will loop back to the start when it reaches the end.
IsPlaying bool
Is the Animancer.AnimancerState.Time automatically advancing?
IsStopped bool
Returns true if this state is not playing and is at 0 Animancer.AnimancerNode.Weight.
IsValid bool
Indicates whether the Animancer.AnimancerNode._Playable is usable (properly initialised and not destroyed).
Inherited from AnimancerNode
KeepChildrenConnected bool
Indicates whether child playables should stay connected to this mixer at all times (default false).
Inherited from AnimancerNode
Key Object
The object used to identify this state in the root Animancer.AnimancerPlayable.States dictionary. Can be null.
Layer AnimancerLayer
The root Animancer.AnimancerLayer which this state is connected to.
LayerIndex int
The index of the Animancer.AnimancerLayer this state is connected to (determined by the Animancer.AnimancerState.Parent).
Length float
The total time this state takes to play in seconds (when Speed = 1).
MainObject Object
The main object to show in the Inspector for this state (if any).
NormalizedTime float
The Animancer.AnimancerState.Time of this state as a portion of the animation's Animancer.AnimancerState.Length, meaning the value goes from 0 to 1 as it plays from start to end, regardless of how long that actually takes.

This value will continue increasing after the animation passes the end of its Animancer.AnimancerState.Length while the animated object either freezes in place or starts again from the beginning according to whether it is looping or not.

The fractional part of the value (NormalizedTime % 1) is the percentage (0-1) of progress in the current loop while the integer part ((int)NormalizedTime) is the number of times the animation has been looped.

Animancer Lite does not allow this value to be changed to a value other than 0 in a runtime build.
Parent IPlayableWrapper
The object which receives the output of the UnityEngine.Playables.Playable.
RawTime float
The internal implementation of Animancer.AnimancerState.Time which directly gets and sets the underlying value.
RemainingDuration float
The number of seconds the animation will take to reach the end at its current Animancer.AnimancerNode.Speed.

Setting this value modifies the Animancer.AnimancerNode.Speed, not the Animancer.AnimancerState.Length. Animancer Lite does not allow this value to be changed in a runtime build.

For the time it would take to play fully from the start, use Animancer.AnimancerState.Duration instead.
Speed float
How fast the Animancer.AnimancerState.Time is advancing every frame.

1 is the normal speed.

A negative value will play the animation backwards.

Animancer Lite does not allow this value to be changed in a runtime build.
Inherited from AnimancerNode
TargetWeight float
The desired Animancer.AnimancerNode.Weight which this node is fading towards according to the Animancer.AnimancerNode.FadeSpeed.
Inherited from AnimancerNode
Time float
The number of seconds that have passed since the start of this animation.

This value will continue increasing after the animation passes the end of its Animancer.AnimancerState.Length while the animated object either freezes in place or starts again from the beginning according to whether it is looping or not.

Animancer Lite does not allow this value to be changed in a runtime build (except resetting it to 0).
Weight float
The current blend weight of this node which determines how much it affects the final output. 0 has no effect while 1 applies the full effect of this node and values inbetween apply a proportional effect.

Setting this property cancels any fade currently in progress. If you don't wish to do that, you can use Animancer.AnimancerNode.SetWeight(System.Single) instead.

Animancer Lite only allows this value to be set to 0 or 1 in a runtime build.
Inherited from AnimancerNode

Methods

Name Value Summary
AppendDescription(StringBuilder, int, string) void
Appends a detailed descrption of the current details of this node.
Inherited from AnimancerNode
AppendDetails(StringBuilder, string) void
Called by Animancer.AnimancerNode.AppendDescription(System.Text.StringBuilder,System.Int32,System.String) to append the details of this node.
ChangeMainObject<T>(T, T) void
Sets the `currentObject` and calls Animancer.AnimancerNode.RecreatePlayable. If the `currentObject` was being used as the Animancer.AnimancerState.Key then it is changed as well.
ConnectToGraph() void
Connects the Animancer.AnimancerNode._Playable to the Animancer.AnimancerNode.Parent.
Inherited from AnimancerNode
CreatePlayable() void
Creates and assigns the Animancer.AnimancerNode._Playable.
Inherited from AnimancerNode
Destroy() void
Destroys the UnityEngine.Playables.Playable.
DisconnectFromGraph() void
Disconnects the Animancer.AnimancerNode._Playable from the Animancer.AnimancerNode.Parent.
Inherited from AnimancerNode
GatherAnimationClips(ICollection<AnimationClip>) void
[Animancer.IAnimationClipCollection] Gathers all the animations in this state.
GetChild(int) AnimancerState
Returns the state connected to the specified `index` as a child of this node.
Inherited from AnimancerNode
GetDescription(int, string) string
Returns a detailed descrption of the current details of this node.
Inherited from AnimancerNode
GetEnumerator() IEnumerator<AnimancerState>
Gets an enumerator for all of this node's child states.
Inherited from AnimancerNode
GetPath() string
Returns the hierarchy path of this state through its Animancer.AnimancerState.Parents.
IndexOf(Key) int
Returns location of this object in the list (or -1 if it is not currently in a keyed list).
Inherited from Key
static
IsInList(Key) bool
Indicates whether the specified object is currently in a keyed list.
Inherited from Key
static
OnAddChild(IList<AnimancerState>, AnimancerState) void
Connects the `state` to the `mixer` at its Animancer.AnimancerNode.Index.
Inherited from AnimancerNode
Play() void
Plays this animation immediately, without any blending. Sets Animancer.AnimancerState.IsPlaying = true, Animancer.AnimancerNode.Weight = 1, and clears the Animancer.AnimancerState.Events.

This method does not change the Animancer.AnimancerState.Time so it will continue from its current value.
RecreatePlayable() void
Destroys the UnityEngine.Playables.Playable and creates a new one using Animancer.AnimancerNode.CreatePlayable.
Inherited from AnimancerNode
RecreatePlayableRecursive() void
Calls Animancer.AnimancerNode.RecreatePlayable on this node and all its children recursively.
Inherited from AnimancerNode
SetMinEventPoolCount(int) void
If the Animancer.AnimancerState.EventPoolCount is less than the specified value, this method increases it to that value by creating new objects.
static
SetParent(AnimancerNode, int) void
Connects this state to the `parent` mixer at the specified `index`.

See also Animancer.AnimancerLayer.AddChild(Animancer.AnimancerState) to connect a state to an available port on a layer.
SetWeight(float) void
Sets the current blend weight of this node which determines how much it affects the final output. 0 has no effect while 1 applies the full effect of this node.

This method allows any fade currently in progress to continue. If you don't wish to do that, you can set the Animancer.AnimancerNode.Weight property instead.

Animancer Lite only allows this value to be set to 0 or 1 in a runtime build.
Inherited from AnimancerNode
StartFade(float, float) void
Calls Animancer.AnimancerNode.OnStartFade and starts fading the Animancer.AnimancerNode.Weight over the course of the `fadeDuration` (in seconds).

If the `targetWeight` is 0 then Animancer.AnimancerNode.Stop will be called when the fade is complete.

If the Animancer.AnimancerNode.Weight is already equal to the `targetWeight` then the fade will end immediately.

Animancer Lite only allows a `targetWeight` of 0 or 1 and the default `fadeDuration` in a runtime build.
Inherited from AnimancerNode
Stop() void
Stops the animation and makes it inactive immediately so it no longer affects the output. Sets Animancer.AnimancerNode.Weight = 0, Animancer.AnimancerState.IsPlaying = false, Animancer.AnimancerState.Time = 0, and clears the Animancer.AnimancerState.Events.

If you only want to freeze the animation in place, you can set Animancer.AnimancerState.IsPlaying = false instead. Or to freeze all animations, you can call Animancer.AnimancerPlayable.PauseGraph.

Extension Methods

Name Value Summary
CalculateEditorFadeDuration(float) float
Returns the duration of the `node`s current fade (if any), otherwise returns the `defaultDuration`.
IsValid() bool
Returns true if the `node` is not null and Animancer.AnimancerNode.IsValid.