Feature request: Tween.Delay(numberOfFrames)

[floky]

Although not obvious at first sight, it would be highly useful for various custom scenarios to have a Tween.Delay that waits for a number of frames instead of a duration in seconds.
Is this possible to easily add with the current API?

[octia]

The amount of times I wanted a delay of ONE frame but primetween complained when I tried to put in a delay value of "0.001" or something, is too damn high.

Or even zero frames. Sometimes I define the delay from the inspector - and sometimes, in that inspector I put in 0, and I wish it to be zero. It's annoying to do checks around that.

It's not as useful for actual animations (since different PCs have different framerates), but a delay of a few frames can be helpful during initialization steps sometimes. UI in my game isn't initialized for 2 frames after the scene loads, for example - and while I wouldn't use this feature to work around that specifically, I can see the appeal.

[floky]

@octia I feel you! ✌️😅
@KyryloKuzyk what do you think?
I would gladly make an extra donation just for this feature. ✌️

[KyryloKuzyk]

@floky Hey, thanks for the suggestion! I thought about this problem a lot, but I don't have a good solution.

The issue is that PrimeTween uses duration in many places in its API. For example, these Tween/Sequence properties depend on duration: progress, progressTotal, elapsedTime, elapsedTimeTotal, duration, durationTotal. Using numberOfFrame instead of duration would break all of these properties, as they will no longer make sense because the duration of a frame is unknown.

Additionally, if a Sequence has any frame-based tween in it, then using Chain() will no longer be possible. Again, because the duration of the future frames is unknown at this point.

To address @octia concern with zero-duration tweens, you can disable the warning with PrimeTweenConfig.warnZeroDuration = false;.

To address the unknown duration problem and to allow waiting on custom user-specifid events, I thought about having a new concept in PrimeTween, something like Waiter. It's just an idea at this point, and it probably deserves its own product independenf ot PrimeTween. But its API can look something like this:

Waiter waiter = Waiter.DelayFrames(numOfFrames: 5)
    .Chain(Waiter.WaitWhile(enemy => enemy.isAlive))
    .ChainDelay(1f)
    .ChainCallback(() => print("done"));
//...
if (waiter.isAlive) {
    waiter.Cancel();
}

[floky]

Yep, I thought about it a bit also and it is indeed tricky. Basically we end up thinking of a high performance and allocation free replacement for Unity's coroutine yield instructions for waiting one or more frames or waiting for the end of a frame, etc. 🙈

To be fair, usually having the need to wait for a specific number of frames should first trigger an architectural alarm in the app/game needing it.
But there are exceptions to the rule indeed where your would need to schedule something to happen the next frame or even easily split a longer queue of operations in multiple future frames and optionally have a callback for when that long queue has finally finished without using jobs or threads due to other complexities involved.

Like you said @KyryloKuzyk, it seems a problem for a totally separate system with maybe some possible intersections here and there with PrimeTween through various extension methods.

In the meantime, workarounds using traditional helper coroutines that wait for one or more frames and then optionally call a callback can work just fine for initialization purposes and chaining with other systems/libs like PrimeTween:

    public static class CoroutinesExt
    {
        public static IEnumerator Ext_StartDelayCoroutine<T>(this MonoBehaviour thisBehaviour, int numFramesDelay, T targetObject = default, Action<T> onComplete = null)
        {
            if (thisBehaviour == null)
            {
                Debug.LogWarning("MonoBehaviour is null. Cannot start coroutine. Ignoring...");
                return null;
            }

            Debug.Assert(numFramesDelay >= 0, $"{nameof(numFramesDelay)} must be non-negative.");
            if (numFramesDelay == 0)
            {
                onComplete?.Invoke(targetObject);
                return null;
            }

            IEnumerator coroutineEnumerator = DelayCoroutine(numFramesDelay, targetObject, onComplete);
            thisBehaviour.StartCoroutine(coroutineEnumerator);

            return coroutineEnumerator;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static void Ext_StopCoroutine(this MonoBehaviour thisBehaviour, IEnumerator originalCoroutineEnumerator)
        {
            if (thisBehaviour != null && originalCoroutineEnumerator != null)
                thisBehaviour.StopCoroutine(originalCoroutineEnumerator);
        }

        private static IEnumerator DelayCoroutine<T>(int numFrames, T targetObject = default, Action<T> onComplete = null)
        {
            for (int i = 0; i < numFrames; i++)
                yield return null;

            onComplete?.Invoke(targetObject);
        }
    }

But this approach will still allocate some memory by the engine when starting a coroutine. But using it only in some initialization situations should do the trick for now.

I think this issue can be closed.