📝 Lesson 3.3: Coroutines and Async in Unity

Why You Can't Just Sleep

Your instinct from console C# might be: "wait 3 seconds" = Thread.Sleep(3000). In Unity that freezes the entire game. Remember from Lesson 1.2 that Unity runs your code on one main thread, calling Update each frame. Blocking that thread means no rendering, no input, no anything — a frozen window for 3 seconds.

void Update()
{
    if (triggered)
    {
        Thread.Sleep(3000);   // ❌ freezes the whole game for 3 seconds
        OpenDoor();
    }
}

You need a way to say "pause this task for 3 seconds, but keep the game running." That's exactly what a coroutine does: it lets a method give control back to Unity, then pick up where it left off later.

💡 Connection to Intermediate C#: a coroutine is literally a C# iterator — the IEnumerator/yield return feature you saw for lazy sequences. Unity repurposes it: each yield hands a value back to the engine that says "resume me when this condition is met."

Coroutine Basics

Three pieces: the method returns IEnumerator, it uses yield return to pause, and you launch it with StartCoroutine.

using System.Collections;   // IEnumerator lives here
using UnityEngine;

public class Door : MonoBehaviour
{
    void Start()
    {
        StartCoroutine(OpenAfterDelay());   // launch the coroutine
    }

    private IEnumerator OpenAfterDelay()
    {
        Debug.Log("Waiting...");
        yield return new WaitForSeconds(3f);   // pause HERE for 3 seconds, game keeps running
        Debug.Log("Opening!");                 // resumes here 3 seconds later
        Open();
    }

    private void Open() => transform.Translate(Vector3.up * 3f);
}

⚠️ Important: StartCoroutine is a MonoBehaviour method, and coroutines are tied to the MonoBehaviour that starts them. Start it on the component that "owns" the task. You can keep the returned Coroutine handle to stop it later.

The Yield Instructions

What you yield return decides when the coroutine resumes. The essential set:

A per-frame example — a smooth fade over one second using yield return null:

private IEnumerator FadeOut(CanvasGroup group, float duration)
{
    float elapsed = 0f;
    while (elapsed < duration)
    {
        elapsed += Time.deltaTime;                 // count up each frame
        group.alpha = 1f - (elapsed / duration);   // 1 → 0
        yield return null;                          // wait one frame, then loop
    }
    group.alpha = 0f;   // ensure exact final value
}

Common Patterns

Coroutines shine wherever something unfolds over time. Three you'll reuse constantly:

Timed sequence

Do a series of steps with pauses between — a cutscene, a tutorial, a countdown:

private IEnumerator StartRound()
{
    ui.Show("Ready");
    yield return new WaitForSeconds(1f);
    ui.Show("Set");
    yield return new WaitForSeconds(1f);
    ui.Show("Go!");
    yield return new WaitForSeconds(0.5f);
    ui.Hide();
    BeginPlay();
}

Spawn waves

Repeat an action on an interval (with the cached-wait optimization):

[SerializeField] private Enemy enemyPrefab;
[SerializeField] private float interval = 2f;

private IEnumerator SpawnWaves()
{
    var wait = new WaitForSeconds(interval);   // cache — don't allocate per loop
    while (true)                               // runs until the object is disabled/destroyed
    {
        Instantiate(enemyPrefab, transform.position, Quaternion.identity);
        yield return wait;
    }
}

Wait for a condition

private IEnumerator WaitForLoad()
{
    yield return new WaitUntil(() => assetLoader.IsReady);
    Debug.Log("Loaded — continue.");
}

Stopping & Lifecycle Gotchas

Coroutines are tied to the MonoBehaviour that started them, which leads to important rules:

private Coroutine spawner;

void OnEnable()  => spawner = StartCoroutine(SpawnWaves());
void OnDisable() => StopCoroutine(spawner);   // tidy stop; also happens automatically

// Stop by handle is precise; StopAllCoroutines() stops every coroutine on this component.

💡 Starting by method name: you can also StartCoroutine("SpawnWaves") with a string, which lets StopCoroutine("SpawnWaves") stop it by name — but the string form is slower and typo-prone. Prefer starting with the method call and stopping via the returned Coroutine handle.

Coroutines vs async/await

C# has its own way to write code that waits without blocking: async/await (Intermediate C#). It works in Unity too, and Unity 6 adds Awaitable to make it first-class. So when do you use which?

using UnityEngine;

public class Door : MonoBehaviour
{
    // Unity 6's Awaitable makes async play nicely with the frame loop.
    private async void Start()
    {
        Debug.Log("Waiting...");
        await Awaitable.WaitForSecondsAsync(3f);   // non-blocking, resumes on main thread
        Debug.Log("Opening!");
        transform.Translate(Vector3.up * 3f);
    }
}

Exercise & Quiz

using System.Collections;
using UnityEngine;

public class Door : MonoBehaviour
{
    [SerializeField] private float openHeight = 3f;
    [SerializeField] private float moveDuration = 1f;

    void Start() => StartCoroutine(OpenSequence());

    private IEnumerator OpenSequence()
    {
        // TODO: count down 3..2..1 (WaitForSeconds), then smoothly raise the door.
        yield return null;
    }
}

using System.Collections;
using UnityEngine;

public class Door : MonoBehaviour
{
    [SerializeField] private float openHeight = 3f;
    [SerializeField] private float moveDuration = 1f;

    void Start() => StartCoroutine(OpenSequence());

    private IEnumerator OpenSequence()
    {
        var oneSecond = new WaitForSeconds(1f);   // cached, no per-loop allocation

        for (int i = 3; i > 0; i--)
        {
            Debug.Log(i);
            yield return oneSecond;
        }
        Debug.Log("Opening!");

        Vector3 start = transform.position;
        Vector3 end = start + Vector3.up * openHeight;
        float elapsed = 0f;

        while (elapsed < moveDuration)
        {
            elapsed += Time.deltaTime;
            transform.position = Vector3.Lerp(start, end, elapsed / moveDuration);
            yield return null;                    // one frame; smooth over moveDuration
        }
        transform.position = end;                 // snap to exact final position
    }
}

Summary

📚 Additional Resources

• Manual — Coroutines
• Scripting Reference — StartCoroutine
• Scripting Reference — Awaitable (Unity 6)
• Manual — Asynchronous programming with Awaitable

🚀 What's Next?

That completes Module 3 — Structuring Game Code: data assets, decoupled events, and time-based logic. Module 4 builds the systems that hold a whole game together. Lesson 4.1, Game State and Managers, covers singletons, scene management, and the central controllers that coordinate everything you've built.