assembly-definitions

Assembly Definitions

Assembly definitions (.asmdef) split your project into separate compilation units. Without them, Unity recompiles ALL scripts on every change. With them, only the changed assembly and its dependents recompile.

When to Create an Asmdef

• > 50 scripts in a folder — the compilation speed benefit becomes noticeable
• Editor-only code — MUST be in a separate Editor assembly
• Test code — MUST be in separate test assemblies
• Shared library code — core utilities used across systems
• Third-party code — isolate external packages

Recommended Structure

Assets/
├── Scripts/
│   ├── Core/                          # MyGame.Core.asmdef
│   │   ├── Core.asmdef
│   │   ├── Events/
│   │   ├── Pooling/
│   │   └── Utilities/
│   │
│   ├── Gameplay/                      # MyGame.Gameplay.asmdef
│   │   ├── Gameplay.asmdef
│   │   ├── Player/
│   │   ├── Enemies/
│   │   └── Items/
│   │
│   ├── Systems/                       # MyGame.Systems.asmdef
│   │   ├── Systems.asmdef
│   │   ├── Audio/
│   │   ├── Save/
│   │   └── UI/
│   │
│   └── Editor/                        # MyGame.Editor.asmdef
│       ├── Editor.asmdef
│       └── CustomInspectors/
│
├── Tests/
│   ├── EditMode/                      # MyGame.Tests.Editor.asmdef
│   │   └── Tests.Editor.asmdef
│   └── PlayMode/                      # MyGame.Tests.Runtime.asmdef
│       └── Tests.Runtime.asmdef

Reference Rules (Dependency Direction)

Gameplay → Systems → Core
    ↓         ↓        ↓
  (game)   (audio,   (events,
            save,     pooling,
            UI)       utilities)

Editor → [any runtime assembly]
Tests  → [assembly being tested]

Never reverse the arrows. Core must not reference Gameplay. Systems must not reference Gameplay.

Asmdef JSON Structure

{
    "name": "MyGame.Gameplay",
    "rootNamespace": "MyGame.Gameplay",
    "references": [
        "MyGame.Core",
        "MyGame.Systems"
    ],
    "includePlatforms": [],
    "excludePlatforms": [],
    "allowUnsafeCode": false,
    "overrideReferences": false,
    "precompiledReferences": [],
    "autoReferenced": true,
    "defineConstraints": [],
    "versionDefines": [],
    "noEngineReferences": false
}