UE5-Modular-Game-Framework/docs/developer/project-setup-migration.md

# Project Setup & Migration Guide — UE5 Modular Game Framework

**Version:** 1.0 | **Target UE:** 5.5–5.7

This guide covers everything you need to configure when migrating the framework into a new or existing UE5 project. Follow these steps in order.

---

## 1. Prerequisites

### 1.1 Required UE5 Plugins
Enable these in `Edit → Plugins`:

| Plugin | Category | Required For |
|--------|----------|-------------|
| `Enhanced Input` | Input | `SS_EnhancedInputManager`, all input handling |
| `GameplayTags` | Gameplay | All tag-driven state management (enabled by default) |
| `Motion Warping` | Animation | `BPC_ContextualTraversalSystem` vault/mantle |
| `Gameplay Abilities` | Gameplay | *(optional — only if using GAS for combat layer)* |

### 1.2 Framework Files to Copy
Copy these folders into your project's `Content/` directory:

```
YourProject/Content/
├── Framework/
│   ├── Core/          ← Foundation (GI_GameFramework, DA_GameTagRegistry, FL_GameUtilities, etc.)
│   ├── Player/        ← Health, Stamina, Stress, Movement, Hiding, Camera, Body
│   ├── Interaction/   ← Doors, Puzzles, Traversal, Physics, UsableObjects, Displays
│   ├── Inventory/     ← InventorySystem, Containers, Pickups, Equipment, Keys, etc.
│   ├── Weapons/       ← WeaponBase, Firearm, Melee, Ammo, Reload, Recoil, Shield
│   ├── UI/            ← HUD, Menus, Inventory UI, Notifications, Settings
│   ├── Narrative/     ← NarrativeState, Dialogue, Objectives, Choices, Cutscenes
│   ├── AI/            ← EnemyBase, Controller, Perception, Alert, StateMachine
│   ├── Adaptive/      ← Atmosphere, Difficulty, Scares, Pacing, Audio
│   ├── Save/          ← SaveManager, Checkpoints, Death, Respawn, Corpses
│   ├── Meta/          ← Achievements, Progress Stats
│   ├── Settings/      ← Settings, Accessibility
│   ├── Polish/        ← Tutorial, Loading, Credits, Debug
│   ├── DataAssets/    ← All DA_* Data Assets
│   ├── Input/         ← IA_* Input Actions, IMC_* Input Mapping Contexts
│   ├── DataTables/    ← All DT_Tags_* Data Tables
│   ├── State/         ← BPC_StateManager, DA_StateGatingTable, Enums, Structs
│   └── Audio/         ← MS_* MetaSound buses, SS_AudioManager, RoomZones
```

---

## 2. Project Settings Configuration

### 2.1 Maps & Modes
`Edit → Project Settings → Maps & Modes`

| Setting | Value | Notes |
|---------|-------|-------|
| **Default GameMode** | `GM_CoreGameMode` | Or your project's subclass |
| **Default Game Instance** | `GI_GameFramework` | **Critical** — owns all SS_ subsystems |
| **Default Pawn Class** | Your GASP-based player character | With all BPC_ components attached |
| **Default Player Controller** | `PC_CoreController` | Handles input routing |
| **Game Default Map** | Your main menu / startup level | |
| **Editor Startup Map** | Your testing/development level | |

### 2.2 Gameplay Tags — Register All Data Tables
`Edit → Project Settings → Gameplay Tags`

Under **Gameplay Tag Table List**, click `+` 11 times and assign:

| Index | Data Table | Tag Count |
|-------|-----------|:---------:|
| 0 | `DT_Tags_Player` | 34 |
| 1 | `DT_Tags_Interaction` | 36 |
| 2 | `DT_Tags_Item` | 26 |
| 3 | `DT_Tags_Narrative` | 48 |
| 4 | `DT_Tags_AI` | 23 |
| 5 | `DT_Tags_Save` | 22 |
| 6 | `DT_Tags_Environment` | 30 |
| 7 | `DT_Tags_Combat` | 26 |
| 8 | `DT_Tags_State` | 39 |
| 9 | `DT_Tags_Audio` | 30 |
| 10 | `DT_Tags_Achievement` | 20 |

> **⚠️ Critical:** Without this step, NO framework GameplayTags will be recognized. `Is Gameplay Tag Valid` will return false for all tags. `DA_GameTagRegistry.ValidateTag()` will fail.

**Alternative — .ini approach:** If you prefer `DefaultGameplayTags.ini`, add entries manually:
```ini
+GameplayTagList=(Tag="Framework.Player.State.Alive",DevComment="Player is alive and active")
+GameplayTagList=(Tag="Framework.Player.State.Dead",DevComment="Player health reached zero")
; ... (all 334 tags)
```
The Data Table approach is recommended because the CSV files are maintained alongside the framework docs.

### 2.3 Asset Manager — Data Asset Registration
`Edit → Project Settings → Asset Manager`

Under **Primary Asset Types to Scan**, add entries for framework Data Asset types:

| Primary Asset Type | Base Class | Has Blueprint Classes | Directory |
|-------------------|-----------|----------------------|-----------|
| `Item` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Items` |
| `Equipment` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Equipment` |
| `Weapon` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Weapons` |
| `AIProfile` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/AI` |
| `Narrative` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Narrative` |
| `Encounter` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Encounters` |
| `Objective` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Objectives` |
| `Puzzle` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Puzzles` |
| `Atmosphere` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Atmosphere` |
| `Scare` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Scares` |
| `Audio` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Audio` |
| `Input` | `PrimaryDataAsset` | ✓ | `/Game/Framework/DataAssets/Input` |

> **⚠️ Why:** This enables `Async Load Primary Asset` for Data Assets. Without it, async loading and the `DA_GameTagRegistry` lookups via Asset Manager will fail.

### 2.4 Collision Presets
`Edit → Project Settings → Collision`

Create these custom Object Channels and Presets:

| Name | Type | Response |
|------|------|----------|
| `Interaction` | **Object Channel** | Used by `BPC_InteractionDetector` traces |
| `HideSpot` | **Object Channel** | Used by `I_HidingSpot` overlap detection |
| `WeaponTrace` | **Trace Channel** | Used by `BPC_FirearmSystem` hitscan |
| `MeleeHitbox` | **Object Channel** | Used by `BPC_MeleeSystem` swing detection |

**Interaction Preset:**
- Block: WorldStatic, WorldDynamic
- Ignore: Pawn, Camera
- Overlap: Interaction objects

---

## 3. Enhanced Input Setup

### 3.1 Input Actions Required (Create in `Content/Framework/Input/Actions/`)

| Input Action | Type | Used By |
|-------------|------|---------|
| `IA_Move` | Axis2D | Movement |
| `IA_Look` | Axis2D | Camera |
| `IA_Jump` | Digital | Jump / Traversal |
| `IA_Sprint` | Digital | Stamina drain |
| `IA_Crouch` | Digital | Posture toggle |
| `IA_Interact` | Digital | InteractionDetector |
| `IA_Fire` | Digital | WeaponBase |
| `IA_Aim` | Digital | ADS aim |
| `IA_Reload` | Digital | ReloadSystem |
| `IA_Melee` | Digital | MeleeSystem |
| `IA_Block` | Digital | Shield / Block |
| `IA_UseItem` | Digital | ActiveItemSystem / Consumable |
| `IA_Hotkey1` through `IA_Hotkey8` | Digital | Quick slot selection |
| `IA_NextItem` | Digital | Cycle quick slot forward |
| `IA_PreviousItem` | Digital | Cycle quick slot backward |
| `IA_Pause` | Digital | Pause menu |
| `IA_Inventory` | Digital | Inventory toggle |
| `IA_Journal` | Digital | Journal toggle |
| `IA_Map` | Digital | Map toggle |
| `IA_SkipCutscene` | Digital | CutsceneBridge skip |
| `IA_SkipDialogue` | Digital | DialoguePlayback skip |
| `IA_Grab` | Digital | PhysicsDragSystem |

### 3.2 Input Mapping Contexts (Create in `Content/Framework/Input/Contexts/`)

| Mapping Context | Priority | Contains |
|----------------|:--------:|----------|
| `IMC_Default` | 0 | Move, Look, Jump, Sprint, Crouch, Interact, Fire, Aim, Reload, Melee, Block, UseItem, Hotkey1-8, NextItem, PreviousItem, Pause, Inventory, Journal, Map, Grab |
| `IMC_Hiding` | 5 | PeekLeft, PeekRight, ExitHide, HoldBreath |
| `IMC_WristwatchUI` | 10 | Menu navigation (d-pad), Confirm, Back |
| `IMC_Inspection` | 20 | RotateItem, ZoomItem, ExitInspect |
| `IMC_UI` | 100 | Menu navigation, Confirm, Back (consumes input) |

### 3.3 Platform Input Profiles
Create `DA_InputMappingProfile` Data Assets per platform:

- `DA_InputProfile_PC` — Keyboard + Mouse bindings
- `DA_InputProfile_Xbox` — Xbox controller bindings
- `DA_InputProfile_PS5` — DualSense bindings

Each profile maps Input Actions to keys/buttons. Reference: `SS_EnhancedInputManager` reads these at init.

---

## 4. Gameplay Tag Configuration

### 4.1 Verify Tag Registration
After adding all 11 Data Tables to Project Settings:

1. Open `DA_GameTagRegistry` → call `GetAllRegisteredTags()` → output should show ~334 tags
2. Call `ValidateTag(Framework.Player.State.Alive)` → should return `true`
3. Call `ValidateTag(NonExistent.Tag)` → should return `false`

### 4.2 Project-Specific Tags
Add project narrative/achievement tags to the existing CSVs (e.g., `DT_Tags_Narrative.csv`) or create a new `DT_Tags_Project.csv`. The `Game.` prefix namespace is reserved for project-specific tags. Example:

```csv
Name,Tag,DevComment
Game_Narrative_MyBossFight,Game.Narrative.Flag.BossDefeated,Boss fight completed
Game_Narrative_MySecretEnding,Game.Narrative.Ending.Secret,Secret ending flag
```

### 4.3 Tag-Driven State Gates
`BPC_StateManager` reads `DA_StateGatingTable` which maps action tags to blocking state tags. Ensure all state tags in the gating table exist in `DT_Tags_State.csv`.

---

## 5. Data Asset Population

### 5.1 Minimum Required Data Assets
Create these before running the game:

| Data Asset | Type | Required For |
|-----------|------|-------------|
| `DA_GameTagRegistry` | Base | Tag validation (loaded by GI_GameFramework.Init) |
| `DA_StateGatingTable` | State | `BPC_StateManager` action permission checks |
| `DA_AudioSettings` | Audio | `SS_AudioManager` bus volumes and defaults |
| `DA_InputMappingProfile` | Input | `SS_EnhancedInputManager` key bindings |
| `DA_AISettings` (or per-enemy) | AI | `AI_BaseAgentController` perception config |

### 5.2 Content Data Assets (Populate as you build content)

| Data Asset | One Per |
|-----------|---------|
| `DA_ItemData` | Each item in the game |
| `DA_EquipmentConfig` | Each weapon / equipment piece |
| `DA_ObjectiveData` | Each quest / objective |
| `DA_DialogueSequence` | Each conversation |
| `DA_PuzzleData` | Each puzzle device |
| `DA_EncounterData` | Each enemy encounter group |
| `DA_AtmosphereProfile` | Each room / zone |
| `DA_ScareEvent` | Each scare event |
| `DA_RoomAcousticPreset` | Each acoustic zone |
| `DA_EndingCondition` | Each ending path |

---

## 6. Player Character Setup

Your player character Blueprint must have these components attached:

| Component | Location | Notes |
|-----------|----------|-------|
| `BPC_HealthSystem` | Character | Must be first-tier for damage cascade |
| `BPC_StaminaSystem` | Character | |
| `BPC_StressSystem` | Character | |
| `BPC_MovementStateSystem` | Character | Bridges to CMC + ABP_GASP |
| `BPC_HidingSystem` | Character | |
| `BPC_InteractionDetector` | Character | |
| `BPC_InventorySystem` | Character | Central authority |
| `BPC_ActiveItemSystem` | Character | Quick slots |
| `BPC_EquipmentSlotSystem` | Character | Equipped items |
| `BPC_ConsumableSystem` | Character | |
| `BPC_KeyItemSystem` | Character | |
| `BPC_DocumentArchiveSystem` | Character | |
| `BPC_JournalSystem` | Character | |
| `BPC_CameraStateLayer` | Character | Camera FOV / shake |
| `BPC_EmbodimentSystem` | Character | First-person body |
| `BPC_PlayerMetricsTracker` | Character | Analytics |
| `BPC_DeathHandlingSystem` | PlayerController | Death orchestrator |
| `BPC_StateManager` | PlayerController | State authority |
| `BPC_ContextualTraversalSystem` | Character | Motion warping vaults |
| `BPC_PhysicsDragSystem` | Character | Grab/drag |

**GASP Integration:** Add your GASP Animation Blueprint to the character's Mesh. `BPC_MovementStateSystem` sets GASP variables directly.

---

## 7. Level Setup

### 7.1 Minimum Level Requirements
Every playable level needs:

- **GameMode override:** `GM_CoreGameMode` (or per-level subclass)
- **Player Start:** Standard `PlayerStart` actor
- **Lighting:** At minimum a DirectionalLight + Skylight

### 7.2 World-Placed Framework Actors
Place these as needed:

| Actor | Purpose |
|-------|---------|
| `BP_DoorActor` | Interactive doors (set LinkedActors, DoorConfig per instance) |
| `BP_ItemPickup` | World items (set ItemData Data Asset per instance) |
| `BP_ContainerInventory` | Lootable containers |
| `BP_PuzzleDeviceActor` | Puzzles (set PuzzleData per instance) |
| `BP_NarrativeTriggerVolume` | Story triggers (set TriggerActions per instance) |
| `BP_Checkpoint` | Respawn points |
| `BP_RoomAudioZone` | Acoustic zones |
| `BP_EnemyBase` | AI enemies (set AIProfile per instance) |
| `BP_PatrolPath` | Enemy patrol routes |

---

## 8. Initialization Sequence (First Boot)

The framework boot order on a fresh project launch:

```
1. Engine creates UGameInstance → GI_GameFramework
2. GI_GameFramework.Init()
   ├─ InitPlatformServices()
   ├─ UE auto-creates all SS_ GameInstanceSubsystems:
   │   ├─ SS_SaveManager.Initialize()
   │   ├─ SS_AudioManager.Initialize() → loads DA_AudioSettings
   │   ├─ SS_EnhancedInputManager.Initialize() → loads DA_InputMappingProfile
   │   ├─ SS_UIManager.Initialize()
   │   └─ SS_AchievementSystem.Initialize()
   ├─ SS_SettingsSystem loads persistent settings
   └─ SetGamePhase(MainMenu)

3. GM_CoreGameMode loads (on level start)
   ├─ Spawns GS_CoreGameState (replicated state bus)
   ├─ Spawns PlayerController → auto-possesses Player Pawn
   └─ All BPC_ components BeginPlay → bind dispatchers

4. PlayerController.BeginPlay()
   ├─ BPC_StateManager.BeginPlay() → load DA_StateGatingTable
   ├─ SS_EnhancedInputManager.PushContext(IMC_Default, Priority=0)
   └─ GI_GameFramework.SetGamePhase(InGame)

5. If loading a save:
   ├─ SS_SaveManager.LoadFromSlot(SlotIndex)
   ├─ Deserializes all I_Persistable actors
   └─ Restores player position, inventory, narrative flags
```

---

## 9. Common Migration Pitfalls

### 9.1 "No Gameplay Tags Registered" Warning
**Cause:** Data Tables not added to `Project Settings → Gameplay Tags → Gameplay Tag Table List`.  
**Fix:** Add all 11 DT_Tags_* tables. Restart editor to refresh tag table.

### 9.2 "GetAllRegisteredTags Returns Empty Array"
**Cause:** `DA_GameTagRegistry.TagDataTables` array is empty (the variable defaults need populating in the Data Asset).  
**Fix:** Open `DA_GameTagRegistry` → set `TagDataTables` array → add all 11 Data Table references.

### 9.3 "SS_Subsystem Not Found" / Null Subsystem
**Cause:** `GI_GameFramework` not set as Default Game Instance in Project Settings.  
**Fix:** `Project Settings → Maps & Modes → Default Game Instance → GI_GameFramework`.

### 9.4 Enhanced Input Not Working
**Cause:** Enhanced Input plugin not enabled, or Input Mapping Contexts not pushed.  
**Fix:** Enable plugin → verify `SS_EnhancedInputManager.PushContext()` is called in PlayerController.BeginPlay.

### 9.5 Motion Warping Traversals Not Aligning
**Cause:** Motion Warping plugin not enabled.  
**Fix:** `Edit → Plugins → Motion Warping → Enable → Restart Editor`.

### 9.6 AI Behavior Trees Not Running
**Cause:** `AI_BaseAgentController` not assigned to enemy pawn, or Blackboard not configured.  
**Fix:** Set `AI Controller Class` on `BP_EnemyBase` to `AI_BaseAgentController`. Ensure `BB_AgentBoard` is assigned.

---

## 10. Testing the Migration

### 10.1 Smoke Test Checklist
- [ ] Editor opens without asset-loading errors
- [ ] PIE (Play In Editor): no `GetSubsystem()` null pointer errors
- [ ] GameplayTag validation: `DA_GameTagRegistry.ValidateTag(Framework.Player.State.Alive)` returns true
- [ ] Player can move (IMC_Default pushed, input routed)
- [ ] Health/Stamina/Stress bars appear on HUD
- [ ] Interaction: approach a door, see prompt, press E → door opens
- [ ] Inventory: pick up an item → appears in inventory UI
- [ ] Combat: fire weapon → damage applies → enemy reacts
- [ ] Save/Load: save game → quit → load → state restored
- [ ] Death: die → respawn at checkpoint
- [ ] State Gating: sprint → reload while sprinting → sprint blocked

---

## 11. Updating This Document

When adding new framework systems that require Project Settings changes:

1. Add the setting to the appropriate section above
2. Update the Prerequisites or Data Asset lists
3. Add a Common Pitfall if the setting is easy to forget
4. Increment the version at the top

---

*Project Setup & Migration Guide v1.0 — Required reading before importing the framework into any UE5 project.*