Unity

--- name: Unity description: Avoid common Unity mistakes — lifecycle ordering, GetComponent caching, physics timing, and Unity's fake null. metadata: {"clawdbot":{"emoji":"🎮","os":["linux","darwin","win32"]}} ---

Lifecycle Order

• Awake before Start — use Awake for self-init, Start for cross-references
• OnEnable called before Start — but after Awake
• Order between scripts not guaranteed — use Script Execution Order if needed
• Awake called even if disabled — Start only when enabled

GetComponent Performance

• GetComponent every frame is slow — cache in Awake or Start
• GetComponentInChildren searches recursively — expensive on deep hierarchies
• TryGetComponent returns bool — avoids null check, slightly faster
• Use RequireComponent attribute — ensures dependency, documents requirement

Physics Timing

• Physics in FixedUpdate, not Update — consistent regardless of framerate
• FixedUpdate can run 0 or multiple times per frame — don't assume 1:1
• Rigidbody.MovePosition in FixedUpdate — transform.position bypasses physics
• Time.deltaTime in Update, Time.fixedDeltaTime in FixedUpdate — or just use deltaTime

Unity's Fake Null

• Destroyed objects aren't truly null — == null returns true, but object exists
• Null-conditional ?. doesn't work properly — use == null or bool conversion
• Destroy doesn't happen immediately — object gone next frame
• Use DestroyImmediate only in editor — causes issues in builds

Coroutines

• StartCoroutine needs MonoBehaviour active — disabled/destroyed stops coroutines
• yield return null waits one frame — yield return new WaitForSeconds(1) for time
• StopCoroutine needs same method or Coroutine reference — string overload unreliable
• Can't return values — use callbacks or set field in coroutine

Instantiate and Pooling

• Instantiate is expensive — pool frequently created/destroyed objects
• Instantiate(prefab, parent) sets parent — avoids extra SetParent call
• SetActive(false) before returning to pool — not Destroy
• Pool inactive objects under a parent — keeps hierarchy clean

Serialization

• [SerializeField] for private fields in inspector — prefer over public
• public fields auto-serialize — but exposes API you may not want
• [HideInInspector] hides but still serializes — [NonSerialized] to skip entirely
• Serialized fields keep inspector values — code defaults ignored after first serialize

ScriptableObjects

• Data containers that live as assets — share between scenes/prefabs
• CreateAssetMenu attribute for easy creation — right-click → Create
• Don't modify at runtime in builds — changes not saved (except in editor)
• Great for config, item databases — reduces prefab duplication

Common Mistakes

• Find methods every frame — cache references
• String comparisons for tags — use CompareTag("Enemy"), not tag == "Enemy"
• Physics queries allocate — use NonAlloc variants: RaycastNonAlloc
• UI anchors wrong — stretches unexpectedly on different resolutions
• async/await without context — use UniTask or careful error handling