Coroutines and building a Coroutine Que

Intro

In unity I have found myself using coroutines methods like Destory(gameobject, delay), and Move(gameobject, movetime) quite often, today I took the time to understand how they really work.

A coroutine is like a function that has the ability to pause execution and return control to Unity but then to continue where it left off on the following frame. I highly recommend reading entire documentation on Coroutines here before continuing.

Outline

To understand what a coroutine really is it is important to understand two things

	public IEnumerator HeyBaby() // 1 what is a IEnumerator
	{
	yield return null; // 2 what is a yield statment
	}

view raw i.cs hosted with ❤ by GitHub

Enumerators

A coroutine is similar to a foreach statement in that they are both enumerators! A foreach stament, while loop, and a coroutine are all enumerators. The following code blocks are equivalent.

	foreach (Foo bar in baz)
	{
	…
	}
	IEnumerator bat = baz.GetEnumerator();
	while (bat.MoveNext())
	{
	bar = (Foo)bat.Current
	…
	}

view raw i.cs hosted with ❤ by GitHub

By “functionally equivalent,” I mean that’s actually what the compiler turns the code into. You can’t use foreach on baz in this example unless baz implements IEnumerable.

Adding Foreach to your own class

I started with learning how you can turn any class into a enumerator. That’s right! You can write your very own class that will allow you to call foreach on it, as long as it implements IEnumerable.

This helped me a lot to cement my understanding of how the magic really happens with foreach etc.

To implement IEnumerable you have to have 1 method in your class which is called getIEnumerator. And the IEnumerator class must implement 2 methods bringing the total to 3. They are as follows.

IEnumerator GetEnumerator()

bool MoveNext()

Object Current()

If you want to read and understand this even better the full explanation of the IEnumerable class is here

Yield

Understanding what a yield statement does is also essential to understanding coroutines. Understanding yields is quite cool and very useful. Lets start with an example of when a yield would be helpful. This First a code block just has a function which returns the Fibonacci Sequence then prints it out. It doesn’t use a yield statement. You will probably have to look at this code awhile before it sinks in.

	static List<int> GenerateFibonacciNumbers(int n)
	{
	List<int> myList = new List<int>();
	for (int i = 0, j = 0, k = 1; i < n; i++)
	{
	myList.Add(j);
	int temp = j + k;
	j = k;
	k = temp;
	}
	return myList;
	}
	public static void Main(String[] args)
	{
	List<int> myOuterList = GenerateFibonacciNumbers(5);
	foreach (int x in myOuterList)
	{
	Console.WriteLine(x);
	}
	}

view raw fib.cs hosted with ❤ by GitHub

Here we need to create two lists, and iterate through each of them. This might seem ok to you, but using a yield statement it can be done better. Here is what it looks like

	static IEnumberable<int> GenerateFibonacciNumbers(int n)
	{
	List<int> myList = new List<int>();
	for (int i = 0, j = 0, k = 1; i < n; i++)
	{
	yield return j;
	int temp = j + k;
	j = k;
	k = temp;
	}
	return myList;
	}
	public static void Main(String[] args)
	{
	foreach (int x in GenerateFibonacciNumbers(5))
	{
	Console.WriteLine(x);
	}
	}

view raw fibIenum.cs hosted with ❤ by GitHub

So to explain the yield code above a little better.

• Step 1:- Caller calls the function to iterate through the Fibbonacce sequence.

• Step 2:- Inside the function the for loop runs until it reaches the yield return. The “yield” keyword sends this data back to the caller.

Step 3:- Caller displays the value on the console and re-enters the function for more data. It reenters the function right after the yield return, and then executes the j = k; and k = temp;. It has also remembered all their values from before! Then it reaches the end of the loop and starts again, calling the next yield. The iteration continues further as usual.

Yes this actually works! A yield keyword can do these iterations with the need of creating a extra “temporaty collection”. Note that the control is returned to the caller each time the “yield return” statement is encountered and executed. Most importantly, with each such call, the callee’s state information is preserved so that execution can continue immediately after the yield statement when the control returns. If you want a detailed explanation of why this is cool at a slower pace you can look at the original explanation here or here. 

Coroutine Que

In many cases I have created terrible bugs with coroutines being called from different objects that conflict with each other. Say for example I called a move coroutine from a player object, in the move coroutine if I took damage, I would call the delete coroutine from a board manager object. If the delete coroutine finished before the move coroutine then I would get all kinds of weird errors because the object being moved was deleted. This might not be the best example, but problems like this can be easily solved with a Coroutine Que. This Coroutine Que is based on one from the Udemy class “How to make a card battle system”. It’s very simple. It only allows one coroutine to run at a time. After the coroutine is done, it sends a message back to the Que, and the next coroutine is started. Of course in some cases it is altogether better to avoid using coroutines and just called these methods in update or fixed update.

	using UnityEngine;
	using System.Collections;
	using System.Collections.Generic;
	public class Command
	{
	public static Queue<Command> CommandQueue = new Queue<Command>();
	public static bool playingQueue = false;
	public virtual void AddToQueue()
	{
	CommandQueue.Enqueue(this);
	if (!playingQueue)
	PlayFirstCommandFromQueue();
	}
	public virtual void StartCommandExecution()
	{
	// list of everything that we have to do with this command (move, delete, show a message, show a effect, etc…)
	// there are 2 options of timing :
	// 1) use tween sequences and call CommandExecutionComplete in OnComplete()
	// 2) use coroutines (IEnumerator) and WaitFor… to introduce delays, call CommandExecutionComplete() in the end of coroutine
	}
	public static void CommandExecutionComplete()
	{
	if (CommandQueue.Count > 0)
	PlayFirstCommandFromQueue();
	else
	playingQueue = false;
	if (TurnManager.Instance.whoseTurn != null)
	TurnManager.Instance.whoseTurn.HighlightPlayableCards();
	}
	public static void PlayFirstCommandFromQueue()
	{
	playingQueue = true;
	CommandQueue.Dequeue().StartCommandExecution();
	}
	}

view raw Command.cs hosted with ❤ by GitHub

	using UnityEngine;
	using System.Collections;
	public class MoveCommand : Command {
	public override void StartCommandExecution()
	{
	Debug.Log("Play Move Coroutine");
	// AFTER COROUTINE IS DONE THEN CALL
	CommandExecutionComplete();
	}
	}

view raw MoveCommand.cs hosted with ❤ by GitHub

	// how to add method to que
	// que starts playing automatically.
	new MoveCommand.AddToQueue();

view raw gamemanager.cs hosted with ❤ by GitHub