12 Mar

DOTween: How to append a tween to a sequence already playing?

I’m using the fantastic DOTween engine for creating and managing tweens on Unity, but the latest version cannot handle a specific case: how to append a tween to a sequence which is already playing? First a bit of background. After completing DragonScales 6, we’re focusing on a new game, a casual Match 3 with a traditional tile swapping gameplay. Our DragonScales games are created with Java and LibGDX. However, this new project will be built on Unity with C#, and we make intensive use of tweens.

In particular, we want the players to be able to keep playing and swapping tiles even if the game is simultaneously processing matches in other areas of the board. When a match is detected, tiles above those matched tiles will fall. We’re implementing this falling path with position tweens, via DOTween. However, new matches in other areas might alter the path of tiles which are already falling. In order to handle such cases we’ll be appending new tweens to the tweens which are already executing. The problem is that sequences in the current version of DOTween must be entirelly defined beforehand, which clearly does not suit our requirements.

Luckily, there’s a sound workaround published by user EvgenL in this pertinent and open DOTween issue. In short: use a queue of sequences. Here’s the class we’re using, completely based on the referred code:

public class TweenChain
{
    public Queue<Sequence> SequenceQueue = new Queue<Sequence>();

    public TweenChain()
    {
        // empty
    }

    public void AddAndPlay(Tween tween)
    {
        // Create a paused DOTween sequence to "wrap" our tween
        var sequence = DG.Tweening.DOTween.Sequence();
        sequence.Pause();
        // "Wrap" the tween
        sequence.Append(tween);
        // Add tween to queue
        SequenceQueue.Enqueue(sequence);
        // If this is the only tween in queue, play it immediately
        if (SequenceQueue.Count == 1)
        {
            SequenceQueue.Peek().Play();
        }
        // When the tween finishes, we'll evaluate the queue
        sequence.OnComplete(OnComplete);
    }

    private void OnComplete()
    {
        // Tween completed. Remove it.
        SequenceQueue.Dequeue();

        // Other tweens awaiting?
        if (SequenceQueue.Count > 0)
        {
            // Play next tween in queue
            SequenceQueue.Peek().Play();
        }
    }

    public bool IsRunning()
    {
        // Are tweens being processed?
        return (SequenceQueue.Count() > 0);
    }

    public void Destroy()
    {
        // Goodbye. Thanks for your hard work.
        foreach (var sequence in SequenceQueue)
        {
            sequence.Kill();
        }
        SequenceQueue.Clear();
    }
}

Hopefully future versions of DOTween will handle this use case in a straightforward fashion. We needed to append a tween to a sequence in execution and, for the time being, this class solves our requirement.