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:

+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:

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.