# cysharp/unitask architecture

> Architecture diagram of the GitHub repository cysharp/unitask, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cysharp/unitask
- Repository: https://github.com/cysharp/unitask

## Overview

This project is a specialized asynchronous utility library for Unity. It is designed to provide a zero-allocation, high-performance alternative to standard async/await constructs (using custom task-like types such as UniTask) and is tailored for Unity’s single‐threaded environment. In addition to the core async functionality for Unity, the repository includes several projects for .NET Core compatibility, testing, code analysis, and a sandbox sample.

##### Main Components
- Core UniTask Library (located in src/UniTask):
– Contains the main assets (in Assets/Plugins/UniTask) where the asynchronous types, extension methods, and runtime components live.
– Subcomponents include:
▪ Async core logic – e.g., zero-allocation async/await integration and utility methods (UniTask, UniTask<T>, UniTaskVoid).
▪ PlayerLoop integration – custom player loop injection, timing methods (UniTask.Delay, UniTask.Yield, waiting for frames, WaitForEndOfFrame, etc.)
▪ Async extension modules – supporting cancellation, progress reporting, and conversion from Unity’s native async operations.
▪ External integration – modules for DOTween, TextMeshPro, Addressables, and bridges to allow Unity’s async operations (like WebRequests, coroutines).
- Analyzer Project (src/UniTask.Analyzer):
– Implements code analysis tools (Roslyn analyzer) to help maintain high code quality.
- .NET Core Version (src/UniTask.NetCore):
– A subset of the library packaged for .NET Core where Unity-specific player loop features have been removed.
- Sandbox & Tests:
– Sandbox sample (src/UniTask.NetCoreSandbox) to demonstrate usage.
– Comprehensive tests (src/UniTask.NetCoreTests) validating functionality and integration.
- Documentation and CI:
– The docs/ directory holds documentation and API references (generated with DocFX) that complement the README.
– GitHub Actions workflows in the .github/workflows directory show CI/CD integration.

##### Relationships and Interactions
- The Core Library is the heart of the system. It interacts with Unity’s PlayerLoop (via injected custom timing and scheduling) and provides extension methods to make Unity’s AsyncOperations and Coroutines awaitable.
- The external/ subdirectories (inside Assets/Plugins/UniTask/Runtime/External) represent integrations, where specific asynchronous adapters are provided for other assets (e.g., DOTween, TextMeshPro).
- The Analyzer project depends on the Core projects to ensure that usage adheres to best practices and to warn about common pitfalls.
- The .NET Core project mirrors much of the UniTask functionality but with player loop and other Unity-specific aspects removed. This shows a separation of concerns based on target platforms.
- Testing projects are used to verify that the features (such as cancellation, timeout, progress, and asynchronous LINQ) operate as expected. There is an implicit dependency from tests on the core runtime.
- CI/CD workflows automate build, test, and documentation generation, ensuring that all components remain synchronized.

##### Architectural Patterns and Design Principles
- Separation of Concerns – distinct projects for Unity (core), .NET Core compatibility, static analysis, and sandbox usage.
- Modular Composition – submodules deployed as separate assembly definitions (asmdefs) in the Assets folder (e.g., external integrations, runtime, editor utilities).
- Dependency Injection / Loose Coupling – the player loop injection and cancellation mechanisms abstract Unity engine details.
- Event-driven/Asynchronous Programming – primary design built around awaitable tasks, custom async method builders, event triggers, asynchronous LINQ queries, and channels (for pub/sub messaging).

## Diagram (Mermaid)

```mermaid
graph TD
    A["Game Code (Unity MonoBehaviour)"]:::game

    subgraph "UniTask Core (Unity)"
        CORE["Core UniTask Library"]:::unity
        ASYNC["Async Core Logic, PlayerLoop Integration & Async Extensions"]:::unity
        EXTERNAL["External Assets Integration"]:::external
        CORE --> ASYNC
        CORE --> EXTERNAL
    end

    ANALYZER["Analyzer Project"]:::analyzer
    DOTNET[".NET Core Version"]:::dotnet
    SANDBOX["Sandbox Sample"]:::sandbox
    TESTS["Tests Suite"]:::tests
    DOCS["Documentation"]:::docs
    CI["CI/CD Workflows"]:::ci

    A -->|"calls"| CORE
    ANALYZER -->|"analyzes"| CORE
    TESTS -->|"tests"| CORE
    TESTS -->|"tests"| DOTNET
    SANDBOX -->|"demonstrates"| DOTNET
    DOCS -->|"generatedFrom"| CORE
    DOCS -->|"generatedFrom"| DOTNET
    CI -->|"buildsTests"| CORE
    CI -->|"buildsTests"| ANALYZER
    CI -->|"buildsTests"| DOTNET
    CI -->|"buildsTests"| SANDBOX
    CI -->|"buildsTests"| TESTS

    click CORE "https://github.com/cysharp/unitask/tree/master/src/UniTask/Assets/Plugins/UniTask"
    click ASYNC "https://github.com/cysharp/unitask/tree/master/src/UniTask/Assets/Plugins/UniTask/Runtime"
    click EXTERNAL "https://github.com/cysharp/unitask/tree/master/src/UniTask/Assets/Plugins/UniTask/Runtime/External"
    click ANALYZER "https://github.com/cysharp/unitask/blob/master/src/UniTask.Analyzer"
    click DOTNET "https://github.com/cysharp/unitask/blob/master/src/UniTask.NetCore"
    click SANDBOX "https://github.com/cysharp/unitask/blob/master/src/UniTask.NetCoreSandbox"
    click TESTS "https://github.com/cysharp/unitask/blob/master/src/UniTask.NetCoreTests"
    click DOCS "https://github.com/cysharp/unitask/tree/master/docs"
    click CI "https://github.com/cysharp/unitask/tree/master/.github/workflows"

    classDef unity fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef external fill:#A3E4D7,stroke:#000,stroke-width:2px;
    classDef analyzer fill:#F7D6AE,stroke:#000,stroke-width:2px;
    classDef dotnet fill:#FFF79A,stroke:#000,stroke-width:2px;
    classDef sandbox fill:#D6A3F7,stroke:#000,stroke-width:2px;
    classDef tests fill:#F7A3D6,stroke:#000,stroke-width:2px;
    classDef docs fill:#D4F7A3,stroke:#000,stroke-width:2px;
    classDef ci fill:#C0C0C0,stroke:#000,stroke-width:2px;
    classDef game fill:#F0E68C,stroke:#000,stroke-width:2px;
```
