Tutorial de scripts para Unity 3d

StartCoroutine:

function StartCoroutine (routine : IEnumerator) : Coroutine


Antes de entrar a analizar esta función quisiera explicar aunque fuera de forma superficial lo que es una corutina y cómo son tratadas por Unity.

Una corutina es una función -que individualizamos con la palabra clave yield- que puede suspender su ejecución hasta que una instruction dada -que también contendrá la palabra clave yield- termine. Veámoslo con un ejemplo sacado del manual de referencia de Unity:

//Imprime Starting 0.0

print ("Starting " + Time.time);

/* Se llama a continuación a la función WaitAndPrint como coroutine, cosa que se 
consigue anteponiendo la palabra clave yield. Al hacer esto permitimos que la 
función se pueda suspender por una instrucción yield. Por lo tanto, el flujo del 
script se va a la función waitandprint, donde se encuentra con una instrucción yield
que le dice que espere cinco segundos, luego imprimirá “WaitandPrint 5.0 (que será 
el tiempo transcurrido desde el inicio del cómputo) y volverá arriba para  imprimir 
“done 5.0” (o un número cercano).*/

yield WaitAndPrint();
print ("Done " + Time.time);

function WaitAndPrint () {
// suspende la ejecución por 5 segundos
yield WaitForSeconds (5);
print ("WaitAndPrint "+ Time.time);
}

Si no veis clara la diferencia con el proceso secuencial habitual, no tenéis más que borrar la palabra yield que está antes de la llamada a la función. Si hacéis eso, el programa empezará escribiendo "starting 0", bajará a la siguiente instrucción, donde se encuentra con la función WaitAndPrint, que le indica que no va a hacer nada durante cinco segundos, así que pasará inmediatamente a la siguiente declaración e imprimirá "Done 0", para luego, cinco segundos después, imprimir por fin "Waitandprint 5".


Bien. Con estas nociones vamos ya a la función que nos ocupa, StartCoroutine. Como su nombre indica, inicia una corrutina cuya ejecución puede ser pausada en cualquier momento usando una instrucción yield.

Programando en javascript, no es necesario escribir StartCoroutine, ya que el compilador la dará por supuesta.

Veamos un segundo ejemplo sacado igualmente del manual de referencia de Unity. En este ejemplo, a diferencia del anterior, vamos a invocar una corrutina que no suspenderá la ejecución de la función que se desarrolla en paralelo:

function Start() {
// - Después de 0 segundos imprimirá "Starting 0.0"
// - Después de 0 segundos, imprimirá "Before WaitAndPrint Finishes 0.0"
// - Después de 2 segundos imprimirá "WaitAndPrint 2.0"
 
//Empezamos (función Start) imprimiendo “Starting 0.0”

print ("Starting " + Time.time);

/* Ahora vamos a iniciar la función WaitAndPrint como coroutine (en paralelo), pero
sin suspender el flujo de llamadas a funciones que se puedan seguir dando en el hilo
principal. Si hubiéramos querido suspenderlo, hubiéramos utilizado la fórmula del 
ejemplo anterior, y hubiéramos antepuesto la palabra clave yield a la llamada a la
función. 
Lo que sigue podría también haberse escrito (en javascript) así:
  WaitAndPrint(2.0) 
y el compilador añadiría el StartCoroutine por ti automáticamente.*/

StartCoroutine(WaitAndPrint(2.0)); 

/*Como no hemos interrumpido el flujo principal con yield, la declaración que  viene 
ahora se ejecutará antes que la la función anterior, puesto que la anterior ha de 
esperar dos segundos y el print que viene ahora no.*/

print ("Before WaitAndPrint Finishes " + Time.time);
}

function WaitAndPrint (waitTime : float) {
// suspende la ejecución por los segundos que le fijemos en waitTime 
yield WaitForSeconds (waitTime);
print ("WaitAndPrint "+ Time.time);
}

La función StartCoroutine tiene una segunda modalidad:

function StartCoroutine (methodName : String, value : object = null) : Coroutine


Es como la función anterior, pero usando un string. Esta variante tiene una mayor sobrecarga de procesamiento, pero es la única que se puede detener con StopCoroutine.

Vamos a realizar otro ejemplo en el que , aparte de usar la variante con string de la función, aprovecharemos para ilustrar de nuevo otra posibilidad que nos dan este tipo de instrucciones Yield. El script ejecuta la función DoSomething, que dispara un bucle. Al siguiente frame el script se detendrá un segundo al toparse con la instrucción yield, pasará al yielf waitforseconds, esperará un segundo y luego se detendrá.

 
function Start () {
 
  StartCoroutine("DoSomething", 2.0);

  yield WaitForSeconds(1);

  StopCoroutine("DoSomething");
}

function DoSomething (someParameter : float) {
  while (true) {
       print("DoSomething Loop");

// Detiene la ejecución de esta corutina y vuelve al loop principal hasta el 
//siguiente frame. 

 yield;
 }
}

StopCoroutine:

function StopCoroutine (methodName : String) : void


Como hemos visto en el ejemplo anterior, detiene las corrutinas con el nombre que le suministramos como parámetro iniciadas en este script. Dicho nombre de función lo hemos de pasar como un string, y no hemos de olvidar que sólo las corrutinas con el nombre indicado que se hayan iniciado mediante la variante string de StartCoroutine (la segunda modalidad de las anteriormente vistas) podrán ser detenidas con StopCoroutine.


StopAllCoroutines:

function StopAllCoroutines () : void


Detiene todas las corrutinas que estén corriendo en ese script.