gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-csharp-scripting
unity-csharp-scripting
FlaggedWrites and fixes Unity 6.3 LTS C# gameplay scripts: MonoBehaviour lifecycle, serialization, .meta/GUID discipline and command-line tests. Use for new or renamed .cs files, "Missing script" or a field missing from the Inspector. Not for physics (`unity-physics`), input (`unity-input-system`), data assets (`unity-scriptableobjects`) or builds (`unity-build-pipeline`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| references/agent-checks.md | markdown | 6.2 KB |
| references/lifecycle-and-coroutines.md | markdown | 5.4 KB |
| scripts/check_unity_project.py | script | 35.9 KB |
references/lifecycle-and-coroutines.md
View on GitHub# MonoBehaviour lifecycle & coroutines (Unity 6.3 LTS)
Depth for the `unity-csharp-scripting` skill: the full execution order and the coroutine
patterns that don't fit in the main playbook. Verified against the Unity Manual
"Event function execution order" page and `ScriptReference/MonoBehaviour`.
## Contents
- Execution order
- Coroutine yield instructions
- `Awaitable` (async/await) instead of a coroutine
- Custom yield instruction
- Gotchas
## Execution order (the parts that matter for gameplay)
Per object, the engine calls these in this order:
| Phase | Callback | Runs | Use for |
|-------|----------|------|---------|
| Load | `Awake` | once, when the object loads — even if the script component is disabled, but not while the GameObject is inactive | cache `GetComponent`, set up self |
| Enable | `OnEnable` | each time the object/script enables | subscribe to events, re-arm coroutines |
| Init | `Start` | once, before first `Update`, after every `Awake` | wiring that depends on other objects |
| Physics | `FixedUpdate` | every fixed step (default 0.02s) | rigidbody forces, `MovePosition` |
| Physics | `OnTriggerXXX` / `OnCollisionXXX` | during the physics step | collision/trigger response |
| Frame | `Update` | once per rendered frame | input polling, non-physics logic |
| Frame | `LateUpdate` | once per frame, after all `Update`s | camera follow, IK fix-up |
| Disable | `OnDisable` | each time the object/script disables | unsubscribe from events |
| Teardown | `OnDestroy` | once, when destroyed | release native handles, save |
Key consequences:
- `FixedUpdate` may run zero, one, or several times per frame depending on frame rate. Never
read raw "per frame" input there — read it in `Update`, consume it in `FixedUpdate`.
- All `Awake` calls finish before any `Start`. Order *among* `Awake`s (and among `Start`s) is
undefined unless you set a Script Execution Order in Project Settings.
- `OnEnable` runs after `Awake` on first enable, then again on every re-enable. Pair every
`OnEnable` subscription with an `OnDisable` unsubscription to avoid duplicate handlers.
## Coroutine yield instructions
```csharp
yield return null; // resume at the start of the next frame
yield return new WaitForSeconds(2f); // wait 2s of scaled game time (affected by Time.timeScale)
yield return new WaitForSecondsRealtime(2f);// wait 2s of real time (ignores timeScale; good for pause menus)
yield return new WaitForFixedUpdate(); // resume after the next physics step
yield return new WaitUntil(() => isReady); // resume once the predicate is true
yield return new WaitWhile(() => isLoading);// resume once the predicate is false
yield return StartCoroutine(OtherRoutine());// run a nested coroutine to completion first
```
## `Awaitable` (async/await) instead of a coroutine
Unity 6 ships `UnityEngine.Awaitable`, an allocation-light awaitable for `async` methods.
The coroutine waits map directly:
| Coroutine | `Awaitable` |
|-----------|-------------|
| `yield return null` | `await Awaitable.NextFrameAsync()` |
| `yield return new WaitForSeconds(t)` | `await Awaitable.WaitForSecondsAsync(t)` |
| `yield return new WaitForFixedUpdate()` | `await Awaitable.FixedUpdateAsync()` |
| `yield return new WaitForEndOfFrame()` | `await Awaitable.EndOfFrameAsync()` |
| (no equivalent) | `await Awaitable.BackgroundThreadAsync()` / `MainThreadAsync()` |
```csharp
using System;
using UnityEngine;
public class Blinker : MonoBehaviour
{
[SerializeField] private Renderer target;
private async void Start()
{
try
{
while (true)
{
target.enabled = !target.enabled;
// The token cancels the wait when this component is destroyed.
await Awaitable.WaitForSecondsAsync(0.5f, destroyCancellationToken);
}
}
catch (OperationCanceledException) { /* destroyed: stop quietly */ }
}
}
```
Rules that differ from coroutines:
- An async method is **not** stopped when its object is disabled or destroyed. Pass
`destroyCancellationToken` (read it before the object is destroyed) or check state after
each `await`.
- `Awaitable` instances are pooled: await each one **once**. To await a result twice, store
the result, not the `Awaitable`.
- After `BackgroundThreadAsync`, most Unity APIs are off-limits until you
`await Awaitable.MainThreadAsync()`. Background work does not stop when you exit Play mode;
use `Application.exitCancellationToken` for that.
- Prefer `async Awaitable` over `async void` for methods you call yourself, so callers can
await them; reserve `async void` for Unity messages such as `Start`.
## Custom yield instruction
When you want a reusable wait condition:
```csharp
public class WaitForAnimationEnd : CustomYieldInstruction
{
private readonly Animator _a;
private readonly int _layer;
public WaitForAnimationEnd(Animator a, int layer = 0) { _a = a; _layer = layer; }
// keepWaiting == true means "keep yielding"; false resumes the coroutine.
public override bool keepWaiting => _a.GetCurrentAnimatorStateInfo(_layer).normalizedTime < 1f;
}
```
## Gotchas
- Coroutines are killed when the GameObject is **deactivated** (`SetActive(false)`) or the
script is destroyed — but *not* when only the script component is disabled while the object
stays active. Re-arm in `OnEnable` if needed.
- Allocating `new WaitForSeconds(x)` every loop iteration creates garbage; cache the instance.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |