# Game Examples — Concrete Blueprint Walkthroughs

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

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.

---

## How to Use These Examples

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

---

## Example Index

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

---

## Folder Structure in Your UE5 Project

```
Content/
├── Framework/                    ← Framework systems (read-only, don't 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.
│   └── ...
│
└── 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
    └── ...
```

> **Rule:** Never modify files in `Content/Framework/`. Create your assets in `Content/Game/` and reference framework systems via interfaces and dispatchers.

---

## Reference — Framework Systems Used by These Examples

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