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

docs: Update item pickup setup instructions and add game examples for Blueprint walkthroughs

Browse Source
This commit is contained in:
Lefteris Notas
2026-05-21 20:45:44 +03:00
parent 7e876e4f0c
commit 44aca98885
4 changed files with 813 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/game/README.md Normal file
View File

@@ -0,0 +1,72 @@
# 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 |

411
docs/game/item-flashlight.md Normal file
View File

@@ -0,0 +1,411 @@
# Item Example — Flashlight (Tool)
**Item Type:** `Tool`
**Complexity:** Medium
**Systems Used:** `DA_ItemData`, `BP_ItemPickup`, `I_UsableItem`, `I_Toggleable`, `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`
**What You Learn:** Data Asset setup, pickup actor with soft reference mesh, Construction Script wiring, toggleable active-use item, inventory integration
---
## 1. Create the DA_ItemData
### 1.1 — Create the Data Asset
```
Content Browser → Game/Items/
(create folder "Items" if needed)
Right-click → Miscellaneous → Data Asset
Class: DA_ItemData
Name: DA_Item_Flashlight
```
### 1.2 — Fill Core Properties
Open `DA_Item_Flashlight`:
| Property | Value | Notes |
|----------|-------|-------|
| `Item Tag` | `Framework.Item.Tool.Flashlight` | Must be registered in `DA_GameTagRegistry`. Tag hierarchy: Framework → Item → Tool → Flashlight |
| `Display Name` | "Flashlight" | Player sees this in inventory UI |
| `Description` | "A heavy-duty tactical flashlight. Click to toggle on/off." | Shown in inventory |
| `Icon` | `T_Flashlight_Icon` | Assign any texture; for prototype, use a white square |
| `World Mesh` | `SM_Flashlight` | **Soft reference** — doesn't need to be loaded at startup; Construction Script resolves it |
| `Weight` | `1.5` | Carried weight in your carry limit |
| `Stack Limit` | `1` | Cannot stack multiple flashlights |
| `Item Type` | `Tool` | Determines that `Equipment Data` panel shows |
### 1.3 — Fill Equipment Data
Scroll down — the `Equipment Data` panel appears because `ItemType == Tool`:
| Field | Value | Notes |
|-------|-------|-------|
| `Slot` | `Framework.Equipment.Slot.Tool` | Which equipment slot it goes into |
| `Damage` | `0` | Not a weapon |
| `Fire Rate` | `0` | Not a weapon |
| `Range` | `0` | N/A |
| `Magazine Size` | `0` | N/A |
| `Reload Time` | `0` | N/A |
### 1.4 — Save
File → Save (or Ctrl+S). The Data Asset is ready.
---
## 2. Create the BP_Pickup_Flashlight (World Pickup Actor)
This is the actor the player sees in the level. It reads the Data Asset and represents it in the world.
### 2.1 — Create Blueprint
```
Content Browser → Game/Pickups/
(create folder "Pickups" if needed)
Right-click → Blueprint Class → Actor
Name: BP_Pickup_Flashlight
```
### 2.2 — Add Components
Open `BP_Pickup_Flashlight` → **Viewport** tab.
**Add Component** button (top-left of the Components panel):
| Order | Component Class | Name | Purpose |
|-------|----------------|------|---------|
| 1 | `StaticMeshComponent` | `Mesh` | Renders the flashlight 3D model in the world |
| 2 | `SphereComponent` | `PickupTrigger` | Detects when player is close enough to interact |
| 3 | *(Optional)* `PointLightComponent` | `BatteryIndicator` | Small glow showing the pickup has charge |
**Select `PickupTrigger` → Details:**
- `Sphere Radius` → `200.0`
- **Collision → Collision Presets** → `OverlapOnlyPawn`
**Select `Mesh` → Details:**
- **Collision → Collision Enabled** → `No Collision` (the sphere handles interaction; mesh collision is unnecessary)
Your Components panel should look like:
```
BP_Pickup_Flashlight (self)
├── DefaultSceneRoot
├── Mesh ← StaticMeshComponent
├── PickupTrigger ← SphereComponent (radius 200)
└── BatteryIndicator ← PointLightComponent (optional)
```
### 2.3 — Create the ItemData Variable
In the **My Blueprint** panel (left side):
1. Click **+ Variable** → name: `ItemData` → type: **DA_ItemData → Object Reference**
2. Select the variable → Details:
- **Instance Editable** → ✓
- **Category** → `Pickup`
- **Tooltip** → "The item Data Asset this pickup represents"
This is simpler than using a struct for a single item — you can expand to a struct later if you need more fields.
### 2.4 — Wire the Construction Script
Switch to the **Construction Script** tab (or open the graph). This runs when the blueprint is compiled or when you change `ItemData` in the editor.
```
[Construction Script]
│
├─ ItemData (drag from My Blueprint → Get ItemData)
│
├─ Is Valid? (ItemData)
│ │
│ ├─ Branch (Condition = IsValid result)
│ │
│ ├─ True:
│ │ │
│ │ ├─ ItemData → Get World Mesh
│ │ │ This returns a TSoftObjectPtr<UStaticMesh>
│ │ │ │
│ │ │ └─ To Soft Object Reference (conversion node, or just drag from pin)
│ │ │ └─ Resolve Soft Reference (or "Async Load Asset")
│ │ │ │
│ │ │ ├─ On Complete (if async) → Set Static Mesh (Mesh component, New Mesh = loaded asset)
│ │ │ │
│ │ │ └─ For Construction Script, use "Load Synchronous" to see it in editor immediately:
│ │ │ └─ Sync Load Asset (from soft ref) → Set Static Mesh (Mesh)
│ │ │
│ │ ├─ ItemData → Get Display Name → Set Actor Label
│ │ │ (This renames the actor in the world to "Flashlight" so it's easy to find in the World Outliner)
│ │ │
│ │ └─ ItemData → Get Weight → (optional: store for physics if dropped)
│ │
│ └─ False:
│ └─ Print String ("No ItemData assigned to BP_Pickup_Flashlight")
│ └─ Only if Editor (not PIE/standalone)
```
**Exact node sequence:**
| Step | Right-click / Drag | Search | Connect |
|------|-------------------|--------|---------|
| 1 | Drag `ItemData` variable → Get | — | — |
| 2 | Drag from ItemData pin | `Is Valid` | Branch Condition |
| 3 | True branch → drag from ItemData | `Get World Mesh` | — |
| 4 | Drag from World Mesh pin | `Load Synchronous` | — |
| 5 | Drag `Mesh` component from Components → Get | — | Target of Set Static Mesh |
| 6 | Drag from Load Synchronous Return Value | `Set Static Mesh` (New Mesh) | — |
| 7 | Drag from ItemData → `Get Display Name` | — | To String (Auto) |
| 8 | Drag from string result | `Set Actor Label` → New Actor Label | — |
### 2.5 — Add I_Interactable Interface
1. **Class Settings** (toolbar button)
2. **Implemented Interfaces** → **Add** → search and select `UInteractable`
3. **Compile** (blue checkmark). Now these events appear:
#### Event Interact
```
Event Interact (Interface -> UInteractable)
│ Interactor: AActor*
│ Return Node expects a Boolean
│
├─ Interactor → Get Component by Class → Class: UBPC_InventorySystem
│ │
│ └─ Is Valid?
│ ├─ False → Return False (no inventory on this actor)
│ │
│ └─ True → [InventorySystem ref]
│ │
│ ├─ ItemData → Is Valid?
│ │ └─ False → Return False
│ │
│ ├─ [InventorySystem] → Can Add Item
│ │ ├─ Item: ItemData
│ │ ├─ Quantity: 1
│ │ └─ Result → Branch
│ │ ├─ True:
│ │ │ ├─ [InventorySystem] → Add Item (Item=ItemData, Quantity=1)
│ │ │ │ → Result (int32, ignore)
│ │ │ ├─ Destroy Actor
│ │ │ └─ Return True
│ │ └─ False:
│ │ ├─ Print String ("Inventory full or cannot carry")
│ │ └─ Return False
```
#### Event Can Interact
```
Event Can Interact (Interface -> UInteractable)
│ Interactor: AActor*
│ OutBlockReason: FText& (by reference)
│ Return Node expects Boolean
│
├─ ItemData → Is Valid?
│ ├─ False → OutBlockReason = "No item data configured" → Return False
│ └─ True → Return True
```
#### Event Get Interaction Prompt
```
Event Get Interaction Prompt (Interface -> UInteractable)
│ Return Node expects FText
│
├─ ItemData → Get Display Name
├─ Format Text: "Pick up {0}" (format with DisplayName)
└─ Return the formatted text
```
### 2.6 — Optional: Bobbing & Rotation
In **Event Graph → Event BeginPlay**:
```
Event BeginPlay
│
├─ Mesh → Set Collision Enabled → No Collision
├─ PickupTrigger → Set Collision Enabled → Query Only
│
├─ [Create a Timeline named "FloatAnim"]
│ │
│ ├─ Float Track: 0.0 to 1.0, length 2.0 seconds, Looping ✓
│ │
│ └─ Timeline → Update pin:
│ │
│ ├─ Mesh → Add World Rotation
│ │ ├─ Delta Rotation: (0, 0, TimelineOutput * 90.0)
│ │ └─ Sweep: false, Teleport: false
│ │
│ └─ Mesh → Set World Location (interpolation)
│ └─ Z = ActorLocation.Z + sin(TimelineOutput * 2π) * 5.0
│ (Use "Make Vector" → Break Actor Location → modify Z → "Lerp" or direct set)
│
└─ Play Timeline from Start
```
> For the bobbing math: `sin(TimelineOutput * 6.28318) * 5.0` gives a smooth ±5 unit bounce.
---
## 3. Create the BP_Flashlight (Active-Use Actor — Toggleable)
This is a separate Blueprint for the *held* flashlight — what the player actually uses after picking it up. It implements `I_UsableItem` and `I_Toggleable`.
### 3.1 — Create Blueprint
```
Content Browser → Game/Actors/
Right-click → Blueprint Class → Actor
Name: BP_Flashlight
```
### 3.2 — Add Components
| # | Component | Name | Purpose |
|---|-----------|------|---------|
| 1 | `StaticMeshComponent` | `BodyMesh` | Flashlight body |
| 2 | `SpotLightComponent` | `LightBeam` | The actual light cone |
| 3 | `AudioComponent` | `ClickSound` | Plays the toggle click sound |
Select `LightBeam` → Details:
- `Intensity` → `5000.0` (bright)
- `Inner Cone Angle` → `15.0`
- `Outer Cone Angle` → `30.0`
- **Visible** → false (starts off — player toggles it on)
### 3.3 — Add Toggle State Variable
**+ Variable** → Name: `bIsOn` → Type: `Boolean` → Default: `false`
- **Replication** → `Replicated` (if multiplayer)
### 3.4 — Add Interfaces
Class Settings → Interfaces → Add:
- `UUsableItem` — so the player can select and use it from inventory
- `UToggleable` — so the player can toggle it on/off
### 3.5 — Wire I_Toggleable
```
Event Toggle (Interface -> UToggleable)
│ Toggler: AActor*
│
├─ bIsOn = NOT bIsOn (FlipFlop or Boolean NOT)
│
├─ Branch (bIsOn)
│ ├─ True:
│ │ ├─ LightBeam → Set Visibility (true)
│ │ ├─ ClickSound → Play
│ │ └─ (Optional) Play toggle-on animation montage
│ │
│ └─ False:
│ ├─ LightBeam → Set Visibility (false)
│ └─ ClickSound → Play
Event Set State (Interface -> UToggleable)
│ bNewState: Boolean, Setter: AActor*
│
├─ Set bIsOn = bNewState
├─ LightBeam → Set Visibility (bNewState)
└─ (Don't play click sound — this is programmatic, not player toggle)
Event Get Current State
│ Return Boolean
└─ Return bIsOn
Event Get State Label
│ Return FText
└─ Format Text: "Flashlight is {0}" → format with (bIsOn ? "ON" : "OFF")
```
### 3.6 — Wire I_UsableItem
```
Event Use Item (Interface -> UUsableItem)
│ User: AActor*, Target: AActor*
│ Return Boolean
│
├─ Call Toggle (self, User) ← reuses the I_Toggleable logic
└─ Return True
Event Can Use Item
│ User, Target
│ Return Boolean
└─ Return True (can always toggle flashlight)
Event Get Use Duration
│ Return Float
└─ Return 0.0 (instant toggle)
Event On Item Used
│ User: AActor*
│
└─ (Optional) Play a small haptic pulse on controller
```
### 3.7 — Compile & Save
The held flashlight is ready. When a player picks up `BP_Pickup_Flashlight` and the inventory's `BPC_ActiveItemSystem` routes the item to use, it calls `I_UsableItem.UseItem()` on this actor, which toggles the light.
---
## 4. Wire Inventory Integration
### 4.1 — In Your Player Pawn BP
When `BPC_ActiveItemSystem` detects that an item of type `Tool` is used:
1. Get the equipped item from `BPC_EquipmentSlotSystem`
2. Spawn `BP_Flashlight` actor (if not already spawned)
3. Call `I_UsableItem.UseItem()`
4. The flashlight actor handles its own toggle state
### 4.2 — Quick Test Without Full Integration
For a rapid prototype, add this to your **PlayerCharacter's Event Graph**:
```
Event InputAction (IA_UseItem, Pressed)
│
├─ Branch (bFlashlightEquipped) ← set this bool when flashlight is picked up
│ ├─ True:
│ │ ├─ Get All Actors of Class (BP_Flashlight)
│ │ ├─ For Each → Call I_Toggleable.Toggle
│ │ └─ (In production, use BPC_ActiveItemSystem instead of this crude search)
│ └─ False: do nothing
```
---
## 5. Verification Checklist
**Step 1 — Data Asset:** Open `DA_Item_Flashlight` → all fields filled, no blank properties.
**Step 2 — Pickup in Editor:** Drag `BP_Pickup_Flashlight` into level → set `ItemData` → the mesh appears in viewport immediately (Construction Script).
**Step 3 — Pickup Interaction (PIE):**
- [ ] Walk up to flashlight pickup → interaction prompt appears ("Pick up Flashlight")
- [ ] Press Interact → flashlight disappears from world
- [ ] Check log/print: `BPC_InventorySystem.AddItem` was called
- [ ] In debug: `Get All Items` on inventory → flashlight is in a slot
**Step 4 — Held Use:**
- [ ] Toggle via IA_UseItem → light turns on (visible in world)
- [ ] Toggle again → light turns off
- [ ] Click sound plays on each toggle
**Step 5 — Equipment Slot:**
- [ ] Flashlight occupies `Framework.Equipment.Slot.Tool` slot
- [ ] Cannot equip another tool while flashlight is in slot (slot type validation)
---
## 6. Common Issues
| Issue | Cause | Fix |
|-------|-------|-----|
| Mesh doesn't appear in Construction Script | Soft reference not loaded | Use `Load Synchronous` instead of `Async Load Asset` in Construction Script |
| Pickup doesn't respond to interaction | `UInteractable` interface not added | Class Settings → Interfaces → Add `UInteractable` → Compile |
| "Can Add Item" always returns false | `BPC_InventorySystem.MaxWeight` too low or `GridWidth/Height = 0` | Set MaxWeight to 0 (unlimited) for testing, or increase it |
| Light doesn't toggle | `bIsOn` variable not replicated or `I_Toggleable` not wired | Verify `Toggle` event is called; check `Set Visibility` target is the correct light component |
| "No ItemData configured" error | Forgot to set `ItemData` on the pickup instance in the level | Select the pickup → Details → set ItemData → recompile |