unity-unitask-design

name	unity-unitask-design
description	Source-anchored design rules for UniTask 2.5.10

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Writing or reviewing async UniTask code
• Choosing PlayerLoopTiming
• Handling CancellationToken
• Composing WhenAll/WhenAny
• 编写或审查 async UniTask 代码、选择 PlayerLoopTiming、处理 CancellationToken、组合 WhenAll/WhenAny

UniTask - Design Rules

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

• 2.5.10 — com.cysharp.unitask@2.5.10 (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 overload both exist. Semantically match but are zero-alloc when tasks are UniTask-native. returns tuple for .

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

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.