PrimeTween for basic 2D sprite animations?

[wundev]

Hi, is PrimeTween a good choice for animating 2D sprites (keyframing different sprites)? I'm currently using a Sprite Renderer + Animator + Animancer Component, which seems like overkill for a basic sprite animation.

[KyryloKuzyk]

Hey!

Although there is no built-in support for this, it's absolutely possible to use PrimeTween for simple sprite animations. Here is a simple script:

using System;
using PrimeTween;
using UnityEngine;
using UnityEngine.Assertions;

[Serializable]
public class SpriteAnimation {
    [SerializeField] SpriteRenderer spriteRenderer;
    [SerializeField] Sprite[] sprites;
    [SerializeField] TweenSettings settings = new TweenSettings(1f, Ease.Linear, cycles: -1);
    int curIndex = -1;

    public Tween Play() {
        Assert.IsNotNull(spriteRenderer, nameof(spriteRenderer) + " reference is not populated in Inspector.");
        Assert.IsTrue(sprites != null && sprites.Length > 0, "Sprites array is empty.");
        curIndex = -1;
        tween.Stop();
        tween = Tween.Custom(this, 0f, sprites.Length, settings, static (_this, val) => {
            int newIndex = (int)val;
            var _sprites = _this.sprites;
            if (newIndex < _sprites.Length && _this.curIndex != newIndex) {
                _this.curIndex = newIndex;
                _this.spriteRenderer.sprite = _sprites[newIndex];
            }
        });
        return tween;
    }

    public Tween tween { get; private set; }
    public bool isAlive => tween.isAlive;
    public void Stop() => tween.Stop();
}

Usage example:

using UnityEngine;

public class SpriteAnimationExample : MonoBehaviour {
    [SerializeField] SpriteAnimation idleAnimation;
    [SerializeField] SpriteAnimation walkAnimation;
    [SerializeField] SpriteAnimation jumpAnimation;
    SpriteAnimation currentAnimation;

    void Update() {
        if (jumpAnimation.isAlive) {
            return;
        }
        if (Input.GetKeyDown(KeyCode.Space)) {
            SetCurrentAnimation(jumpAnimation);
            jumpAnimation.tween.OnComplete(() => print("jump completed"));
            return;
        }
        if (Input.GetKey(KeyCode.RightArrow)) {
            SetCurrentAnimation(walkAnimation);
        } else {
            SetCurrentAnimation(idleAnimation);
        }
    }

    void SetCurrentAnimation(SpriteAnimation animation) {
        if (currentAnimation == animation) {
            return;
        }
        currentAnimation?.Stop();
        animation.Play();
        currentAnimation = animation;
    }
}

I used this free 2D Character Sprite Animation - Penguin asset to test this and here is the result:
https://github.com/KyryloKuzyk/PrimeTween/assets/13222270/da45ea3f-9c2b-4812-b1d6-4485fed30305

[wundev]

Thank you for the example code. I modified it to use ScriptableObjects to hold each group of sprites per animation, and the Component Names asset to organize the different sprite animations. https://i.gyazo.com/1ac7a0fde5e816c0c586a3557bc5cc02.png

using System;
using PrimeTween;
using Sisus.ComponentNames;
using UnityEngine;
using UnityEngine.Assertions;

[Serializable]
public class SpriteAnimation: MonoBehaviour {
  [SerializeField] private SpriteRenderer _renderer;
  [SerializeField] private SO_CharacterSpriteSet _sprite_set;
  [SerializeField] private bool _is_flip_x;
  [SerializeField] private float TIME_PER_FRAME = 0.1f;
  [SerializeField] private TweenSettings _settings = new TweenSettings(999, Ease.Linear, cycles: -1);
  private Tween _tween;
  private int _cur_idx = -1;

  public Tween Play() {
    Assert.IsNotNull(_renderer, nameof(_renderer) + " SpriteRenderer not found.");
    Assert.IsTrue( _sprite_set.sprites != null && _sprite_set.sprites.Length > 0, "Sprites[] is empty.");
    Reset();
    _settings.duration = TIME_PER_FRAME *  _sprite_set.sprites.Length;
    return Tween.Custom(this, 0,  _sprite_set.sprites.Length, _settings, (_this, next_idx) => _this.UpdateSprites((int)next_idx));
  }
  
  public void Stop() => _tween.Stop();

  private void UpdateSprites(int next_idx) {
    if (next_idx <  _sprite_set.sprites.Length && _cur_idx != next_idx) {
      _cur_idx = next_idx;
      _renderer.sprite =  _sprite_set.sprites[_cur_idx];
    }
  }

  private void Reset() {
    Stop();
    _cur_idx = -1;
  }

  private void OnValidate() {
    gameObject.GetComponentInParentOrChildren<SpriteRenderer>(ref _renderer);
    string name =  _sprite_set.action + " " + (_is_flip_x ? _sprite_set.flipped_x_direction : _sprite_set.direction);
    this.SetName(name);
  }
}

using UnityEngine;

[CreateAssetMenu(menuName = "ScriptableObject/Animation/SpriteSet", order = 0)]
public class SO_SpriteSet : ScriptableObject {
  public Sprite[] sprites;

using UnityEngine;

public enum CharacterAnimationAction {
  Idle,
  Move,
  Attack,
  Heal,
  Taunt,
  Block,
  Flinch,
  Dazed,
  Die,
}

public enum Direction {
  Up,
  Down,
  Left,
  Right,
  UpLeft,
  UpRight,
  DownLeft,
  DownRight,
}

[CreateAssetMenu(menuName = "ScriptableObject/Animation/CharacterSpriteSet", order = 0)]
public class SO_CharacterSpriteSet : SO_SpriteSet {
  [Header("Informational Labels")]
  public CharacterAnimationAction action;
  public Direction direction;
  
  /// <summary>
  ///  Returns the flipped direction of a right-facing sprite.
  /// </summary>
  /// <returns></returns>
  public Direction flipped_x_direction {
    get {
      if (direction == Direction.Right) {
        return Direction.Left;
      } else if (direction == Direction.UpRight) {
        return Direction.UpLeft;
      } else if (direction == Direction.DownRight) {
        return Direction.DownLeft;
      }
    
      return Direction.Right;
    }
  }
}

I have not tested the performance yet to compare it against the Unity Animator. But with the Unity Animator, I was seeing ~2 ms spent each frame on animation (https://gyazo.com/042d3858cf90eb93937ce7f2232c53ce), and I think PrimeTween would perform much better. I have not yet converted my existing animations to using PrimeTween yet, because I am unsure what will be my workflow for lining up / syncing Collider2D shape animations to sprite animations, but it is on my list of TODOs.

[KyryloKuzyk]

This looks great! Please shake your performance results once you have them. But judging from the code there should not be any performance issues, the code is very straight-forward.

Our of curiosity, why do you use 999 as the default duration? Wouldn't it be more reasonable to use a smaller default value?

[wundev]

Oh the 999 is just a placeholder value I use throughout my code to remind myself that that's not the actual value. The actual value is set in Play by _settings.duration = TIME_PER_FRAME * _sprite_set.sprites.Length;.