diff --git a/CONTEXT.md b/CONTEXT.md index 742742d..584fb4a 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -91,9 +91,10 @@ docs/ 15-input/ # Enhanced Input System (1 file, 128) 16-state/ # State Management (2 files, 130-131) developer/ # Developer Reference Docs (NEW) - INDEX.md # Master developer docs index (11 docs) + INDEX.md # Master developer docs index (12 docs) architecture-overview.md # Framework-wide architecture walkthrough implementation-patterns.md # Common UE5 Blueprint patterns used + project-setup-migration.md # Project setup & migration guide (NEW — Project Settings, plugins, init sequence) 01-core-foundation.md # Foundation systems explained 02-player-systems.md # Player state & embodiment explained 03-interaction-systems.md # Interaction & world manipulation explained @@ -122,7 +123,7 @@ docs/ enhanced-input-system.md bpc-statemanager.md # NEW — State Manager implementation checklist ``` -**Total: 135 numbered Blueprint files + 5 enums + 5 Data Assets + 11 Data Table CSVs + TEMPLATE.md + AUDIT_REPORT.md + INDEX.md + 11 developer docs + 8 architecture docs + 1 audit report = 177 files in 19 directory groups** +**Total: 135 numbered Blueprint files + 5 enums + 5 Data Assets + 11 Data Table CSVs + TEMPLATE.md + AUDIT_REPORT.md + INDEX.md + 12 developer docs + 8 architecture docs + 1 audit report = 178 files in 19 directory groups** ## Naming Conventions | Prefix | Type | diff --git a/docs/developer/INDEX.md b/docs/developer/INDEX.md index 0455a47..d202f42 100644 --- a/docs/developer/INDEX.md +++ b/docs/developer/INDEX.md @@ -1,6 +1,6 @@ # Developer Reference — UE5 Modular Game Framework -**Version:** 1.1 | **Generated:** 2026-05-19 | **Files:** 14 (1 index + 2 overview + 10 category docs + 1 combined) | **Networking:** All docs include multiplayer sections +**Version:** 1.2 | **Generated:** 2026-05-19 | **Files:** 15 (1 index + 2 overview + 1 migration + 10 category docs + 1 combined) | **Networking:** All docs include multiplayer sections This directory contains developer-facing reference documentation for every system in the framework. Unlike the blueprint spec files (which define *what* to build), these documents explain *how each system works internally* — the data flow, state machines, integration points, and design rationale. Use these when you need to understand a system's behavior to implement, debug, or extend it. @@ -18,6 +18,7 @@ docs/developer/ ├── INDEX.md ← THIS FILE ├── architecture-overview.md ← Framework-wide architecture walkthrough ├── implementation-patterns.md ← Common UE5 Blueprint patterns used +├── project-setup-migration.md ← Project setup & migration guide (NEW — Project Settings, plugins, init sequence) │ ├── 01-core-foundation.md ← Foundation systems (systems 01-07) ├── 02-player-systems.md ← Player state & embodiment (systems 08-15) @@ -175,10 +176,12 @@ docs/developer/ ## How to Use These Docs 1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture. -2. **Implementing a system?** Find it in the quick reference above, then read its category document. -3. **Debugging?** Each category doc includes a data flow section showing how data moves between systems. -4. **Need implementation patterns?** See [`implementation-patterns.md`](implementation-patterns.md) for common UE5 Blueprint patterns. -5. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md) for the full networking architecture. Every category doc has a Multiplayer Networking section. +2. **Setting up a new project?** Read [`project-setup-migration.md`](project-setup-migration.md) — covers all Project Settings, plugins, Data Tables, Enhanced Input, and initialization sequence. +3. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic. +4. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory. +5. **Debugging?** Each category doc includes a data flow section showing how data moves between systems. +6. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md). +7. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section. ## Relationship to Spec Files @@ -187,8 +190,8 @@ docs/developer/ | **Purpose** | Define what to build with node-by-node logic (v2.0) | Explain how it works (understanding) | | **Audience** | Implementers building Blueprints manually | Anyone needing to understand internals | | **Content** | Enums, structs, variables, functions, **Manual Implementation Guide** | Data flow, state machines, design rationale | -| **Format** | TEMPLATE.md v2.0 — includes Build Checklist | Per-category reference docs | +| **Format** | TEMPLATE.md v2.0 — includes Build Checklist | Per-category reference docs + project-setup-migration.md | --- -*Developer Reference Index v1.0 — Companion to the Blueprint Spec system. Update both together.* +*Developer Reference Index v1.2 — Companion to the Blueprint Spec system. Update both together.* diff --git a/docs/developer/project-setup-migration.md b/docs/developer/project-setup-migration.md new file mode 100644 index 0000000..9251d01 --- /dev/null +++ b/docs/developer/project-setup-migration.md @@ -0,0 +1,384 @@ +# 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.*