unity-code-style-guide AGENTS.md

AGENTS.md — Unity 6 C#

Coding conventions for this Unity project. Copy this file into your own repo and edit the Project Setup block below — everything else is ready to use as-is.

Rules marked [opinion] are stylistic preferences, not industry consensus. Change them freely as long as you change them everywhere. Everything unmarked is standard Unity or C# practice and should survive contact with any team.

---

Project Setup — EDIT THIS BLOCK

Unity version:    6.3 (6000.3.x)
C# version:       9.0
Render pipeline:  URP
Input:            Input System package  (NOT the legacy Input Manager)
UI:               UI Toolkit            (NOT uGUI / Canvas)
Async:            Awaitable             (NOT coroutines, unless per-frame iteration is needed)
Pooling:          UnityEngine.Pool.ObjectPool<T>

Never generate code for a system listed as "NOT". If the project uses something different, change the block above first.

---

Never do these — they corrupt the project

Style mistakes produce ugly code. These produce a broken Unity project, and the damage is often silent until someone opens the Editor.

• ❌ Never create or hand-edit a .meta file. Unity owns the GUID inside it. A wrong or duplicated GUID breaks every reference to that asset, across every scene and prefab.
• ❌ Never edit .asset, .prefab, .unity, .controller, .mat, or .anim YAML directly. They carry fileID + GUID pairs that must stay internally consistent. Use the Editor, or an Editor script that goes through AssetDatabase / SerializedObject.
• ❌ Never move, rename, or delete an asset with filesystem commands (mv, rm, git mv). The .meta must travel with it. Use the Project window or AssetDatabase.MoveAsset.
• ❌ Never rename a serialized field without [FormerlySerializedAs("oldName")]. Serialization is keyed on the field name — the Inspector value is silently lost on every asset and scene using it.
• ❌ Never reorder or renumber the members of a serialized enum. They persist as integers, so existing assets silently remap to different values. Append new members at the end.
• ⚠️ Don't edit ProjectSettings/*.asset or Packages/manifest.json while the Editor is open — it may overwrite your change when it regains focus.
• ⚠️ Library/, Temp/, obj/, Logs/ and UserSettings/ are generated. Never edit them, never commit them.