NamedAnimancerComponent Class

Summary

An Animancer.AnimancerComponent which uses the UnityEngine.Object.names of UnityEngine.AnimationClips so they can be referenced using strings as well as the clips themselves.

It also has fields to automatically register animations on startup and play the first one automatically without needing another script to control it, much like Unity's Legacy UnityEngine.Animation component.
Assembly
Animancer.dll
Namespace
Animancer
Interfaces
Base Types
Derived Types
graph BT Type-->Base0["AnimancerComponent"] click Base0 "/animancer/api/Animancer/AnimancerComponent" Base0-->Base1["MonoBehaviour"] Type-.->Interface0["IAnimancerComponent"] click Interface0 "/animancer/api/Animancer/IAnimancerComponent" Type-.->Interface1["IEnumerable<AnimancerState>"] Type-.->Interface2["IEnumerator"] Type-.->Interface3["IAnimationClipSource"] Type-.->Interface4["IAnimationClipCollection"] click Interface4 "/animancer/api/Animancer/IAnimationClipCollection" Type["NamedAnimancerComponent"] class Type type-node Derived0["HybridAnimancerComponent"]-->Type click Derived0 "/animancer/api/Animancer/HybridAnimancerComponent"

Syntax

[AddComponentMenu(Strings.MenuPrefix + "Named Animancer Component")]
[HelpURL(Strings.APIDocumentationURL + "/" + nameof(NamedAnimancerComponent))]
public class NamedAnimancerComponent : AnimancerComponent, IAnimancerComponent, 
    IEnumerable<AnimancerState>, IEnumerator, IAnimationClipSource, IAnimationClipCollection

Attributes

Type Description
AddComponentMenu
HelpURLAttribute

Properties

Name Value Summary
ActionOnDisable AnimancerComponent.DisableAction
[UnityEngine.SerializeField] Determines what happens when this component is disabled or its UnityEngine.GameObject becomes inactive (i.e. in Animancer.AnimancerComponent.OnDisable).

The default value is Animancer.AnimancerComponent.DisableAction.Stop.
Inherited from AnimancerComponent
Animations AnimationClip[]
[UnityEngine.SerializeField] Animations in this array will be automatically registered by Animancer.NamedAnimancerComponent.Awake as states that can be retrieved using their name and the first element will be played by Animancer.NamedAnimancerComponent.OnEnable if Animancer.NamedAnimancerComponent.PlayAutomatically is true.
Animator Animator
[UnityEngine.SerializeField] The UnityEngine.Animator component which this script controls.
Inherited from AnimancerComponent
DefaultAnimation AnimationClip
The first element in the Animancer.NamedAnimancerComponent.Animations array. It will be automatically played by Animancer.NamedAnimancerComponent.OnEnable if Animancer.NamedAnimancerComponent.PlayAutomatically is true.
InitialUpdateMode Nullable<AnimatorUpdateMode>
[Editor-Only] The Animancer.AnimancerComponent.UpdateMode what was first used when this script initialised. This is used to give a warning when changing to or from UnityEngine.AnimatorUpdateMode.AnimatePhysics at runtime since it won't work correctly.
Inherited from AnimancerComponent
IsPlayableInitialised bool
Indicates whether the Animancer.AnimancerComponent.Playable has been initialised.
Inherited from AnimancerComponent
Layers AnimancerPlayable.LayerList
The layers which each manage their own set of animations.
Inherited from AnimancerComponent
Playable AnimancerPlayable
The internal system which manages the playing animations. Accessing this property will automatically initialise it.
Inherited from AnimancerComponent
PlayAutomatically bool
[UnityEngine.SerializeField] If true, the first clip in the Animancer.NamedAnimancerComponent.Animations array will be automatically played by Animancer.NamedAnimancerComponent.OnEnable.
States AnimancerPlayable.StateDictionary
The states managed by this component.
Inherited from AnimancerComponent
UpdateMode AnimatorUpdateMode
Determines when animations are updated and which time source is used. This property is mainly a wrapper around the UnityEngine.Animator.updateMode.

Note that changing to or from UnityEngine.AnimatorUpdateMode.AnimatePhysics at runtime has no effect.
Inherited from AnimancerComponent

Methods

Name Value Summary
~AnimancerComponent() void
[Editor-Only] Ensures that the Animancer.AnimancerPlayable is destroyed in Edit Mode, but not in Play Mode since we want Unity to complain if that happens.
Inherited from AnimancerComponent
Awake() void
Called by Unity when this component is being loaded.

Creates a state for each clip in the Animancer.NamedAnimancerComponent.Animations array.
CrossFadeAnimationsInSequence(float) IEnumerator
[Coroutine] Cross fades between each clip in the Animancer.NamedAnimancerComponent.Animations array one after the other. Mainly useful for testing and showcasing purposes.
Evaluate() void
Evaluates all of the currently playing animations to apply their states to the animated objects.
Inherited from AnimancerComponent
Evaluate(float) void
Advances all currently playing animations by the specified amount of time (in seconds) and evaluates the graph to apply their states to the animated objects.
Inherited from AnimancerComponent
GatherAnimationClips(ICollection<AnimationClip>) void
[IAnimationClipSource] Gathers all the animations in the UnityEngine.Playables.Playable and the Animancer.NamedAnimancerComponent.Animations array.
GetAnimationClips(List<AnimationClip>) void
[IAnimationClipSource] Calls Animancer.AnimancerComponent.GatherAnimationClips(System.Collections.Generic.ICollection{UnityEngine.AnimationClip}).
Inherited from AnimancerComponent
GetEnumerator() IEnumerator<AnimancerState>
Returns an enumerator that will iterate through all states in each layer (but not sub-states).
Inherited from AnimancerComponent
GetKey(AnimationClip) Object
Returns the clip's name. This method is used to determine the dictionary key to use for an animation when none is specified by the user, such as in Animancer.AnimancerComponent.Play(UnityEngine.AnimationClip).
InitialisePlayable() void
Creates a new Animancer.AnimancerPlayable if it doesn't already exist.
Inherited from AnimancerComponent
IsPlaying() bool
Returns true if at least one animation is being played.
Inherited from AnimancerComponent
IsPlaying(AnimancerState) bool
[Warning] You should not use an Animancer.AnimancerState as a key. Just check Animancer.AnimancerState.IsPlaying.
Inherited from AnimancerComponent
IsPlaying(AnimationClip) bool
Returns true if a state is registered for the `clip` and it is currently playing.

The actual dictionary key is determined using Animancer.AnimancerComponent.GetKey(UnityEngine.AnimationClip).
Inherited from AnimancerComponent
IsPlaying(IHasKey) bool
Returns true if a state is registered with the Animancer.IHasKey.Key and it is currently playing.
Inherited from AnimancerComponent
IsPlaying(Object) bool
Returns true if a state is registered with the `key` and it is currently playing.
Inherited from AnimancerComponent
IsPlayingClip(AnimationClip) bool
Returns true if the `clip` is currently being played by at least one state.

This method is inefficient because it searches through every state to find any that are playing the `clip`, unlike Animancer.AnimancerComponent.IsPlaying(UnityEngine.AnimationClip) which only checks the state registered using the `clip`s key.
Inherited from AnimancerComponent
OnDestroy() void
Called by Unity when this component is destroyed. Ensures that the Animancer.AnimancerComponent.Playable is properly cleaned up.
Inherited from AnimancerComponent
OnDisable() void
Called by Unity when this component becomes disabled or inactive. Acts according to the Animancer.AnimancerComponent.ActionOnDisable.
Inherited from AnimancerComponent
OnEnable() void
Called by Unity when this component becomes enabled and active.

Plays the first clip in the Animancer.NamedAnimancerComponent.Animations array if Animancer.NamedAnimancerComponent.PlayAutomatically is true.

Plays the UnityEngine.Playables.PlayableGraph if it was stopped.
OnValidate() void
[Editor-Only] Called by the Unity Editor in Edit Mode whenever an instance of this script is loaded or a value is changed in the Inspector.

Uses ClipState.ValidateClip to ensure that all of the clips in the Animancer.NamedAnimancerComponent.Animations array are supported by the Animancer system and removes any others.
Play(AnimancerState) AnimancerState
Stops all other animations on the same layer, plays the `state`, and returns it.

The animation will continue playing from its current Animancer.AnimancerState.Time. To restart it from the beginning you can use ...Play(state).Time = 0;.
Inherited from AnimancerComponent
Play(AnimancerState, float, FadeMode) AnimancerState
Starts fading in the `state` while fading out all others in the same layer over the course of the `fadeDuration`. Returns the `state`.

If the `state` was already playing and fading in with less time remaining than the `fadeDuration`, this method will allow it to complete the existing fade rather than starting a slower one.

If the layer currently has 0 Animancer.AnimancerNode.Weight, this method will fade in the layer itself and simply AnimancerState.Play(AnimancerState) the `state`.

Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in a runtime build.
Inherited from AnimancerComponent
Play(AnimationClip) AnimancerState
Stops all other animations on the same layer, plays the `clip`, and returns its state.

The animation will continue playing from its current Animancer.AnimancerState.Time. To restart it from the beginning you can use ...Play(clip, layerIndex).Time = 0;.
Inherited from AnimancerComponent
Play(AnimationClip, float, FadeMode) AnimancerState
Starts fading in the `clip` while fading out all other states in the same layer over the course of the `fadeDuration`. Returns its state.

If the state was already playing and fading in with less time remaining than the `fadeDuration`, this method will allow it to complete the existing fade rather than starting a slower one.

If the layer currently has 0 Animancer.AnimancerNode.Weight, this method will fade in the layer itself and simply AnimancerState.Play(AnimationClip) the `clip`.

Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in a runtime build.
Inherited from AnimancerComponent
Play(ITransition) AnimancerState
Creates a state for the `transition` if it didn't already exist, then calls Animancer.AnimancerComponent.Play(Animancer.AnimancerState) or Animancer.AnimancerComponent.Play(Animancer.AnimancerState,System.Single,Animancer.FadeMode) depending on ITransition.CrossFadeFromStart.
Inherited from AnimancerComponent
Play(ITransition, float, FadeMode) AnimancerState
Creates a state for the `transition` if it didn't already exist, then calls Animancer.AnimancerComponent.Play(Animancer.AnimancerState) or Animancer.AnimancerComponent.Play(Animancer.AnimancerState,System.Single,Animancer.FadeMode) depending on ITransition.CrossFadeFromStart.
Inherited from AnimancerComponent
PlayAnimationsInSequence() IEnumerator
[Coroutine] Plays each clip in the Animancer.NamedAnimancerComponent.Animations array one after the other. Mainly useful for testing and showcasing purposes.
Reset() void
[Editor-Only] Called by the Unity Editor when this component is first added (in Edit Mode) and whenever the Reset command is executed from its context menu.

Destroys the playable if one has been initialised. Searches for an UnityEngine.Animator on this object, or it's children or parents. Removes the UnityEngine.Animator.runtimeAnimatorController if it finds one.

This method also prevents you from adding multiple copies of this component to a single object. Doing so will destroy the new one immediately and change the old one's type to match the new one, allowing you to change the type without losing the values of any serialized fields they share.
Inherited from AnimancerComponent
Stop() void
Stops all animations and rewinds them to the start.
Inherited from AnimancerComponent
Stop(AnimancerState) AnimancerState
[Warning] You should not use an Animancer.AnimancerState as a key. Just call Animancer.AnimancerState.Stop.
Inherited from AnimancerComponent
Stop(AnimationClip) AnimancerState
Gets the state associated with the `clip`, stops and rewinds it to the start, then returns it.
Inherited from AnimancerComponent
Stop(IHasKey) AnimancerState
Gets the state registered with the Animancer.IHasKey.Key, stops and rewinds it to the start, then returns it.
Inherited from AnimancerComponent
Stop(Object) AnimancerState
Gets the state associated with the `key`, stops and rewinds it to the start, then returns it.
Inherited from AnimancerComponent
TryPlay(Object) AnimancerState
Stops all other animations on the same layer, plays the animation registered with the `key`, and returns that state.

The animation will continue playing from its current Animancer.AnimancerState.Time. To restart it from the beginning you can use ...Play(key).Time = 0;.
Inherited from AnimancerComponent
TryPlay(Object, float, FadeMode) AnimancerState
Starts fading in the animation registered with the `key` while fading out all others in the same layer over the course of the `fadeDuration`.

If the state was already playing and fading in with less time remaining than the `fadeDuration`, this method will allow it to complete the existing fade rather than starting a slower one.

If the layer currently has 0 Animancer.AnimancerNode.Weight, this method will fade in the layer itself and simply AnimancerState.Play(AnimancerState) the state.

Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in a runtime build.
Inherited from AnimancerComponent

Operators

Name Value Summary
implicit operator AnimancerLayer(AnimancerComponent) AnimancerLayer
Inherited from AnimancerComponent
implicit operator AnimancerPlayable(AnimancerComponent) AnimancerPlayable
Inherited from AnimancerComponent