SpriteAnimator Class
Animates sprites by playing animation clips.
public class SpriteAnimator : System.IDisposableInheritance System.Object → SpriteAnimator
Implements System.IDisposable
| Properties | |
|---|---|
| AnimationNames | Returns a read-only collection of all registered animation names. |
| AnimationQueueCount | Gets the number of animations currently in the queue. |
| Clips | Returns a read-only collection of all registered animation clips. |
| CrossFadeAlpha | Gets the normalised cross-fade alpha [0, 1]. |
| CrossFadeBaseAlpha | The sprite tint alpha [0,1] captured at the moment a cross-fade starts. Consumed and written by AnimationSystem. |
| CrossFadeOutgoingClip | Gets the outgoing clip during a cross-fade, or null. |
| CrossFadeOutgoingFrame | Gets the outgoing frame during a cross-fade, or null. |
| CurrentAnimation | Gets the currently playing animation clip. |
| CurrentFrame | Gets the current frame, or null if no animation is active or the animator is stopped. |
| CurrentFrameIndex | Gets the zero-based index of the current frame within the active clip, or -1 if no animation is active. |
| CurrentTime | Elapsed playback time of the current clip in seconds, or 0 if nothing is active. For PingPong modes, returns the position within the current pass, not the full cycle time. |
| IsFinished | true when a non-looping clip has finished. false for looping clips, when nothing is active, or when paused. |
| IsPaused | Gets whether the animator has been explicitly paused via Pause(). A paused animator still holds a valid CurrentFrame and can be resumed. |
| IsPlaying | Gets whether an animation is currently playing (not paused and not finished). |
| MaxQueueDepth | Maximum queue depth across all PlayQueued* overloads. Entries beyond this limit are dropped with a warning. Defaults to 32. |
| NormalizedTime | Gets the normalised playback position [0, 1]. Returns 0 if no animation is active or the total duration is zero. |
| QueuedAnimation | Gets the name of the first queued animation, or null. |
| Reversed | Plays the clip in reverse. For PingPong modes, controls the starting direction only; the alternation itself is unaffected. |
| Speed | Gets or sets the playback speed multiplier. Clamped to zero on the low end. A value of 0 effectively freezes playback without losing clip state. Use Pause() for an explicit pause that also sets IsPaused. |
| TimeRemaining | Remaining playback time in seconds for non-looping clips. Returns 0 for looping clips or when nothing is active. |
| Methods | |
|---|---|
| AddAnimation(AnimationClip) | Adds an animation clip. Replaces any existing clip with the same name and logs a warning. |
| CancelQueued() | Cancels all queued animations. |
| CapturePlaybackSnapshot() | Captures all runtime playback state into an immutable AnimatorPlaybackSnapshot. Use with RestorePlaybackSnapshot(AnimatorPlaybackSnapshot) for save/load, rollback netcode, and cutscene/ability override systems. |
| ClearAnimations() | Removes all animation clips and stops the animator. |
| Dispose() | Releases all event subscriptions and clears playback state without firing any callbacks. |
| ForceResetCurrentAnimation() | Forces the animator to the logical start frame of the current clip, respecting Reversed: frame 0 for forward playback, last frame for reversed. |
| ForceResetCurrentAnimationToEnd() | Forces the animator to the logical end frame of the current clip, respecting Reversed: last frame for forward playback, frame 0 for reversed. |
| GetAnimation(string) | Returns the registered clip with the given name, or null if not found. |
| GetCurrentAnimationDuration() | Returns the total duration of the currently set animation clip in seconds, or 0 if no animation is active. |
| GetCurrentAnimationFrameCount() | Returns the total number of frames in the currently set animation clip, or 0 if no animation is active. |
| GetCurrentAnimationFrameDuration(int) | Returns the frame duration at the given index within the currently set animation clip, or 0 if the index is out of bounds or no animation is active. |
| GetCurrentAnimationSampleTime(int) | Returns the start time of the given frame index in the current clip, in seconds. Returns 0 if out of bounds or nothing is active. |
| HasAnimation(string) | Returns true if an animation clip with the given name has been added. |
| IsAnimationActive(AnimationClip) | Checks if the given animation clip is currently set as the active animation. |
| NotifyClipMutated() | Notifies the animator that the active clip's frame list has been structurally mutated (frames removed or cleared) while this animator was playing it. The current frame index is clamped to valid bounds; if all frames were removed the animator is stopped. Call this after any RemoveFrame(SpriteFrame) or ClearFrames() on the CurrentAnimation. |
| Pause() | Pauses playback without resetting position. Sets IsPaused to true. |
| Play(string, bool) | Plays an animation by name from the beginning. |
| PlayDirect(AnimationClip, bool) | Plays an AnimationClip instance directly without requiring it to be pre-registered via AddAnimation(AnimationClip). Useful for procedurally generated or temporary clips. |
| PlayDirectQueued(AnimationClip) | Queues a clip instance to play directly after the current non-looping clip finishes (or immediately if nothing is playing). The clip does not need to be registered via AddAnimation(AnimationClip). Behaviour is otherwise identical to PlayQueued(string). |
| PlayDirectQueuedWithCrossFade(AnimationClip, float) | Queues a clip instance to play directly with a cross-fade after the current non-looping clip finishes (or immediately if nothing is playing). The clip does not need to be registered via AddAnimation(AnimationClip). Behaviour is otherwise identical to PlayQueuedWithCrossFade(string, float). |
| PlayDirectWithCrossFade(AnimationClip, float, bool) | Plays an AnimationClip instance directly with a cross-fade, without requiring it to be pre-registered via AddAnimation(AnimationClip). |
| PlayFromFrame(string, int, bool) | Plays an animation by name, beginning at a specific frame index. |
| PlayFromFrameWithCrossFade(string, int, float, bool) | Plays an animation by name beginning at a specific frame index, with a cross-fade over fadeDuration seconds from the currently playing clip. |
| PlayFromNormalizedTime(string, float, bool) | Plays an animation by name, beginning at a normalised time [0, 1]. |
| PlayFromNormalizedTimeWithCrossFade(string, float, float, bool) | Plays an animation by name beginning at a normalised time [0, 1], with a cross-fade over fadeDuration seconds from the currently playing clip. |
| PlayIfNotPlaying(string, bool) | Plays the animation if it is not already active. Returns false if it was already playing. |
| PlayQueued(string) | Queues an animation to play after the current non-looping clip finishes (or immediately if nothing is playing). Multiple calls append to the queue; animations play in order. Indefinitely-looping clips (no RepeatCount) cannot be queued behind because they never complete; a warning is logged and the call is ignored. The queue depth is capped at MaxQueueDepth; attempts to exceed it are ignored with a warning. |
| PlayQueuedWithCrossFade(string, float) | Queues an animation to play with a cross-fade after the current non-looping clip finishes (or immediately if nothing is playing). Multiple calls append to the queue. The queue depth is capped at MaxQueueDepth; attempts to exceed it are ignored with a warning. |
| PlayReversed(string, bool) | Plays the named animation in reverse. Equivalent to setting Reversed to true then calling Play(string, bool). After the clip ends, Reversed remains true — set it back to false explicitly if subsequent clips should play forward. |
| PlayWithCrossFade(string, float, bool) | Plays an animation by name with a cross-fade over fadeDuration seconds. |
| RemoveAnimation(string) | Removes an animation clip by name. If the clip is currently active the animator is stopped. Any queued entries for this clip are also removed. |
| RestorePlaybackSnapshot(AnimatorPlaybackSnapshot) | |
| Resume() | Resumes a paused animation. Clears IsPaused. No-op if not paused. |
| SeekToTime(float, bool) | Seeks the animation to a specific time in seconds. |
| SetCurrentAnimationNormalizedTime(float) | Sets the normalized time [0, 1] of the currently playing animation clip. |
| SetCurrentAnimationTime(float) | Forces the currently playing animation clip to the given time in seconds. |
| SetFrame(int) | Immediately jumps to a specific frame index within the active clip. |
| SkipToNextFrame() | Skips forward to the next frame in the currently playing animation clip, respecting playback direction (including ping-pong). |
| SkipToPreviousFrame() | Skips back to the previous frame in the currently playing animation clip, respecting playback direction (including ping-pong). |
| Stop(bool) | Stops and clears the current animation and the entire animation queue. CurrentFrame returns null after this call. |
| TryGetAnimation(string, AnimationClip) | Attempts to retrieve a registered animation clip by name. |
| Update(float) | Updates the animation state. Called once per frame by AnimationSystem. |
| Events | |
|---|---|
| OnAnimationComplete | Raised when a non-looping animation reaches its terminal frame. |
| OnAnimationStart | Raised when a new animation begins playing. |
| OnFrameChanged | Raised each time the active frame index changes. |
| OnLoopComplete | Raised each time a looping animation wraps, each time a ping-pong animation reverses direction, or when a RepeatCount clip completes a pass. |
| OnStopped | Raised when Stop(bool) is called or a OnceStop clip finishes. Receives the clip that was active, or null. Always fires regardless of the fireCallbacks parameter on Stop(bool). |