# Developer Reference — UE5 Modular Game Framework

**Version:** 1.5 | **Generated:** 2026-05-21 | **Files:** 18 (1 index + 2 overview + 1 migration + 1 integration + 1 prototype + 1 starter + 10 category docs + 1 combined) | **C++:** 12 full + 10 stubs = 22 systems

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.

## Who This Is For

- **Blueprint implementers** turning `.md` specs into actual UE5 Blueprint assets
- **Debuggers** tracing why something doesn't work
- **Designers** needing to understand constraints before modifying Data Assets
- **New team members** learning the framework's internal logic

## Directory Map

```
docs/developer/
├── INDEX.md                              ← THIS FILE
├── architecture-overview.md              ← Framework-wide architecture walkthrough
├── implementation-patterns.md            ← Common UE5 Blueprint patterns used
├── cpp-integration-guide.md              ← C++ per-system integration & setup (22 systems)
├── project-setup-migration.md            ← Project setup & migration guide
├── project-prototype-guide.md            ← Step-by-step prototype build guide (NEW)
├── 00-starter-gameinstance.md            ← Starter GameInstance: GI_StarterGameInstance setup guide
├── 01-core-foundation.md                 ← Foundation systems explained
├── 02-player-systems.md                  ← Player state & embodiment (systems 08-15)
├── 03-interaction-systems.md             ← Interaction & world manipulation (systems 16-23)
├── 04-inventory-systems.md               ← Inventory, items & collectibles (systems 24-34)
├── 05-saveload-systems.md                ← Save/load, persistence, death loop (systems 35-43)
├── 06-ui-systems.md                      ← UI, menus & diegetic presentation (systems 44-57)
├── 07-narrative-systems.md               ← Narrative, dialogue, objectives (systems 58-68)
├── 08-weapons-systems.md                 ← Weapons, equipment & damage (systems 69-79)
├── 09-ai-systems.md                      ← AI, perception & encounters (systems 80-88)
├── 10-adaptive-systems.md                ← Adaptive environment & atmosphere (systems 89-101, 132-133)
└── 11-16-systems.md                      ← Meta, Settings, Polish, Data Assets, Input, State (systems 102-135)
```

## Quick Reference — Every System at a Glance

| # | System | Category | Role |
|---|--------|----------|------|
| — | `GI_StarterGameInstance` | Project Setup | Minimal GameInstance; tag validation entry point |
| 01 | `DA_GameTagRegistry` | Foundation | Central GameplayTag → asset registry |
| 02 | `FL_GameUtilities` | Foundation | Shared utility functions (logging, math) |
| 03 | `I_InterfaceLibrary` | Foundation | All framework interfaces |
| 04 | `GI_GameFramework` | Foundation | Application kernel; owns subsystems |
| 05 | `GM_CoreGameMode` | Foundation | Spawns player, manages game rules |
| 06 | `GS_CoreGameState` | Foundation | Shared game state, phase tracker |
| 07 | `DA_ItemData` | Foundation | Base item data asset |
| 08 | `BPC_HealthSystem` | Player | Health, damage, death trigger |
| 09 | `BPC_StaminaSystem` | Player | Stamina pool, sprint drain, exhaustion |
| 10 | `BPC_StressSystem` | Player | Psychological stress tiers, hallucinations |
| 11 | `BPC_MovementStateSystem` | Player | Movement mode + posture, GASP liaison |
| 12 | `BPC_HidingSystem` | Player | Hide/peek/breath-hold, LOS checks |
| 13 | `BPC_EmbodimentSystem` | Player | First-person body, arm IK, overlays |
| 14 | `BPC_CameraStateLayer` | Player | Camera FOV/offset per state |
| 15 | `BPC_PlayerMetricsTracker` | Player | Player metrics: accuracy, deaths, ratios |
| 16 | `BPC_InteractionDetector` | Interaction | Raycast interaction detection |
| 17 | `I_HidingSpot` | Interaction | Interface for hideable objects |
| 18 | `BPC_DiegeticDisplay` | Interaction | In-world screens (wristwatch, monitors) |
| 19 | `BP_DoorActor` | Interaction | Physical door with state machine |
| 20 | `BP_PuzzleDeviceActor` | Interaction | Puzzle device base actor |
| 21 | `BPC_ContextualTraversalSystem` | Interaction | Vault/mantle/slide/squeeze/climb |
| 22 | `BPC_PhysicsDragSystem` | Interaction | Grab/drag/release physics objects |
| 23 | `BPC_UsableWorldObjectSystem` | Interaction | Generic world object use (levers, buttons) |
| 24 | `BPC_ContainerInventory` | Inventory | World container inventory |
| 25 | `BP_ItemPickup` | Inventory | Physical item pickup in world |
| 26 | `BPC_ActiveItemSystem` | Inventory | Quick-slot item management |
| 27 | `BPC_CollectibleTracker` | Inventory | Collectible tracking, set bonuses |
| 28 | `BPC_ConsumableSystem` | Inventory | Consumable use (health packs, syringes) |
| 29 | `BPC_DocumentArchiveSystem` | Inventory | Document/journal archive |
| 30 | `BPC_EquipmentSlotSystem` | Inventory | Equipment slots, equip/unequip |
| 31 | `BPC_InventorySystem` | Inventory | Core inventory grid |
| 32 | `BPC_ItemCombineSystem` | Inventory | Item combination crafting |
| 33 | `BPC_JournalSystem` | Inventory | Quest/objective journal |
| 34 | `BPC_KeyItemSystem` | Inventory | Key item tracking, use-on-target |
| 35 | `SS_SaveManager` | Save/Load | Save/load subsystem |
| 36 | `I_Persistable` | Save/Load | Persistence interface |
| 37 | `BP_Checkpoint` | Save/Load | Checkpoint actor |
| 38 | `BPC_AltDeathSpaceSystem` | Save/Load | Alternate death/void space |
| 39 | `BPC_DeathHandlingSystem` | Save/Load | Death orchestrator |
| 40 | `BPC_PersistentCorpseSystem` | Save/Load | Corpse persistence |
| 41 | `BPC_PersistentWorldStateRecorder` | Save/Load | World state change recording |
| 42 | `BPC_PlayerRespawnSystem` | Save/Load | Respawn logic |
| 43 | `BPC_RunHistoryTracker` | Save/Load | Run/session history |
| 44 | `SS_UIManager` | UI | UI subsystem, menu stack |
| 45 | `WBP_AccessibilityUI` | UI | Accessibility settings UI |
| 46 | `WBP_DiegeticHUDFrame` | UI | Diegetic in-world HUD frame |
| 47 | `WBP_HUDController` | UI | Root HUD widget |
| 48 | `WBP_InteractionPromptDisplay` | UI | Interaction prompt popup |
| 49 | `WBP_InventoryMenu` | UI | Inventory grid UI |
| 50 | `WBP_JournalDocumentViewer` | UI | Document/journal viewer |
| 51 | `WBP_MainMenu` | UI | Main menu |
| 52 | `WBP_MenuFlowController` | UI | Menu state machine |
| 53 | `WBP_NotificationToast` | UI | Toast notification |
| 54 | `WBP_ObjectiveDisplay` | UI | Active objective HUD element |
| 55 | `WBP_PauseMenu` | UI | Pause menu |
| 56 | `WBP_ScreenEffectController` | UI | Full-screen effects |
| 57 | `WBP_SettingsMenu` | UI | Settings menu |
| 58 | `BPC_NarrativeStateSystem` | Narrative | Narrative state machine |
| 59 | `BPC_ObjectiveSystem` | Narrative | Objective tracker |
| 60 | `BPC_DialoguePlaybackSystem` | Narrative | Dialogue playback |
| 61 | `BPC_DialogueChoiceSystem` | Narrative | Dialogue choices |
| 62 | `BPC_BranchingConsequenceSystem` | Narrative | Consequence execution |
| 63 | `BPC_TrialScenarioSystem` | Narrative | Timed trial/puzzle scenario |
| 64 | `BPC_CutsceneBridge` | Narrative | Cutscene bridge |
| 65 | `BPC_LoreUnlockSystem` | Narrative | Lore/journal unlock |
| 66 | `DA_NarrativeDataAssets` | Narrative | Narrative data assets |
| 67 | `BP_NarrativeTriggerVolume` | Narrative | Narrative trigger volume |
| 68 | `BPC_EndingAccumulator` | Narrative | Ending condition tracker |
| 69 | `BP_WeaponBase` | Weapons | Weapon base actor |
| 70 | `BPC_AmmoComponent` | Weapons | Ammo pool |
| 71 | `BPC_CombatFeedbackComponent` | Weapons | Combat feedback (hit markers) |
| 72 | `BPC_DamageReceptionSystem` | Weapons | Damage reception/resistance |
| 73 | `BPC_DeathCauseTracker` | Weapons | Death cause logging |
| 74 | `BPC_FirearmSystem` | Weapons | Firearm specialization |
| 75 | `BPC_HitReactionSystem` | Weapons | Hit reaction animations |
| 76 | `BPC_MeleeSystem` | Weapons | Melee weapon system |
| 77 | `BPC_RecoilSystem` | Weapons | Recoil pattern |
| 78 | `BPC_ReloadSystem` | Weapons | Reload system |
| 79 | `BPC_ShieldDefenseSystem` | Weapons | Shield defense |
| 80 | `BP_EnemyBase` | AI | Enemy base character |
| 81 | `BP_PatrolPath` | AI | Patrol path spline |
| 82 | `BPC_AlertSystem` | AI | AI alert states |
| 83 | `BPC_AIStateMachine` | AI | AI state machine |
| 84 | `AI_BaseAgentController` | AI | Base AI controller |
| 85 | `BB_AgentBoard` | AI | AI blackboard definition |
| 86 | `BPC_AIMemorySystem` | AI | AI memory/last known locations |
| 87 | `BPC_AIPerceptionSystem` | AI | AI perception (sight/hearing) |
| 88 | `BPC_BehaviourVariantSelector` | AI | Behavior variant selection |
| 89 | `BPC_DifficultyManager` | Adaptive | Dynamic difficulty scaling |
| 90 | `BPC_FearSystem` | Adaptive | Fear system (AI + player) |
| 91 | `BPC_PerformanceScaler` | Adaptive | Performance scaling (LOD) |
| 92 | `BPC_ProceduralEncounter` | Adaptive | Procedural encounter generation |
| 93 | `BPC_AdaptiveEnvironmentDirector` | Adaptive | Adaptive environment director |
| 94 | `BPC_AtmosphereStateController` | Adaptive | Atmosphere state (tone, tension) |
| 95 | `BPC_AudioAtmosphereController` | Adaptive | Audio atmosphere [DEPRECATED] |
| 96 | `BPC_LightEventController` | Adaptive | Light events (flicker/strobe) |
| 97 | `BPC_MemoryDriftSystem` | Adaptive | Memory drift distortions |
| 98 | `BPC_PacingDirector` | Adaptive | Pacing director |
| 99 | `BPC_PlaystyleClassifier` | Adaptive | Playstyle classification |
| 100 | `BPC_RareEventSystem` | Adaptive | Rare event system |
| 101 | `BPC_ScareEventSystem` | Adaptive | Scare event system |
| 102 | `BPC_ProgressStatTracker` | Meta | Progress statistics |
| 103 | `SS_AchievementSystem` | Meta | Achievement subsystem |
| 104 | `BPC_AccessibilitySettings` | Settings | Accessibility settings |
| 105 | `SS_SettingsSystem` | Settings | Persistent settings subsystem |
| 106 | `BPC_AnalyticsTracker` | Polish | Analytics/telemetry |
| 107 | `BPC_DevCheatManager` | Polish | Developer cheats |
| 108 | `BPC_ErrorHandler` | Polish | Error/crash handling |
| 109 | `BPC_FPSCounter` | Polish | FPS counter |
| 110 | `BPC_LoadingScreen` | Polish | Loading screen |
| 111 | `BPC_TutorialSystem` | Polish | Tutorial system |
| 112 | `WBP_CreditsScreen` | Polish | Credits screen |
| 113 | `WBP_DebugMenu` | Polish | Debug menu |
| 114 | `WBP_SplashScreen` | Polish | Splash screen |
| 115 | `DA_AdaptationRule` | Data Assets | Difficulty adaptation rules |
| 116 | `DA_AtmosphereProfile` | Data Assets | Atmosphere profile (audio/light/FX) |
| 117 | `DA_BehaviourVariant` | Data Assets | AI behavior variant |
| 118 | `DA_DataAssetArchitecture` | Data Assets | Data asset architecture overview |
| 119 | `DA_EncounterData` | Data Assets | Encounter definition |
| 120 | `DA_EquipmentConfig` | Data Assets | Equipment configuration |
| 121 | `DA_HapticProfile` | Data Assets | Haptic feedback profile |
| 122 | `DA_InteractionData` | Data Assets | Interaction definition |
| 123 | `DA_ObjectiveData` | Data Assets | Objective/quest data |
| 124 | `DA_PuzzleData` | Data Assets | Puzzle definition |
| 125 | `DA_RareEvent` | Data Assets | Rare event definition |
| 126 | `DA_RoomMutation` | Data Assets | Room mutation definition |
| 127 | `DA_ScareEvent` | Data Assets | Scare event definition |
| 128 | `SS_EnhancedInputManager` | Input | Enhanced Input manager |
| 129 | `DA_InputMappingProfile` | Data Assets | Input mapping profile per platform |
| 130 | `BPC_StateManager` | State | Central state authority |
| 131 | `DA_StateGatingTable` | State | State gating rules |
| 132 | `SS_AudioManager` | Adaptive | Audio subsystem (MetaSounds) |
| 133 | `BP_RoomAudioZone` | Adaptive | Room audio zone trigger |
| 134 | `DA_AudioSettings` | Data Assets | Audio bus/settings config |
| 135 | `DA_RoomAcousticPreset` | Data Assets | Room acoustic profile |

## How to Use These Docs

1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture.
2. **Setting up a new project?** Read [`00-starter-gameinstance.md`](00-starter-gameinstance.md) first — create `GI_StarterGameInstance` to validate your GameplayTags immediately. Then follow [`project-setup-migration.md`](project-setup-migration.md) for full Project Settings, plugins, Data Tables, and init sequence.
3. **Building a prototype?** Follow [`project-prototype-guide.md`](project-prototype-guide.md) — step-by-step instructions from blank project to working test character with verification checklist.
4. **Using the C++ classes?** Read [`cpp-integration-guide.md`](cpp-integration-guide.md) — per-system setup steps, Blueprint children to create, usage patterns, and build order. See [`../checklists/cpp-blueprint-status.md`](../checklists/cpp-blueprint-status.md) for the full 135-system status grid.
5. **Need the prioritized BP build list?** See [`../checklists/remaining-blueprint-build-order.md`](../checklists/remaining-blueprint-build-order.md) — every system with C++ status, what BP to build, and dependency-safe order.
6. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
7. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
8. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
9. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md).
10. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section.

## Relationship to Spec Files

| Aspect | Blueprint Spec (`docs/blueprints/`) | Developer Reference (`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 + cpp-integration-guide + project-setup-migration |

---

*Developer Reference Index v1.4 — Companion to the Blueprint Spec system. Update both together.*