OpenParable
Skip to content
← Back to skills

Unity Unitask Design

Development
unity-unitask-design

Unity Unitask Design is an Agent Skill for development published in the Besty0728/Unity-Skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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 时使用。

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Besty0728/Unity-Skills/blob/HEAD/SkillsForUnity/unity-skills~/skills/unitask-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/unity-unitask-design, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

#RuleSource anchor
1UniTask 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
2A 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
3PlayerLoopTiming 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
4UniTask.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
5this.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
6UniTask.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
7AsyncOperation.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
8UniTaskCompletionSource 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
9UniTask.SwitchToThreadPool() and UniTask.Run(...) are compile-time available on all platforms BUT throw NotSupportedException at runtime on WebGL. Guard with `#if !UNITY_WEBGL
10Returning 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-docWhen to read
BASICS.mdUniTask vs Task differences, struct semantics, UniTaskVoid, zero-alloc state machine, AsyncUniTaskMethodBuilder
PLAYERLOOP.md16-value PlayerLoopTiming table, Yield/NextFrame/Delay/WaitForEndOfFrame/WaitForFixedUpdate, DelayType, frame-ordering with legacy coroutines
CANCELLATION.mdCancellationToken patterns, GetCancellationTokenOnDestroy (3 overloads), AttachExternalCancellation, CancelAfterSlim, AddTo, OperationCanceledException flow
COMPOSITION.mdWhenAll, WhenAny, WhenEach, Forget, SuppressCancellationThrow, ContinueWith, timeout patterns
CONVERSION.mdAsyncOperation.ToUniTask, UnityWebRequest.SendWebRequest().ToUniTask, IEnumerator.ToUniTask, Task.AsUniTask, UniTask.AsTask, UniTask.ToCoroutine
ASYNCENUMERABLE.mdIUniTaskAsyncEnumerable<T>, UniTaskAsyncEnumerable, AsyncReactiveProperty<T>, Channel<T>, EveryValueChanged, Publish, LINQ-to-async operators
TRIGGERS.mdAsyncTriggerBase, GetAsyncStartTrigger, GetAsyncDestroyTrigger, OnCollisionEnterAsync, OnClickAsync, MonoBehaviourMessagesTriggers, lifecycle cancellation
PITFALLS.md30 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.