Unity Script Reference – Overview: Coroutines & Yield

Overview: Coroutines & Yield

Previous: Instantiate Next: Using C#

When writing game code, one often ends up needing to script a sequence of events. This could result in code like the following.

JavaScripts

private var state = 0;

function Update() {
if (state == 0) {
// do step 0
state = 1;
return;
}
if (state == 1) {
// do step 1
state = 2;
return;
}
// ...
}

using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
private int state = 0;
void Update() {
if (state == 0) {
state = 1;
return;
}
if (state == 1) {
state = 2;
return;
}
}
}

import UnityEngine
import System.Collections

class example(MonoBehaviour):

private state as int = 0

def Update():
if state == 0:
state = 1
return
if state == 1:
state = 2
return

It is often more convenient to use the yield statement. The yield statement is a special kind of return, that ensures that the function will continue from the line after the yield statement next time it is called.

JavaScripts

while(true) {
// do step 0
yield; // wait for one frame
// do step 1
yield; // wait for one frame
// ...
}

using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
IEnumerator Awake() {
while (true) {
yield return null;
yield return null;
}
}
}

import UnityEngine
import System.Collections

class example(MonoBehaviour):

def Awake() as IEnumerator:
while true:
yield
yield

You can also pass special values to the yield statement to delay the execution of the Update function until a certain event has occurred.

JavaScripts

// do something
yield WaitForSeconds(5.0); // wait for 5 seconds
// do something more...

using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
IEnumerator Awake() {
yield return new WaitForSeconds(5.0F);
}
}

import UnityEngine
import System.Collections

class example(MonoBehaviour):

def Awake() as IEnumerator:
yield WaitForSeconds(5.0F)

You can both stack and chain coroutines.

This example will execute Do but continue after calling do immediately.

JavaScripts

Do ();
print ("This is printed immediately");

function Do () {
print("Do now");

yield WaitForSeconds (2);

print("Do 2 seconds later");
}

using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
IEnumerator Do() {
print("Do now");
yield return new WaitForSeconds(2);
print("Do 2 seconds later");
}
void Awake() {
Do();
print("This is printed immediately");
}
}

import UnityEngine
import System.Collections

class example(MonoBehaviour):

def Do() as IEnumerator:
print('Do now')
yield WaitForSeconds(2)
print('Do 2 seconds later')

def Awake():
Do()
print('This is printed immediately')

This example will execute Do and wait until it is finished before continuing its own execution

JavaScripts

// chain the coroutine

yield StartCoroutine("Do");
print("Also after 2 seconds");

print ("This is after the Do coroutine has finished execution");

function Do () {
print("Do now");

yield WaitForSeconds (2);

print("Do 2 seconds later");
}

using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
IEnumerator Do() {
print("Do now");
yield return new WaitForSeconds(2);
print("Do 2 seconds later");
}
IEnumerator Awake() {
yield return StartCoroutine("Do");
print("Also after 2 seconds");
print("This is after the Do coroutine has finished execution");
}
}

Any event handler can also be a coroutine.

Note that you can't use yield from within Update or FixedUpdate, but you can use StartCoroutine to start a function that can.

See YieldInstruction, WaitForSeconds, WaitForFixedUpdate, Coroutine and MonoBehaviour.StartCoroutine for more information on using yield.

Previous: Instantiate Next: Using C#