Unity Async Patterns

Prerequisites

⚠️ REQUIRED SKILL: This skill depends on and automatically references csharp-async-patterns for foundational async/await knowledge.

What this means: When unity-async is activated, Claude will automatically consult the csharp-async-patterns skill for:

• Task and async/await fundamentals
• CancellationToken patterns
• ConfigureAwait usage
• Error handling in async code
• ValueTask optimization

Learning Path: Master C# async basics via csharp-async-patterns → Apply Unity-specific constraints and patterns via this skill

🔧 Foundation: unity-csharp-fundamentals - Required Unity C# patterns (TryGetComponent, FindAnyObjectByType, null-safe coding)

Overview

Unity-specific async patterns extending foundational C# async/await concepts.

Core Topics:

• Coroutines and yield instructions
• async/await with Unity main thread constraints
• Unity Job System and Burst compiler
• Thread safety and marshaling
• Addressables and UnityWebRequest integration

Learning Path: C# async basics → Unity context → UniTask optimization → Reactive patterns

Quick Start

Three Unity Async Approaches

// 1. Coroutine (Unity-specific, frame-based)
IEnumerator LoadDataCoroutine()
{
    yield return new WaitForSeconds(1f);
    UnityWebRequest request = UnityWebRequest.Get(url);
    yield return request.SendWebRequest();
    ProcessData(request.downloadHandler.text);
}

// 2. Async/Await (C# standard + Unity constraints)
async Task<string> LoadData(CancellationToken ct)
{
    await Task.Delay(1000, ct);
    using UnityWebRequest request = UnityWebRequest.Get(url);
    await request.SendWebRequest();
    return request.downloadHandler.text;
    // Unity auto-marshals to main thread
}

// 3. Job System (parallel data processing)
[BurstCompile]
struct VelocityJob : IJobParallelFor
{
    [ReadOnly] public NativeArray<Vector3> velocities;
    public NativeArray<Vector3> positions;
    public float deltaTime;

    public void Execute(int index)
    {
        positions[index] += velocities[index] * deltaTime;
    }
}

When to Use

Unity Async (This Skill)

• Frame-based timing and Unity API integration
• Standard async/await with Unity constraints
• Job System parallelization
• Main thread restrictions and solutions

Specialized Agents

• unity-unitask-pro: Zero-allocation async, memory-critical scenarios
• unity-reactive-pro: Event streams, MVVM/MVP, reactive state management

Reference Documentation

Unity-Specific Extensions

Unity Async Best Practices

• Coroutines vs async/await decision framework
• Main thread restrictions and solutions
• Job System usage patterns
• MonoBehaviour lifecycle integration

Coroutine Patterns

• yield return variations
• Coroutine chaining and composition
• Custom yield instructions
• Performance considerations

Unity Threading Guide

• Main thread vs background threads
• UnityMainThreadDispatcher patterns
• Job System and Burst compiler
• Thread-safe data structures (NativeArray, NativeContainer)

Key Principles

1. Main Thread Only: Unity APIs require main thread
2. Coroutines for Frames: Frame-based operations use coroutines
3. Job System for Parallelism: CPU-intensive data processing
4. UniTask for Performance: Zero-allocation critical paths
5. R3 for Reactive: Complex event streams and data binding

Common Patterns

Frame Timing

yield return null;                    // Next frame
yield return new WaitForEndOfFrame(); // After rendering
yield return new WaitForFixedUpdate(); // Physics update

Async Resource Loading

AsyncOperation asyncLoad = SceneManager.LoadSceneAsync("Scene");
while (!asyncLoad.isDone)
{
    float progress = Mathf.Clamp01(asyncLoad.progress / 0.9f);
    yield return null;
}

Addressables Integration

AsyncOperationHandle<GameObject> handle = Addressables.LoadAssetAsync<GameObject>("AssetKey");
await handle.Task;
GameObject prefab = handle.Result;

Platform Considerations

• WebGL: No threading, coroutines primary, Job System unavailable
• Mobile: Battery optimization critical, limit thread count
• Desktop: Full threading support, higher performance budgets

Agent Delegation

Unity Async Needs
├── Frame timing → unity-async (coroutines)
├── Standard async → unity-async (async/await)
├── Parallel data → unity-async (Job System)
├── Zero-allocation → unity-unitask-pro agent
└── Reactive patterns → unity-reactive-pro agent