admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add UI Overrides and Weapons Index documentation for Project Void

Browse Source 
- Created ui-overrides.md detailing game-specific Widget Blueprint overrides, including purpose, widget index, visual styling, and accessibility requirements.
- Established weapons-index.md outlining all held weapon actors, including their components, logic, and comparisons for gameplay mechanics.
This commit is contained in:
Lefteris Notas
2026-05-21 22:27:57 +03:00
parent c515920eea
commit 040db37720
17 changed files with 6795 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
docs/game/README.md
View File

@@ -1,32 +1,86 @@
# Game Examples — Concrete Blueprint Walkthroughs
# Game Examples — "Project Void" Horror Game Prototype
**Directory:** `docs/game/`
**Purpose:** Step-by-step examples of building specific game items using the PG_Framework. Each document shows exactly what to create, what components to add, what Blueprint nodes to wire, and how to verify it works.
**Purpose:** Complete reference documentation for building the "Project Void" psychological horror FPS prototype using the UE5 Modular Game Framework. Every document shows exactly what Blueprint assets to create, how to wire them, and how to integrate with framework systems.
These documents are **separate from the framework** — they belong in a `Content/Game/` folder in your project, not in `Content/Framework/`. The framework provides the rules and systems; these examples show how to use them.
These documents are **separate from the framework** — they describe assets that go in a `Content/Game/` folder, not `Content/Framework/`. The framework provides the rules and systems; these examples show how to build a complete game with them.
---
## How to Use These Examples
## Master Index
Each example follows the same structure:
1. **DA_ItemData** — Create the Data Asset that defines the item's identity
2. **BP_ItemPickup** — Create the world actor that represents the item
3. **Optional: BP_UsableItem** — If the item has active-use behavior (flashlight toggle, weapon fire), create a specialized actor with `I_UsableItem`
4. **Blueprints & Wiring** — Exact node-by-node graphs with screenshots descriptions
5. **Verification** — How to test it works in PIE
| Document | Covers | Status |
|----------|--------|:---:|
| **[GAMEINDEX.md](GAMEINDEX.md)** | **MASTER REFERENCE** — Complete game structure, all 170+ assets, all 135 framework systems mapped, 21-phase build order, scene flow | ✅ |
| **[README.md](README.md)** | **THIS FILE** — How to use these docs, framework separation rules | ✅ |
---
## Example Index
## Core Game Systems (Build Phase 1)
| Example | Item Type | Complexity | What You Learn |
|---------|-----------|-----------|----------------|
| [Flashlight Tool](item-flashlight.md) | `Tool` | Medium | Data Asset setup, `I_UsableItem`, `BP_ItemPickup` Construction Script, soft reference resolution, toggleable function via `I_Toggleable` |
| [Pistol Weapon](item-pistol.md) | `Weapon` | High | `Equipment Data`, `BPC_AmmoComponent`, `I_Equippable`, frame-driven fire, ammo consumption |
| [MedKit Consumable](item-medkit.md) | `Consumable` | Low | `Consumable Data`, quick-slot use, `BPC_HealthSystem` integration |
| [Keycard Key Item](item-keycard.md) | `KeyItem` | Low | `bIsKeyItem`, `I_Lockable` interaction, door unlocking |
| Document | Asset(s) | Systems Demonstrated |
|----------|----------|---------------------|
| [core-gameinstance.md](core-gameinstance.md) | `GI_HorrorGame` | `GI_GameFramework` (04) — boot sequence, subsystem init, save slots |
| [core-gamemode.md](core-gamemode.md) | `GM_HorrorGameMode` | `GM_CoreGameMode` (05) — spawn rules, death routing, chapter transitions |
| [core-controller-state.md](core-controller-state.md) | `PC_HorrorController`, `PS_HorrorPlayerState`, `GS_HorrorGameState` | PlayerController, PlayerState, GameState — input routing, player data, global session state |
---
## Gameplay Systems (Build Phases 2-6)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [scene-flow.md](scene-flow.md) | All 11 `.umap` levels — scene transitions | `GI_GameFramework`, `GM_CoreGameMode`, `SS_UIManager`, `BPC_LoadingScreen`, `WBP_SplashScreen` — complete boot-to-credits scene loading |
| [playercharacter.md](playercharacter.md) | `BP_HorrorPlayerCharacter` (27 components) | All `02-player` (8), `03-interaction` (1), `04-inventory` (8), `08-weapons` (5), `16-state` (1) — the single most important game asset |
| [levels.md](levels.md) | All 11 level maps — layout, objectives, encounters | `GM_CoreGameMode`, `BP_DoorActor`, `BP_Checkpoint`, `BP_NarrativeTriggerVolume`, `BPC_ProceduralEncounter` |
| [ui-overrides.md](ui-overrides.md) | 8 `WBP_Game*` widgets | All 14 `06-ui` systems — MainMenu, HUD, PauseMenu, Inventory, Journal, SplashScreen, DeathScreen, LoadingScreen |
---
## Content Systems (Build Phases 5-13)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [items-index.md](items-index.md) | 13 `DA_Item_*` + 18 `BP_Pickup_*` characters | `DA_ItemData` (07), `BP_ItemPickup` (25), `BPC_InventorySystem` (31), all item types |
| **[item-flashlight.md](item-flashlight.md)** | `DA_Item_Flashlight` + `BP_Pickup_Flashlight` + `BP_Flashlight_Held` | Tool, `I_UsableItem`, `I_Toggleable` — FULL BUILD |
| **[item-pistol.md](item-pistol.md)** | `DA_Item_Pistol` + `BP_Pickup_Pistol` + `BP_Pistol_Held` | Weapon, hitscan, ammo, recoil, reload — FULL BUILD |
| **[item-medkit.md](item-medkit.md)** | `DA_Item_MedKit` + `BP_Pickup_MedKit` | Consumable, health restore — FULL BUILD |
| **[item-keycard.md](item-keycard.md)** | `DA_Item_KeycardOmega` + `BP_Pickup_KeycardOmega` + `BP_Door_OmegaWing` | KeyItem, `I_Lockable`, door unlocking — FULL BUILD |
| [weapons-index.md](weapons-index.md) | `BP_Pistol_Held`, `BP_Shotgun_Held`, `BP_Flashlight_Held`, `BP_Crowbar_Held` | `BP_WeaponBase` (69), `BPC_FirearmSystem` (74), `BPC_MeleeSystem` (76), pellet spread, shell reload |
| [enemies-index.md](enemies-index.md) | 3 enemy types + 1 NPC + 3 AI controllers + 3 behavior trees + 3 blackboards | All `09-ai` (9): `BP_EnemyBase`, `BPC_AlertSystem`, `BPC_AIStateMachine`, `BPC_AIPerceptionSystem`, `BPC_AIMemorySystem` |
---
## Narrative & Progression (Build Phase 13)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [narrative-progression.md](narrative-progression.md) | 4 `DA_Dialogue_*`, 4 `DA_Objective_*`, 2 `DA_Cutscene_*`, 4 `BP_NarrativeTriggerVolume`, lore entries | All `07-narrative` (11): `BPC_NarrativeStateSystem`, `BPC_ObjectiveSystem`, `BPC_DialoguePlaybackSystem`, `BPC_DialogueChoiceSystem`, `BPC_BranchingConsequenceSystem`, `BPC_CutsceneBridge`, `BPC_EndingAccumulator` — 3 endings |
---
## Atmosphere, Audio & Scares (Build Phases 14-18)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [atmosphere-audio.md](atmosphere-audio.md) | 6 `DA_AtmosphereProfile`, 6 `DA_RoomAcousticPreset`, 6 `DA_ScareEvent`, 6 `BP_RoomAudioZone`, light events, memory drift | All `10-adaptive` (15) including `132-135` MetaSounds Audio: `SS_AudioManager`, `BP_RoomAudioZone`, `BPC_ScareEventSystem`, `BPC_LightEventController`, `BPC_MemoryDriftSystem`, `BPC_PacingDirector`, `BPC_AdaptiveEnvironmentDirector` |
---
## Save, Death & Persistence (Build Phase 15)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [save-checkpoints.md](save-checkpoints.md) | 4 `BP_Checkpoint_*`, death screen, void space logic | All `05-saveload` (9): `SS_SaveManager`, `BPC_DeathHandlingSystem`, `BPC_AltDeathSpaceSystem`, `BPC_PlayerRespawnSystem`, `BPC_PersistentCorpseSystem`, `BPC_PersistentWorldStateRecorder`, `BPC_RunHistoryTracker`, `I_Persistable` |
---
## Polish & State Gating (Build Phases 19-21)
| Document | Assets | Systems Demonstrated |
|----------|--------|---------------------|
| [polish-loading-credits.md](polish-loading-credits.md) | 6 `BP_TutorialTrigger_*`, `WBP_CreditsScreen`, `WBP_DebugMenu`, `BPC_DevCheatManager` | All `13-polish` (9): `BPC_TutorialSystem`, `BPC_LoadingScreen`, `BPC_AnalyticsTracker`, `BPC_DevCheatManager`, `BPC_ErrorHandler`, `BPC_FPSCounter`, `WBP_CreditsScreen`, `WBP_DebugMenu` |
| [state-gating-examples.md](state-gating-examples.md) | `DA_StateGatingTable_Horror` | `BPC_StateManager` (130), `DA_StateGatingTable` (131) — 15 game-specific gating rules, void space restrictions, horror state logic |
---
@@ -34,39 +88,115 @@ Each example follows the same structure:
```
Content/
├── Framework/ ← Framework systems (read-only, don't modify)
├── Framework/ ← Framework systems (READ-ONLY — NEVER modify)
│ ├── Core/ GI_GameFramework, DA_GameTagRegistry, etc.
│ ├── Player/ BPC_HealthSystem, BPC_StateManager, etc.
│ ├── Inventory/ BP_ItemPickup base, BPC_InventorySystem
│ ├── DataAssets/ DA_ItemData, DA_EquipmentConfig, etc.
│ ├── Weapons/ BP_WeaponBase, BPC_FirearmSystem, etc.
│ ├── UI/ All WBP_* framework widgets
│ ├── AI/ BP_EnemyBase, AI_BaseAgentController, etc.
│ ├── DataAssets/ All DA_* framework Data Assets
│ ├── Input/ All IA_* Input Actions, IMC_* Contexts
│ ├── State/ BPC_StateManager, DA_StateGatingTable, enums
│ ├── Audio/ MS_* MetaSound buses, SS_AudioManager
│ └── ...
│
└── Game/ ← YOUR project content (this is what you create)
├── Items/ DA_ItemData instances (DA_Item_MedKit, DA_Item_Flashlight)
├── Weapons/ DA_ItemData weapon instances (DA_Item_Pistol)
├── Pickups/ BP_Pickup_* children (BP_Pickup_MedKit, BP_Pickup_Flashlight)
├── Actors/ BP_Door_*, BP_Puzzle_* instances
└── ...
└── Game/ ← YOUR PROJECT CONTENT (this is what you create)
├── Core/ GI_HorrorGame, GM_HorrorGameMode, PC/PS/GS
├── Characters/ BP_HorrorPlayerCharacter, BP_Enemy_*, BP_NPC_*
├── Items/ All DA_Item_* Data Assets (13 items)
├── Pickups/ All BP_Pickup_* actors (18 pickups)
├── Actors/ BP_Door_*, BP_Puzzle_*, BP_HidingSpot_*, etc.
├── Weapons/ BP_Pistol_Held, BP_Shotgun_Held, etc.
├── UI/ All WBP_Game* widgets (8 widgets)
├── DataAssets/ All DA_* content instances (20+)
├── AI/ AI controllers, behavior trees, blackboards
├── Narrative/ DA_Dialogue_*, DA_Objective_*, trigger volumes
├── Encounters/ BP_EncounterSpawner_*
├── Atmosphere/ BP_LightEvent_*, BP_ScareEvent_*
├── Audio/ BP_RoomAudioZone_*, DA_AudioSettings_Horror
├── Save/ BP_Checkpoint_* instances
├── Polish/ BP_TutorialTrigger_*
├── Input/ Game-specific input overrides (if any)
└── Maps/ All 11 .umap levels
```
> **Rule:** Never modify files in `Content/Framework/`. Create your assets in `Content/Game/` and reference framework systems via interfaces and dispatchers.
> **Rule:** Never modify files in `Content/Framework/`. Create your assets in `Content/Game/` as **children** of framework classes and reference framework systems via interfaces, event dispatchers, and Data Asset references.
---
## Reference — Framework Systems Used by These Examples
## How to Build This Prototype
| Framework System | Asset Path | Used For |
|-----------------|-----------|----------|
| `DA_ItemData` | `Content/Framework/DataAssets/Items/` (C++ class) | Item identity definition |
| `BP_ItemPickup` | `Content/Framework/Inventory/` (base BP) | World pickup actor |
| `BPC_InventorySystem` | C++ component (auto-attach to pawn) | Add/remove/query items |
| `BPC_HealthSystem` | C++ stub → BP child on pawn | Taking/healing damage |
| `BPC_DamageReceptionSystem` | C++ component (auto-attach to pawn) | Damage pipeline |
| `BPC_ConsumableSystem` | BP child on pawn | Using consumable items |
| `BPC_EquipmentSlotSystem` | BP child on pawn | Equipping weapons/tools |
| `BPC_KeyItemSystem` | BP child on pawn | Key item unlock logic |
| `I_Interactable` | C++ interface in `I_InterfaceLibrary.h` | Interaction detection |
| `I_UsableItem` | C++ interface in `I_InterfaceLibrary.h` | Active-use items (flashlight, weapon) |
| `I_Toggleable` | C++ interface in `I_InterfaceLibrary.h` | On/off state (flashlight toggle) |
| `I_Lockable` | C++ interface in `I_InterfaceLibrary.h` | Locked doors/containers |
| `I_Damageable` | C++ interface in `I_InterfaceLibrary.h` | Receiving damage |
### Phase-by-Phase (from GAMEINDEX.md)
1. **Project Settings** — Enable plugins, register 11 GameplayTag Data Tables, set Asset Manager
2. **Core Classes** — Create 5 game-specific children of framework classes
3. **Maps** — Create splash, menu, and sandbox levels
4. **Player Character** — Build BP_HorrorPlayerCharacter with all 27 components
5. **Items & Pickups** — Create all 13 Data Assets + 18 pickup actors
6. **Doors & Actors** — Create all interaction actors
7. **Weapons** — Create 4 held weapon/tool actors
8. **UI** — Create 8 game-specific widget overrides
9. **Enemies** — Create 3 enemy types with full AI
10. **Narrative** — Create dialogue, objectives, cutscenes, ending system
11. **Atmosphere & Audio** — Create profiles, scare events, room zones
12. **Save System** — Create checkpoints, wire death/respawn/void space
13. **Polish** — Tutorials, loading screen, credits, debug, analytics
14. **State Gating** — Configure game-specific state rules
15. **Full Levels** — Populate all 11 maps with placed assets
### Each document provides:
1. **What to create** — Exact asset name, parent class, folder location
2. **Blueprint wiring** — Node-by-node logic flows, event graph structure
3. **Variables & configuration** — Every variable with type, default, purpose
4. **Integration points** — How the game asset talks to framework systems
5. **Verification checklist** — How to test it works
---
## Reference — Framework Systems Used
All 135 framework Blueprint systems are covered by at least one game asset. See [GAMEINDEX.md](GAMEINDEX.md) for the complete framework-to-game mapping.
| System Category | Framework Systems | Game Assets That Use Them |
|----------------|:---:|---|
| 00-project-setup | 1 | `GI_StarterGameInstance` → `GI_HorrorGame` |
| 01-core | 7 + 11 CSVs | `GI_HorrorGame`, `GM_HorrorGameMode`, `GS_HorrorGameState`, all items/pickups/doors |
| 02-player | 8 | `BP_HorrorPlayerCharacter` (all 8 components) |
| 03-interaction | 8 | All doors, puzzles, hiding spots, usable objects, pickups |
| 04-inventory | 11 | `BP_HorrorPlayerCharacter` (all 11 components), all pickups, containers |
| 05-saveload | 9 | Checkpoints, death system, void space, respawn, persistence |
| 06-ui | 14 | All 8 `WBP_Game*` widget overrides |
| 07-narrative | 11 | Dialogue, objectives, cutscenes, branching choices, endings |
| 08-weapons | 11 | All 4 held weapons, ammo, recoil, reload, hit reactions |
| 09-ai | 9 | 3 enemy types with full AI setup |
| 10-adaptive | 15 | Atmosphere profiles, scare events, lighting, memory drift, pacing, room audio |
| 11-meta | 2 | Achievements, progress stats |
| 12-settings | 2 | Settings menu, accessibility |
| 13-polish | 9 | Tutorials, loading, credits, debug, analytics, error handling |
| 14-data-assets | 16 | All DA_* content instances |
| 15-input | 1 | All input actions + contexts via `SS_EnhancedInputManager` |
| 16-state | 2 | State gating rules, GASP liaison, vital signals |
---
## Notes for Expansion
This prototype covers the **minimum viable product** to demonstrate all 135 framework systems. For a full game:
- Replace whitebox meshes with final art assets
- Record professional audio (150+ sound triggers per sound catalog)
- Write complete narrative with branching dialogue for all interactions
- Add 10+ puzzle devices with increasing complexity
- Create 20+ scare events with unique anticipation/payoff pairs
- Implement adaptive difficulty with player metrics feedback loop
- Add 3-5 ending variations
- Localize all text into multiple languages
- Add multiplayer support (server-authoritative replication)
- Create platform-specific builds (PC, Xbox, PS5)
See each individual document's **"Notes for Expansion"** section for system-specific extension ideas.
---
*README v2.0 — Complete game prototype documentation for Project Void. See [GAMEINDEX.md](GAMEINDEX.md) for the master game structure reference.*