Unity Coroutines

When you call a function, it runs to completion before returning.This effectively means that any action taking place in a functionmust happen within a single frame update; a function call can't beused to contain a procedural animation or a sequence of events overtime. As an example, consider the task of gradually reducing anobject's alpha (opacity) value until it becomes completelyinvisible.

void Fade() {        for (float f = 1f; f >= 0; f -= 0.1f) {                Color c = renderer.material.color;                c.alpha = f;                renderer.material.color = c;        }}

As it stands, the Fade function will not have the effect you mightexpect. In order for the fading to be visible, the alpha must bereduced over a sequence of frames to show the intermediate valuesbeing rendered. However, the function will execute in its entiretywithin a single frame update. The intermediate values will never beseen and the object will disappear instantly.

It is possible to handle situations like this by adding code to theUpdate function that executes the fade on a frame-by-frame basis.However, it is often more convenient to use a coroutine for thiskind of task.

A coroutine is like a function that has the ability to pauseexecution and return control to Unity but then to continue where itleft off on the following frame. In C#, a coroutine is declaredlike this:-

IEnumerator Fade() {        for (float f = 1f; f >= 0; f -= 0.1f) {                Color c = renderer.material.color;                c.alpha = f;                renderer.material.color = c;                yield return;        }}

It is essentially a function declared with a return type ofIEnumerator and with the yield return statement included somewherein the body. The yield return line is the point at which executionwill pause and be resumed the following frame. To set a coroutinerunning, you need to use the StartCoroutine function:-

void Update() {        if (Input.GetKeyDown("f")) {                StartCoroutine("Fade");        }}

In UnityScript, things are slightly simpler. Any function thatincludes the yield statement is understood to be a coroutine andthe IEnumerator return type need not be explicitly declared:-

function Fade() {        for (var f = 1.0; f <= 0; f -= 0.1) {                var c = renderer.material.color;                c.alpha = f;                renderer.material.color = c;                yield;        }}

Also, a coroutine can be started in UnityScript by calling it as ifit were a normal function:-

function Update() {        if (Input.GetKeyDown("f")) {                Fade();        }}

You will notice that the loop counter in the Fade functionmaintains its correct value over the lifetime of the coroutine. Infact any variable or parameter will be correctly preserved betweenyields.

By default, a coroutine is resumed on the frame after it yields butit is also possible to introduce a time delayusing WaitForSeconds:-

IEnumerator Fade() {        for (float f = 1f; f <= 0; f -= 0.1f) {                Color c = renderer.material.color;                c.alpha = f;                renderer.material.color = c;                yield return new WaitForSeconds(.1f);        }}

...on in UnityScript

function Fade() {        for (var f = 1.0; f <= 0; f -= 0.1) {                var c = renderer.material.color;                c.alpha = f;                renderer.material.color = c;                yield WaitForSeconds(0.1);        }}

This can be used as a way to spread an effect over a period timebut it is also a useful optimization. Many tasks in a game need tobe carried out periodically and the most obvious way to do this isto include them in the Update function. However, this function willtypically be called many times per second. When a task doesn't needto be repeated quite so frequently, you can put it in a coroutineto get an update regularly but not every single frame. An exampleof this might be an alarm that warns the player if an enemy isnearby. The code might look something like this:-

function ProximityCheck() {        for (int i = 0; i < enemies.Length; i++) {                if (Vector3.Distance(transform.position, enemies[i].transform.position) < dangerDistance) {                                return true;                }        }        return false;}

If there are a lot of enemies then calling this function everyframe might introduce a significant overhead. However, you coulduse a coroutine to call it every tenth of a second:-

IEnumerator DoCheck() {        for(;;) {                ProximityCheck;                yield return new WaitForSeconds(.1f);        }}

This would greatly reduce the number of checks carried out withoutany noticeable effect on gameplay.