Frame-specific attacks in Unity

Explanation

Why would I want to check specific frames? There's several situations where checking if an animation is in a specific frame comes in handy:

Examples are endless, but you can see where this is going: More control over our animations gives us more possibilities.

The underlying logic (and code) for all the situations I mentioned will be the same, but in this post I'll center in one of those cases: I want to be able to tell  an attack how many frames of startup, hit and recovery it has. Or in other words, Move Stages.

Animation, Frames and Move Stages

So what do we see when we watch a fighting or action game? Characters fighting each other, is it not obvious? You may say, and you would be correct. But if we look deeper, what we are actually seeing are animation frames. Sprites being rendered one after the other at a fixed rate (Or polygons being moved and deformed at a fixed rate if you are in a 3D enviroment). 

This "fixed rate" is usually 60 or 30 frames per second for 3D games. In 2D games it depends on what the developer or artist wants: More frames per second will give you a smoother and more detailed animation, but it means more sprites need to be created for every action. Note that we are talking about animation frames and not the speed the game runs at. For a fighting game to be responsive enough to be good it should at least detect the player input at a high framerate, indepentendly of the type of animation used.

SF3 runs at 60fps but it's animated at a much lower framerate (And it looks awesome).

As your probably know, an animation is composed of frames and has a duration that we can also measure in frames. Why would we want to measure an animation in frames? because as we stated previously we want to check if our animation is playing a specific frame. 

When you trigger an attack in a game it doesn't automatically hit the enemy. The character starts the animation by preparing the attack, it hits for some amount of time and then recovers from the movement. Playing with the duration of those phases is how you get "heavier" or "lighter" characters, moves or weapons.

Here's an example from Dark Souls, a quick Rapier that does small amounts of damage vs. a slower Great Club that does enourmos damage.

Pay attention to the really long startup of the club

Those stages of an attack animation are called Move Stages. Or Attack Phases, or any combination of those 4 words. As always, it depends on who you ask. I'll call them Move Stages just to be consistent.

Move Stages

As we mentioned, an attack has 3 stages:

Here's a nice graphic from Shoryuken.com:

So when do we want our Hitboxes to check for collisions? You guessed right, in the Active Frames Stage.

Now that we know what we want, let's get to work! (This may seem obvious but never underestimate the power of actually knowing what problem you are trying to solve)

Quick solutions

As with every problem, there's the quick way and there's the more complicated way. Note that I didn't say one is right and one is wrong. Which solution you choose should respond to what problem you have, the scope of the problem and how much time you are willing to invest to solve it. Don't let yourself be distracted of your objective because some coding guru told you that the right way to iterate an array is an incredibly performant-functional-disruptive way that would take you 2 months to implement when you had it solved and working perfectly in 5 minutes with a for loop.

Okay, rant over.

There's 2 standard ways to change script values in specific frames of an animation:

These two methods could work perfectly depending on the needs of your game, and you can implement any of them in 5 minutes, so really evaluate what you need.

The problems

The long way

To solve the problems that we mentioned, we first need to understand how animations in Unity work.

Getting to know the components

In Unity, an animation is represented by an AnimationClip. It holds the keyframe data of an animation and you can reutilize it for different characters (if the animated objects respect the same hierarchy and have the same names).

Unless you are rolling your own animation system, to actually play a clip you need an Animator Controller. An animator controller provides you with a node-based interface to handle animation states, layers, transitions, playback speed and animation blending. Here's where things can get a little complicated, but don't worry too much right now.

Let's enumerate some definitions:

Working

Lets get the hash fo the state. We need to make a string composed of the name of the layer and the name of the state separated by a dot, and then ask the Animator class what's the hash:

string name = animator.GetLayerName(layerNumber) + "." + animatorStateName;
string animationFullNameHash = Animator.StringToHash(name);

If you have Sub-state machines the "name of the state" is composed the same way: sub-state machine name and state separated by a dot.

Note that you get the layer name from an Animator instance, but the hash from the Animator class using a static method.

As you can see there's some level of indirection to get the progress of a state. In cases like this I like to use Extension Methods. Check the link if you don't know what extensions are. Be warned that some developers don't like extension methods because in some ways you are "hiding" your own methods in other classes. I'm not going to discuss that in this article but I recommend you do some googling and decide for yourself.

Lets make an extension to check if the animator is playing a certain animation and another to check the progress of the current animation.

public static class AnimatorExtension {
    public static bool isPlayingOnLayer(this Animator animator, int fullPathHash, int layer) {
        return animator.GetCurrentAnimatorStateInfo(layer).fullPathHash == fullPathHash;

    }

    public static double normalizedTime(this Animator animator, System.Int32 layer) {
        double time = animator.GetCurrentAnimatorStateInfo(layer).normalizedTime;
        return time > 1 ? 1 : time;
    }

}

Some notes about normalizedTime: 

With the code above we have a way of querying an animator for the progress of a certain state, but if want to work with animation frames we need to convert that percentage to frames, or our frames to percentage.

An AnimationClip has a length and a frameRate. With those two values we can get the amount of frames of a clip:

int totalFrames = Mathf.RoundToInt(clip.length * clip.frameRate);

With the number of frames and the extensions we made we can now convert frames to percentage (I stored _totalFrames as a property):

double percentageOnFrame(int frameNumber) {
    return (double)frameNumber / (double)_totalFrames;
}

Now we can get the progress of a state and also what that number should be in every frame.  One problem you probably guessed is that normalized time is not precise, at least not in my experience. If you do something like this you'll get mixed results:

// WARNING, read above

public bool itsOnFrame(int frameNumber) {
    double percentage = animator.normalizedTime(layerNumber);
    return (percentage >= percentageOnFrame(frameNumber) && (percentage < percentageOnFrame(frameNumber + 1)));
}

Take this with a grain of salt but from what I tried the precision will vary based on the framerate of your animations. For what is worth, I'm using 16 samples per animation.

In the Animation tab it's called Samples, 60 by default.

So how do we solve this?  It will depend on the precision you need and your project.

I went with the third option because it worked pretty well for my needs:

public bool biggerOrEqualThanFrame(int frameNumber) {
    double percentage = animator.normalizedTime(layerNumber);
    return (percentage >= percentageOnFrame(frameNumber));
}

Obviously this method will return true in the frame we want and in all subsequent ones, so we need a flag to avoid repeating functionality we just wanted to run on that specific frame.

While we are at it we could add a special case for the last frame, to avoid the aforementioned problem with transitions:

public bool itsOnLastFrame() {
    double percentage = animator.normalizedTime(layerNumber);
    return (percentage > percentageOnFrame(_totalFrames - 1));
}

Now that we have the methods we need, lets put them in a class that makes sense. We need a class that represents an Animation from our point of view, that you can ask in what frame it is, if it's active in an animator and how many frames does it have.

I chose to call this class AnimationClipExtended. It's an awful name and you are right in hating me right now. Feel free to suggest a better name! I'll be happy to change it.

[System.Serializable]
public class AnimationClipExtended {
    public Animator animator;
    public AnimationClip clip;
    public string animatorStateName;
    public int layerNumber;

    private int _totalFrames = 0;
    private int _animationFullNameHash;

    public void initialize() {
        _totalFrames = Mathf.RoundToInt(clip.length * clip.frameRate);

        if (animator.isActiveAndEnabled) {
            string name = animator.GetLayerName(layerNumber) + "." + animatorStateName;

            _animationFullNameHash = Animator.StringToHash(name);

        }

    }

    public bool isActive() {
        return animator.isPlayingOnLayer(_animationFullNameHash, 0);

    }

    // ... And add the methods we worked on before.

}

In my defense, I intended to change the name later...

Using this class you should be able to add it to you Attack script and do whatever you want with the hitboxes, but if you want to check frame ranges in different classes you would be repeating a lot of code and we don't want that. We can take one more step and make it more reusable by encapsulating the frame range checking. I would like to be able to:

For the callbacks lets take the same approach we did with Hitboxes and make an interface. If you want to know the rationale behind it check the post.

public interface IFrameCheckHandler {
    void onHitFrameStart();
    void onHitFrameEnd();
    void onLastFrameStart();
    void onLastFrameEnd();
}

Now we have everything we need to make our class:

[System.Serializable]
public class FrameChecker {
    public int hitFrameStart;
    public int hitFrameEnd;
    public int totalFrames;

    private IFrameCheckHandler _frameCheckHandler;
    private AnimationClipExtended _extendedClip;
    private bool _checkedHitFrameStart;
    private bool _checkedHitFrameEnd;
    private bool _lastFrame;

    public void initialize(IFrameCheckHandler frameCheckHandler, AnimationClipExtended extendedClip) {
        frameCheckHandler = frameCheckHandler;

        _extendedClip = extendedClip;

        totalFrames = extendedClip.totalFrames();

        initCheck();

    }

    public void initCheck() {
        _checkedHitFrameStart = false;

        _checkedHitFrameEnd = false;

        _lastFrame = false;

    }

    public void checkFrames() {
        if (_lastFrame) {

            _lastFrame = false;

            _frameCheckHandler.onLastFrameEnd();

        }

        if (!_extendedClip.isActive()) { return; }

        if (!_checkedHitFrameStart && _extendedClip.biggerOrEqualThanFrame(hitFrameStart)) {

            _frameCheckHandler.onHitFrameStart();

            _checkedHitFrameStart = true;

        } else if (!_checkedHitFrameEnd && _extendedClip.biggerOrEqualThanFrame(hitFrameEnd)) {

            _frameCheckHandler.onHitFrameEnd();

            _checkedHitFrameEnd = true;

        }

        if (!_lastFrame && _extendedClip.itsOnLastFrame()) {

            _frameCheckHandler.onLastFrameStart();

            _lastFrame = true; // This is here so we don't skip the last frame

        }

    }

}

We could use an enum to handle state changes instead of booleans, but then the last frame and the last active frame can't be equal. As always, it depends of your use case.

How do we use this class? 

And that's it! Here's a look at all of this in action  in the game I'm working on:

So now what?

In my next post I'll probably delve a little in how I handle attacks and combos as the one you saw in the gif, with animation interruption and such.

Also, with a really simple Editor script you can make the FrameChecker look like this:

Any feedback or questions? Let me know in the comments!

If you enjoyed the post, remember to check the Patreon!

You can also follow Strangewire on Twitter.