UE5-Modular-Game-Framework/docs/developer/08-weapons-systems.md

08 — Weapons, Equipment & Damage Systems (Systems 69-79)

Category Purpose: These 11 systems form the complete combat layer — weapon actors (ranged and melee), ammo management, combat feedback (hit markers, kill confirm), damage reception and resistance, death cause tracking, firearm specialization, hit reactions, melee combat, recoil patterns, reload mechanics, and shield defense. The BP_WeaponBase is the base actor class extended by all weapons; combat flows through BPC_DamageReceptionSystem to BPC_HealthSystem.

---

System Index

#	System	Asset Type	Role
69	BP_WeaponBase	Actor	Weapon base actor; fire, equip, holster, FX, audio
70	BPC_AmmoComponent	Component	Ammo pool; reserve/loaded, ammo types, pickup
71	BPC_CombatFeedbackComponent	Component	Hit markers, kill confirm, damage direction indicators
72	BPC_DamageReceptionSystem	Component	Damage reception; calculate, resist, apply, stagger
73	BPC_DeathCauseTracker	Component	Death cause logging; killing blow, killer ID, damage type
74	BPC_FirearmSystem	Component	Firearm specialization; fire modes, ADS, chamber check
75	BPC_HitReactionSystem	Component	Hit reaction; directional flinch, stagger, knockdown anims
76	BPC_MeleeSystem	Component	Melee weapon; combos, hit detection, block, parry
77	BPC_RecoilSystem	Component	Recoil; camera spring arm offset, pattern, recovery
78	BPC_ReloadSystem	Component	Reload; tactical/empty reload, notifies, interrupt
79	BPC_ShieldDefenseSystem	Component	Shield defense; block, durability, break, stun

---

Category Data Flow

┌──────────────────────────────────────────────────────────────────┐
│                      COMBAT PIPELINE                             │
│                                                                  │
│  Input → BP_WeaponBase                                           │
│    │  State machine: Holstered→Equipping→Ready→Firing→Reloading  │
│    │                                                             │
│    ├─► Ready state: StartFire → OnFire (subclass override)       │
│    │     │                                                       │
│    │     ├─► BPC_FirearmSystem (ranged): raycast/projectile      │
│    │     │     ├─► BPC_RecoilSystem.ApplyRecoil()                │
│    │     │     ├─► BPC_AmmoComponent.ConsumeAmmo()               │
│    │     │     └─► Hit target → BPC_DamageReceptionSystem        │
│    │     │                                                       │
│    │     └─► BPC_MeleeSystem (melee): hitbox sweep               │
│    │           ├─► Hit detection, combo tracking                 │
│    │           └─► Hit target → BPC_DamageReceptionSystem        │
│    │                                                             │
│    └─► BPC_ReloadSystem (reload): tactical/empty, anim notifies  │
│          └─► BPC_AmmoComponent.RefillAmmo()                      │
│                                                                  │
│  BPC_DamageReceptionSystem (on target)                           │
│    │  Calculate effective damage (resistance, armor)             │
│    ├─► BPC_HealthSystem.ApplyDamage()                            │
│    ├─► BPC_HitReactionSystem (flinch, stagger)                   │
│    └─► BPC_CombatFeedbackComponent (hit marker)                  │
│                                                                  │
│  BPC_ShieldDefenseSystem (on target, if equipped)                │
│    │  Blocks damage, reduces durability, breaks at 0            │
│    └─► Staggers attacker on perfect parry                        │
│                                                                  │
│  BPC_DeathCauseTracker (on death)                                │
│    └─► Logs: who killed, with what, damage type, location       │
└──────────────────────────────────────────────────────────────────┘

---

69 — BP_WeaponBase: Base Weapon Actor

What It Does: The base class for all weapon actors. Manages the weapon lifecycle state machine, attachment to character sockets, fire input handling, aim-down-sights FOV transition, and event dispatching. Extended by ranged and melee weapon subclasses.

State Machine:

Holstered → Equipping → Ready ⇄ Firing → Reloading → Ready
                                                  → Holstering → Holstered

• Firing blocked during: Holstered, Equipping, Holstering, Reloading, Broken
• SetWeaponState(NewState) updates state and broadcasts OnWeaponStateChanged

Fire Modes: SemiAutomatic (one shot per press), FullAutomatic (continuous while held), BurstFire (fixed burst count), ChargeAndRelease (hold to charge), MeleeSwing

ADS System:

• StartAim() / StopAim(): blends camera FOV between DefaultFOV and AimDownSightsFOV
• Uses ADSInterpSpeed for smooth transition
• Notifies BPC_CameraStateLayer for FOV management

Implementation Patterns:

• OnFire() is virtual — subclasses implement actual fire logic (raycast, projectile, melee hitbox)
• Does NOT handle: specific fire logic, ammo math, damage calculation, visual/audio feedback — delegates to specialized components
• All properties from DA_EquipmentConfig Data Asset

---

70 — BPC_AmmoComponent: Ammo Management

What It Does: Manages ammunition for weapons. Tracks reserve ammo (total carried) and loaded ammo (in magazine). Handles ammo types, pickup from world, and consumption on fire.

Key Features:

• Reserve ammo tracked per ammo type (GameplayTag)
• Magazine capacity from weapon data; reload transfers from reserve to loaded
• Ammo pickup: adds to reserve, respects max carry limits
• Different ammo types for different weapons (pistol, rifle, shotgun, energy)

---

72 — BPC_DamageReceptionSystem: Damage Processing

What It Does: Processes incoming damage on the target side before passing to BPC_HealthSystem. Handles armor calculation, damage type resistance, critical hit multipliers, and directional damage awareness.

Flow:

1. Receive damage event (source weapon, damage type, hit location, base amount)
2. Calculate effective damage: apply armor reduction, type resistance, critical multiplier
3. Pass to BPC_HealthSystem.ApplyDamage()
4. Trigger BPC_HitReactionSystem for flinch/stagger based on damage amount
5. Notify BPC_CombatFeedbackComponent for hit marker display

---

73-79: Supporting Combat Systems

• 71 BPC_CombatFeedbackComponent: Hit markers (direction, critical), kill confirm (X indicator), damage direction arrows. Visual/audio feedback for combat clarity.
• 73 BPC_DeathCauseTracker: On death: records killing blow details (instigator, weapon, damage type, hit location). Used by death screen, player metrics, and narrative systems.
• 74 BPC_FirearmSystem: Extends weapon base with firearm-specific logic: raycast hitscan, projectile spawning, spread patterns, aim-down-sights accuracy bonus, chamber check animation.
• 75 BPC_HitReactionSystem: Directional hit reactions: flinch animation toward damage source, stagger on heavy hits, knockdown on lethal/critical hits. Drives animation montages and camera shake.
• 76 BPC_MeleeSystem: Melee combat: combo system (light/heavy attacks chaining), hitbox sweep detection, blocking (reduces damage), parrying (timed block that staggers attacker), riposte (counter after parry).
• 77 BPC_RecoilSystem: Camera recoil patterns: pitch/yaw offset per shot, pattern spread, recovery speed. Configurable per weapon via Data Asset. Affects camera spring arm.
• 78 BPC_ReloadSystem: Reload mechanics: tactical reload (magazine not empty, faster), empty reload (magazine empty, slower with bolt/charge). Animation notifies for ammo refill timing. Interruptible during early phase.
• 79 BPC_ShieldDefenseSystem: Active shield: blocks damage from front arc, has durability that depletes on block, breaks at 0 with stun, recharge delay before regenerating.

---

Common Implementation Patterns in This Category

1. Weapon as Actor, Logic in Components: BP_WeaponBase is an attachable actor; specialized logic (ammo, recoil, reload) lives in components that can be mixed and matched.
2. State Machine Gating: Weapon state prevents firing during reload, equip, holster. Systems don't need to check each other — the state machine handles it.
3. Data-Driven Weapon Stats: Fire rate, damage, spread, recoil pattern, magazine size — all in DA_EquipmentConfig. Changing a weapon's stats never touches Blueprint.
4. Damage Pipeline: Damage flows: Weapon → DamageReceptionSystem → HealthSystem → HitReaction → CombatFeedback. Each step is a separate concern.
5. Animation Notify Contract: Reload and fire animations use specific notifies (OnAmmoRefill, OnFireComplete) that gameplay systems bind to — not hardcoded timers.

---

Developer Reference v1.0 — 08 Weapons Systems. Companion to docs/blueprints/08-weapons/ specs.