bernatmv/unity-unitask-design

UniTask - Design Rules

Advisory module. Every rule is distilled from Cysharp UniTask source at:

• 2.5.10 — [email protected] (Unity 2018.4 baseline; actively used with 2022.3 / Unity 6)

Each rule cites a concrete file/line so the reasoning is auditable and the AI does not improvise against stale memory.

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

When to Load This Module

Load before writing or reviewing any of:

• Any async UniTask / async UniTask<T> / async UniTaskVoid method signature
• .Forget(), .AttachExternalCancellation(token), .SuppressCancellationThrow() chaining
• UniTask.Yield, UniTask.NextFrame, UniTask.Delay, UniTask.WaitForEndOfFrame, UniTask.WaitForFixedUpdate
• UniTask.WaitUntil, UniTask.WaitWhile, UniTask.WaitUntilValueChanged, UniTask.WaitUntilCanceled
• UniTask.WhenAll, UniTask.WhenAny, UniTask.WhenEach
• UniTask.SwitchToMainThread, UniTask.SwitchToThreadPool, UniTask.Run
• AsyncOperation.ToUniTask(), UnityWebRequest.SendWebRequest().ToUniTask(), Coroutine.ToUniTask()
• this.GetCancellationTokenOnDestroy(), GetAsyncStartTrigger() and other AsyncTrigger* extensions
• UniTaskCompletionSource / UniTaskCompletionSource<T> manual completion sources
• IUniTaskAsyncEnumerable<T> / UniTaskAsyncEnumerable / AsyncReactiveProperty<T> / Channel<T>
• WebGL-specific async code paths where Task.Run / SwitchToThreadPool are forbidden

Critical Rule Summary

| # | Rule | Source anchor | |---|------|---------------| | 1 | UniTask is a readonly partial struct (value type). Once awaited, its IUniTaskSource is recycled; awaiting the same UniTask variable twice throws. Use .Preserve() to obtain a memoized copy that can be awaited multiple times. | UniTask.cs:34, UniTask.cs:103-113 | | 2 | A UniTask returned by a method must be either awaited, .Forget()ed, or .AttachExternalCancellation(token)ed. Orphan UniTasks silently swallow exceptions into UniTaskScheduler.UnobservedTaskException. | UniTaskScheduler.cs:13, UniTaskVoid.cs:11-17 | | 3 | PlayerLoopTiming defines 16 timing slots (2020.2+; 14 on older Unity). Default UniTask.Yield() / UniTask.Delay uses PlayerLoopTiming.Update. Mixing LastPostLateUpdate with legacy WaitForEndOfFrame coroutines changes observed frame ordering. | PlayerLoopHelper.cs:71-99 | | 4 | UniTask.Delay(int ms, DelayType, PlayerLoopTiming, CancellationToken, bool cancelImmediately) accepts DelayType.DeltaTime / UnscaledDeltaTime / Realtime. The old bool ignoreTimeScale overload still exists but mixes semantics — prefer the DelayType overload for new code. | UniTask.Delay.cs:12-20, UniTask.Delay.cs:147-165 | | 5 | this.GetCancellationTokenOnDestroy() is defined for MonoBehaviour, GameObject, and Component in AsyncTriggerExtensions. Plain C# classes do NOT receive this extension — they must own a CancellationTokenSource explicitly. | Triggers/AsyncTriggerExtensions.cs:14,22,28 | | 6 | UniTask.WhenAll(params UniTask[] tasks) and the IEnumerable<UniTask> overload both exist. Semantically match Task.WhenAll but are zero-alloc when tasks are UniTask-native. WhenAny returns (winnerIndex, result) tuple for UniTask<T>. | UniTask.WhenAll.cs:12,22,31,41, UniTask.WhenAny.cs | | 7 | AsyncOperation.ToUniTask(IProgress<float>, PlayerLoopTiming, CancellationToken) is the canonical adapter. await operation works too but silently leaks the progress callback if you also set operation.completed += …. | UnityAsyncExtensions.cs | | 8 | UniTaskCompletionSource and UniTaskCompletionSource<T> support TrySetResult / TrySetException / TrySetCanceled. Once any of the three succeeds, subsequent calls return false — they do not throw. | UniTaskCompletionSource.cs:573,610,754,792 | | 9 | UniTask.SwitchToThreadPool() and UniTask.Run(...) are compile-time available on all platforms BUT throw NotSupportedException at runtime on WebGL. Guard with #if !UNITY_WEBGL || UNITY_EDITOR or fall back to UniTask.Yield()-based cooperative work. | UniTask.Threading.cs:57 | | 10 | Returning async UniTaskVoid is the fire-and-forget idiom that lets await be used INSIDE the method. async void methods cannot return UniTask — a common compile error when porting from Task. | UniTaskVoid.cs:11-17, UniTask.Factory.cs:112-131 |

Sub-doc Routing

| Sub-doc | When to read | |---------|--------------| | BASICS.md | UniTask vs Task differences, struct semantics, UniTaskVoid, zero-alloc state machine, AsyncUniTaskMethodBuilder | | PLAYERLOOP.md | 16-value PlayerLoopTiming table, Yield/NextFrame/Delay/WaitForEndOfFrame/WaitForFixedUpdate, DelayType, frame-ordering with legacy coroutines | | CANCELLATION.md | CancellationToken patterns, GetCancellationTokenOnDestroy (3 overloads), AttachExternalCancellation, CancelAfterSlim, AddTo, OperationCanceledException flow | | COMPOSITION.md | WhenAll, WhenAny, WhenEach, Forget, SuppressCancellationThrow, ContinueWith, timeout patterns | | CONVERSION.md | AsyncOperation.ToUniTask, UnityWebRequest.SendWebRequest().ToUniTask, IEnumerator.ToUniTask, Task.AsUniTask, UniTask.AsTask, UniTask.ToCoroutine | | ASYNCENUMERABLE.md | IUniTaskAsyncEnumerable<T>, UniTaskAsyncEnumerable, AsyncReactiveProperty<T>, Channel<T>, EveryValueChanged, Publish, LINQ-to-async operators | | TRIGGERS.md | AsyncTriggerBase, GetAsyncStartTrigger, GetAsyncDestroyTrigger, OnCollisionEnterAsync, OnClickAsync, MonoBehaviourMessagesTriggers, lifecycle cancellation | | PITFALLS.md | 30 concrete hallucination / runtime pitfalls (double-await, forgotten Forget, WebGL threadpool, tracker memory, wrong PlayerLoopTiming, coroutine interop bugs) |

Routing to Other Modules

• Choice between UniTask, raw Task, and IEnumerator at the architecture layer → load async
• DOTween tween → UniTask adapter (tween.ToUniTask(TweenCancelBehaviour, token)) → load dotween-design
• YooAsset handle → UniTask via handle.ToUniTask() extension → load yooasset-design
• Addressables AsyncOperationHandle.ToUniTask() rules → load addressables-design
• Performance review of UniTask-heavy code paths (tracker cost, state machine alloc) → load performance
• Asmdef layout for UniTask consumers (Cysharp.Threading.Tasks.asmdef reference) → load asmdef

Version Scope

Targets UniTask 2.5.10. Earlier 2.x versions are mostly source-compatible; key differences:

• WaitForEndOfFrame(MonoBehaviour coroutineRunner) overload added in recent 2.x — on 2023.1+ a parameterless overload is available (#if UNITY_2023_1_OR_NEWER). See UniTask.Delay.cs:78-103.
• UniTask.WhenEach is a newer addition; not all 2.x builds ship it.

When in doubt, read the cited source — not your memory.