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