How cysharp/unitask works
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).