A Game Design Tip a Day #8 – [Unity C#] Coroutines (Part 1)

Unity has a cool feature (I’m not a nerd at all) that lets you run a function over various frames without using some clunky method that’s difficult to write and long as hell. Coroutines are special kinds of method that, together with the yield keyword, can be used to suspend the execution of one call to a function temporarily – this allows it to run over several frames. Well, they’re much more complex than that, but I’ll be going into more detail in another tip at some later date. One great thing about coroutines is that they’re run in the same thread as all your other MonoBehaviour stuff (like Start or Update), so there’s no problems to worry about with regards to messing with the same variable in both Update and a coroutine, for example. They also have minimal overhead while providing huge amounts of functionality.

Coroutines in C# have a return type of IEnumerator:


This coroutine does… absolutely nothing at all, but it’s just here to show you the basic structure of one. Firstly, every coroutine needs a yield statement somewhere in it, or else it will fail to run. In this example, yield return null will cause the coroutine to wait until just after the next Update() method is called. Coroutines also need to be called in a special way – we use the StartCoroutine() method, which has many overloads:


The three uses of StartCoroutine in the Start method are all valid ways of calling a coroutine. For coroutines that have more than one parameter, you’ll want to use the third version. There’s also a StopCoroutine(“MyCoroutineName”) method that can be used on any coroutine that was called using one of the string-based StartCoroutine functions, which will tell a coroutine to cease execution forever. Like coroutine murder, with less blood. Unfortunately, that does mean that any coroutines that have more than one parameter can’t be stopped in this way.

There are many other kinds of yield statements you can use, too. Rather than always using yield return null and just waiting for the next Update frame to finish, there’s tons of other yield statements in your coroutine goodie bag:


Some of these are very interesting (to reiterate, I’m definitely not a nerd). I’ve listed many of their effects above, and they’re all pretty straightforward. I’ve never really used WWW before, so I can’t claim to know how they work in much detail, but it seems they wait until some WWW download has finished before doing what yield return null does. The next one, yield return StartCoroutine(SomeCoroutine(someParameter)) is an extremely useful coroutine feature that suspends this current coroutine until another one has finished execution. I can even put a similar statement in the second one to wait for a third coroutine – this is called coroutine chaining. Just be careful that you don’t create a circular chain of coroutines that call each other, or things will get very ugly very quickly. You’ll want to be careful when some of these because they run in a specific order – for example, a WaitForSeconds always runs before a WWW. Consult Unity’s Execution Order of Event Functions manual page for more info – the diagram at the bottom of the page should be ingrained in your memory by now.

I’ll be wrapping up some other coroutine features in another tip some day, but for now I’ll leave you guys to play around with these ones.