AbleAnimator

AbleAnimator lets you animate 2D objects straight from the inspector. You give an object a list of animations, pick one to start with, and press play. No Animator Controller, no animation clips.

Every animation is in one of two modes:

• Sprite Mode plays a list of sprites over a set duration. Good for walk cycles, idles, flickering torches and the like.
• Key Frame Mode runs a list of timed steps. Each step can swap the sprite, wait, move, rotate or scale the object, start or stop other animations, or fire Unity Events.

The source code is fully commented, so if something here isn't clear, the scripts are a good second place to look. Or just email us.

1. Getting started

1. Select a GameObject and add the AbleAnimator component. A SpriteRenderer is added for you if there isn't one.
2. Click Add New Animation.
3. Give it an alias (the name you'll use from code), choose a mode and fill it in.
4. Pick the Starting animation at the top of the component.
5. Press play.

There's a demo scene in Tests/RunTime/AbleAnimatorDemo.unity with a little wizard you can poke at.

In code, everything lives in the MugHeadStudios.AbleAnimator namespace:

using MugHeadStudios.AbleAnimator;

If your own scripts are inside an assembly definition, add a reference to MugHeadStudios.AbleAnimator (and MugHeadStudios.AbleAnimator.Editor if you're writing editor code that uses ours). Scripts in the normal Assembly-CSharp don't need anything.

2. Animations in the inspector

Each animation in the list has a small header with:

• The eye button, which collapses or expands the animation so long lists stay tidy.
• Duplicate, which copies the animation and puts the copy just below it (with a new alias).
• Delete, which removes it.

You can drag animations to reorder them. The Starting animation drop-down shows them by number and alias.

When you're not in play mode, the SpriteRenderer shows the first sprite of the starting animation, so you can see what you're working with.

3. Sprite Mode

Add any number of sprites and set a Duration in seconds. The sprites are spread evenly across that duration, so 4 sprites over 1 second shows each one for 0.25 seconds.

Want one frame to hold longer? Add the same sprite more than once.

4. Key Frame Mode

Key frames run one after another, top to bottom. Each has a type:

Type	What it does
Sprite Change	Shows a sprite, then waits for its time.
Wait	Just waits for its time.
Position	Moves the object to a position over its time. With relative ticked the value is added to where the object started (in local space). Otherwise it's a world position.
Rotate	Rotates the object to a rotation (Euler angles) over its time. Relative works the same way as Position.
Scale	Scales the object to a size over its time.
Concurrent Animation	Starts or stops other animations that play alongside this one (see below). Takes no time.
Event	Fires the Unity Events you hook up in the inspector. Takes no time.

A Position, Rotate or Scale key frame with a time of 0 jumps straight to its value.

Concurrent animations

A concurrent animation plays at the same time as the main one, on the same object. It doesn't change the main animation's timing. The options are:

• Run stops any concurrent animations already playing, then starts the one you name.
• Append starts the one you name and leaves the others playing.
• Stop stops the one you name.
• Stop all stops every concurrent animation.

A typical use: the main animation walks the character left and right, and a concurrent "Blink" animation swaps the eyes every few seconds.

5. Play amount

Every animation has a play amount:

Setting	What happens
Infinite Loop	Loops until you run something else.
Play Once	Plays once and stops on its last frame.
Play X Times	Plays the number of times you set, then stops.
Play X Then Switch	Plays the number of times you set, then switches to the animation whose alias you type in.

When a non-looping animation finishes, its onComplete action runs (see section 6).

6. Using AbleAnimator from code

using MugHeadStudios.AbleAnimator;
using UnityEngine;

public class Wizard : MonoBehaviour
{
    AbleAnimator animator;

    void Awake()
    {
        animator = GetComponent<AbleAnimator>();
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            // Plays the "Attack" animation. If it's a "Play once" animation that has
            // already finished, calling this again starts it from the beginning.
            animator.RunAnimation("Attack");
        }
    }
}

Running something when an animation ends:

AbleAnimation attack = animator.ableAnimations.Find(a => a.alias == "Attack");
attack.onComplete = finished => animator.RunAnimation("Idle");

Building an animation in code:

AbleAnimation spin = animator.AddAnimation();
spin.alias = "Spin";
spin.mode = AbleAnimation.Modes.KeyFrameMode;
spin.playAmountMode = AbleAnimation.PlayAmountMode.InfiniteLoop;
spin.playAmount = -1;
spin.keyFrames.Add(new AbleAnimationKeyFrame {
    keyFrameType = AbleAnimationKeyFrame.KeyFrameType.Rotate,
    vector3 = new Vector3(0, 0, 360),
    relative = true,
    time = 1f
});

animator.RunAnimation("Spin");

If you ask for an alias that doesn't exist, AbleAnimator logs a warning and carries on.

7. Class reference

AbleAnimator (component)

Member	Description
List<AbleAnimation> ableAnimations	All the animations on this object.
int startingAnimationIndex	Which animation plays when the object starts.
AbleAnimation currentAnimation	The main animation playing right now (read only).
List<AbleAnimation> concurrentAnimations	Concurrent animations playing right now (read only).
SpriteRenderer spriteRenderer	The SpriteRenderer being animated.
AbleAnimation AddAnimation(AbleAnimation animation = null)	Adds an animation (a new default one if you pass nothing) and returns it.
void RunAnimation(string alias) / (int index)	Stops everything and plays this animation. Does nothing if it's already playing, unless it has finished.
void RunConcurrentAnimation(string alias) / (int index)	Plays an animation alongside the main one.
bool IsAnimationPlaying(string alias) / (int index)	True if this is the current main animation.
bool IsConcurrentAnimationPlaying(string alias) / (int index)	True if this concurrent animation is playing and hasn't finished.
void StopAllAnimations()	Stops the main animation and all concurrent ones.
void StopConcurrentAnimations()	Stops all concurrent animations.
void StopConcurrentAnimation(string alias)	Stops one concurrent animation.

AbleAnimation

Member	Description
string alias	The animation's name.
Modes mode	SpriteMode or KeyFrameMode.
float duration	Length of a Sprite Mode animation, in seconds.
List<Sprite> sprites	Sprites for Sprite Mode.
List<AbleAnimationKeyFrame> keyFrames	Key frames for Key Frame Mode.
PlayAmountMode playAmountMode	See section 5.
int playAmount	-1 loops forever, any positive number plays that many times.
string switchOnComplete	Alias to switch to with "Play X Then Switch".
int currentPlayCount	How many times it has played so far.
Action<AbleAnimation> onComplete	Runs when a non-looping animation finishes.
bool stopped	True once stopped.
bool isFinished	True once stopped or played the set number of times.
AbleAnimator parent	The AbleAnimator running it.
AbleAnimation Run(AbleAnimator ableAnimator, bool forceRestart = false)	Resets and prepares the animation. You'll normally use AbleAnimator.RunAnimation instead.
AbleAnimation SetFrameIndex(int newFrameIndex)	Jumps to a frame or key frame.
AbleAnimation Stop()	Stops it updating.

AbleAnimationKeyFrame

Field	Description
KeyFrameType keyFrameType	SpriteChange, Wait, Position, Rotate, Scale, ConcurrentAnimation or Event.
Sprite sprite	Sprite for SpriteChange.
Vector3 vector3	Target for Position, Rotate and Scale.
bool relative	Whether vector3 is added to the starting value.
float time	How long the step takes, in seconds.
string stringValue	Alias used by ConcurrentAnimation.
ConcurrentAnimationType concurrentAnimationType	Run, Append, Stop or StopAll.
UnityEvent action	Events fired by an Event key frame.

8. Notes and limits

• Animations use Time.deltaTime, so they slow down and pause with Time.timeScale.
• AbleAnimator works with any render pipeline. It only touches the Transform and SpriteRenderer.
• Absolute rotations are blended as Euler angles, so very large turns (more than 180 degrees in one step) may go the "long way round". Use relative rotations for spins.
• One AbleAnimation shouldn't be the main animation and a concurrent animation at the same time, because they share their timers.

9. Contact

Found a bug, or something in here doesn't make sense? Email us at [email protected]. We read everything and we're happy to help.

MugHead Studios · mugheadstudios.com