Unity Code Conventions

Unity-Specific Naming

Library vs Demo Naming (CRITICAL)

• Library packages (Packages/): NEVER use game/demo names. Types must be generic and reusable across games.
  • BAD: ColorFitGameState, BackpackResult, BattleDemoPhase
  • GOOD: QueuePuzzleGameState, GridFillSystem, CharacterMovementSystem
  • Test: "Would this name make sense in a completely different game?" If no → rename it.
• Demo code (Assets/Demos/): Game-specific names are fine here (ColorFitCanvasUI, BattleDemoSceneSetup)

File Naming

• One type per file, filename matches type name: AttackTimerSystem.cs
• Keep files under 200 lines — split into partial classes or helper systems
• Editor scripts in Editor/ folder with Editor-only asmdef

No Hardcoded Values (CRITICAL)

Strings — NEVER inline literals for:

• Shader names: "Universal Render Pipeline/Lit" → ShaderConstants.UrpLit
• Shader properties: "_BaseMap" → ShaderConstants.PropBaseMap
• GameObject names: "BattlefieldArena" → private const string ArenaRootName
• File paths: "Assets/Prefabs/" → private const string PrefabFolder

Acceptable inline strings: Debug.Log(), [MenuItem("...")] attributes, nameof(), one-time errors.

Numbers — NEVER inline numeric literals:

• -1 sentinel → private const int InvalidIndex = -1;
• 0.1f threshold → private const float DamageThreshold = 0.1f;
• 2450 render queue → private const int AlphaTestRenderQueue = 2450;

→ See references/constants-patterns.md for the full SharedConstants class pattern and file-local private const usage.

Code Organization

Class Structure Order

1. Constants (const, static readonly)
2. Static fields / Instance fields
3. Constructors / Properties
4. Public → Internal → Private methods
5. Nested types

Assembly Definitions

• Each folder with distinct dependencies gets its own .asmdef
• Editor code MUST be in Editor-only asmdef (Editor/ folder)
• Test code MUST have UNITY_INCLUDE_TESTS define constraint

Namespace Conventions

• Match folder structure: Packages/[pkg]/Runtime/Combat/ → [Namespace].Combat
• Editor: [YourPackage].Editor | Tests: [YourNamespace].Tests

DOTS-Specific Conventions

Component Design

• Pure data, no logic — structs implementing IComponentData
• No managed types (string, class, List<T>) — use FixedString32Bytes/FixedString64Bytes
• Tag components: empty struct (struct Dead : IComponentData {})
• Prefer EnableableComponent over add/remove for frequent state changes

System Design

• ISystem (struct) over SystemBase (class) for Burst compatibility
• [BurstCompile] on struct AND all lifecycle methods
• [RequireMatchingQueriesForUpdate] to skip when no matching entities
• Cache ComponentLookup<T> in OnCreate, update in OnUpdate
• Hoist SystemAPI.Time.ElapsedTime before foreach loops

System Ordering

[UpdateInGroup(typeof(SimulationSystemGroup))]
[UpdateAfter(typeof(DetectionSystem))]
[UpdateBefore(typeof(NavigationSystemGroup))]

→ See references/anti-patterns.md for the full anti-patterns table (10 patterns with correct alternatives).

Editor Script Conventions

• Menu path: "Tools/[Package]/[Action]" — must be compile-time string literal
• Always check existence before creating: AssetDatabase.LoadAssetAtPath<T>(path)
• Clean up temporaries: Object.DestroyImmediate(tempGo)
• Save after creation: AssetDatabase.SaveAssets() + EditorSceneManager.SaveScene()
• Execute Unity Editor actions via MCP tools — never ask user to run menu items manually

Reference Files