⏱️ Lesson 1.3: Async & Await in Unity 6 — Awaitable

Coroutines Recap & Their Limits

A quick refresher from Intermediate: a coroutine is a method returning IEnumerator, driven by StartCoroutine, that yields to spread work across frames.

IEnumerator FadeOut()
{
    for (float t = 1f; t > 0f; t -= Time.deltaTime)
        yield return null;              // resume next frame
    yield return new WaitForSeconds(1); // resume after a second
}
// StartCoroutine(FadeOut());

Coroutines are great for simple frame-spread animation. But they hit walls the moment you need more:

• No return value. A coroutine can't hand back a result. Loading data means writing it into a field and hoping the caller checks later.
• Not awaitable / composable. You can't await a coroutine from a normal method, or easily "run these three, then continue." Chaining is clumsy.
• Exceptions are awkward. An exception thrown inside a coroutine doesn't propagate to a caller in a natural try/catch.
• Single-threaded only. A coroutine always runs on the main thread. It can't offload heavy CPU work to a background thread.
• Bound to a MonoBehaviour. StartCoroutine needs a live component; disable it and the coroutine dies quietly.

async/await answers every one of these — if you have an awaitable type the engine understands. That's what Unity 6 added.

Task vs Coroutine vs Awaitable

C# already has async/await built on Task. So why did Unity add a new type instead of telling you to use Task? Because Task is a general-purpose .NET construct that knows nothing about Unity's frame loop or its main-thread rule, and it allocates — every Task is a heap object, which matters when you do this thousands of times (Module 2's garbage lesson will make you care). Awaitable is Unity's answer: an awaitable type wired into the player loop, poolable to avoid allocations, and aware that most engine APIs must run on the main thread.

💡 You can still use Task. Awaitable interoperates — you can await a Task and vice versa, and library APIs that return Task (a web request, a file read) work fine. Reach for Awaitable for engine-timed waits and thread hops; let Task handle genuinely external async I/O.

Meet Awaitable

An async method in Unity 6 returns Awaitable (or Awaitable<T> when it produces a value), and inside it you await the engine-timed operations you used to yield. The mapping from coroutine land is almost one-to-one:

using UnityEngine;

public class Fader : MonoBehaviour
{
    async Awaitable FadeOut()
    {
        for (float t = 1f; t > 0f; t -= Time.deltaTime)
            await Awaitable.NextFrameAsync();        // was: yield return null

        await Awaitable.WaitForSecondsAsync(1f);     // was: yield return new WaitForSeconds(1)
        Debug.Log("Faded.");
    }
}

The everyday awaitables:

• Awaitable.NextFrameAsync() — resume next frame (the yield return null equivalent).
• Awaitable.WaitForSecondsAsync(seconds) — resume after a delay in scaled time.
• Awaitable.EndOfFrameAsync() — resume at end of frame, after rendering.
• Awaitable.FixedUpdateAsync() — resume on the next physics step.

Unlike a coroutine, an async Awaitable<T> can return a value, and the caller can await it in a plain method with normal try/catch. Here's an async loader that returns its result — the shape you'll build the bootstrapper's service init from in Lesson 1.5:

async Awaitable<PlayerData> LoadPlayerAsync()
{
    // Spread parsing across frames so the game doesn't hitch.
    var data = new PlayerData();
    for (int i = 0; i < chunks.Length; i++)
    {
        data.Merge(Parse(chunks[i]));
        await Awaitable.NextFrameAsync();   // yield a frame between chunks
    }
    return data;                            // a coroutine could never do this
}

// Caller — clean, with real exception handling:
async void Start()
{
    try
    {
        PlayerData data = await LoadPlayerAsync();
        Apply(data);
    }
    catch (System.Exception e) { Debug.LogException(e); }
}

Switching Threads

Here's the capability coroutines simply don't have. Nearly all Unity API calls must happen on the main thread — touch a Transform from a worker thread and you get an exception. But pure C# work (parsing, pathfinding math, procedural generation) doesn't need the main thread and shouldn't block it. Awaitable lets you hop across the boundary with two calls:

async Awaitable ProcessAsync()
{
    // ... on the main thread here (safe to touch Unity objects) ...

    await Awaitable.BackgroundThreadAsync();
    // Now on a thread-pool worker: do heavy CPU work, NO Unity API calls.
    var result = CrunchNumbers();

    await Awaitable.MainThreadAsync();
    // Back on the main thread: safe to apply results to the scene.
    transform.position = result;
}

The pattern is: await Awaitable.BackgroundThreadAsync() to leave the main thread for heavy work, then await Awaitable.MainThreadAsync() to return before touching anything in the scene. This is how you keep a 60 FPS main thread while a big computation runs — impossible with coroutines, and cleaner than hand-managed Threads or Task.Run plus a dispatcher.

Cancellation

Async work has a lifetime problem coroutines partly dodge: a coroutine dies with its MonoBehaviour, but an async method keeps running even after the object that started it is destroyed — leading to the dreaded "setting transform on a destroyed object" exception. The fix is cooperative cancellation with a CancellationToken.

Every MonoBehaviour in Unity 6 exposes a destroyCancellationToken that is automatically cancelled when the object is destroyed. Pass it into your awaits and the whole chain unwinds the moment the object goes away:

public class Loader : MonoBehaviour
{
    async Awaitable LoadLevelAsync()
    {
        // Token cancels automatically when THIS object is destroyed.
        CancellationToken token = destroyCancellationToken;

        for (int i = 0; i < steps; i++)
        {
            token.ThrowIfCancellationRequested();      // bail out early if cancelled
            DoStep(i);
            await Awaitable.NextFrameAsync(token);      // await also observes the token
        }
    }
}

Two ways the token protects you: token.ThrowIfCancellationRequested() checks at the top of each iteration, and passing the token into the awaitable (NextFrameAsync(token)) makes the wait itself cancellable. On cancellation the method throws OperationCanceledException, which unwinds it cleanly — you typically let that exception propagate silently (it's expected), or catch it specifically.

For cancellation you trigger yourself (a "cancel loading" button, or timing out a request), create your own source and combine it with the destroy token:

using System.Threading;

private CancellationTokenSource _cts;

void BeginLoad()
{
    // Cancel if EITHER the user cancels OR the object is destroyed.
    _cts = CancellationTokenSource.CreateLinkedTokenSource(destroyCancellationToken);
    _ = RunAsync(_cts.Token);   // fire-and-forget an Awaitable-returning method
}

void CancelLoad() => _cts?.Cancel();

A Frame Timeline

It helps to see where an async method's pieces actually run across frames and threads. Below, a load routine yields a frame, offloads to a worker thread, then hops back to apply results — all without blocking the render loop.

Figure 1: One async load across frames and threads. The method releases the main thread each await (so rendering continues), does its heavy lifting on a worker, and returns to the main thread before touching the scene. A cancellation token unwinds the whole chain if the object is destroyed mid-flight.

💡 Awaits are suspension points. Each await is a spot where the method pauses and gives the frame back to Unity, resuming later — next frame, after a delay, or on another thread. Between awaits your code runs synchronously; the awaits are the seams where the engine (and your cancellation token) get a say.

Pitfalls

Async is powerful and has sharp edges. Three cut most often.

Respect those three and async in Unity 6 is a clear upgrade over coroutines for anything beyond a trivial frame-spread: it returns values, composes, handles exceptions properly, and reaches other threads — all while staying friendly to the engine's frame loop.

Hands-on Challenge

Summary

🚀 What's Next?

You now have structure (assemblies), wiring (DI), and time control (async). The last piece before the mini-project is a vocabulary of reusable shapes. In Lesson 1.4: Scaling Design Patterns — Command, State, Service Locator & Event Bus, you'll add four patterns that keep large systems decoupled — including an event bus your async services can broadcast through.