Skill v1.0.2

currentAutomated scan100/100

besty0728/unity-skills/unitask-design

+1 new

──Details

PublishedAugust 18, 2026 at 07:35 PM

Content Hashsha256:b5b7b012b496b143...

Git SHAa1ee16e0d432

Bump Typepatch

Compare with v1.0.1

──Files

Files (1 file, 7.8 KB)

SKILL.md7.8 KBactive

SKILL.md · 85 lines · 7.8 KB

version: "1.0.2" 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 `await`ed, `.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.

← v1.0.1 All versions