# Game Examples — "Project Void" Horror Game Prototype

**Directory:** `docs/game/`
**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 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.

---

## Master Index

| 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 | ✅ |

---

## Core Game Systems (Build Phase 1)

| 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 |

---

## Folder Structure in Your UE5 Project

```
Content/
├── 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
│   ├── 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)
    ├── 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/` as **children** of framework classes and reference framework systems via interfaces, event dispatchers, and Data Asset references.

---

## How to Build This Prototype

### 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.*


All tasks complete. Here's a summary of what was built:

---

## Summary — "Project Void" Game Prototype Documentation

**21 files** in `docs/game/` documenting a complete psychological horror FPS prototype that covers all 135 framework Blueprint systems.

### Master Reference
| File | Lines | Content |
|------|:---:|---------|
| **GAMEINDEX.md** | ~450 | Master game structure — 170+ asset catalog, 135 system coverage map, 21-phase build order, full `Content/Game/` folder tree, scene flow diagram |
| **README.md** | ~180 | Updated to document all 21 files with index, build phases, folder structure |

### Core Systems (3 docs)
| File | Lines | Content |
|------|:---:|---------|
| `core-gameinstance.md` | ~120 | `GI_HorrorGame` — boot sequence, subsystem init, save slots, first-launch flow |
| `core-gamemode.md` | ~200 | `GM_HorrorGameMode` — spawn rules, death routing, void space branching, ending triggers, chapter transitions |
| `core-controller-state.md` | ~180 | `PC_HorrorController` + `PS_HorrorPlayerState` + `GS_HorrorGameState` — input, heartbeat haptics, sanity, fear, session data |

### Gameplay Systems (4 docs)
| File | Lines | Content |
|------|:---:|---------|
| `scene-flow.md` | ~350 | Complete scene flow — Splash → Menu → 7 gameplay levels → 3 endings → Credits, with pause/death/void branches |
| `playercharacter.md` | ~350 | `BP_HorrorPlayerCharacter` — 27 components, all input bindings with state gating, dispatcher wiring, health/stamina/stress triad |
| `levels.md` | ~400 | All 11 `.umap` levels — layout diagrams, placed assets, objectives per level, atmosphere config, dev sandbox |
| `ui-overrides.md` | ~350 | 8 `WBP_Game*` widgets — MainMenu, HUD, PauseMenu, Inventory, Journal, SplashScreen, DeathScreen, LoadingScreen with horror styling |

### Content Systems (5 docs + 4 existing)
| File | Lines | Content |
|------|:---:|---------|
| `items-index.md` | ~250 | All 13 `DA_Item_*` + 18 `BP_Pickup_*` — quick builds for ammo, shotgun, battery, adrenaline, sanity pill, crowbar, 3 keys, 2 documents, photo, void shard |
| `weapons-index.md` | ~250 | 4 held weapons — pistol (hitscan), shotgun (pellet spread + shell reload), flashlight (battery), crowbar (melee + pry) |
| `enemies-index.md` | ~300 | 3 enemy types (Patient, Orderly, Shade) + NPC Survivor — full AI controllers, behavior trees, blackboards, perception, behavior variants |
| `narrative-progression.md` | ~300 | 4 objectives, 4 dialogues, 2 cutscenes, 3 ending paths, lore system, ending accumulator evaluation formula |

### Polish & Systems (4 docs)
| File | Lines | Content |
|------|:---:|---------|
| `atmosphere-audio.md` | ~300 | 6 atmosphere profiles, MetaSounds bus hierarchy, 8 gameplay audio parameters, 6 scare events, light events, memory drift, pacing director |
| `save-checkpoints.md` | ~250 | Save slots, checkpoint flow, death → respawn, void space entry/exit, persistent corpses, world state recorder, run history |
| `polish-loading-credits.md` | ~250 | 6 tutorial triggers, loading screen with tips, credits, debug tools (11 cheats + 5-tab debug menu), analytics, error handler |
| `state-gating-examples.md` | ~250 | 15 game-specific gating rules, DA_StateGatingTable_Horror config, void space restrictions, GASP liaison, force stack/overlay examples |

### Existing Item Walkthroughs (unchanged)
- `item-flashlight.md` (411 lines)
- `item-pistol.md` (379 lines)  
- `item-medkit.md` (197 lines)
- `item-keycard.md` (262 lines)

### Key Design Decisions
- **Framework separation**: All game content in `Content/Game/` — children of `Content/Framework/` classes, never modifying framework
- **All 135 systems covered**: Each framework system is demonstrated by at least one game asset (mapped in GAMEINDEX.md)
- **Horror-specific extensions**: Stress/sanity, void space, memory drift hallucinations, flashlight battery management, fear intensity scaling
- **21-phase dependency-safe build order**: Can implement incrementally, testing each layer before building the next