Yielding a nested IEnumerator waits a frame even on break

Unity Engine
1

Firstly - I understand why this behaviour happens, but as it is quite nuanced I do not think it is made especially clear in the documentation. I am not sure what, if anything, can be done to resolve it, but I want to start a discussion about whether this is something that could be dealt with.

The problem is writing “yield return anything” will always wait a frame.

I began this by needing to loop over a collection of objects in a coroutine, each of which have their own IEnumerator method that will optionally run some logic over the course of several frames, but if the condition is not met, will break out immediately with “yield break”.

Every write up I’ve since read about nested coroutines describes the following two means of nesting them as equivalent - this isn’t strictly true.

//First method of nesting
yield return NestedRoutine();

//Second method of nesting
IEnumerator nested = NestedRoutine();
while(nested.MoveNext())
    yield return nested.Current;

For the most part, these are indeed equivalent. They differ, however, in how they handle ‘yield break’.

If in the above code, NestedRoutine is implemented as follows:

private IEnumerator NestedRoutine()
{
   if(!ShouldRun) yield break;

   //Run logic over some frames
}

Then the first means of nesting will wait a single frame before continuing the Coroutine, whereas the second will continue running the parent routine immediately.

When you “yield return” anything other than a YieldInstruction - e.g. null, true, false, 1 etc - Unity will wait a frame before continuing the Coroutine. This remains true even if you return another IEnumerator that itself actually broke rather than returned null.

This is subtly mentioned in the documentation:

By wrapping the yield return statement within a while loop and checking MoveNext(), the second means of nesting works as expected, as when it reaches a break statement, MoveNext() will return false and skip the return entirely.

This is a workaround, but becomes ugly very quickly - every time you need to yield another coroutine, you need to set a local variable and wrap its MoveNext() in a while loop before actually yielding it. This turns a single line of easy to read code into three, and moreover, three lines that can’t be wrapped in a method, because as soon as you ‘yield return’ that method, you will wait a frame.

The first, most commonly used means of nesting, results in any IEnumerator that could ‘break’ if some condition isn’t met, consuming a frame. This isn’t immediately apparent nor intuitive, because writing yield break infers different intent to yield return null, but this intent is lost in the parent loop, where they are both returned and thus evaluated as null.

As such, my only proposition, and I’m unsure whether it’s feasible, would be a YieldInstruction we can return that tells Unity to resume the parent coroutine immediately. Perhaps something like 'YieldResumeImmediate’. I am aware we can implement CustomYieldInstructions, but so far I have been unable to find a way of implementing one such that it never waits - at a minimum, it will always wait a single frame.

Consider the following CustomYieldInstruction:

public class ContinueImmediately : CustomYieldInstruction
{
    public override bool keepWaiting => false;
}

If you were to return this a few times within an IEnumerator and record the frameCount before and after, you will find each return statement waits a frame. With this being the case, I can’t see how a CustomYieldInstruction would be able to continue immediately, unless there’s something I need to override that I’ve been unable to find. If somebody knows how to implement a CustomYieldInstruction such that it will resume the parent method immediately, that would be fantastic. Any thoughts on the matter would be appreciated :slight_smile: Thanks!

2

I would imagine that Unity isn’t looking at what value you yield-returned until the next time that a coroutine could potentially start up, and I imagine there’s an argument from performance for doing it that way (adding those checks would slightly slow things down for all coroutine-users while benefiting only a tiny subset). Not sure how strong that argument is, but it probably exists.

Writing 2 extra lines of boilerplate each time you do an unusual thing does not strike me as terribly onerous. It’s kind of like the issue with value-type getters/setters that stops you from writing transform.position.x = 1;.

You could probably reduce it to 1 extra line with some refactoring; conceptually, check “should run” before you start up the coroutine, rather than inside of it, so your code looks like:

if (NestedRoutineShouldRun) yield return NestedRoutine();
3

I got interested in how Unity’s coroutines were implemented and decided to write my own implementation. This has most of the features that Unity’s coroutines have and it does not have any frame delays when other things than null are yield returned. Unfortunately this does not support Unity’s yield instructions that do not inherit from IEnumerator like WaitForSeconds or WaitForEndOfFrame.

EDIT: I cleaned this up, added documentation and put it to github: GitHub - villevli/UnitySimpleCoroutines: An alternative to Unity's Coroutines with no delay when yielding
I also got rid of the MyYieldInstruction as it seemed unnecessary and using Unity’s CustomYieldInstruction or just IEnumerator works fine.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class MyCoroutine
{
    private Stack<IEnumerator> ienumeratorStack = new Stack<IEnumerator>();
    private MyYieldInstruction currentYieldInstruction = null; // in case a MyYieldInstruction has been yield returned
    private MyCoroutine nestedCoroutine = null; // in case another MyCoroutine has been yield returned
    private int yieldFrame = -1; // in case null has been yield returned

    public bool IsRunning()
    {
        if (yieldFrame == Time.frameCount)
            return true;
        if (ienumeratorStack.Count > 0)
            return true;
        if (currentYieldInstruction != null && currentYieldInstruction.keepWaiting)
            return true;
        if (nestedCoroutine != null && nestedCoroutine.IsRunning())
            return true;
        return false;
    }

    public void Start(IEnumerator routine)
    {
        ienumeratorStack.Clear();
        ienumeratorStack.Push(routine);
        currentYieldInstruction = null;
        nestedCoroutine = null;
        yieldFrame = Time.frameCount - 1;

        Update();
    }

    // Execute a single step of the coroutine. Unity equivalent is the MoveNext you see in coroutine stack traces
    // Returns true if the coroutine should continue running
    public bool Update()
    {
        // this ensures yield return null waits a frame in all situations
        if (yieldFrame == Time.frameCount)
            return true;

        // do not continue with the IEnumerators until the last returned yield instruction returns keepWaiting false
        if (currentYieldInstruction != null && currentYieldInstruction.keepWaiting)
            return true;
        currentYieldInstruction = null;

        // do not continue with the IEnumerators until the last returned MyCoroutine has finished running
        if (nestedCoroutine != null && nestedCoroutine.IsRunning())
            return true;
        nestedCoroutine = null;

        if (ienumeratorStack.Count > 0)
        {
            var ie = ienumeratorStack.Peek(); // the top of the stack is the currently executing IEnumerator
            if (ie.MoveNext()) // execute IEnumerator until next yield (true) or break/end (false)
            {
                // ie.Current is what was yield returned in the IEnumerator
                if (ie.Current is IEnumerator)
                {
                    // move to execute a nested IEnumerator
                    ienumeratorStack.Push(ie.Current as IEnumerator);
                    return Update(); // nested IEnumerator execution is started without frame delay
                }
                if (ie.Current is MyYieldInstruction)
                {
                    currentYieldInstruction = ie.Current as MyYieldInstruction;
                    currentYieldInstruction.Reset();
                }
                if (ie.Current is MyCoroutine)
                {
                    nestedCoroutine = ie.Current as MyCoroutine;
                }
                if (ie.Current == null)
                {
                    // unity likely does this for "unsupported" yield returned objects as well
                    yieldFrame = Time.frameCount;
                }
                // TODO: add logic for custom yieldable objects here
            }
            else
            {
                ienumeratorStack.Pop();
                return Update(); // nested IEnumerator returns without frame delay
            }
            return true;
        }
        else
        {
            return false;
        }
    }
}

// Start and run the coroutines in the player loop
public class MyCoroutineRunner
{
    private List<MyCoroutine> runningCoroutines = new List<MyCoroutine>();

    // Call this as you would call MonoBehaviour.StartCoroutine
    public MyCoroutine StartCoroutine(IEnumerator ie)
    {
        var myCoroutine = new MyCoroutine();
        myCoroutine.Start(ie);
        runningCoroutines.Add(myCoroutine);
        return myCoroutine;
    }

    // Call this each frame (MonoBehaviour.Update)
    public void Update()
    {
        for (int i = runningCoroutines.Count - 1; i >= 0; i--)
        {
            if (!runningCoroutines[i].Update())
                runningCoroutines.RemoveAt(i);
        }
    }
}

public abstract class MyYieldInstruction
{
    public abstract bool keepWaiting { get; }
    public abstract void Reset();
}

public class MyWaitForSeconds : MyYieldInstruction
{
    private float seconds;
    private float waitCompleteTime;

    public MyWaitForSeconds(float seconds)
    {
        this.seconds = seconds;
    }

    public override bool keepWaiting => Time.time < waitCompleteTime;

    public override void Reset()
    {
        waitCompleteTime = Time.time + seconds;
    }
}
4 Likes
4

I’m not sure it would slow it down. The current YieldInstructions allow a coroutine to resume its execution at various points later in the frame or in the next frame (for instance, end of frame, in fixed update etc). If it’s able to delay until the end of the frame, I doubt there’d be any further expense in not delaying at all.

I can see why 2 extra lines doesn’t sound bad, but unlike the value setters, this also cannot be moved to an extension method. If you were to have a coroutine that yields even a few other processes, it can start to get hard to see the wood for the trees, as the important code is cluttered between while loops and the intent becomes less clear.

Take for example a simple pattern where we might apply damage to an entity, that may need to execute some code before it takes damage, and optionally more after. If this sounds contrived, I assure you it is not at all uncommon in cases where entities can be effected by various “statuses” etc, which may or may not run code on certain events.

Naively, you would probably write the following.

private IEnumerator TakeDamage(DamageInfo info)
{
    yield return OnApplyingDamage();

    //Apply the damage

     yield return OnAppliedDamage();
}

But should the damageable not have any logic to run in either of those methods, each will have “eaten” a frame. To correct it, you would have to change it as follows:

private IEnumerator TakeDamage()
{
    IEnumerator e = OnApplyingDamage();
    while(e.MoveNext())
        yield return e.Current;

    //Apply the damage

     e = OnAppliedDamage();
     while(e.MoveNext())
            yield return e.Current;
}

In the first example, I can immediately see the methods that are being called and that we are yielding them. In the second, that is much less clear.

I appreciate a single frame may sound trivial, but imagine the call to TakeDamage() is called as follows:

foreach(IDamageable in damageables)
{
    yield return damageable.TakeDamage(damageInfo);
}

Let’s say you’re dealing damage to 12 damageables, each of which may or may not run code in either OnApplyingDamage or OnAppliedDamage. Let’s say 50% of these calls break out early. This is already bad; 6 frames will have been consumed for no real reason - plenty enough to be felt by the player if those frames delay visual feedback for the code that does run.

You might suggest in this case, if we need to iterate over several elements and care about losing thsoe frames, we should change the implementation. However that is only because of this strange behaviour.

The more I consider this, the more I consider it a bug, or at least an implementation detail that we need a means of working around more cleanly. I would suspect anybody writing yield break is expecting their method to break early and allow any parent loops to continue immediately; not that they’re actually consuming a frame.

Considering, I would suspect, most people would see yield break as analagous to return in a regular void method, i.e immediately breaking with no frame delay, if this cannot be differentiated (in the value of IEnumerator.Current) from null, I think we need a dedicated type we can return to indicate that instead.

Checking the conditional outside of the method first seems like it might reduce the code, but it is both potentially quite a conceptual upheaval and probably won’t reduce code, as every IEnumerator in an object now needs to have a companion method to indicate whether it can run.

The bottom line of this is anybody who nests a coroutine that has an if statement which at some point in the method breaks early is (almost certainly unknowingly) losing a frame.

1 Like
5

This looks interesting! I could probably do fine without the Unity YieldInstructions, the only one I ever tend to use is WaitForSeconds, and even that get’s cached in our own class due to the alleged cost of creating new ones on the fly, so it wouldn’t take much more to just switch to a completely custom system.

6

Say…you’re going to all this trouble to try to avoid an extra delay of 1 frame in the case where the nested coroutine ends early. Are you 100% sure that you don’t also have an extra delay of 1 frame when the nested coroutine doesn’t end early?

I could totally imagine Unity doing something conceptually like:

foreach (var coroutine in coroutines)
{
    if (coroutine is not waiting) coroutine.continue();
}

But if it’s doing that, and you happen to evaluate the “parent” coroutine’s condition before the nested coroutine’s condition, then the parent will have already forfeited its opportunity to run in the current frame by the time the child finishes, so you might get a delay anyway. Have you checked?

It also occurs to me that you could probably take advantage of the fact that coroutines are technically enumerators to run a nested coroutine like this:

foreach (var result in NestedCoroutine())
{
    yield return result;
}

That should solve both problems–you’ll continue running immediately on the frame that the NestedCoroutine ends, regardless of whether that’s now or later, and regardless of how Unity tests the conditions.

Needing to run code before and after taking damage doesn’t sound contrived at all.

But needing to wait for coroutines before and after taking damage sounds pretty contrived. Typical status effects could modify the damage taken or trigger new effects in reaction to it, but “wait a second before applying that damage” isn’t a status effect that I can recall seeing before.

And waiting for target #1 to react to the damage before you apply the same damage packet to target #2 sounds even more contrived. What sort of game are you making where a multi-target attack allows the first target to delay damage to the second target? But not vice-versa?

In my experience coroutines are generally not very useful for gameplay-related stuff because gameplay-related stuff that takes place over a period of time generally wants to be constantly reacting to other stuff that’s happening in parallel, and coroutines are just not a very convenient model for that sort of interactivity.

Using coroutines for animations makes more sense because animations generally aren’t reactive in this way. But by the same token, animations probably don’t need to call stuff like BeforeTakingDamage() because that was already handled at the gameplay layer.

7

Heh, I appreciate it may sound like a waste of effort, but unfortunately there are enough opportunities for these delays to accumulate that whilst it doesn’t hang the game, it delays some logic that triggers visual feedback such that a player would notice it. In my case I can avoid it with the while loop method I initially outlined, but it started me on a curiosity rabbit hole and now I’m beginning to question anywhere I’ve ever yielded a coroutine that can return early.

Yes that will also consume a frame, because a coroutine that contains some form of yield statement earlier in its body doesn’t need to explicitly declare yield break afterward - it is implied - similarly to the use of return in a regular void method. However, no frames are consumed if every coroutine is yielded via the while(e.MoveNext()) wrapper, which is the significant difference between the implementations.

This looks like it would be a good solution, but I’m unsure exactly how it would work. Neither a plain IEnumerator nor an actual Coroutine can be iterated in a foreach like that. Coroutines inherit YieldInstruction, which may be handled via iterators internally but I don’t know how I would access it. Am I missing something?

I appreciate that might seem contrived, alas it’s not. Ours is probably a more uncommon case - we’re working on a deckbuilder where several characters can each have status effects, with wildly varying behaviour.

Take for instance a scenario where a character has a status effect that draws the player a card whenever that character takes damage. Then another character gets buffed whenever a card is drawn. If the first character is part of a multi-target attack, you may want the card-drawing effect to trigger before the next target is dealt damage. This likely means waiting for the card to visually finish the drawing animation, and then in turn trigger the second character’s status afterwards. (I won’t get into a discussion around the specifics of this order, queueing such scenarious, or how you might handle a recursive relationship, as these are unique design decisions we’ve discussed internally at length that are somewhat tangential here).

Furthermore, the code needs to be paced across time for the player to be able to follow the chain of events.This could probably be handled with callbacks, but the code is far easier to follow if it’s executed within coroutines - (or, I suppose for the sake of specificity, IEnumerators, as I only tend to have a single coroutine at the root of the chain) - as they clearly communicate a chronological sequence in a very parsable way that doesn’t jump all over the project.

We also have tooling in place that allows the construction of these graphs by a non-coder, which would make callbacks harder still.

I would normally agree, however in this case the gameplay is quite tightly bound to a “boardgamey” rhythm where the order of events is crucial, and isn’t executing in parallel with other systems.

The above aside, I don’t want to get too bogged down in the specifics of our project - my initial post was much more generally about whether nested coroutines that break early should be expected to consume a frame, regardless of the consequence of a single frame in most projects. It seems like a non-trivial detail that isn’t very clearly documented to me, and one you would likely choose to avoid should there be a trivial way of doing so.

8

I don’t normally iterate IEnumerators directly, but there’s obviously a way to do it, and you could easily write a helper function that lets you treat it as an IEnumerable if you prefer that syntax.

I’m the lead programmer for 2 published digital board games made in Unity. Neither uses coroutines in this way.

Sounds like you have no separation between between the model and the view, and therefore find yourself encoding your animation rules into your gameplay logic. Seems like a mistake to me, but hey, it’s your project. Best of luck.

1 Like
9

That reads a little terse, so if I’ve in any way offended you I apologise. I would like to defend that we do have that separation, but that defence would stray away from the purpose of this thread. I don’t wish to dismiss your advice though, so will send you a PM you can freely ignore if you wish :slight_smile:

EDIT: Ah, it appears I can’t. That’s a shame, I’m all ears for hearing different, better approaches, I just don’t think this thread is the venue for it. Have a nice day anyway

10

I do not agree with that, we use it all the time for gameplay and similar. For example here I drive the finger IK using user input

https://www.youtube.com/watch?v=W5U_dE2TpBU

1 Like
11

Very nice work villevli !

I encountered this problem lately, unability to nest IEnumerator without having them to “yield frames”.

Instead of having to deal with “runner” and its manual update(), what do you think of making an extension which will create a Unity coroutine which will execute the Update() automatically.

So you only have to do :

myMonoBehaviourClass.StartSCoroutine(mySCoroutine);

public static class SCoroutineExtensionClass
{
    static IEnumerator SCoroutineWrapper(IEnumerator ieCoroutine)
    {
        SimpleCoroutines.SCoroutineRunner runner = new SimpleCoroutines.SCoroutineRunner();
        runner.StartCoroutine(ieCoroutine);
        while (runner.Update())
        {
            yield return null;
        }
    }

    public static void StartSCoroutine(this MonoBehaviour comp, IEnumerator ie)
    {
        comp.StartCoroutine(SCoroutineWrapper(ie));
    }
}

To stop the Unity Coroutine when the SCoroutine is done :

public class SCoroutineRunner
{
    [...]

    public bool Update()
    {
        for (int i = runningCoroutines.Count - 1; i >= 0; i--)
        {
            if (!runningCoroutines[i].Update())
                runningCoroutines.RemoveAt(i);
        }

        return runningCoroutines.Count > 0;
    }
}

Seems to work as expected, but I need to test it more thoroughly.

In the case anyone tries and what to call it from inside your monobehaviour class, you need to use “this” keyword :

this.StartSCoroutine(mySCoroutine);

Maybe it could be something to add to your repos !
Thank you !

12

Just to help people out with the problem that this solves, since there’s a ton of noise in this thread.

You are experiencing an issue of the form

  • You call a coroutine SomeCoroutine from another coroutine using yield return SomeCoroutine() or yield return StartCoroutine(SomeCoroutine()).
  • Observe that even if SomeCoroutine does nothing (such as by yield break 'ing), Unity will resume execution next frame. It should instead continue executing “in the same frame” i.e. without interruption.
IEnumerator SomeCoroutine() {
  yield break;
}

If you want to call SomeCoroutine from another coroutine and not lose a frame, replace:

yield return SomeCoroutine();

with

var childCoroutine = SomeCoroutine();
while (childCoroutine.MoveNext()) {
  yield return childCoroutine.Current;
}

wherever you are doing (instead of) yield return SomeCoroutine();

5 Likes