Coroutines

Big Ideas:

  • Every command and function in Unity needs to essentially run to completion in a single Update() call (a single frame).
  • A coroutine is a simple way to create a separate thread, that can use wait times.
  • This is a great way to do something like:
    • Spawn an enemy every X seconds
    • Fire a projectile every X seconds
    • Create a procedural animation that does something like blink a sign on and off.


In a little more detail: A coroutine actually runs its code in a single frame or Update() call until it hits a "yield return" statement. The "yield return" statement gives control back to Unity, and the value you return is how much time should pass before Unity comes back to your coroutine.

Important Information:


1. Include Library - You need to include the "using System.Collections;" library at that top. Coroutines come from this standard C# library.


2. Create a Coroutine - To create your own coroutine, you simply create your own method/function with a return type of "IEnumerator"


3. Start the Coroutine - You start a coroutine in one of two ways. The first one, in which you pass in the string name of the coroutine, is the one most commonly seen in tutorials online. The second method accomplishes the same thing, but lets you pass input parameters to your coroutine.


4. Wait Times - To create a wait time, you use the command "yield return new WaitForSeconds(float time)" like in the code below. You can also create the new WaitForSeconds object once and reuse it if the time interval is not changing.

5. Keep it Looping - There are two main ways to keep the Coroutine running - loops or recursion. You can either create some sort of loop such as "while (true)" or at the end of the coroutine you can simply tell the coroutine to start again. Be careful - read #6 about how you need a "yield return" statement in your loop, otherwise a "while (true)" loop will freeze your game.

6. All in a Single Update() - Coroutines actually take control from Unity and execute in a single frame. If, for example you create a for loop to run 1000 times, it will run all 1000 iterations of the loop in a single Update() frame and display the end result without showing any in between progress.

... instead

If you want to see progress of your loop, or if you want to have a forever loop such as "while (true)", then you need to return control to Unity. You need to use any "yield return" command. If you don't want to wait for any amount of time, use "yield return null" to give control back to Unity and let it run "Update()" again before moving on.

Complete Example

Here is an example of spawning an enemy prefab every 1 second.

Another Way to Look at Coroutines (Thanks to Josh Cai)

Coroutines

Some Great Resources:

Website Tutorials

"Mastering Coroutines in Unity in 10mins" - A website tutorial from May 2018, created by Rudra Gesota. The tutorial walks you through much of the same basics as above but with different wording and examples.


Unity Official Materials:

YouTube Video Literally Spawning Enemy Objects Every 1 Second

"Spawning Objects in Unity [Using Instantiate]" (10min, Sep 2018) by PressStart. A quick video that goes over how to bring in a sprite (asteroid), create a prefab, spawn these asteroids every 1 second and have them travel through the screen and destroy when they exit the screen.


YouTube Videos

"How to Coroutine in Unity" (6min, Apr 2018) by SpeedTutor. A super quick overview of coroutines. Solid intro.

"USING A COROUTINE IN C#..." (7.5min, Oct 2018) by JimmyVegas. A quick and easy intro, where he doesn't go into any hardcore detail.

"Coroutines In Unity - What Are Coroutines And How To Use Them" (18min, July 2018) by AwesomeTuts. This is a deeper dive that goes into how to manipulate coroutines while they are running.