Unity Folder Structure Conventions

Status: RESOLVED — July 19, 2026

---

Decisions

Assembly Definitions

Already defined in the project. Keep existing structure. No changes needed.

Addressables

Use Addressables for asset management (not Resources). Enables DLC delivery in the future.

Art Pipeline

• 2D sprites: Aseprite with Pixellab integration for Unity import.
• 3D terrain: Custom mesh generation (no models to import — grid is generated).
• Source files (Aseprite .ase files) live outside Unity. Pixellab handles import.

---

Proposed Asset Structure

Assets/
├── _Project/                     # All game-specific content
│   ├── Scenes/
│   │   ├── Boot.unity
│   │   ├── MainMenu.unity
│   │   ├── Hub.unity
│   │   ├── Battle.unity
│   │   └── CoOpBattle.unity
│   │
│   ├── Scripts/
│   │   ├── Core/                 # Grid, CT timeline, battle state machine
│   │   ├── Units/                # Unit data, stats, status effects
│   │   ├── Aspects/              # Aspect definitions, slot system, synergy detection
│   │   ├── Grid/                 # Tile data, pathfinding (A*), LOS (Bresenham)
│   │   ├── Generation/           # Grammar engine (editor-time) + map export
│   │   ├── UI/                   # HUD, timeline bar, tooltips, menus
│   │   ├── Roguelike/            # Run state, node map, relic system, meta-progression
│   │   ├── Networking/           # INetworkTransport abstraction + Steamworks impl
│   │   ├── Save/                 # System.Text.Json serialization, save/load
│   │   └── Audio/                # Music, SFX management
│   │
│   ├── Prefabs/
│   │   ├── Units/
│   │   ├── UI/
│   │   ├── Grid/                 # Tile prefabs, cover, hazard objects
│   │   └── Effects/
│   │
│   ├── ScriptableObjects/
│   │   ├── Aspects/              # AspectDefinition assets
│   │   ├── Characters/           # CharacterDefinition assets
│   │   ├── Enemies/              # EnemyDefinition assets
│   │   ├── Equipment/            # EquipmentDefinition assets
│   │   ├── Relics/               # RelicDefinition assets
│   │   ├── Abilities/            # AbilityDefinition assets
│   │   ├── Encounters/           # Node/encounter definitions
│   │   ├── Synergies/            # Explicit synergy combination table
│   │   └── Maps/                 # Exported map assets (editor-grammar output)
│   │
│   ├── Art/
│   │   ├── Sprites/              # 2D character sprites (Aseprite → Pixellab)
│   │   ├── Materials/            # Materials for grid mesh + sprite shaders
│   │   └── Shaders/              # Height indicator, outline, billboard
│   │
│   ├── Audio/
│   │   ├── Music/
│   │   └── SFX/
│   │
│   ├── Input/
│   │   └── InputActions.inputactions  # KBM + future controller
│   │
│   └── AddressableAssetsData/    # Addressables groups + profiles
│
├── Plugins/                      # Steamworks.NET, Newtonsoft (if needed)
├── TextMesh Pro/                 # TMP essentials
└── MCP/                          # AI context (points to gdd/)

---

Naming Conventions

Asset Type	Convention	Example
Scenes	PascalCase	MainMenu.unity
Scripts	PascalCase, one class per file	CTTimeline.cs
ScriptableObjects	PascalCase + suffix	Aspect_Knight_Key.asset
Prefabs	PascalCase + prefix	Unit_Knight.prefab
Sprites	snake_case + suffix	tile_grass_01.png
Materials	PascalCase + _Mat suffix	TileGrass_Mat.mat
Audio	snake_case + category	sfx_spell_fireball.wav

---

Open Questions

• [ ] Existing asmdef structure: audit and document what's already defined.
• [ ] Pixellab integration: verify compatibility with Unity 6 (6000.x) + URP.
• [ ] Map export pipeline: where do exported map assets live? ScriptableObjects/Maps/ or a dedicated folder?