Agent Skills
› Besty0728/Unity-Skills
› unity-unitask-design
unity-unitask-design
GitHub为Unity UniTask提供源码级设计规则，涵盖结构体语义、PlayerLoop时机、取消令牌处理及异步组合等。适用于编写或审查UniTask代码、选择时机、处理CancellationToken及使用WhenAll/WhenAny时，确保零分配与正确性。
Trigger Scenarios
编写 async UniTask 代码
审查 UniTask 实现
选择 PlayerLoopTiming
处理 CancellationToken
组合 WhenAll/WhenAny
用户提及异步或零分配
Install
npx skills add Besty0728/Unity-Skills --skill unity-unitask-design -g -y
SKILL.md
Frontmatter
{
"name": "unity-unitask-design",
"description": "Source-anchored design rules for Cysharp UniTask 2.5.10 (Unity 2018.4+) — struct semantics, PlayerLoop timing, cancellation, composition, conversion, async enumerables, triggers, and pitfalls. Use when writing or reviewing async UniTask code, choosing PlayerLoopTiming, handling CancellationToken, or composing WhenAll\/WhenAny, even if the user just says \"异步\" or \"零分配async\". 为 Cysharp UniTask 2.5.10(Unity 2018.4+)提供源码锚定的设计规则(struct 语义、PlayerLoop 时机、取消、组合、转换、异步流、触发器、陷阱);当用户要编写或审查 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 UniTaskVoidmethod signature .Forget(),.AttachExternalCancellation(token),.SuppressCancellationThrow()chainingUniTask.Yield,UniTask.NextFrame,UniTask.Delay,UniTask.WaitForEndOfFrame,UniTask.WaitForFixedUpdateUniTask.WaitUntil,UniTask.WaitWhile,UniTask.WaitUntilValueChanged,UniTask.WaitUntilCanceledUniTask.WhenAll,UniTask.WhenAny,UniTask.WhenEachUniTask.SwitchToMainThread,UniTask.SwitchToThreadPool,UniTask.RunAsyncOperation.ToUniTask(),UnityWebRequest.SendWebRequest().ToUniTask(),Coroutine.ToUniTask()this.GetCancellationTokenOnDestroy(),GetAsyncStartTrigger()and otherAsyncTrigger*extensionsUniTaskCompletionSource/UniTaskCompletionSource<T>manual completion sourcesIUniTaskAsyncEnumerable<T>/UniTaskAsyncEnumerable/AsyncReactiveProperty<T>/Channel<T>- WebGL-specific async code paths where
Task.Run/SwitchToThreadPoolare 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 |
|
| 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, rawTask, andIEnumeratorat 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.asmdefreference) → 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). SeeUniTask.Delay.cs:78-103.UniTask.WhenEachis a newer addition; not all 2.x builds ship it.
When in doubt, read the cited source — not your memory.
Version History
- ec9f870 Current 2026-07-05 14:41
