async & await

async/await is C#'s built-in way to write code that waits without freezing the game. It's an alternative to coroutines. It reads top to bottom like normal code, can return values, and works with try/catch.

Awaitable (Unity 6)

Unity 6 includes Awaitable, which is designed for games: it's allocation-friendly and continues on Unity's main thread, so you can safely touch GameObjects after awaiting.

Code Samples

A countdown

using UnityEngine;

public class Countdown : MonoBehaviour
{
    async void Start() // "async void" is OK for Unity event methods like Start
    {
        for (int i = 3; i > 0; i--)
        {
            Debug.Log(i);
            await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
        }
        Debug.Log("Go!");
    }
}

Returning a value

Something coroutines can't do directly:

using UnityEngine;

public class DoorPuzzle : MonoBehaviour
{
    [SerializeField] private Door door;

    async void Start()
    {
        bool solved = await WaitForPlayerAnswer(10f);
        if (solved) door.Open();
    }

    async Awaitable<bool> WaitForPlayerAnswer(float timeout)
    {
        float end = Time.time + timeout;
        while (Time.time < end)
        {
            if (Input.GetKeyDown(KeyCode.Y)) return true;
            await Awaitable.NextFrameAsync(destroyCancellationToken);
        }
        return false;
    }
}

Heavy work off the main thread

async Awaitable GenerateMapAsync()
{
    await Awaitable.BackgroundThreadAsync();   // now on a worker thread
    int[,] tiles = BuildNoiseMap(512, 512);    // heavy pure-C# math: OK here
    // transform.position = ...;               // NOT OK: Unity APIs need the main thread

    await Awaitable.MainThreadAsync();         // back on the main thread
    SpawnTiles(tiles);                         // now Unity APIs are fine
}

Cancellation: stopping when the object is destroyed

Unlike coroutines, async methods don't stop automatically when the GameObject is destroyed. They keep running and then crash on the destroyed object. Pass a CancellationToken: every MonoBehaviour has destroyCancellationToken (Unity 2022.2+), which is cancelled when it's destroyed.

async void Start()
{
    try
    {
        while (true)
        {
            transform.Rotate(0f, 90f, 0f);
            await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
        }
    }
    catch (System.OperationCanceledException)
    {
        // Object was destroyed: normal, nothing to do.
    }
}

What happens at runtime

Coroutine or async?

Common Mistakes

• No cancellation. The method outlives its object and throws MissingReferenceException. Pass destroyCancellationToken.
• Using Task.Delay for game timing. Task.Delay runs on the system clock: it ignores Time.timeScale and knows nothing about Unity's frames, and in the Editor a pending Task can keep running after you exit Play Mode. Prefer Awaitable methods, which run inside Unity's player loop.
• Using Unity APIs on a background thread. Most Unity APIs throw ("can only be called from the main thread"). Switch back first.
• async void for your own methods. Callers can't await it or catch its exceptions. Use async Awaitable (or Task); keep async void for Unity messages like Start and UI callbacks.
• Awaiting the same Awaitable twice. Awaitables are pooled and reused; await each one only once.

See also

• Iterators & yield
• Coroutines
• Exceptions & try/catch

This page is a simplified, AI-assisted interpretation. For the complete and authoritative reference, see the official Microsoft C# documentation.