commit a742985fb358dcb1792a1cd18f83ec0f6fc3deac Author: admin Date: Tue May 19 11:08:17 2026 +0000 Add UE5 Modular Game Framework diff --git a/UE5-Modular-Game-Framework.md b/UE5-Modular-Game-Framework.md new file mode 100644 index 0000000..9c6a40e --- /dev/null +++ b/UE5-Modular-Game-Framework.md @@ -0,0 +1,198 @@ +# Developer Reference — UE5 Modular Game Framework + +**Version:** 1.0 | **Generated:** 2026-05-19 + +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 +│ +├── 01-core-foundation.md ← Foundation systems (systems 01-07) +├── 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-meta-systems.md ← Achievements & progression (systems 102-103) +├── 12-settings-systems.md ← Settings & accessibility (systems 104-105) +├── 13-polish-systems.md ← Tutorial, loading, credits, debug (systems 106-114) +├── 14-data-assets.md ← Data Asset definitions (systems 115-127, 129, 134-135) +├── 15-input-system.md ← Enhanced Input System (system 128) +└── 16-state-management.md ← State Management (systems 130-131) +``` + +## Quick Reference — Every System at a Glance + +| # | System | Category | Role | +|---|--------|----------|------| +| 01 | `GI_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. **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. + +## Relationship to Spec Files + +| Aspect | Blueprint Spec (`docs/blueprints/`) | Developer Reference (`docs/developer/`) | +|--------|--------------------------------------|----------------------------------------| +| **Purpose** | Define what to build (contract) | Explain how it works (understanding) | +| **Audience** | Implementers following a spec | Anyone needing to understand internals | +| **Content** | Enums, structs, variables, functions | Data flow, state machines, design rationale | +| **Updates** | When design changes | When implementation details change | + +--- + +*Developer Reference Index v1.0 — Companion to the Blueprint Spec system. Update both together.*