unity-async-patterns
Unity async and coroutine correctness patterns. Catches common mistakes with Awaitable double-await, missing cancellation tokens, thread context after BackgroundThreadAsync, coroutine error swallowing, batch mode WaitForEndOfFrame, and Addressables handle leaks. PATTERN format: WHEN/WRONG/RIGHT/GOTCHA. Based on Unity 6.3 LTS documentation.
Nice-Wolf-Studio · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-async-patterns技能说明
name: unity-async-patterns description: > Unity async and coroutine correctness patterns. Catches common mistakes with Awaitable double-await, missing cancellation tokens, thread context after BackgroundThreadAsync, coroutine error swallowing, batch mode WaitForEndOfFrame, and Addressables handle leaks. PATTERN format: WHEN/WRONG/RIGHT/GOTCHA. Based on Unity 6.3 LTS documentation. globs:
- "**/*.cs"
Async & Coroutine Patterns -- Correctness Patterns
Prerequisite skills:
unity-scripting(coroutines, Awaitable API, yield types),unity-lifecycle(destruction timing, destroyCancellationToken)
These patterns target async bugs that are especially dangerous because they often work during testing and fail in production: exceptions silently swallowed, objects destroyed mid-await, and thread context violations.
PATTERN: Awaitable Double-Await
WHEN: Storing an Awaitable instance and awaiting it more than once
WRONG (Claude default):
Awaitable task = Awaitable.WaitForSecondsAsync(2f);
await task; // First await -- works
await task; // Second await -- UNDEFINED BEHAVIOR (may complete instantly or throw)
RIGHT:
// Awaitable is POOLED -- after the first await completes, the instance is recycled
// Each Awaitable should be awaited exactly once
// If you need to await the same operation from multiple places, use .AsTask():
var task = Awaitable.WaitForSecondsAsync(2f).AsTask();
await task; // Works
await task; // Works -- Task is not pooled
// Or simply create separate Awaitables:
await Awaitable.WaitForSecondsAsync(2f);
await Awaitable.WaitForSecondsAsync(2f); // Fresh instance
GOTCHA: Unity pools Awaitable instances to avoid allocation. After completion, the instance is returned to the pool and may be reused by a completely different operation. A second await on the same instance may see a different operation's state, complete instantly, or throw. This is unlike Task which can be safely awaited multiple times. Use .AsTask() when you need multi-await semantics, but be aware this allocates.
PATTERN: Missing destroyCancellationToken
WHEN: Writing async methods in MonoBehaviours
WRONG (Claude default):
async Awaitable Start()
{
await Awaitable.WaitForSecondsAsync(5f);
// If object was destroyed during the wait:
// - MissingReferenceException on next Unity API call
// - Or worse: silently operates on a "fake-null" object
transform.position = Vector3.zero;
}
RIGHT:
async Awaitable Start()
{
try
{
await Awaitable.WaitForSecondsAsync(5f, destroyCancellationToken);
transform.position = Vector3.zero;
}
catch (OperationCanceledException)
{
// Object was destroyed -- this is expected, not an error
}
}
// For methods that chain multiple awaits:
async Awaitable DoMultiStepWork()
{
var token = destroyCancellationToken;
await Awaitable.NextFrameAsync(token);
ProcessStep1();
await Awaitable.WaitForSecondsAsync(1f, token);
ProcessStep2(); // Safe: would have thrown before reaching here if destroyed
await LoadAssetAsync(token);
ProcessStep3();
}
GOTCHA: destroyCancellationToken is a property on MonoBehaviour that triggers when OnDestroy begins. Every Awaitable wait method accepts an optional CancellationToken. Without it, the await completes normally even after the object is destroyed, leading to MissingReferenceException. Always pass the token AND catch OperationCanceledException.
PATTERN: Thread Context After BackgroundThreadAsync
WHEN: Returning to Unity APIs after doing work on a background thread
WRONG (Claude default):
async Awaitable ProcessData()
{
await Awaitable.BackgroundThreadAsync();
var result = HeavyComputation(); // OK: runs on background thread
// CRASH: Accessing Unity API from background thread
transform.position = new Vector3(result, 0, 0);
}
RIGHT:
async Awaitable ProcessData()
{
await Awaitable.BackgroundThreadAsync();
var result = HeavyComputation(); // Runs on background thread
await Awaitable.MainThreadAsync(); // Switch BACK to main thread
transform.position = new Vector3(result, 0, 0); // Now safe
// Can switch back and forth:
await Awaitable.BackgroundThreadAsync();
var moreData = AnotherHeavyTask();
await Awaitable.MainThreadAsync();
ApplyResults(moreData);
}
GOTCHA: After BackgroundThreadAsync(), ALL subsequent code runs on a thread pool thread until you explicitly switch back with MainThreadAsync(). Unity APIs (Transform, GameObject, Physics, etc.) are not thread-safe and will throw or corrupt state if called from a background thread. MainThreadAsync() resumes on the next frame's player loop update, not immediately.
PATTERN: Coroutine Error Swallowing
WHEN: Exceptions occur inside coroutines
WRONG (Claude default):
IEnumerator LoadAndProcess()
{
yield return LoadData(); // If this throws, coroutine silently stops
ProcessData(); // Never reached, no error in console (or just a log, no stack)
}
// try/catch doesn't work with yield:
IEnumerator BadErrorHandling()
{
try
{
yield return SomethingDangerous(); // COMPILER ERROR: cannot yield in try block with catch
}
catch (Exception e)
{
Debug.LogError(e);
}
}
RIGHT:
// Option 1: Use Awaitable instead (proper exception propagation)
async Awaitable LoadAndProcess()
{
try
{
await LoadDataAsync();
ProcessData();
}
catch (Exception e)
{
Debug.LogError($"Load failed: {e}");
}
}
// Option 2: Error handling without yield in the try block
IEnumerator LoadAndProcessCoroutine()
{
bool success = false;
Exception error = null;
// Wrap the yield outside try/catch
yield return LoadDataCoroutine(result =>
{
success = true;
});
// Handle errors
阅读完整来源 ↗