This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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:

Open DA_GameTagRegistry → call GetAllRegisteredTags() → output should show ~334 tags
Call ValidateTag(Framework.Player.State.Alive) → should return true
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:

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

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