874 lines
40 KiB
C#
874 lines
40 KiB
C#
// Animancer // https://kybernetik.com.au/animancer // Copyright 2018-2024 Kybernetik //
|
|
|
|
using Animancer.TransitionLibraries;
|
|
using System;
|
|
using System.Collections;
|
|
using System.Collections.Generic;
|
|
using UnityEngine;
|
|
using UnityEngine.Playables;
|
|
|
|
namespace Animancer
|
|
{
|
|
/// <summary>
|
|
/// The main component through which other scripts can interact with <see cref="Animancer"/>. It allows you to play
|
|
/// animations on an <see cref="UnityEngine.Animator"/> without using a <see cref="RuntimeAnimatorController"/>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This class can be used as a custom yield instruction to wait until all animations finish playing.
|
|
/// <para></para>
|
|
/// This class is mostly just a wrapper that connects an <see cref="AnimancerGraph"/> to an
|
|
/// <see cref="UnityEngine.Animator"/>.
|
|
/// <para></para>
|
|
/// <strong>Documentation:</strong>
|
|
/// <see href="https://kybernetik.com.au/animancer/docs/manual/playing/component-types">
|
|
/// Component Types</see>
|
|
/// </remarks>
|
|
/// https://kybernetik.com.au/animancer/api/Animancer/AnimancerComponent
|
|
///
|
|
[AddComponentMenu(Strings.MenuPrefix + "Animancer Component")]
|
|
[AnimancerHelpUrl(typeof(AnimancerComponent))]
|
|
[DefaultExecutionOrder(DefaultExecutionOrder)]
|
|
public class AnimancerComponent : MonoBehaviour,
|
|
IAnimancerComponent,
|
|
IEnumerator,
|
|
IAnimationClipSource,
|
|
IAnimationClipCollection
|
|
{
|
|
/************************************************************************************************************************/
|
|
#region Fields and Properties
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Initialize before anything else tries to use this component.</summary>
|
|
public const int DefaultExecutionOrder = -5000;
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
[SerializeField]
|
|
[Tooltip("Animancer works by using Unity's Playables API to control an Animator component." +
|
|
"\n\nThe Animator's Controller field should be empty unless you intend to use it.")]
|
|
private Animator _Animator;
|
|
|
|
/// <summary>[<see cref="SerializeField"/>]
|
|
/// Animancer works by using Unity's Playables API to control an <see cref="UnityEngine.Animator"/> component.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The <see cref="Animator.runtimeAnimatorController"/> should be empty unless you intend to use it.
|
|
/// </remarks>
|
|
public Animator Animator
|
|
{
|
|
get => _Animator;
|
|
set
|
|
{
|
|
_Animator = value;
|
|
if (IsGraphInitialized)
|
|
{
|
|
_Graph.DestroyOutput();
|
|
_Graph.CreateOutput(value, this);
|
|
}
|
|
}
|
|
}
|
|
|
|
#if UNITY_EDITOR
|
|
/// <inheritdoc/>
|
|
string IAnimancerComponent.AnimatorFieldName
|
|
=> nameof(_Animator);
|
|
#endif
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
[SerializeField]
|
|
[Tooltip(Strings.ProOnlyTag + "An optional Transition Library" +
|
|
" which can modify the way Animancer transitions between animations.")]
|
|
private TransitionLibraryAsset _Transitions;
|
|
|
|
/// <summary>[<see cref="SerializeField"/>] [Pro-Only]
|
|
/// An optional <see cref="TransitionLibraryAsset"/>
|
|
/// which can modify the way Animancer transitions between animations.
|
|
/// </summary>
|
|
public TransitionLibraryAsset Transitions
|
|
{
|
|
get => _Transitions;
|
|
set
|
|
{
|
|
_Transitions = value;
|
|
if (IsGraphInitialized)
|
|
_Graph.Transitions = value?.Library;
|
|
}
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
private AnimancerGraph _Graph;
|
|
|
|
/// <summary>
|
|
/// The internal system which manages the playing animations.
|
|
/// Accessing this property will automatically initialize it.
|
|
/// </summary>
|
|
public AnimancerGraph Graph
|
|
{
|
|
get
|
|
{
|
|
InitializeGraph();
|
|
return _Graph;
|
|
}
|
|
}
|
|
|
|
/// <summary>Has the <see cref="Graph"/> been initialized?</summary>
|
|
public bool IsGraphInitialized
|
|
=> _Graph != null
|
|
&& _Graph.IsValidOrDispose();
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>The layers which each manage their own set of animations.</summary>
|
|
public AnimancerLayerList Layers
|
|
=> Graph.Layers;
|
|
|
|
/// <summary>The states managed by this component.</summary>
|
|
public AnimancerStateDictionary States
|
|
=> Graph.States;
|
|
|
|
/// <summary>Dynamic parameters which anything can get or set.</summary>
|
|
public ParameterDictionary Parameters
|
|
=> Graph.Parameters;
|
|
|
|
/// <summary>A dictionary of callbacks to be triggered by any event with a matching name.</summary>
|
|
public NamedEventDictionary Events
|
|
=> Graph.Events;
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Returns the <see cref="Graph"/>.</summary>
|
|
public static implicit operator AnimancerGraph(AnimancerComponent animancer)
|
|
=> animancer.Graph;
|
|
|
|
/// <summary>Returns layer 0.</summary>
|
|
public static implicit operator AnimancerLayer(AnimancerComponent animancer)
|
|
=> animancer.Graph.Layers[0];
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
[SerializeField, Tooltip("Determines what happens when this component is disabled" +
|
|
" or its " + nameof(GameObject) + " becomes inactive (i.e. in OnDisable):" +
|
|
"\n• [" + nameof(DisableAction.Stop) + "] and reset all animations" +
|
|
"\n• [" + nameof(DisableAction.Pause) + "] to later resume from the current state" +
|
|
"\n• [" + nameof(DisableAction.Continue) + "] playing while inactive" +
|
|
"\n• [" + nameof(DisableAction.Reset) + "] to the original values" +
|
|
"\n• [" + nameof(DisableAction.Destroy) + "] all layers and states" +
|
|
"\n• If you're only destroying objects and not disabling them," +
|
|
" using " + nameof(DisableAction.Continue) + " is the most efficient" +
|
|
" because it avoids wasting performance stopping things that will be destroyed anyway.")]
|
|
private DisableAction _ActionOnDisable;
|
|
|
|
#if UNITY_EDITOR
|
|
/// <summary>[Editor-Only]
|
|
/// The name of the serialized backing field for the <see cref="ActionOnDisable"/> property.
|
|
/// </summary>
|
|
string IAnimancerComponent.ActionOnDisableFieldName
|
|
=> nameof(_ActionOnDisable);
|
|
#endif
|
|
|
|
/// <summary>[<see cref="SerializeField"/>]
|
|
/// Determines what happens when this component is disabled
|
|
/// or its <see cref="GameObject"/> becomes inactive
|
|
/// (i.e. in <see cref="OnDisable"/>).
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The default value is <see cref="DisableAction.Stop"/>.
|
|
/// <para></para>
|
|
/// If you're only destroying objects and not disabling them,
|
|
/// using <see cref="DisableAction.Continue"/> is the most efficient
|
|
/// because it avoids wasting performance stopping things that will be destroyed anyway.
|
|
/// </remarks>
|
|
public ref DisableAction ActionOnDisable
|
|
=> ref _ActionOnDisable;
|
|
|
|
/// <inheritdoc/>
|
|
bool IAnimancerComponent.ResetOnDisable
|
|
=> _ActionOnDisable == DisableAction.Reset;
|
|
|
|
/// <summary>
|
|
/// An action to perform when disabling an <see cref="AnimancerComponent"/>.
|
|
/// See <see cref="ActionOnDisable"/>.
|
|
/// </summary>
|
|
public enum DisableAction
|
|
{
|
|
/// <summary>
|
|
/// Stop and reset all animations, but leave all animated values as they are (unlike <see cref="Reset"/>).
|
|
/// </summary>
|
|
/// <remarks>Calls <see cref="Stop()"/> and <see cref="AnimancerGraph.PauseGraph"/>.</remarks>
|
|
Stop,
|
|
|
|
/// <summary>Pause to later resume from the current state.</summary>
|
|
/// <remarks>Calls <see cref="AnimancerGraph.PauseGraph"/>.</remarks>
|
|
Pause,
|
|
|
|
/// <summary>Keep playing while inactive.</summary>
|
|
Continue,
|
|
|
|
/// <summary>
|
|
/// Stop all animations, rewind them, and force the object back into its original state (often called the
|
|
/// bind pose).
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The <see cref="AnimancerComponent"/> must be either above the <see cref="UnityEngine.Animator"/> in
|
|
/// the Inspector or on a child object so that so that this <see cref="OnDisable"/> gets called first.
|
|
/// <para></para>
|
|
/// Calls <see cref="Stop()"/>, <see cref="Animator.Rebind"/>, and <see cref="AnimancerGraph.PauseGraph"/>.
|
|
/// </remarks>
|
|
Reset,
|
|
|
|
/// <summary>
|
|
/// Destroy the <see cref="PlayableGraph"/> and all its layers and states. This means that any layers or
|
|
/// states referenced by other scripts will no longer be valid so they will need to be recreated if you
|
|
/// want to use this object again.
|
|
/// </summary>
|
|
/// <remarks>Calls <see cref="AnimancerGraph.Destroy()"/>.</remarks>
|
|
Destroy,
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
#region Update Mode
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Determines when animations are updated and which time source is used. This property is mainly a wrapper
|
|
/// around the <see cref="Animator.updateMode"/>.
|
|
/// </summary>
|
|
/// <remarks>Note that changing to or from <see cref="AnimatorUpdateMode.AnimatePhysics"/> at runtime has no effect.</remarks>
|
|
/// <exception cref="NullReferenceException">No <see cref="Animator"/> is assigned.</exception>
|
|
public AnimatorUpdateMode UpdateMode
|
|
{
|
|
get => _Animator.updateMode;
|
|
set
|
|
{
|
|
_Animator.updateMode = value;
|
|
|
|
if (!IsGraphInitialized)
|
|
return;
|
|
|
|
// UnscaledTime on the Animator is actually identical to Normal when using the Playables API so we need
|
|
// to set the graph's DirectorUpdateMode to determine how it gets its delta time.
|
|
_Graph.UpdateMode = value == AnimatorUpdateMode.UnscaledTime ?
|
|
DirectorUpdateMode.UnscaledGameTime :
|
|
DirectorUpdateMode.GameTime;
|
|
|
|
#if UNITY_EDITOR
|
|
if (InitialUpdateMode == null)
|
|
{
|
|
InitialUpdateMode = value;
|
|
}
|
|
else if (UnityEditor.EditorApplication.isPlaying)
|
|
{
|
|
if (Editor.AnimancerGraphCleanup.HasChangedToOrFromAnimatePhysics(InitialUpdateMode, value))
|
|
Debug.LogWarning(
|
|
$"Changing the {nameof(Animator)}.{nameof(Animator.updateMode)} to or from " +
|
|
#if UNITY_2023_1_OR_NEWER
|
|
nameof(AnimatorUpdateMode.Fixed) +
|
|
#else
|
|
nameof(AnimatorUpdateMode.AnimatePhysics) +
|
|
#endif
|
|
" at runtime will have no effect." +
|
|
" You must set it in the Unity Editor or on startup.", this);
|
|
}
|
|
#endif
|
|
}
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
#if UNITY_EDITOR
|
|
/// <inheritdoc/>
|
|
public AnimatorUpdateMode? InitialUpdateMode { get; private set; }
|
|
#endif
|
|
|
|
/************************************************************************************************************************/
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
#region Initialization
|
|
/************************************************************************************************************************/
|
|
|
|
#if UNITY_EDITOR
|
|
/// <summary>[Editor-Only]
|
|
/// Destroys the <see cref="Graph"/> if it was initialized and searches for an <see cref="Animator"/> on
|
|
/// this object, or it's children or parents.
|
|
/// </summary>
|
|
protected virtual void Reset()
|
|
{
|
|
OnDestroy();
|
|
gameObject.GetComponentInParentOrChildren(ref _Animator);
|
|
}
|
|
#endif
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Ensures that the <see cref="PlayableGraph"/> is playing.</summary>
|
|
protected virtual void OnEnable()
|
|
{
|
|
if (IsGraphInitialized)
|
|
{
|
|
_Graph.UnpauseGraph();
|
|
|
|
#if UNITY_EDITOR
|
|
AnimancerGraph.ClearInactiveInitializationStackTrace(this);
|
|
#endif
|
|
}
|
|
}
|
|
|
|
/// <summary>Acts according to the <see cref="ActionOnDisable"/>.</summary>
|
|
protected virtual void OnDisable()
|
|
{
|
|
if (!IsGraphInitialized)
|
|
return;
|
|
|
|
switch (_ActionOnDisable)
|
|
{
|
|
case DisableAction.Stop:
|
|
_Graph.Stop();
|
|
_Graph.PauseGraph();
|
|
break;
|
|
|
|
case DisableAction.Pause:
|
|
_Graph.PauseGraph();
|
|
break;
|
|
|
|
case DisableAction.Continue:
|
|
break;
|
|
|
|
case DisableAction.Reset:
|
|
Debug.Assert(_Animator.isActiveAndEnabled,
|
|
$"{nameof(DisableAction)}.{nameof(DisableAction.Reset)} failed because the {nameof(Animator)}" +
|
|
$" is not enabled. This most likely means you are disabling the {nameof(GameObject)} and the" +
|
|
$" {nameof(Animator)} is above the {nameof(AnimancerComponent)} in the Inspector so it got" +
|
|
$" disabled right before this method was called." +
|
|
$" See the Inspector of {this} to fix the issue" +
|
|
$" or use {nameof(DisableAction)}.{nameof(DisableAction.Stop)}" +
|
|
$" and call {nameof(Animator)}.{nameof(Animator.Rebind)} manually" +
|
|
$" before disabling the {nameof(GameObject)}.",
|
|
this);
|
|
|
|
_Graph.Stop();
|
|
_Animator.Rebind();
|
|
_Graph.PauseGraph();
|
|
break;
|
|
|
|
case DisableAction.Destroy:
|
|
_Graph.Destroy();
|
|
_Graph = null;
|
|
break;
|
|
|
|
default:
|
|
throw new ArgumentOutOfRangeException(nameof(ActionOnDisable));
|
|
}
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Creates and initializes the <see cref="Graph"/> if it wasn't already initialized.</summary>
|
|
public void InitializeGraph()
|
|
{
|
|
if (IsGraphInitialized)
|
|
return;
|
|
|
|
TryGetAnimator();
|
|
|
|
AnimancerGraph.SetNextGraphName(name + " (Animancer)");
|
|
_Graph = new(_Transitions?.Library);
|
|
_Graph.CreateOutput(_Animator, this);
|
|
OnInitializeGraph();
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Sets the <see cref="Graph"/> and connects it to the <see cref="Animator"/>.</summary>
|
|
/// <exception cref="InvalidOperationException">
|
|
/// The <see cref="AnimancerGraph"/> is already initialized.
|
|
/// You must call <see cref="AnimancerGraph.Destroy"/> before re-initializing it.
|
|
/// </exception>
|
|
public void InitializePlayable(AnimancerGraph graph)
|
|
{
|
|
if (IsGraphInitialized)
|
|
throw new InvalidOperationException(
|
|
$"The {nameof(AnimancerGraph)} is already initialized." +
|
|
$" Either call this method before anything else uses it or call" +
|
|
$" animancerComponent.{nameof(Graph)}.{nameof(AnimancerGraph.Destroy)}" +
|
|
$" before re-initializing it.");
|
|
|
|
TryGetAnimator();
|
|
|
|
_Graph = graph;
|
|
_Graph.Transitions = _Transitions?.Library;
|
|
_Graph.CreateOutput(_Animator, this);
|
|
OnInitializeGraph();
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Called right after the <see cref="Graph"/> is initialized.</summary>
|
|
protected virtual void OnInitializeGraph()
|
|
{
|
|
#if UNITY_ASSERTIONS
|
|
ValidateGraphInitialization();
|
|
#endif
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Tries to ensure that an <see cref="Animator"/> is present using
|
|
/// <see cref="Component.TryGetComponent{T}(out T)"/> if necessary.
|
|
/// </summary>
|
|
public bool TryGetAnimator()
|
|
=> _Animator != null
|
|
|| TryGetComponent(out _Animator);
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
#if UNITY_ASSERTIONS
|
|
/// <summary>[Assert-Only]
|
|
/// Validates various conditions relating to <see cref="AnimancerGraph"/> initialization.
|
|
/// </summary>
|
|
private void ValidateGraphInitialization()
|
|
{
|
|
#if UNITY_EDITOR
|
|
if (_Animator != null)
|
|
InitialUpdateMode = UpdateMode;
|
|
|
|
#if UNITY_IMGUI
|
|
if (OptionalWarning.CreateGraphDuringGuiEvent.IsEnabled())
|
|
{
|
|
var currentEvent = Event.current;
|
|
if (currentEvent != null)
|
|
{
|
|
var eventType = currentEvent.type;
|
|
if (eventType == EventType.Layout ||
|
|
eventType == EventType.Repaint)
|
|
{
|
|
OptionalWarning.CreateGraphDuringGuiEvent.Log(
|
|
$"An {nameof(AnimancerGraph)} is being initialized" +
|
|
$" during a {eventType} event which is likely undesirable.",
|
|
this);
|
|
}
|
|
}
|
|
}
|
|
#endif
|
|
#endif
|
|
|
|
if (_Animator != null)
|
|
{
|
|
if (!_Animator.enabled)
|
|
OptionalWarning.AnimatorDisabled.Log(Strings.AnimatorDisabledMessage, this);
|
|
|
|
if (_Animator.isHuman &&
|
|
_Animator.runtimeAnimatorController != null)
|
|
OptionalWarning.NativeControllerHumanoid.Log(
|
|
$"An Animator Controller is assigned to the {nameof(Animator)} component" +
|
|
$" but the Rig is Humanoid so it can't be blended with Animancer." +
|
|
$" See the documentation for more information: {Strings.DocsURLs.AnimatorControllersNative}",
|
|
this);
|
|
}
|
|
}
|
|
#endif
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Ensures that the <see cref="Graph"/> is properly cleaned up.</summary>
|
|
protected virtual void OnDestroy()
|
|
{
|
|
if (IsGraphInitialized)
|
|
{
|
|
_Graph.Destroy();
|
|
_Graph = null;
|
|
}
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
#if UNITY_EDITOR
|
|
/// <summary>[Editor-Only]
|
|
/// Ensures that the <see cref="AnimancerGraph"/> is destroyed in Edit Mode, but not in Play Mode since we want
|
|
/// to let Unity complain if that happens.
|
|
/// </summary>
|
|
~AnimancerComponent()
|
|
{
|
|
if (_Graph != null)
|
|
{
|
|
UnityEditor.EditorApplication.delayCall += () =>
|
|
{
|
|
if (!UnityEditor.EditorApplication.isPlayingOrWillChangePlaymode)
|
|
OnDestroy();
|
|
};
|
|
}
|
|
}
|
|
#endif
|
|
|
|
/************************************************************************************************************************/
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
#region Play Management
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Returns the `clip` itself.</summary>
|
|
/// <remarks>
|
|
/// This method is used to determine the dictionary key to use for an animation when none is specified by the
|
|
/// caller, such as in <see cref="Play(AnimationClip)"/>.
|
|
/// </remarks>
|
|
public virtual object GetKey(AnimationClip clip)
|
|
=> clip;
|
|
|
|
/************************************************************************************************************************/
|
|
// Play Immediately.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Stops all other animations on the same layer, plays the `clip`, and returns its state.</summary>
|
|
/// <remarks>
|
|
/// The animation will continue playing from its current <see cref="AnimancerState.Time"/>.
|
|
/// To restart it from the beginning you can use <c>...Play(clip).Time = 0;</c>.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the `clip` was already playing.
|
|
/// </remarks>
|
|
public AnimancerState Play(AnimationClip clip)
|
|
=> Graph.Layers[0].Play(States.GetOrCreate(clip));
|
|
|
|
/// <summary>Stops all other animations on the same layer, plays the `state`, and returns it.</summary>
|
|
/// <remarks>
|
|
/// The animation will continue playing from its current <see cref="AnimancerState.Time"/>.
|
|
/// To restart it from the beginning you can use <c>...Play(state).Time = 0;</c>.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the `state` was already playing.
|
|
/// </remarks>
|
|
public AnimancerState Play(AnimancerState state)
|
|
=> Graph.Layers[0].Play(state);
|
|
|
|
/************************************************************************************************************************/
|
|
// Cross Fade.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Starts fading in the `clip` while fading out all other states in the same layer over the course of the
|
|
/// `fadeDuration`. Returns its state.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 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.
|
|
/// <para></para>
|
|
/// If the layer currently has 0 <see cref="AnimancerNode.Weight"/>, this method will fade in the layer itself
|
|
/// and simply <see cref="AnimancerState.Play"/> the `state`.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the `clip` was already playing.
|
|
/// <para></para>
|
|
/// <em>Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in runtime builds.</em>
|
|
/// </remarks>
|
|
public AnimancerState Play(AnimationClip clip, float fadeDuration, FadeMode mode = default)
|
|
=> Graph.Layers[0].Play(States.GetOrCreate(clip), fadeDuration, mode);
|
|
|
|
/// <summary>
|
|
/// Starts fading in the `state` while fading out all others in the same layer over the course of the
|
|
/// `fadeDuration`. Returns the `state`.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 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.
|
|
/// <para></para>
|
|
/// If the layer currently has 0 <see cref="AnimancerNode.Weight"/>, this method will fade in the layer itself
|
|
/// and simply <see cref="AnimancerState.Play"/> the `state`.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the `state` was already playing.
|
|
/// <para></para>
|
|
/// <em>Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in runtime builds.</em>
|
|
/// </remarks>
|
|
public AnimancerState Play(AnimancerState state, float fadeDuration, FadeMode mode = default)
|
|
=> Graph.Layers[0].Play(state, fadeDuration, mode);
|
|
|
|
/************************************************************************************************************************/
|
|
// Transition.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Creates a state for the `transition` if it didn't already exist, then calls
|
|
/// <see cref="Play(AnimancerState)"/> or <see cref="Play(AnimancerState, float, FadeMode)"/>
|
|
/// depending on <see cref="ITransition.CrossFadeFromStart"/>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This method is safe to call repeatedly without checking whether the `transition` was already playing.
|
|
/// </remarks>
|
|
public AnimancerState Play(ITransition transition)
|
|
=> Graph.Layers[0].Play(transition);
|
|
|
|
/// <summary>
|
|
/// Creates a state for the `transition` if it didn't already exist, then calls
|
|
/// <see cref="Play(AnimancerState)"/> or <see cref="Play(AnimancerState, float, FadeMode)"/>
|
|
/// depending on <see cref="ITransition.CrossFadeFromStart"/>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This method is safe to call repeatedly without checking whether the `transition` was already playing.
|
|
/// </remarks>
|
|
public AnimancerState Play(ITransition transition, float fadeDuration, FadeMode mode = default)
|
|
=> Graph.Layers[0].Play(transition, fadeDuration, mode);
|
|
|
|
/************************************************************************************************************************/
|
|
// Try Play.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Stops all other animations on the base layer,
|
|
/// plays the animation registered with the `key`,
|
|
/// and returns the animation's state.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If no state is registered with the `key`, this method does nothing and returns null.
|
|
/// <para></para>
|
|
/// The animation will continue playing from its current <see cref="AnimancerState.Time"/>.
|
|
/// To restart it from the beginning you can simply set the returned state's time to 0.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the animation was already playing.
|
|
/// </remarks>
|
|
/// <exception cref="ArgumentNullException">The `key` is null.</exception>
|
|
public AnimancerState TryPlay(object key)
|
|
=> Graph.Layers[0].TryPlay(key);
|
|
|
|
/// <summary>
|
|
/// Stops all other animations on the base layer,
|
|
/// plays the animation registered with the `key`,
|
|
/// and returns the animation's state.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If no state is registered with the `key`, this method does nothing and returns null.
|
|
/// <para></para>
|
|
/// The animation will continue playing from its current <see cref="AnimancerState.Time"/>.
|
|
/// To restart it from the beginning you can simply set the returned state's time to 0.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the animation was already playing.
|
|
/// </remarks>
|
|
public AnimancerState TryPlay(
|
|
IHasKey hasKey)
|
|
=> TryPlay(hasKey.Key);
|
|
|
|
/// <summary>
|
|
/// Starts fading in the animation registered with the `key` while fading out all others in the same layer
|
|
/// over the course of the `fadeDuration`. Or if no state is registered with that `key`, this method does
|
|
/// nothing and returns null.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 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.
|
|
/// <para></para>
|
|
/// If the layer currently has 0 <see cref="AnimancerNode.Weight"/>, this method will fade in the layer itself
|
|
/// and simply <see cref="AnimancerState.Play"/> the `state`.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the animation was already playing.
|
|
/// <para></para>
|
|
/// <em>Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in runtime builds.</em>
|
|
/// </remarks>
|
|
/// <exception cref="ArgumentNullException">The `key` is null.</exception>
|
|
public AnimancerState TryPlay(object key, float fadeDuration, FadeMode mode = default)
|
|
=> Graph.Layers[0].TryPlay(key, fadeDuration, mode);
|
|
|
|
/// <summary>
|
|
/// Starts fading in the animation registered with the `key`
|
|
/// while fading out all others in the same layer over the course of the `fadeDuration`
|
|
/// and returns the animation's state.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If no state is registered with the `key`, this method does nothing and returns null.
|
|
/// <para></para>
|
|
/// If the `state` was already playing and fading in with less time remaining than the `fadeDuration`,
|
|
/// this method allows it to continue the existing fade rather than starting a slower one.
|
|
/// <para></para>
|
|
/// If the layer currently has 0 <see cref="AnimancerNode.Weight"/>, this method will
|
|
/// fade in the layer itself and simply <see cref="AnimancerState.Play"/> the `state`.
|
|
/// <para></para>
|
|
/// This method is safe to call repeatedly without checking whether the animation was already playing.
|
|
/// <para></para>
|
|
/// <em>Animancer Lite only allows the default `fadeDuration` (0.25 seconds) in runtime builds.</em>
|
|
/// </remarks>
|
|
public AnimancerState TryPlay(
|
|
IHasKey hasKey,
|
|
float fadeDuration,
|
|
FadeMode mode = default)
|
|
=> TryPlay(hasKey.Key, fadeDuration, mode);
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Gets the state associated with the `clip`, stops and rewinds it to the start, then returns it.
|
|
/// </summary>
|
|
public AnimancerState Stop(AnimationClip clip)
|
|
=> Stop(GetKey(clip));
|
|
|
|
/// <summary>
|
|
/// Gets the state registered with the <see cref="IHasKey.Key"/>, stops and rewinds it to the start, then
|
|
/// returns it.
|
|
/// </summary>
|
|
public AnimancerState Stop(IHasKey hasKey)
|
|
=> _Graph?.Stop(hasKey);
|
|
|
|
/// <summary>
|
|
/// Gets the state associated with the `key`, stops and rewinds it to the start, then returns it.
|
|
/// </summary>
|
|
public AnimancerState Stop(object key)
|
|
=> _Graph?.Stop(key);
|
|
|
|
/// <summary>Stops all animations and rewinds them to the start.</summary>
|
|
public void Stop()
|
|
{
|
|
if (IsGraphInitialized)
|
|
_Graph.Stop();
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Returns true if a state is registered for the `clip` and it is currently playing.
|
|
/// <para></para>
|
|
/// The actual dictionary key is determined using <see cref="GetKey"/>.
|
|
/// </summary>
|
|
public bool IsPlaying(AnimationClip clip)
|
|
=> IsPlaying(GetKey(clip));
|
|
|
|
/// <summary>
|
|
/// Returns true if a state is registered with the <see cref="IHasKey.Key"/> and it is currently playing.
|
|
/// </summary>
|
|
public bool IsPlaying(IHasKey hasKey)
|
|
=> IsGraphInitialized
|
|
&& _Graph.IsPlaying(hasKey);
|
|
|
|
/// <summary>
|
|
/// Returns true if a state is registered with the `key` and it is currently playing.
|
|
/// </summary>
|
|
public bool IsPlaying(object key)
|
|
=> IsGraphInitialized
|
|
&& _Graph.IsPlaying(key);
|
|
|
|
/// <summary>
|
|
/// Returns true if at least one animation is being played.
|
|
/// </summary>
|
|
public bool IsPlaying()
|
|
=> IsGraphInitialized
|
|
&& _Graph.IsPlaying();
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Returns true if the `clip` is currently being played by at least one state.
|
|
/// <para></para>
|
|
/// This method is inefficient because it searches through every state to find any that are playing the `clip`,
|
|
/// unlike <see cref="IsPlaying(AnimationClip)"/> which only checks the state registered using the `clip`s key.
|
|
/// </summary>
|
|
public bool IsPlayingClip(AnimationClip clip)
|
|
=> IsGraphInitialized
|
|
&& _Graph.IsPlayingClip(clip);
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Immediately applies the current states of all animations to the animated objects.
|
|
/// </summary>
|
|
public void Evaluate()
|
|
=> Graph.Evaluate();
|
|
|
|
/// <summary>
|
|
/// Advances time by the specified value (in seconds)
|
|
/// and immediately applies the current states of all animations to the animated objects.
|
|
/// </summary>
|
|
public void Evaluate(float deltaTime)
|
|
=> Graph.Evaluate(deltaTime);
|
|
|
|
/************************************************************************************************************************/
|
|
#region Key Error Methods
|
|
#if UNITY_EDITOR
|
|
/************************************************************************************************************************/
|
|
// These are overloads of other methods that take a System.Object key to ensure the user doesn't try to use an
|
|
// AnimancerState as a key, since the whole point of a key is to identify a state in the first place.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>[Warning]
|
|
/// You should not use an <see cref="AnimancerState"/> as a key.
|
|
/// Just call <see cref="AnimancerState.Stop"/>.
|
|
/// </summary>
|
|
[Obsolete("You should not use an AnimancerState as a key. Just call AnimancerState.Stop().", true)]
|
|
public AnimancerState Stop(AnimancerState key)
|
|
{
|
|
key.Stop();
|
|
return key;
|
|
}
|
|
|
|
/// <summary>[Warning]
|
|
/// You should not use an <see cref="AnimancerState"/> as a key.
|
|
/// Just check <see cref="AnimancerState.IsPlaying"/>.
|
|
/// </summary>
|
|
[Obsolete("You should not use an AnimancerState as a key. Just check AnimancerState.IsPlaying.", true)]
|
|
public bool IsPlaying(AnimancerState key)
|
|
=> key.IsPlaying;
|
|
|
|
/************************************************************************************************************************/
|
|
#endif
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
#region Enumeration
|
|
/************************************************************************************************************************/
|
|
// IEnumerator for yielding in a coroutine to wait until all animations have stopped.
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>Are any animations are still playing?</summary>
|
|
/// <remarks>This allows this object to be used as a custom yield instruction.</remarks>
|
|
bool IEnumerator.MoveNext()
|
|
=> IsGraphInitialized
|
|
&& ((IEnumerator)_Graph).MoveNext();
|
|
|
|
/// <summary>Returns null.</summary>
|
|
object IEnumerator.Current
|
|
=> null;
|
|
|
|
/// <summary>Does nothing.</summary>
|
|
void IEnumerator.Reset()
|
|
{ }
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>[<see cref="IAnimationClipSource"/>]
|
|
/// Calls <see cref="GatherAnimationClips(ICollection{AnimationClip})"/>.
|
|
/// </summary>
|
|
public void GetAnimationClips(List<AnimationClip> clips)
|
|
{
|
|
var set = SetPool.Acquire<AnimationClip>();
|
|
set.UnionWith(clips);
|
|
|
|
GatherAnimationClips(set);
|
|
|
|
clips.Clear();
|
|
clips.AddRange(set);
|
|
SetPool.Release(set);
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
|
|
/// <summary>[<see cref="IAnimationClipCollection"/>]
|
|
/// Gathers all the animations in the <see cref="Graph"/>.
|
|
/// <para></para>
|
|
/// In the Unity Editor this method also gathers animations from other components on parent and child objects.
|
|
/// </summary>
|
|
public virtual void GatherAnimationClips(ICollection<AnimationClip> clips)
|
|
{
|
|
if (IsGraphInitialized)
|
|
_Graph.GatherAnimationClips(clips);
|
|
|
|
#if UNITY_EDITOR
|
|
Editor.AnimationGatherer.GatherFromGameObject(gameObject, clips);
|
|
|
|
if (_Animator != null && _Animator.gameObject != gameObject)
|
|
Editor.AnimationGatherer.GatherFromGameObject(_Animator.gameObject, clips);
|
|
#endif
|
|
}
|
|
|
|
/************************************************************************************************************************/
|
|
#endregion
|
|
/************************************************************************************************************************/
|
|
}
|
|
}
|
|
|