Stop the nested (inner/child) tween when the parent Sequence isAlive.

[flo-wolf]

I noticed that this simple snippet produces errors when CreateWrappingSequence() is called again while the Sequence still runs:

private Sequence _innerSequence;

public void CreateWrappingSequence()
{
    Sequence wrappingSequence = Sequence.Create();
    wrappingSequence.Chain(GetInnerSequence());
}

private Sequence GetInnerSequence()
{
    if (_innerSequence.isAlive)
    {
        _innerSequence.Stop();
        Debug.Log("Stopping inner sequence that still runs");
    }

    Sequence innerSequence = Sequence.Create();

    // some tween that runs for three seconds
    innerSequence.Chain(Tween.Custom(0, 1, 3, (t) => { }));

    _innerSequence = innerSequence;
    return innerSequence;
}

The following error appears for the Sequence innerSequence = Sequence.Create() line:

When a tween or sequence is added to another sequence, they become 'nested', and manipulating them directly is no longer allowed.
Use Stop()/Complete()/isPaused/timeScale/elapsedTime/etc. of their parent Sequence instead.

When I remove the _innerSequence = innerSequence; line, the error disappears. Why is this the case? _innerSequence is a value type, and the creation of a new Sequence should not be a problem here. I should be able to just stop the current sequence and create a new one here.

Why am I even stopping the sequence? Because I want to prevent callbacks from being executed from the ongoing sequence (the code above is just a test-case to showcase the problem, my actual use case is more complex)

[KyryloKuzyk]

Hey Florian,

Not allowing to manipulate nested (inner) tweens and sequences is a design decision. PrimeTween logs an error when you try to call any method or change any property of the nested animation. In your case the error comes from _innerSequence.Stop();, not from the _innerSequence = innerSequence; assignment.

The reasoning behind this decision was the following: sequence is a logical union of all its nested animations that act as a whole. When you add an animation to the parent sequence, this animation becomes dependent on the parent sequence, meaning that it no longer updates itself directly. Instead, the parent sequence takes control over all its nested animations and it's no longer allowed to manipulate them directly.

In your case, you probably want to store the _wrappingSequence and stop it if it's still running when the CreateWrappingSequence() is called:

Sequence _wrappingSequence;

public void CreateWrappingSequence() {
    if (_wrappingSequence.isAlive) {
        _wrappingSequence.Stop();
    }
    _wrappingSequence = Sequence.Create().Chain(GetInnerSequence());
}

Few other thoughts on this design decision:

1. It makes it easy to reason about the sequence as one logical union: you combine multiple animations into the parent sequence because they are closely connected and should act together. If you want to separate those animations in any way after they're combined into one parent sequence, it's a sign that those animations should be separate.
2. Let's consider the next example:

var t1 = Tween.Position(transform, Vector3.one, duration: 1f);
var t2 = Tween.Rotation(transform, new Vector3(90, 0), duration: 1f);
Sequence.Create(t1).Chain(t2);
t1.Complete();

What should happen after the t1.Complete(); if manipulating nested animation was allowed? Should the sequence immediately jump to the elapsedTime == 1f? Or should we just complete the t1 and the parent sequence should stay at elapsedTime == 0f? Disallowing to manipulate the nested animations removes the ambiguity and makes the code easier to reason about.

3. It doesn't make sense to modify isPaused/timeScale/elapsedTime properties of nested animations because the parent sequence controls those properties. In the same manner, stopping the nested animation should not be allowed for consistency.

[flo-wolf]

Thank you for the thorough explanation, this cleared a lot up for me.

Is it possible to somehow grab the "root sequence" of a Sequence? This way, I could stop the whole sequence some tween might be part of, without actually having to inform my function what the root sequence is I would like to stop

Besides, I believe I used Sequences to much to orchestrate the "sequence" of my gameloop, which is why I often end up with one big parent sequence that then chains child sequences with animations. I might be abusing Sequences here a bit too much and probably should be using Coroutines instead for these higher-level orchestrations. This is also where my need for stopping nested sequences came from - the more complex some sequence gets, the bigger the need to stop certain parts of it when something changes.

[flo-wolf]

@KyryloKuzyk Any news on this?

[KyryloKuzyk]

Hey! I'm sorry for the late reply.

Is it possible to somehow grab the "root sequence" of a Sequence?

Technically yes, it's possible. But my concern for adding such a feature is that it would encourage bad practices which will lead to a convoluted and hard-to-debug code.

In the current design, a sequence can only be created in one place with Sequence.Create(), and if you want to stop the sequence in the future, it's reasonable to store the reference in the class where the sequence was created and call sequence.Stop() on that reference. In some sense, we can call that one place an "owner" of the sequence and if you want to stop the sequence, you should ask its owner to do it.

But if the tween.GetParentSequence() was available, it would break this "owner" paradigm making it harder to reason about the code: it would no longer be obvious from reading the code where the sequence was created.

the more complex some sequence gets, the bigger the need to stop certain parts of it when something changes.

Yes, the idea of splitting this big sequence into smaller ones sounds good.

[flo-wolf]

Thank you for the reply :) In this case I will use Sequences for more granular animations