Overview: Coroutines & Yield Manual     Reference     Scripting  
Scripting
Overview: Coroutines & Yield
Previous: Instantiate Next: Using C# & Boo

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

JavaScript 
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.

JavaScript 
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 Example() {
        while (true) {
            yield return null;
            yield return null;
        }
    }
}
import UnityEngine
import System.Collections

class example(MonoBehaviour):

    def Example() 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.

JavaScript 
// do something
yield WaitForSeconds(5.0); // wait for 5 seconds
// do something more...
using UnityEngine;
using System.Collections;

public class example : MonoBehaviour {
    IEnumerator Example() {
        yield return new WaitForSeconds(5.0F);
    }
}
import UnityEngine
import System.Collections

class example(MonoBehaviour):

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

You can both stack and chain coroutines.

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

JavaScript 
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 Example() {
        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 Example():
        Do()
        print('This is printed immediately')

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

JavaScript 
// 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 Example() {
        yield return StartCoroutine("Do");
        print("Also after 2 seconds");
        print("This is after the Do coroutine has finished execution");
    }
}
import UnityEngine
import System.Collections

class example(MonoBehaviour):

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

    def Example() as IEnumerator:
        yield 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# & Boo