SetID feature for tweens and sequences

[Krykutay]

With DoTween, I like to orginize my tweens and sequences with an ID whenever I'm calling one, usually as int, and call DoTween.Kill(id) when I need to kill all tweens with the given ID.

Currently, with PrimeTween, I've found to kill/stop tweens only with specific target which is usually the unity object. I could add PrimeTween to my project without hesitate if there was a way to set tweens' and sequences' ids then be able to stop those specific ones on demand so long as this id resets on stop and complete.

I'd really appreciate this feature if you could manage to add it.

[KyryloKuzyk]

You're right, there is currently no SetID() API in PrimeTween. I thought about this API for a long time and didn't find good use cases for it.

For the majority of use cases, people use SetID() to stop tweens before destroying objects. But with PrimeTween, you don't have to think about stopping tweens before destroying objects or unloading a scene.

The suggested way to stop tweens/sequences in PrimeTween is to store the Tween/Sequence reference and call the .Stop() method on it. For example, I found these two extensive usages of SetID() on GitHub (1, 2), and in both cases, SetID() can be easily replaced by storing the Sequence reference, then calling sequence.Stop().

If you have a good real-world example of SetID() usage, please share it with me. I'm all for adding new features and APIs, but I'd like to understand first if the benefits outweigh the added complexity.

[Krykutay]

Sure thing!

In a nutshell, let's say I'm not destroying my objects and simply disabling those by using object pooling. Since objects are not destroyed but disabled, I need to manually check every single tween and stop those on the objects disable, and sometimes I need to do their complete calls in which case I use .Complete() instead of .Stop().

If you do need a real world example, let's think of this case.

Let's say in my game players can proceed to level 3 from level 2 as soon as level 2 is completed, and all the objects are pooled rather than destroyed and instatiated. In this case, I have to manually control every single tween's Stop() and Complete() case on their OnDisable(). Sometimes these tweens are not played on MonoBehaviours, thus someone else needs to control their tweens (like particles). On DoTween, what I usually do is I tag the tween by giving it an ID which is unique for level 2, and when player proceeds to level 3, I simply call DoTween.Kill(myLevelId) and all my desired tweens are killed whether with their complete call or not.

I hope I managed to explain the situation well. Oh by the way, I'm not talking about the id parameter on ReusableTween.cs, let's say I'm talking about a new field that carries the link id.

Thanks for giving it a thought o/

[KyryloKuzyk]

Thanks for the great example!

While I see the benefits of using SetID() in this particular case, this example is also possible with PrimeTween. And, in my opinion, not using SetID() even leads to a simpler and more maintainable code.

You mentioned that tweens may be running on non-MonoBehaviour targets, on ParticleSystem, for example. To start the animation, you already have a reference to the ParticleSystem, so stopping all tweens on it is as simple as calling Tween.StopAll(particleSystem). The same goes for other animations: your poolable object already has all references to things it animates, so it's possible to stop all children's animations in one place, in the ResetAfterReturnToPool() method, for example.

I composed two examples to prove my point. The PoolableObjectPrimeTween.cs script is much simpler to understand and maintain. The ResetAfterReturnToPool() method has more lines of code, sure, especially when you have a lot of animations. But it's much easier to reason about which tweens should be stopped and which ones should be completed. And the code that starts the animations is much simpler because you don't have to write additional SetID() calls.

Another benefit of not using SetID() is that your poolable object is responsible for resetting all its animations: the LevelManager knows nothing about how to reset pooled objects, and the pooled objects know nothing about the LevelManager. Such decoupling is almost always good in real projects.

PoolableObjectDOTween.cs (click to expand)

using DG.Tweening;
using UnityEngine;

public class PoolableObjectDOTween : MonoBehaviour {
    [SerializeField] ParticleSystem particleSystem;
    [SerializeField] Transform childObject;
    [SerializeField] Transform childUIElement;
    const int tweenIdOffsetToMarkTweenForCompletion = 10000;

    public void AnimateParticles() {
        particleSystem.transform.DOLocalMoveY(10, 1f)
            .SetId(LevelManager.currentLevelIndex);
    }

    public void AnimateChildObject() {
        childObject.DOLocalRotate(new Vector3(90, 0, 0), 1f)
            .SetId(LevelManager.currentLevelIndex + tweenIdOffsetToMarkTweenForCompletion);
    }

    public void AnimateUIElement() {
        childUIElement.DOLocalRotate(new Vector3(90, 0, 0), 1f)
            .SetLoops(-1)
            .SetId(LevelManager.currentLevelIndex + tweenIdOffsetToMarkTweenForCompletion);
    }
    
    public void ResetAfterReturnToPool() {
        DOTween.Kill(LevelManager.currentLevelIndex);
        DOTween.Kill(LevelManager.currentLevelIndex + tweenIdOffsetToMarkTweenForCompletion, true);
    }
}

PoolableObjectPrimeTween.cs (click to expand)

using PrimeTween;
using UnityEngine;

public class PoolableObjectPrimeTween : MonoBehaviour {
    [SerializeField] ParticleSystem particleSystem;
    [SerializeField] Transform childObject;
    [SerializeField] Transform childUIElement;

    public void AnimateParticles() {
        Tween.LocalPositionY(particleSystem.transform, 10, 1f);
    }

    public void AnimateChildObject() {
        Tween.LocalRotation(childObject, new Vector3(90, 0, 0), 1f);
    }

    public void AnimateUIElement() {
        Tween.LocalRotation(childUIElement, new Vector3(90, 0, 0), 1f, cycles: -1);
    }
    
    public void ResetAfterReturnToPool() {
        Tween.StopAll(particleSystem);
        Tween.CompleteAll(childObject);
        Tween.CompleteAll(childUIElement);
        // This method will become bigger with more animations added, but the code is simpler and more straightforward
        // Tween.StopAll(tweenTarget1);
        // Tween.StopAll(tweenTarget2);
        // Tween.StopAll(tweenTarget3);
    }
}

[Krykutay]

Thanks for explaining your point of view in depth :)

I understand the key benefits on the logic, and avoiding the decoupling with LevelManager is I believe the best outcome, then again, I'd still like it if there was a way to access all my tweens with a shared "tag" let's call it rather than their non-shared objects.

In my observations on the source code, I think this addition would almost be cost-free. Let this be my request alone, though if there happens to be more of this request, I hope you do reconsider it!

Thanks again for hearing me out and writing this amazing allocation free package :)
I wish you have success

[KyryloKuzyk]

In my observations on the source code, I think this addition would almost be cost-free.

This is true, adding this feature is relatively easy. My main concern here is that with every added feature, the library becomes more complicated and less accessible for new users.

Let this be my request alone, though if there happens to be more of this request, I hope you do reconsider it!

Yes, I'll consider adding SetId() in the future if there will be more demand for it. I will also think about other alternatives, and maybe I'll come up with some other solution to this problem.

[KyryloKuzyk]

Just came up with a quick TweenIds class that's independent of PrimeTween, but provides almost identical functionality to the built-in SetId() method. It's not as memory efficient as the built-in solution would be but still is zero-allocating if you provide big enough tweensCapacity and sequencesCapacity. What do you think?

TweenIds.cs (click to expand)

using System.Collections.Generic;
using JetBrains.Annotations;
using PrimeTween;

public class TweenIds {
    readonly List<Tween> tweens;
    readonly List<Sequence> sequences;
    
    public TweenIds(int tweensCapacity = 0, int sequencesCapacity = 0) {
        tweens = new List<Tween>(tweensCapacity);
        sequences = new List<Sequence>(sequencesCapacity);
    }
    
    internal void Add(Tween tween) {
        var i = tweens.FindIndex(t => !t.isAlive);
        if (i != -1) {
            tweens[i] = tween;
        } else {
            tweens.Add(tween);
        }
    }

    internal void Add(Sequence sequence) {
        var i = sequences.FindIndex(s => !s.isAlive);
        if (i != -1) {
            sequences[i] = sequence;
        } else {
            sequences.Add(sequence);
        }
    }

    public void StopAll() {
        foreach (var tween in tweens) {
            tween.Stop();
        }
        foreach (var sequence in sequences) {
            sequence.Stop();
        }
    }

    public void CompleteAll() {
        foreach (var tween in tweens) {
            tween.Complete();
        }
        foreach (var sequence in sequences) {
            sequence.Complete();
        }
    }
}

public static class TweenIdsExtensions {
    public static void SetId(this Tween tween, [NotNull] TweenIds ids) {
        ids.Add(tween);
    }

    public static void SetId(this Sequence sequence, [NotNull] TweenIds ids) {
        ids.Add(sequence);
    }
}

The usage:

PoolableObjectPrimeTween.cs (click to expand)

using PrimeTween;
using UnityEngine;

public class PoolableObjectPrimeTween : MonoBehaviour {
    [SerializeField] ParticleSystem particleSystem;
    [SerializeField] Transform childObject;
    [SerializeField] Transform childUIElement;
    readonly TweenIds tweenIdsToStop = new TweenIds(); // TweenIds fields can be global, so they are shared between all pooled objects
    readonly TweenIds tweenIdsToComplete = new TweenIds();

    public void AnimateParticles() {
        Tween.LocalPositionY(particleSystem.transform, 10, 1f)
            .SetId(tweenIdsToStop);
    }

    public void AnimateChildObject() {
        Tween.LocalRotation(childObject, new Vector3(90, 0, 0), 1f)
            .SetId(tweenIdsToComplete);
    }

    public void AnimateUIElement() {
        Tween.LocalRotation(childUIElement, new Vector3(90, 0, 0), 1f, cycles: -1)
            .SetId(tweenIdsToComplete);
    }
    
    public void ResetAfterReturnToPool() {
        tweenIdsToStop.StopAll();
        tweenIdsToComplete.CompleteAll();
    }
}