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.

C++ Status: System 72 (BPC_DamageReceptionSystem) is a full C++ implementation — attach the component directly. Systems 75 (BPC_HitReactionSystem) and 79 (BPC_ShieldDefenseSystem) are C++ stubs with basic variables and dispatchers — create BP children for full logic. Systems 69-71, 73-74, 76-78 are BP-only.

---

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.

---

Multiplayer Networking

Category Authority Map

System	Authority	Client Prediction
BP_WeaponBase	Server-authoritative state machine	Client predicts fire animation/muzzle flash
BPC_AmmoComponent	Server-authoritative ammo	Client predicts count; server corrects via OnRep
BPC_FirearmSystem	Server performs trace/damage calc	Client predicts tracers; server hit result is canonical
BPC_MeleeSystem	Server validates hit detection	Client predicts swing animation
BPC_ReloadSystem	Server validates reload	Client predicts animation; server validates ammo state
BPC_RecoilSystem	Local only	Recoil is cosmetic; no replication needed
BPC_DamageReceptionSystem	Server calculates damage	HealthSystem is authoritative
BPC_HitReactionSystem	Server triggers → multicast animation	All clients see flinch/stagger
BPC_CombatFeedbackComponent	Local only	Hit markers, kill confirm are per-client
BPC_ShieldDefenseSystem	Server validates block/parry	Shield state replicated

Weapon Fire Flow (Multiplayer)

Client presses Fire:
  1. Client predicts: play fire anim, muzzle flash, recoil immediately
  2. Client calls Server_StartFire() RPC
  3. Server validates: weapon state Ready, has ammo, not on cooldown
  4. Server: trace/damage calc, consume ammo → RepNotify ammo to all
  5. Server: Multicast fire FX to other clients
  6. Client receives OnRep_Ammo → corrects if prediction was wrong

Server RPCs

• Server_StartFire, Server_StopFire, Server_StartReload, Server_EquipWeapon, Server_HolsterWeapon

Anti-Cheat

• Server validates fire rate (timer between Server_StartFire calls must exceed weapon fire rate)
• Server never trusts client damage calculations — always recalculates from weapon data
• Server validates ammo count before allowing fire (prevents infinite ammo cheat)

---

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