// Animancer // Copyright 2020 Kybernetik //
using System;
using System.Collections;
using System.Collections.Generic;
using System.Text;
using UnityEngine;
using UnityEngine.Playables;
using Object = UnityEngine.Object;
#if UNITY_EDITOR
using UnityEditor;
#endif
namespace Animancer
{
/// <summary>
/// Base class for all states in an <see cref="AnimancerPlayable"/> graph.
/// Each state is a wrapper for a <see cref="Playable"/> in the <see cref="PlayableGraph"/>.
/// <para></para>
/// This class can be used as a custom yield instruction to wait until the animation either stops playing or reaches its end.
/// </summary>
/// <remarks>
/// There are various different ways of getting a state:
/// <list type="bullet">
/// <item>
/// 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.
/// </item>
/// <item>
/// 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).
/// </item>
/// <item>
/// AnimancerController.GetOrCreateState looks for an existing state registered with the specified `key` and only
/// creates a new one if it doesn’t already exist.
/// </item>
/// <item>
/// AnimancerController.GetState returns an existing state registered with the specified `key` if there is one.
/// </item>
/// <item>
/// AnimancerController.TryGetState is similar but returns a bool to indicate success and returns the `state`
/// as an out parameter.
/// </item>
/// <item>
/// AnimancerController.Play and CrossFade also return the state they play.
/// </item>
/// </list>
/// <para></para>
/// Note that when inheriting from this class, the <see cref="AnimancerNode._Playable"/> field must be assigned in the
/// constructor to avoid throwing <see cref="ArgumentException"/>s throughout the system.
/// </remarks>
public abstract partial class AnimancerState : AnimancerNode, IAnimationClipCollection
{
/************************************************************************************************************************/
#region Hierarchy
/************************************************************************************************************************/
/// <summary>The object which receives the output of the <see cref="Playable"/>.</summary>
public override IPlayableWrapper Parent { get { return _Parent; } }
private AnimancerNode _Parent;
/// <summary>
/// Connects this state to the `parent` mixer at the specified `index`.
/// <para></para>
/// See also <see cref="AnimancerLayer.AddChild(AnimancerState)"/> to connect a state to an available port on a
/// layer.
/// </summary>
public void SetParent(AnimancerNode parent, int index)
{
if (_Parent != null)
_Parent.OnRemoveChild(this);
Index = index;
_Parent = parent;
if (parent != null)
{
SetWeightDirty();
parent.OnAddChild(this);
}
}
/// <summary>[Internal]
/// Called by <see cref="AnimancerNode.OnAddChild(IList{AnimancerState}, AnimancerState)"/> if the specified
/// port is already occupied so it can be cleared without triggering any other calls.
/// </summary>
internal void ClearParent()
{
Index = -1;
_Parent = null;
}
/************************************************************************************************************************/
/// <summary>
/// The <see cref="AnimancerNode.Weight"/> of this state multiplied by the <see cref="AnimancerNode.Weight"/> of each of
/// its parents down the hierarchy to determine how much this state affects the final output.
/// </summary>
/// <exception cref="NullReferenceException">Thrown if this state has no <see cref="AnimancerNode.Parent"/>.</exception>
public float EffectiveWeight
{
get
{
var weight = Weight;
var parent = _Parent;
while (parent != null)
{
weight *= parent.Weight;
parent = parent.Parent as AnimancerNode;
}
return weight;
}
}
/************************************************************************************************************************/
// Layer.
/************************************************************************************************************************/
/// <summary>The root <see cref="AnimancerLayer"/> which this state is connected to.</summary>
public override AnimancerLayer Layer { get { return _Parent.Layer; } }
/// <summary>
/// The index of the <see cref="AnimancerLayer"/> this state is connected to (determined by the
/// <see cref="Parent"/>).
/// </summary>
public int LayerIndex
{
get { return _Parent.Layer.Index; }
set
{
if (_Parent != null && LayerIndex == value)
return;
Root.Layers[value].AddChild(this);
}
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Key and Clip
/************************************************************************************************************************/
internal object _Key;
/// <summary>
/// The object used to identify this state in the root <see cref="AnimancerPlayable.States"/> dictionary.
/// Can be null.
/// </summary>
public object Key
{
get { return _Key; }
set
{
Root.States.Unregister(this);
Root.States.Register(value, this);
}
}
/************************************************************************************************************************/
/// <summary>The <see cref="AnimationClip"/> which this state plays (if any).</summary>
/// <exception cref="NotSupportedException">
/// Thrown if this state type doesn't have a clip and you try to set it.
/// </exception>
public virtual AnimationClip Clip
{
get { return null; }
set { throw new NotSupportedException(GetType() + " does not support setting the Clip."); }
}
/// <summary>The main object to show in the Inspector for this state (if any).</summary>
/// <exception cref="NotSupportedException">
/// Thrown if this state type doesn't have a main object and you try to set it.
/// </exception>
/// <exception cref="InvalidCastException">
/// Thrown if you try to assign something this state can't use.
/// </exception>
public virtual Object MainObject
{
get { return null; }
set { throw new NotSupportedException(GetType() + " does not support setting the MainObject."); }
}
/************************************************************************************************************************/
/// <summary>The average velocity of the root motion caused by this state.</summary>
public virtual Vector3 AverageVelocity
{
get { return default(Vector3); }
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Playing
/************************************************************************************************************************/
/// <summary>Is the <see cref="Time"/> automatically advancing?</summary>
private bool _IsPlaying = true;
/// <summary>
/// Has <see cref="_IsPlaying"/> changed since it was last applied to the <see cref="Playable"/>.
/// </summary>
/// <remarks>
/// Playables start playing by default so we start dirty to pause it during the first update (unless
/// <see cref="IsPlaying"/> is set to true before that).
/// </remarks>
private bool _IsPlayingDirty;
/************************************************************************************************************************/
/// <summary>Is the <see cref="Time"/> automatically advancing?</summary>
///
/// <example>
/// <code>
/// void IsPlayingExample(AnimancerComponent animancer, AnimationClip clip)
/// {
/// var state = animancer.States.GetOrCreate(clip);
///
/// if (state.IsPlaying)
/// Debug.Log(clip + " is playing");
/// else
/// Debug.Log(clip + " is paused");
///
/// state.IsPlaying = false;// Pause the animation.
///
/// state.IsPlaying = true;// Unpause the animation.
/// }
/// </code>
/// </example>
public virtual bool IsPlaying
{
get { return _IsPlaying; }
set
{
if (_IsPlaying == value)
return;
_IsPlaying = value;
// If it was already dirty then we just returned to the previous state so it is no longer dirty.
if (_IsPlayingDirty)
{
_IsPlayingDirty = false;
}
else
{
_IsPlayingDirty = true;
Root.RequireUpdate(this);
}
}
}
/************************************************************************************************************************/
/// <summary>
/// Returns true if this state is playing and is at or fading towards a non-zero
/// <see cref="AnimancerNode.Weight"/>.
/// </summary>
public bool IsActive
{
get
{
return
_IsPlaying &&
TargetWeight > 0;
}
}
/************************************************************************************************************************/
/// <summary>
/// Returns true if this state is not playing and is at 0 <see cref="AnimancerNode.Weight"/>.
/// </summary>
public bool IsStopped
{
get
{
return
!_IsPlaying &&
Weight == 0;
}
}
/************************************************************************************************************************/
/// <summary>
/// Updates the <see cref="AnimancerNode.Weight"/> for fading, applies it to this state's port on the parent
/// mixer, and plays or pauses the <see cref="Playable"/> if its state is dirty.
/// <para></para>
/// If the <see cref="Parent"/>'s <see cref="AnimancerNode.KeepChildrenConnected"/> is set to false, this
/// method will also connect/disconnect this node from the <see cref="Parent"/> in the playable graph.
/// </summary>
protected internal override void Update(out bool needsMoreUpdates)
{
base.Update(out needsMoreUpdates);
if (_IsPlayingDirty)
{
_IsPlayingDirty = false;
if (_IsPlaying)
{
#if UNITY_2017_3_OR_NEWER
_Playable.Play();
#else
_Playable.SetPlayState(PlayState.Playing);
#endif
}
else
{
#if UNITY_2017_3_OR_NEWER
_Playable.Pause();
#else
_Playable.SetPlayState(PlayState.Paused);
#endif
}
}
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Timing
/************************************************************************************************************************/
// Time.
/************************************************************************************************************************/
/// <summary>
/// The current time of the <see cref="Playable"/>, retrieved by <see cref="Time"/> whenever the
/// <see cref="_TimeFrameID"/> is different from the <see cref="AnimancerPlayable.FrameID"/>.</summary>
private float _Time;
/// <summary>
/// The <see cref="AnimancerPlayable.FrameID"/> from when the <see cref="Time"/> was last retrieved from the
/// <see cref="Playable"/>.
/// </summary>
private uint _TimeFrameID;
/************************************************************************************************************************/
/// <summary>
/// The number of seconds that have passed since the start of this animation.
/// <para></para>
/// This value will continue increasing after the animation passes the end of its <see cref="Length"/> while
/// the animated object either freezes in place or starts again from the beginning according to whether it is
/// looping or not.
/// <para></para>
/// Animancer Lite does not allow this value to be changed in a runtime build (except resetting it to 0).
/// </summary>
///
/// <example>
/// <code>
/// void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
/// {
/// var state = animancer.Play(clip);
///
/// // Skip 0.5 seconds into the animation:
/// state.Time = 0.5f;
///
/// // Skip 50% of the way through the animation (0.5 in a range of 0 to 1):
/// state.NormalizedTime = 0.5f;
///
/// // Skip to the end of the animation and play backwards.
/// state.NormalizedTime = 1;
/// state.Speed = -1;
/// }
/// </code>
/// </example>
///
/// <remarks>
/// This property internally uses <see cref="NewTime"/> whenever the value is out of date or gets changed.
/// </remarks>
public float Time
{
get
{
var frameID = Root.FrameID;
if (_TimeFrameID != frameID)
{
_TimeFrameID = frameID;
_Time = NewTime;
}
return _Time;
}
set
{
if (_TimeFrameID == Root.FrameID)
{
if (_Time == value)
return;
}
else
{
_TimeFrameID = Root.FrameID;
}
Debug.Assert(!float.IsNaN(value), "Time must not be NaN");
_Time = value;
NewTime = value;
}
}
/************************************************************************************************************************/
/// <summary>
/// The internal implementation of <see cref="Time"/> which actually gets and sets the underlying value.
/// </summary>
/// <remarks>
/// Setting this value actually calls <see cref="PlayableExtensions.SetTime"/> twice to ensure that animation
/// events aren't triggered incorrectly. Calling it only once would trigger any animation events between the
/// previous time and the new time. So if an animation plays to the end and you set the time back to 0 (such as
/// by calling <see cref="Stop"/> or playing a different animation), the next time that animation played it
/// would immediately trigger all of its events, then play through and trigger them normally as well.
/// </remarks>
protected virtual float NewTime
{
get { return (float)_Playable.GetTime(); }
set
{
var time = (double)value;
_Playable.SetTime(time);
_Playable.SetTime(time);
if (_EventUpdatable != null)
_EventUpdatable.OnTimeChanged();
}
}
/************************************************************************************************************************/
/// <summary>
/// The <see cref="Time"/> of this state as a portion of the animation's <see cref="Length"/>, meaning the
/// value goes from 0 to 1 as it plays from start to end, regardless of how long that actually takes.
/// <para></para>
/// This value will continue increasing after the animation passes the end of its <see cref="Length"/> while
/// the animated object either freezes in place or starts again from the beginning according to whether it is
/// looping or not.
/// <para></para>
/// The fractional part of the value (<c>NormalizedTime % 1</c>) is the percentage (0-1) of progress in the
/// current loop while the integer part (<c>(int)NormalizedTime</c>) is the number of times the animation has
/// been looped.
/// <para></para>
/// Animancer Lite does not allow this value to be changed to a value other than 0 in a runtime build.
/// </summary>
///
/// <example>
/// <code>
/// void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
/// {
/// var state = animancer.Play(clip);
///
/// // Skip 0.5 seconds into the animation:
/// state.Time = 0.5f;
///
/// // Skip 50% of the way through the animation (0.5 in a range of 0 to 1):
/// state.NormalizedTime = 0.5f;
///
/// // Skip to the end of the animation and play backwards.
/// state.NormalizedTime = 1;
/// state.Speed = -1;
/// }
/// </code>
/// </example>
public float NormalizedTime
{
get
{
var length = Length;
if (length != 0)
return Time / Length;
else
return 0;
}
set { Time = value * Length; }
}
/************************************************************************************************************************/
// Duration.
/************************************************************************************************************************/
/// <summary>
/// The number of seconds the animation will take to play fully at its current
/// <see cref="AnimancerNode.Speed"/>.
/// <para></para>
/// Setting this value modifies the <see cref="AnimancerNode.Speed"/>, not the <see cref="Length"/>.
/// Animancer Lite does not allow this value to be changed in a runtime build.
/// <para></para>
/// For the time remaining from now until it reaches the end, use <see cref="RemainingDuration"/> instead.
/// </summary>
///
/// <example>
/// <code>
/// void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
/// {
/// var state = animancer.Play(clip);
///
/// state.Duration = 1;// Play fully in 1 second.
/// state.Duration = 2;// Play fully in 2 seconds.
/// state.Duration = 0.5f;// Play fully in half a second.
/// state.Duration = -1;// Play backwards fully in 1 second.
/// state.NormalizedTime = 1; state.Duration = -1;// Play backwards from the end in 1 second.
/// }
/// </code>
/// </example>
public float Duration
{
get
{
var speed = Speed;
if (speed == 0)
return float.PositiveInfinity;
else
return Length / Math.Abs(speed);
}
set
{
if (value == 0)
Speed = float.PositiveInfinity;
else
Speed = Length / value;
}
}
/// <summary>
/// The number of seconds the animation will take to reach the end at its current <see cref="AnimancerNode.Speed"/>.
/// <para></para>
/// Setting this value modifies the <see cref="AnimancerNode.Speed"/>, not the <see cref="Length"/>.
/// Animancer Lite does not allow this value to be changed in a runtime build.
/// <para></para>
/// For the time it would take to play fully from the start, use <see cref="Duration"/> instead.
/// </summary>
///
/// <example>
/// <code>
/// void PlayAnimation(AnimancerComponent animancer, AnimationClip clip)
/// {
/// var state = animancer.Play(clip);
///
/// state.RemainingDuration = 1;// Play from the current time to the end in 1 second.
/// state.RemainingDuration = 2;// Play from the current time to the end in 2 seconds.
/// state.RemainingDuration = 0.5f;// Play from the current time to the end in half a second.
/// state.RemainingDuration = -1;// Play backwards from the current time to the end in 1 second.
/// }
/// </code>
/// </example>
public float RemainingDuration
{
get
{
var speed = Speed;
if (speed == 0)
return float.PositiveInfinity;
var length = Length;
if (_EventUpdatable != null)
{
if (speed > 0)
length *= _EventUpdatable.Events.NormalizedEndTime;
else
length *= 1 - _EventUpdatable.Events.NormalizedEndTime;
}
var time = Time;
if (IsLooping)
time = Mathf.Repeat(time, length);
return (length - time) / Math.Abs(speed);
}
set
{
if (value == 0)
throw new ArgumentException("Duration cannot be set to 0 because that would require infinite speed.");
var length = Length;
if (_EventUpdatable != null)
{
if (value > 0)
length *= _EventUpdatable.Events.NormalizedEndTime;
else
length *= 1 - _EventUpdatable.Events.NormalizedEndTime;
}
var time = Time;
if (IsLooping)
time = Mathf.Repeat(time, length);
Speed = (length - time) / value;
}
}
/************************************************************************************************************************/
// Length.
/************************************************************************************************************************/
/// <summary>The total time this state takes to play in seconds (when <c>Speed = 1</c>).</summary>
public abstract float Length { get; }
/// <summary>
/// Indicates whether this state will loop back to the start when it reaches the end.
/// </summary>
public virtual bool IsLooping { get { return false; } }
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Inverse Kinematics
/************************************************************************************************************************/
/// <summary>
/// Determines whether <c>OnAnimatorIK(int layerIndex)</c> will be called on the animated object.
/// The initial value is determined by <see cref="AnimancerLayer.DefaultApplyAnimatorIK"/>.
/// <para></para>
/// This is equivalent to the "IK Pass" toggle in Animator Controller layers, except that due to limitations in
/// the Playables API the <c>layerIndex</c> will always be zero.
/// <para></para>
/// 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
/// <see cref="AnimancerNode.Weight"/> == 1 which meant that IK would not work while fading between animations.
/// <para></para>
/// Returns false and does nothing if this state does not support IK.
/// </summary>
public virtual bool ApplyAnimatorIK
{
get { return false; }
set { }
}
/// <summary>
/// Indicates whether this state is applying IK to the character's feet.
/// The initial value is determined by <see cref="AnimancerLayer.DefaultApplyFootIK"/>.
/// <para></para>
/// This is equivalent to the "Foot IK" toggle in Animator Controller states.
/// <para></para>
/// Returns false and does nothing if this state does not support IK.
/// </summary>
public virtual bool ApplyFootIK
{
get { return false; }
set { }
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Methods
/************************************************************************************************************************/
/// <summary>Constructs a new <see cref="AnimancerState"/>.</summary>
public AnimancerState(AnimancerPlayable root) : base(root)
{
IsPlaying = false;
}
/************************************************************************************************************************/
/// <summary>
/// Plays this animation immediately, without any blending.
/// Sets <see cref="IsPlaying"/> = true, <see cref="AnimancerNode.Weight"/> = 1, and clears the
/// <see cref="Events"/>.
/// <para></para>
/// This method does not change the <see cref="Time"/> so it will continue from its current value.
/// </summary>
public void Play()
{
IsPlaying = true;
Weight = 1;
EventUpdatable.TryClear(_EventUpdatable);
}
/************************************************************************************************************************/
/// <summary>
/// Stops the animation and makes it inactive immediately so it no longer affects the output.
/// Sets <see cref="AnimancerNode.Weight"/> = 0, <see cref="IsPlaying"/> = false, <see cref="Time"/> = 0, and
/// clears the <see cref="Events"/>.
/// <para></para>
/// If you only want to freeze the animation in place, you can set <see cref="IsPlaying"/> = false instead. Or
/// to freeze all animations, you can call <see cref="AnimancerPlayable.PauseGraph"/>.
/// </summary>
public override void Stop()
{
base.Stop();
IsPlaying = false;
Time = 0;
EventUpdatable.TryClear(_EventUpdatable);
}
/************************************************************************************************************************/
/// <summary>
/// Called by <see cref="AnimancerNode.StartFade"/>. Clears the <see cref="Events"/>.
/// </summary>
protected internal override void OnStartFade()
{
EventUpdatable.TryClear(_EventUpdatable);
}
/************************************************************************************************************************/
/// <summary>Destroys the <see cref="Playable"/>.</summary>
public virtual void Destroy()
{
GC.SuppressFinalize(this);
if (_Parent != null)
_Parent.OnRemoveChild(this);
Index = -1;
EventUpdatable.TryClear(_EventUpdatable);
Root.States.Unregister(this);
// For some reason this is slightly faster than _Playable.Destroy().
if (_Playable.IsValid())
Root._Graph.DestroyPlayable(_Playable);
}
/************************************************************************************************************************/
/// <summary>[<see cref="IAnimationClipCollection"/>]
/// Gathers all the animations in this state.
/// </summary>
public virtual void GatherAnimationClips(ICollection<AnimationClip> clips)
{
clips.Gather(Clip);
}
/************************************************************************************************************************/
/// <summary>
/// Returns true if the animation is playing and has not yet passed the
/// <see cref="AnimancerEvent.Sequence.endEvent"/>.
/// <para></para>
/// This method is called by <see cref="IEnumerator.MoveNext"/> so this object can be used as a custom yield
/// instruction to wait until it finishes.
/// </summary>
protected internal override bool IsPlayingAndNotEnding()
{
if (!IsPlaying)
return false;
var speed = EffectiveSpeed;
if (speed > 0)
{
float endTime;
if (_EventUpdatable != null)
{
endTime = _EventUpdatable.Events.endEvent.normalizedTime;
if (float.IsNaN(endTime))
endTime = Length;
else
endTime *= Length;
}
else endTime = Length;
return Time <= endTime;
}
else if (speed < 0)
{
float endTime;
if (_EventUpdatable != null)
{
endTime = _EventUpdatable.Events.endEvent.normalizedTime;
if (float.IsNaN(endTime))
endTime = 0;
else
endTime *= Length;
}
else endTime = 0;
return Time >= endTime;
}
else return true;
}
/************************************************************************************************************************/
#region Descriptions
/************************************************************************************************************************/
#if UNITY_EDITOR
/// <summary>[Editor-Only] Returns a custom drawer for this state.</summary>
protected internal virtual Editor.IAnimancerNodeDrawer GetDrawer()
{
return new Editor.AnimancerStateDrawer<AnimancerState>(this);
}
#endif
/************************************************************************************************************************/
/// <summary>
/// Called by <see cref="AnimancerNode.AppendDescription"/> to append the details of this node.
/// </summary>
protected override void AppendDetails(StringBuilder text, string delimiter)
{
base.AppendDetails(text, delimiter);
text.Append(delimiter).Append("IsPlaying: ").Append(IsPlaying);
text.Append(delimiter).Append("Time (Normalized): ").Append(Time);
text.Append(" (").Append(NormalizedTime).Append(')');
text.Append(delimiter).Append("Length: ").Append(Length);
text.Append(delimiter).Append("IsLooping: ").Append(IsLooping);
if (_Key != null)
text.Append(delimiter).Append("Key: ").Append(_Key);
if (_EventUpdatable != null && _EventUpdatable.Events != null)
_EventUpdatable.Events.endEvent.AppendDetails(text, "EndEvent", delimiter);
var clip = Clip;
if (clip != null)
{
#if UNITY_EDITOR
text.Append(delimiter).Append("AssetPath: ").Append(AssetDatabase.GetAssetPath(clip));
#endif
}
}
/************************************************************************************************************************/
/// <summary>Returns the hierarchy path of this state through its <see cref="Parent"/>s.</summary>
public string GetPath()
{
if (_Parent == null)
return null;
var path = new StringBuilder();
AppendPath(path, _Parent);
AppendPortAndType(path);
return path.ToString();
}
/// <summary>Appends the hierarchy path of this state through its <see cref="Parent"/>s.</summary>
private static void AppendPath(StringBuilder path, AnimancerNode parent)
{
var parentState = parent as AnimancerState;
if (parentState != null && parentState._Parent != null)
{
AppendPath(path, parentState._Parent);
}
else
{
path.Append("Layers[")
.Append(parent.Layer.Index)
.Append("].States");
return;
}
var state = parent as AnimancerState;
if (state != null)
{
state.AppendPortAndType(path);
}
else
{
path.Append(" -> ")
.Append(parent.GetType());
}
}
/// <summary>Appends "[Index] -> GetType().Name".</summary>
private void AppendPortAndType(StringBuilder path)
{
path.Append('[')
.Append(Index)
.Append("] -> ")
.Append(GetType().Name);
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
#region Transition
/************************************************************************************************************************/
/// <summary>
/// Base class for serializable <see cref="ITransition"/>s which can create a particular type of
/// <see cref="AnimancerState"/> when passed into <see cref="AnimancerPlayable.Play(ITransition)"/>.
/// </summary>
/// <remarks>
/// Unfortunately the tool used to generate this documentation does not currently support nested types with
/// identical names, so only one <c>Transition</c> class will actually have a documentation page.
/// <para></para>
/// Even though it has the <see cref="SerializableAttribute"/>, this class won't actually get serialized
/// by Unity because it's generic and abstract. Each child class still needs to include the attribute.
/// </remarks>
[Serializable]
public abstract class Transition<TState> : ITransitionDetailed where TState : AnimancerState
{
/************************************************************************************************************************/
[SerializeField, Tooltip(Strings.ProOnlyTag + "The amount of time the transition will take (in seconds)")]
private float _FadeDuration = AnimancerPlayable.DefaultFadeDuration;
/// <summary>[<see cref="SerializeField"/>] The amount of time the transition will take (in seconds).</summary>
/// <exception cref="ArgumentOutOfRangeException">Thrown when setting the value to a negative number.</exception>
public float FadeDuration
{
get { return _FadeDuration; }
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "must not be negative");
_FadeDuration = value;
}
}
/************************************************************************************************************************/
/// <summary>[<see cref="ITransitionDetailed"/>]
/// Indicates what the value of <see cref="AnimancerState.IsLooping"/> will be for the created state.
/// Returns false unless overridden.
/// </summary>
public virtual bool IsLooping { get { return false; } }
/// <summary>[<see cref="ITransitionDetailed"/>]
/// Determines what <see cref="NormalizedTime"/> to start the animation at.
/// Returns <see cref="float.NaN"/> unless overridden.
/// </summary>
public virtual float NormalizedStartTime { get { return float.NaN; } set { } }
/// <summary>[<see cref="ITransitionDetailed"/>]
/// Determines how fast the animation plays (1x = normal speed).
/// Returns 1 unless overridden.
/// </summary>
public virtual float Speed { get { return 1; } set { } }
/// <summary>[<see cref="ITransitionDetailed"/>]
/// The maximum amount of time the animation is expected to take (in seconds).
/// </summary>
public abstract float MaximumDuration { get; }
/************************************************************************************************************************/
[SerializeField, Tooltip(Strings.ProOnlyTag + "Events which will be triggered as the animation plays")]
private AnimancerEvent.Sequence.Serializable _Events;
/// <summary>[<see cref="SerializeField"/>] Events which will be triggered as the animation plays.</summary>
public AnimancerEvent.Sequence.Serializable Events
{
get { return _Events; }
set { _Events = value; }
}
/************************************************************************************************************************/
/// <summary>
/// The state that was created by this object. Specifically, this is the state that was most recently
/// passed into <see cref="Apply"/> (usually by <see cref="AnimancerPlayable.Play(ITransition)"/>).
/// <para></para>
/// You can use <see cref="AnimancerPlayable.StateDictionary.GetOrCreate(ITransition)"/> or
/// <see cref="AnimancerLayer.GetOrCreateState(ITransition)"/> to get or create the state for a
/// specific object.
/// <para></para>
/// <see cref="State"/> is simply a shorthand for casting this to <typeparamref name="TState"/>.
/// </summary>
public AnimancerState BaseState { get; private set; }
/************************************************************************************************************************/
private TState _State;
/// <summary>
/// The state that was created by this object. Specifically, this is the state that was most recently
/// passed into <see cref="Apply"/> (usually by <see cref="AnimancerPlayable.Play(ITransition)"/>).
/// <para></para>
/// You can use <see cref="AnimancerPlayable.StateDictionary.GetOrCreate(ITransition)"/> or
/// <see cref="AnimancerLayer.GetOrCreateState(ITransition)"/> to get or create the state for a
/// specific object.
/// <para></para>
/// This property is shorthand for casting the <see cref="BaseState"/> to <typeparamref name="TState"/>.
/// </summary>
/// <exception cref="InvalidCastException">
/// Thrown if the <see cref="BaseState"/> is not actually a <typeparamref name="TState"/>. This should only
/// happen if a different type of state was created by something else and registered using the
/// <see cref="Key"/>, causing this <see cref="AnimancerPlayable.Play(ITransition)"/> to pass that
/// state into <see cref="Apply"/> instead of calling <see cref="CreateState"/> to make the correct type of
/// state.
/// </exception>
public TState State
{
get
{
if (_State == null)
_State = (TState)BaseState;
return _State;
}
protected set
{
BaseState = _State = value;
}
}
/************************************************************************************************************************/
/// <summary>
/// The <see cref="AnimancerState.Key"/> which the created state will be registered with.
/// <para></para>
/// By default, a transition is used as its own <see cref="Key"/>, but this property can be overridden.
/// </summary>
public virtual object Key { get { return this; } }
/// <summary>
/// When a transition is passed into <see cref="AnimancerPlayable.Play(ITransition)"/>, this property
/// determines which <see cref="Animancer.FadeMode"/> will be used.
/// </summary>
public virtual FadeMode FadeMode { get { return FadeMode.FixedSpeed; } }
/// <summary>
/// Creates and returns a new <typeparamref name="TState"/> connected to the `layer`.
/// </summary>
public abstract TState CreateState(AnimancerLayer layer);
/// <summary>
/// Creates and returns a new <typeparamref name="TState"/> connected to the `layer`.
/// </summary>
AnimancerState ITransition.CreateState(AnimancerLayer layer)
{
return CreateState(layer);
}
/************************************************************************************************************************/
/// <summary>[<see cref="ITransition"/>]
/// Called by <see cref="AnimancerPlayable.Play(ITransition)"/> to set the <see cref="BaseState"/>
/// and apply any other modifications to the `state`.
/// </summary>
/// <remarks>
/// This method also clears the <see cref="State"/> if necessary, so it will re-cast the
/// <see cref="BaseState"/> when it gets accessed again.
/// </remarks>
public virtual void Apply(AnimancerState state)
{
state.Events = _Events;
BaseState = state;
if (_State != state)
_State = null;
}
/************************************************************************************************************************/
#if UNITY_EDITOR
/************************************************************************************************************************/
/// <summary>[Editor-Only] Don't use Inspector Gadgets Nested Object Drawers.</summary>
private const bool NestedObjectDrawers = false;
/************************************************************************************************************************/
/// <summary>[Editor-Only] Adds context menu functions for this transition.</summary>
void ITransitionDetailed.AddItemsToContextMenu(GenericMenu menu, SerializedProperty property,
Editor.Serialization.PropertyAccessor accessor)
{
AddItemsToContextMenu(menu, property, accessor);
}
/// <summary>[Editor-Only] Adds context menu functions for this transition.</summary>
protected virtual void AddItemsToContextMenu(GenericMenu menu, SerializedProperty property,
Editor.Serialization.PropertyAccessor accessor)
{
var transition = (Transition<TState>)accessor.GetValue(property);
const string EventsPrefix = "Transition Event Details/";
int timeCount, callbackCount;
AnimancerEvent.Sequence.Serializable.GetDetails(transition._Events, out timeCount, out callbackCount);
menu.AddDisabledItem(new GUIContent(EventsPrefix + "Serialized Time Count: " + timeCount));
menu.AddDisabledItem(new GUIContent(EventsPrefix + "Serialized Callback Count: " + callbackCount));
Editor.Serialization.AddPropertyModifierFunction(menu, property, "Reset Transition", Reset);
}
/************************************************************************************************************************/
private static void Reset(SerializedProperty property)
{
var transition = Editor.Serialization.GetValue(property);
if (transition == null)
return;
const System.Reflection.BindingFlags Bindings =
System.Reflection.BindingFlags.Public |
System.Reflection.BindingFlags.NonPublic |
System.Reflection.BindingFlags.Instance;
var type = transition.GetType();
var constructor = type.GetConstructor(Bindings, null, Type.EmptyTypes, null);
if (constructor == null)
{
Debug.LogError("Parameterless constructor not found in " + type);
return;
}
Editor.Serialization.RecordUndo(property);
constructor.Invoke(transition, null);
Editor.Serialization.OnPropertyChanged(property);
}
/************************************************************************************************************************/
#endif
/************************************************************************************************************************/
}
/************************************************************************************************************************/
#endregion
/************************************************************************************************************************/
}
}