docs: Add detailed item examples for Keycard, MedKit, and Pistol, including step-by-step setup instructions
This commit is contained in:
Lefteris Notas
379
docs/game/item-pistol.md
Normal file
379
docs/game/item-pistol.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# Item Example — Pistol (Weapon)
|
||||
|
||||
**Item Type:** `Weapon`
|
||||
**Complexity:** High
|
||||
**Systems Used:** `DA_ItemData`, `BP_ItemPickup`, `BP_WeaponBase`, `BPC_FirearmSystem`, `BPC_AmmoComponent`, `BPC_DamageReceptionSystem`, `BPC_RecoilSystem`, `BPC_ReloadSystem`, `BPC_EquipmentSlotSystem`, `BPC_InventorySystem`, `I_UsableItem`, `I_Damageable`
|
||||
**What You Learn:** Full weapon pipeline — Data Asset with EquipmentData, pickup-to-equip flow, frame-driven fire with hitscan, ammo management, damage application, recoil
|
||||
|
||||
---
|
||||
|
||||
## 1. Create the DA_ItemData
|
||||
|
||||
### 1.1 — Create the Data Asset
|
||||
|
||||
```
|
||||
Content Browser → Game/Items/ (or Game/Weapons/)
|
||||
Right-click → Miscellaneous → Data Asset
|
||||
Class: DA_ItemData
|
||||
Name: DA_Item_Pistol
|
||||
```
|
||||
|
||||
### 1.2 — Fill Core Properties
|
||||
|
||||
| Property | Value | Notes |
|
||||
|----------|-------|-------|
|
||||
| `Item Tag` | `Framework.Item.Weapon.Pistol` | Registered in `DA_GameTagRegistry` |
|
||||
| `Display Name` | "9mm Pistol" | |
|
||||
| `Description` | "A standard-issue 9mm semi-automatic pistol." | |
|
||||
| `Icon` | `T_Pistol_Icon` | |
|
||||
| `World Mesh` | `SM_Pistol` | Soft reference |
|
||||
| `Weight` | `3.0` | Heavier than consumables |
|
||||
| `Stack Limit` | `1` | Cannot stack weapons |
|
||||
| `Item Type` | `Weapon` | Triggers `Equipment Data` panel |
|
||||
|
||||
### 1.3 — Fill Equipment Data
|
||||
|
||||
When `ItemType == Weapon`, the `Equipment Data` panel appears:
|
||||
|
||||
| Field | Value | Notes |
|
||||
|-------|-------|-------|
|
||||
| `Slot` | `Framework.Equipment.Slot.PrimaryWeapon` | Occupies player's primary weapon slot |
|
||||
| `Damage` | `15.0` | Base damage per shot |
|
||||
| `Fire Rate` | `0.15` | Seconds between shots (400 RPM) |
|
||||
| `Range` | `5000.0` | Hitscan range in Unreal units |
|
||||
| `Magazine Size` | `12` | Rounds per magazine |
|
||||
| `Reload Time` | `2.0` | Seconds to reload |
|
||||
|
||||
### 1.4 — Save
|
||||
|
||||
---
|
||||
|
||||
## 2. Create the BP_Pickup_Pistol (World Pickup)
|
||||
|
||||
Same as other pickups, with weapon mesh:
|
||||
|
||||
### 2.1 — Blueprint + Components
|
||||
|
||||
```
|
||||
Content Browser → Game/Pickups/
|
||||
Right-click → Blueprint Class → Actor
|
||||
Name: BP_Pickup_Pistol
|
||||
|
||||
Components:
|
||||
├── StaticMeshComponent "Mesh"
|
||||
└── SphereComponent "PickupTrigger" (radius 200, OverlapOnlyPawn)
|
||||
```
|
||||
|
||||
### 2.2 — Variable & Construction Script
|
||||
|
||||
Same pattern as flashlight — `ItemData` → Get World Mesh → Load Synchronous → Set Static Mesh.
|
||||
|
||||
### 2.3 — I_Interactable Wiring
|
||||
|
||||
Same as other pickups, but **after adding item to inventory**, also auto-equip it:
|
||||
|
||||
```
|
||||
Event Interact
|
||||
│
|
||||
├─ Interactor → Get BPC_InventorySystem
|
||||
├─ CanAddItem(ItemData, 1) → True → AddItem → store result
|
||||
│ │
|
||||
│ ├─ Interactor → Get BPC_EquipmentSlotSystem
|
||||
│ │ └─ Equip To Slot(ItemData, PrimaryWeapon slot tag)
|
||||
│ │ └─ This spawns the BP_Pistol actor at the player's hand socket
|
||||
│ │
|
||||
│ ├─ Destroy Actor
|
||||
│ └─ Return True
|
||||
│
|
||||
└─ False → Print "Inventory Full" → Return False
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Create the BP_Pistol (Held Weapon Actor)
|
||||
|
||||
This is the actor that appears in the player's hand when equipped.
|
||||
|
||||
### 3.1 — Create Blueprint
|
||||
|
||||
```
|
||||
Content Browser → Game/Actors/ (or Game/Weapons/)
|
||||
Right-click → Blueprint Class → Actor (or BP_WeaponBase from framework)
|
||||
Name: BP_Pistol
|
||||
```
|
||||
|
||||
### 3.2 — Add Components
|
||||
|
||||
| # | Component | Name | Purpose |
|
||||
|---|-----------|------|---------|
|
||||
| 1 | `SkeletalMeshComponent` | `WeaponMesh` | Animated weapon (slide, magazine) |
|
||||
| 2 | `SceneComponent` | `MuzzleSocket` | Where the bullet trace starts (attach to muzzle bone) |
|
||||
| 3 | `AudioComponent` | `FireSound` | Plays fire sound |
|
||||
| 4 | `AudioComponent` | `ReloadSound` | Plays reload sound |
|
||||
| 5 | `ParticleSystemComponent` | `MuzzleFlash` | Fire particle effect |
|
||||
| 6 | *(Optional)* `PointLightComponent` | `MuzzleLight` | Brief flash on fire |
|
||||
|
||||
Parent `MuzzleSocket` to the muzzle bone on `WeaponMesh`, or set its relative location to where the barrel ends.
|
||||
|
||||
### 3.3 — Variables
|
||||
|
||||
| Variable | Type | Default | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| `CurrentAmmoInMag` | Integer | `12` | Rounds currently loaded |
|
||||
| `MaxMagazineSize` | Integer | `12` | From EquipmentData |
|
||||
| `bIsFiring` | Boolean | `false` | Prevents re-trigger during fire rate cooldown |
|
||||
| `FireRateTimer` | Float | `0.15` | Seconds between shots |
|
||||
| `WeaponData` | DA_ItemData* | — | Reference to the pistol Data Asset |
|
||||
| `FireRange` | Float | `5000.0` | Hitscan distance |
|
||||
|
||||
### 3.4 — Interfaces
|
||||
|
||||
Class Settings → Interfaces → Add:
|
||||
- `UUsableItem` — so active item system can route fire input
|
||||
|
||||
### 3.5 — Fire Logic (Hitscan)
|
||||
|
||||
```
|
||||
Event Use Item (Interface -> UUsableItem)
|
||||
│ User: AActor*, Target: AActor*
|
||||
│ Return Boolean
|
||||
│
|
||||
├─ bIsFiring? → Branch
|
||||
│ ├─ True → Return False (fire rate lockout)
|
||||
│ └─ False:
|
||||
│ │
|
||||
│ ├─ CurrentAmmoInMag > 0? → Branch
|
||||
│ │ ├─ True:
|
||||
│ │ │ ├─ Set bIsFiring = true
|
||||
│ │ │ ├─ CurrentAmmoInMag = CurrentAmmoInMag - 1
|
||||
│ │ │ │
|
||||
│ │ │ ├─ [Play Effects]
|
||||
│ │ │ │ ├─ MuzzleFlash → Activate
|
||||
│ │ │ │ ├─ FireSound → Play
|
||||
│ │ │ │ └─ MuzzleLight → Set Visibility (true)
|
||||
│ │ │ │ └─ Delay 0.05 → Set Visibility (false)
|
||||
│ │ │ │
|
||||
│ │ │ ├─ [Line Trace — Hitscan]
|
||||
│ │ │ │ │
|
||||
│ │ │ │ ├─ Get Player Controller → Get Camera Location/Direction
|
||||
│ │ │ │ ├─ Start: MuzzleSocket → Get World Location
|
||||
│ │ │ │ ├─ End: Start + (CameraForward × FireRange)
|
||||
│ │ │ │ │
|
||||
│ │ │ │ └─ Line Trace By Channel (Visibility)
|
||||
│ │ │ │ ├─ Trace Complex: false
|
||||
│ │ │ │ └─ Ignore Self, Ignore Owning Pawn
|
||||
│ │ │ │ │
|
||||
│ │ │ │ ├─ Hit? → Branch
|
||||
│ │ │ │ │ │
|
||||
│ │ │ │ │ ├─ True:
|
||||
│ │ │ │ │ │ ├─ Hit Actor → Does Implement Interface (UDamageable)?
|
||||
│ │ │ │ │ │ │ ├─ True:
|
||||
│ │ │ │ │ │ │ │ ├─ Call I_Damageable.Take Damage
|
||||
│ │ │ │ │ │ │ │ │ ├─ Damage Amount: WeaponData → Get Equipment Data → Damage
|
||||
│ │ │ │ │ │ │ │ │ ├─ Damage Causer: Self (or OwningPawn)
|
||||
│ │ │ │ │ │ │ │ │ ├─ Damage Type: Framework.Combat.Damage.Physical
|
||||
│ │ │ │ │ │ │ │ │ ├─ Hit Location: HitResult.ImpactPoint
|
||||
│ │ │ │ │ │ │ │ │ └─ Hit Direction: (ImpactPoint - Start) normalized
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ │ │ │ │ │ └─ Print String: "Hit {HitActor} for {Damage} damage"
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ │ │ │ │ └─ False: Print "Hit non-damageable object"
|
||||
│ │ │ │ │ │ │
|
||||
│ │ │ │ │ │ └─ Spawn Decal/Impact Effect at Hit Location
|
||||
│ │ │ │ │ │
|
||||
│ │ │ │ │ └─ False (miss): nothing
|
||||
│ │ │ │ │
|
||||
│ │ │ │ └─ Draw Debug Line (red for 1 second, editor only)
|
||||
│ │ │ │
|
||||
│ │ │ ├─ [Recoil]
|
||||
│ │ │ │ └─ Get BPC_RecoilSystem (on pawn) → Apply Recoil (WeaponData)
|
||||
│ │ │ │
|
||||
│ │ │ └─ Delay (FireRateTimer) → Set bIsFiring = false → Return True
|
||||
│ │ │
|
||||
│ │ └─ False: (out of ammo)
|
||||
│ │ ├─ Play click/empty sound
|
||||
│ │ ├─ (Optional) Auto-reload → Call Reload
|
||||
│ │ └─ Return False
|
||||
```
|
||||
|
||||
### 3.6 — Reload Logic
|
||||
|
||||
```
|
||||
Function: Reload
|
||||
│
|
||||
├─ CurrentAmmoInMag >= MaxMagazineSize? → Return (already full)
|
||||
├─ Set bIsReloading = true
|
||||
│
|
||||
├─ Get Owning Pawn → Get BPC_AmmoComponent
|
||||
│ │
|
||||
│ └─ Get Ammo Count (AmmoTypeTag = Framework.Item.Ammo.Pistol9mm)
|
||||
│ │
|
||||
│ ├─ Branch (> 0?)
|
||||
│ │ ├─ True:
|
||||
│ │ │ ├─ Rounds To Load = Min(AmmoAvailable, MaxMagazineSize - CurrentAmmoInMag)
|
||||
│ │ │ ├─ CurrentAmmoInMag += Rounds To Load
|
||||
│ │ │ ├─ AmmoComponent → Consume Ammo (RoundsToLoad)
|
||||
│ │ │ └─ Play ReloadSound
|
||||
│ │ │
|
||||
│ │ └─ False: Print "No ammo" → Return
|
||||
│ │
|
||||
│ ├─ Delay (ReloadTime) → Set bIsReloading = false
|
||||
│ └─ Broadcast OnReloadComplete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Wire BPC_AmmoComponent (On Player Pawn)
|
||||
|
||||
Create BP child of `BPC_AmmoComponent` (spec #70):
|
||||
|
||||
| Variable | Type | Default | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| `AmmoPool` | Map (GameplayTag → Integer) | Empty | AmmoType → Count |
|
||||
|
||||
```
|
||||
Function: Get Ammo Count (AmmoTypeTag) → Integer
|
||||
│
|
||||
└─ AmmoPool.Find(AmmoTypeTag) → Return count (0 if not found)
|
||||
|
||||
Function: Consume Ammo (AmmoTypeTag, Amount)
|
||||
│
|
||||
├─ Current = Get Ammo Count (AmmoTypeTag)
|
||||
├─ Current -= Amount
|
||||
├─ Clamp to 0 minimum
|
||||
└─ AmmoPool[AmmoTypeTag] = Current
|
||||
|
||||
Function: Add Ammo (AmmoTypeTag, Amount)
|
||||
│
|
||||
├─ AmmoPool.Find or Add (AmmoTypeTag)
|
||||
└─ Increment by Amount
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Wire BPC_RecoilSystem (On Player Pawn)
|
||||
|
||||
Create BP child of `BPC_RecoilSystem` (spec #77):
|
||||
|
||||
```
|
||||
Function: Apply Recoil (WeaponData: DA_ItemData*)
|
||||
│
|
||||
├─ WeaponData → Get Equipment Data → Get Damage (or FireRate)
|
||||
├─ Calculate kick: PitchUp = random(1.0, 2.5), YawSide = random(-0.5, 0.5)
|
||||
│
|
||||
├─ Get Player Controller → Add Controller Pitch Input (PitchUp × -1)
|
||||
├─ Get Player Controller → Add Controller Yaw Input (YawSide)
|
||||
│
|
||||
└─ (For smooth recovery, use a Timeline or interp to return to original aim)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Create DA_Item_Ammo_Pistol9mm (Ammo Data Asset)
|
||||
|
||||
```
|
||||
Content Browser → Game/Items/
|
||||
Right-click → Miscellaneous → Data Asset → DA_ItemData
|
||||
Name: DA_Item_Ammo_Pistol9mm
|
||||
|
||||
Properties:
|
||||
ItemTag: Framework.Item.Ammo.Pistol9mm
|
||||
DisplayName: "9mm Rounds"
|
||||
ItemType: Ammo
|
||||
StackLimit: 999
|
||||
Weight: 0.05
|
||||
(AmmoData sub-panel auto-appears — set PerPickupCount = 15)
|
||||
```
|
||||
|
||||
Create `BP_Pickup_Ammo_Pistol9mm` following the same pattern as other pickups. On interact, call `BPC_AmmoComponent.Add Ammo(AmmoTypeTag, PerPickupCount)` instead of adding to inventory.
|
||||
|
||||
---
|
||||
|
||||
## 7. Verification Checklist
|
||||
|
||||
**Step 1 — Pickup:**
|
||||
- [ ] Pistol pickup in level → mesh visible → interact → goes to inventory
|
||||
- [ ] Auto-equips to primary weapon slot (weapon appears in player's hand)
|
||||
|
||||
**Step 2 — Fire:**
|
||||
- [ ] Equip pistol, press fire → muzzle flash + sound + hitscan line
|
||||
- [ ] Hit an enemy actor implementing `I_Damageable` → health decreases
|
||||
- [ ] Ammo counter decreases (12 → 11 → 10...)
|
||||
- [ ] Camera kicks slightly on each shot (recoil)
|
||||
- [ ] Fire rate enforced: cannot spam fire faster than 0.15s
|
||||
|
||||
**Step 3 — Empty Magazine:**
|
||||
- [ ] Fire all 12 rounds → click sound plays, no trace, no damage
|
||||
- [ ] Auto-reload? Or manual reload prompt appears
|
||||
|
||||
**Step 4 — Reload:**
|
||||
- [ ] Press Reload key → reload animation/sound plays
|
||||
- [ ] Ammo transfers from pool to magazine
|
||||
- [ ] Magazine shows 12 rounds again
|
||||
- [ ] If no ammo in pool → reload fails
|
||||
|
||||
**Step 5 — Ammo Pickup:**
|
||||
- [ ] Pick up `BP_Pickup_Ammo_Pistol9mm` → ammo pool increases by 15
|
||||
- [ ] Reload → magazine fills, pool decreases by rounds loaded
|
||||
|
||||
**Step 6 — Damage Pipeline:**
|
||||
- [ ] Enemy pawn has `BPC_DamageReceptionSystem` + `BPC_HealthSystem`
|
||||
- [ ] Fire at enemy → `ApplyDamage(15.0, ...)` called
|
||||
- [ ] Damage pipeline: resistance → armor → shield → health
|
||||
- [ ] Enemy health decreases proportionally
|
||||
|
||||
---
|
||||
|
||||
## 8. Weapon Data Flow (Complete)
|
||||
|
||||
```
|
||||
Player Input (IA_Fire)
|
||||
│
|
||||
└─ BPC_ActiveItemSystem routes to equipped weapon
|
||||
│
|
||||
└─ BP_Pistol (implements I_UsableItem)
|
||||
│
|
||||
├─ [Ammo Check] → BPC_AmmoComponent (in-mag count)
|
||||
├─ [Hitscan] → Line Trace from MuzzleSocket
|
||||
│ │
|
||||
│ └─ Hit Actor (implements I_Damageable)
|
||||
│ │
|
||||
│ └─ BPC_DamageReceptionSystem.ApplyDamage(RawDamage, Causer, Type, Location, Direction)
|
||||
│ │
|
||||
│ ├─ Calculate Resistance
|
||||
│ ├─ Apply Shield (BPC_ShieldDefenseSystem)
|
||||
│ ├─ Apply Health (BPC_HealthSystem)
|
||||
│ ├─ Evaluate Hit Reaction (BPC_HitReactionSystem)
|
||||
│ │ ├─ Stagger? (damage > threshold)
|
||||
│ │ └─ Knockdown? (damage > higher threshold)
|
||||
│ │
|
||||
│ └─ Broadcast OnDamageReceived → UI, audio, metrics
|
||||
│
|
||||
├─ [Recoil] → BPC_RecoilSystem.ApplyRecoil()
|
||||
├─ [Effects] → MuzzleFlash, FireSound, ImpactDecal
|
||||
└─ [Fire Rate] → Timer lockout until next shot
|
||||
|
||||
When magazine empty:
|
||||
└─ Player presses IA_Reload
|
||||
└─ BP_Pistol.Reload()
|
||||
└─ BPC_AmmoComponent.ConsumeAmmo() (from pool)
|
||||
└─ BP_Pistol.CurrentAmmoInMag += rounds loaded
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Key Differences — Weapon vs Tool vs Consumable
|
||||
|
||||
| Aspect | Pistol (Weapon) | Flashlight (Tool) | MedKit (Consumable) |
|
||||
|--------|----------------|-------------------|---------------------|
|
||||
| ItemType | `Weapon` | `Tool` | `Consumable` |
|
||||
| Slot | `PrimaryWeapon` | `Tool` | None (inventory bag) |
|
||||
| Use action | Frame-driven (continuous) | Toggle (single click) | One-shot (consumed) |
|
||||
| Ammo | Yes (magazine + pool) | No (battery as optional resource) | No |
|
||||
| Damage output | Yes | No | No (heals) |
|
||||
| Fire rate | Throttled (timer) | N/A | Use duration (2s anim) |
|
||||
| Recoil | Yes | No | No |
|
||||
| Reload | Yes | No | No |
|
||||
| Stackable | No (StackLimit=1) | No (StackLimit=1) | Yes (StackLimit=5) |
|
||||
| Interfaces | `I_UsableItem` | `I_UsableItem` + `I_Toggleable` | `I_UsableItem` |
|
||||
| Pickup → Equip | Auto-equips to slot | Auto-equips to slot | Goes to inventory only |
|
||||
Reference in New Issue
Block a user