StartCoroutine starts a coroutine.
The execution of coroutine can be paused at any point using the yield statement. The yield return value specifies when coroutine is resumed. Coroutines are excellent when modeling behavior over several frames. Coroutines have virtually no performance overhead. The StartCoroutine() function always returns a value immediately; therefore, you can yield the result. This will wait until coroutine has finished execution.
Tip
When using JavaScript, it is not necessary to use StartCoroutine; the compiler will do this for you. However, when writing C# code, you must call StartCoroutine. (For more details, refer to Appendix C, Major Differences Between C# and Unity JavaScript.)
In the following example, we will show how to invoke a coroutine and continue executing the function in parallel:
// JavaScript user: function Start() { // Starting = 0.0 Debug.Log ("Starting = " + Time.time); // StartCoroutine WaitAndPrint (In JavaScript, you can also useWaitAndPrint(5.0) which will get the same result. StartCoroutine(WaitAndPrint(5.0)); // Before WaitAndPrint = 5.0 Debug.Log ("Before WaitAndPrint = " + Time.time); } function WaitAndPrint(waitTime : float) { //Suspend execution for 5 seconds yield WaitForSeconds(waitTime); // WaitAndPrint = 5.0 Debug.Log ("WaitAndPrint = " + Time.time); } // C# user: void Start() { // Starting = 0.0 Debug.Log ("Starting = " + Time.time); StartCoroutine(WaitAndPrint(5.0f)); // Before WaitAndPrint = 5.0 Debug.Log ("Before WaitAndPrint = " + Time.time); } IEnumerator WaitAndPrint(float waitTime) { //Suspend execution for 5 seconds yield return new WaitForSeconds(waitTime); // WaitAndPrint = 5.0 Debug.Log ("WaitAndPrint = " + Time.time); }
The following example will wait until the WaitAndPrint() function has finished its execution and then continue executing the rest of the code in the Start() function:
// JavaScript user: function Start() { // Starting = 0.0 Debug.Log ("Starting = " + Time.time); // StartCoroutine WaitAndPrint (In JavaScript, you can also useyield WaitAndPrint(5.0) which will get the same result. yield StartCoroutine(WaitAndPrint(5.0)); // Done WaitAndPrint = 5.0 Debug.Log ("Done WaitAndPrint = " + Time.time); } function WaitAndPrint(waitTime : float) { //Suspend execution for 5 seconds yield WaitForSeconds(waitTime); // WaitAndPrint = 5.0 Debug.Log ("WaitAndPrint = " + Time.time); } // C# user: IEnumerator Start() { // Starting = 0.0 Debug.Log ("Starting = " + Time.time); yield return StartCoroutine(WaitAndPrint(5.0f)); // Done WaitAndPrint = 5.0 Debug.Log ("Done WaitAndPrint = " + Time.time); } IEnumerator WaitAndPrint(float waitTime) { //Suspend execution for 5 seconds yield return new WaitForSeconds(waitTime); // WaitAndPrint = 5.0 Debug.Log ("WaitAndPrint = " + Time.time); }
In most cases, you want to use the StartCoroutine variation at the start of a code. However, StartCoroutine using a string method name allows you to use StopCoroutine with a specific method name.
Tip
The downside is that the string version has a higher runtime overhead to start coroutine, and you can pass only one parameter.
In the following example, we will see how to invoke coroutine using a string name and stop it:
// JavaScript user: function Start() { // Start Coroutine DoSomething StartCoroutine("DoSomething", 5.0); // Wait for 2 seconds yield WaitForSeconds(2.0); // Stop Coroutine DoSomething StopCoroutine("DoSomething"); } function DoSomething (someParameter : float) { while (true) { // DoSomething Loop Debug.Log ("DoSomething Loop = " + Time.time); // Yield execution of this coroutine and return to the main loop until next frame yield; } } // C# user: IEnumerator Start() { // Start Coroutine DoSomething StartCoroutine("DoSomething", 5.0f); // Wait for 2 seconds yield return new WaitForSeconds(2.0f); // Stop Coroutine DoSomething StopCoroutine("DoSomething"); } IEnumerator DoSomething (float someParameter) { while (true) { // DoSomething Loop Debug.Log ("DoSomething Loop = " + Time.time); // Yield execution of this coroutine and return to the main loop until next frame yield return null; } }