[Proposal] Sequence support

[AnnulusGames]

I'm currently considering adding the Sequence feature to LitMotion, and would like to get your opinions on it.

The current API proposal is as follows. SequencePlayMode can be specified as Sequential or Parallel, and Sequential uses async/await using ValueTask internally.

I made a few changes from the first draft. SequencePlayMode is removed and all sequences are executed sequentially. However, you can also use AppendGroup() to add groups of motions to run in parallel.

using UnityEngine;
using LitMotion;
using LitMotion.Extensions;
using LitMotion.Sequences;

public class SequenceSandbox : MonoBehaviour
{
    [SerializeField] Transform target1;
    [SerializeField] Transform target2;
    [SerializeField] Transform target3;

    MotionSequence sequence;

    void Start()
    {
        sequence = MotionSequence.CreateBuilder()
            .Append(() => LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target1))
            .Append(() => LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target2))
            .Append(() => LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target3))
            .AppendGroup(motions =>
            {
                motions.Add(LMotion.Create(-2f, 2f, 1f).WithLoops(3, LoopType.Yoyo).BindToPositionX(target1));
                motions.Add(LMotion.Create(-2f, 2f, 1f).WithLoops(2, LoopType.Yoyo).BindToPositionX(target2));
                motions.Add(LMotion.Create(-2f, 2f, 1f).BindToPositionX(target3));
            })
            .Build()
            .AddTo(this);
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space) && !sequence.IsPlaying())
        {
            sequence.Play();
        }

        if (Input.GetKeyDown(KeyCode.A) && sequence.IsPlaying())
        {
            sequence.Complete();
        }

        if (Input.GetKeyDown(KeyCode.Z) && sequence.IsPlaying())
        {
            sequence.Cancel();
        }
    }
}

[AnnulusGames]

My initial opinion when implementing LitMotion was that asynchronous processing should be left to async/await and Rx, and that tweens should not have functions like sequences.

However, when creating a composite animation, I ran into a problem where it was difficult to perform operations such as complete all at once using CompositeMotionHandles alone. Therefore, I think it is necessary to provide a new class to handle complex motions.

The MotionSequence proposed this time is just a class for integrating multiple motions, and its functionality is limited (it is likely that the functionality of the code above will be almost all). Also, in other libraries, there are many APIs that allow adding tweens after creating a sequence (or causing a runtime error), but MotionSequence is created using a dedicated builder, so basically It is immutable.

[AnnulusGames]

Also, this feature will not be included in the regular package, but will be distributed as a separate package (LitMotion.Sequences). Therefore, you can install it as needed.

[Akeit0]

MotionSequence.CurrentHandle will be useful to change PlayBackSpeed.
(BTW, I don't like the naming of the Play "Back" Speed.)

[AnnulusGames]

Since MotionSequence supports parallel playback, it may be difficult to determine the current handle. However, PlaybackSpeed support may be required.
I'm not a native English speaker, so I don't know the detailed nuances of naming, but I understand that PlaybackSpeed is a word commonly used to express the playback speed of media. It would be appropriate as a name.

[Akeit0]

I am not a native speaker either, but I am not comfortable with the usage of playback as it is used for records.
playbackは記録に対して使われるものなのでやはりtweenでは違和感がありますね、、

DOTween uses timescale.
Godot uses speed_scale.

[AnnulusGames]

Well... in any case, it seems difficult to change the naming as it would be a breaking change. If so, the naming of MotionSequence should also follow MotionHandle.

[Akeit0]

Sorry for saying something that makes no sense to say.

[AnnulusGames]

No problem. Thank you for your feedback.

[YuliyF]

Can I add delay between Appends - ?

[AnnulusGames]

It is certainly necessary. I will also add AppendDelay() before releasing this feature.

[Akeit0]

Although allocations occur, they could be reproduced in an easy to write coroutine-like form.
SeqYieldPoint is a simple struct with only a version.

IEnumerable<SeqYieldPoint> SequenceFunc(SeqCoroutine s)
{
    yield return s.Wait(LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target1));
    yield return s.Wait(LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target2));
    yield return s.Wait(LMotion.Create(0f, 180f, 1f).BindToEulerAnglesZ(target3));

    Debug.Log(s.IsPlaying() ? "Is Playing" : "Force Complete");

    yield return s.Wait(stackalloc MotionHandle[]
    {
        LMotion.Create(-2f, 2f, 1f).WithLoops(3, LoopType.Yoyo).BindToPositionY(target1),
        LMotion.Create(-2f, 2f, 1f).WithLoops(2, LoopType.Yoyo).BindToPositionY(target2),
        LMotion.Create(-2f, 2f, 1f).BindToPositionY(target3)
    });
}

sequence = new SeqCoroutine(SequenceFunc);

[AnnulusGames]

Honestly, I don't think this API is necessary. Creating a sequence with Append() or waiting inside a coroutine with ToYieldInteraction() as usual would be sufficient.

[Akeit0]

If the IMotionSequenceItem can configure more than once, it would be easy to incorporate this.
And this multiple configuration allows Sequence in Sequence too.

[Akeit0]

public interface IMotionSequenceItem
{
    bool Configure(MotionSequenceItemBuilder builder);
    void Reset(){}
}

[AnnulusGames]

This functionality is too complex to include in a sequence. MotionSequence should only support simple concatenation, anything more should be left to async/await and Rx.

[Akeit0]

OK.

[mic-code]

Hi, After trying LitMotion and I came here from the unity forum thread
I had a problem when using LitMotion for UI animation
I wanted to animate a simple left to right animation for a toggle, which need to play the animation in reverse when the toggle is turned off.
I can make first MotionBuilder with left to right, then a second MotionBuild from right to left.
But it's two definition which is crumblesome.
And there's a problem when the user click the toggle mid way playing the animation.
The toggle will abruptly start from the other animation, unless I do something like making a new MotionBuilder with starting position mid way, and calculate the duration from the current position.

If there's a simple way I missed, please enlighten me.
I am under the impression that MotionSequence should be perfect for this use case.
But need to be able to play the sequence reverse at anytime.

[AnnulusGames]

MotionSequence is a mechanism for lazily evaluating motion creation, which is very different from that of DOTween. It is difficult to support complex stop and play, so it may not be suitable for your use case. Additionally, LitMotion in its current state does not have the functionality to meet this requirement.

As an alternative, I'm considering adding an API to manipulate playtime based on your PR. There are a few things to consider, but this is probably achievable.

[AnnulusGames]

#122

[AnnulusGames]

We added new Sequence features in #158, so this discussion is closed.