UE5-Modular-Game-Framework/docs/blueprints/08-weapons/69_BP_WeaponBase.md

49 — BP_WeaponBase

Blueprint Spec — UE 5.5–5.7

---

Parent Class

Actor (attached to character via AttachToComponent)

Dependencies

• BPC_InventoryComponent
• BPC_EquipmentSystem
• BPC_PlayerCameraManager
• BPC_DamageHandler
• DA_WeaponData
• I_Damageable
• BPC_CombatFeedbackComponent

Purpose

Base class for all weapon actors (ranged and melee). Provides common weapon lifecycle: equip, unequip, fire input, ammo tracking integration, aim-down-sights, and weapon state machine. Designed to be extended by BP_RangedWeapon and BP_MeleeWeapon.

Responsibilities

• Attach/detach from character socket on equip/unequip
• Manage weapon state (holstered / equipping / ready / firing / reloading)
• Handle fire input (start / stop) — base delegates to subclass
• Track aim-down-sights state and apply camera FOV transition
• Fire event dispatchers for UI state changes
• Communicate with BPC_EquipmentSystem for weapon selection
• Communicate with inventory for ammo consumption

Does NOT Handle

• Specific fire logic (raycast / projectile / melee hitbox) — that is subclass
• Ammo math (that is BPC_AmmoComponent)
• Damage calculation (that is BPC_DamageHandler)
• Visual / audio feedback (that is BPC_CombatFeedbackComponent)
• UI display (that is HUD widget)

Variables

Name	Type	Description
WeaponData	DA_WeaponData	Weapon definition asset
WeaponState	EWeaponState	Current state machine
SkeletalMesh	USkeletalMeshComponent	Weapon visual
WeaponRoot	USceneComponent	Attachment root
HolsterSocket	FName	Socket name for holstered
EquipSocket	FName	Socket name for ready
AimDownSightsFOV	Float	FOV when ADS (e.g. 60.0)
DefaultFOV	Float	Normal FOV
ADSInterpSpeed	Float	Camera blend speed
bIsAiming	Bool	Currently ADS
FireRateTimer	FTimerHandle	Fire rate control
bCanFire	Bool	Not on cooldown
EquipDuration	Float	Seconds for equip animation
HolsterDuration	Float	Seconds for holster animation
RecoilPitch	Float	Camera pitch per shot
RecoilYaw	Float	Camera yaw per shot

Enums

Enum	Values	Description
EWeaponState	Holstered, Equipping, Ready, Firing, Reloading, Holstering, Broken	Weapon lifecycle
EWeaponFireMode	SemiAutomatic, FullAutomatic, BurstFire, ChargeAndRelease, MeleeSwing	Fire type

Functions / Events

Name	Inputs	Outputs	Description
Equip	—	—	Play equip anim, attach to EquipSocket, set state to Ready
Holster	—	—	Play holster anim, attach to HolsterSocket, set state to Holstered
StartFire	—	—	Begin fire loop (if auto) or single fire (semi)
StopFire	—	—	End fire loop
CanFire	—	Bool	Check state, ammo, cooldown
OnFire	—	—	Virtual: subclass implements actual fire logic
StartReload	—	—	Begin reload sequence
FinishReload	—	—	Called after reload anim
StartAim	—	—	Blend camera to ADS FOV
StopAim	—	—	Blend camera back to DefaultFOV
SetWeaponState	NewState: EWeaponState	—	Change state and broadcast
GetWeaponTag	—	GameplayTag	Return weapon identifier
OnWeaponBroken	—	—	Weapon disabled (durability zero)

Event Dispatchers

Name	Parameters	Fired When
OnWeaponStateChanged	NewState: EWeaponState, OldState: EWeaponState	State machine change
OnWeaponEquipped	WeaponRef: BP_WeaponBase	Ready to use
OnWeaponHolstered	WeaponRef: BP_WeaponBase	Stored away
OnFireStarted	—	Fire input received and valid
OnFireStopped	—	Fire input released
OnAimStarted	—	ADS enter
OnAimStopped	—	ADS exit
OnReloadStarted	—	Reload begin
OnReloadCompleted	—	Reload finish
OnWeaponBroken	—	Durability depleted

Blueprint Flow

[StartFire]
  └─► If !CanFire → return
  └─► Set WeaponState = Firing
  └─► Broadcast OnFireStarted
  └─► Call OnFire (subclass override)
  └─► If FireMode == FullAutomatic → start FireRateTimer loop
  └─► If FireMode == SemiAutomatic → block until timer clears

[StopFire]
  └─► Clear FireRateTimer
  └─► If FireMode == BurstFire → let burst complete, then stop
  └─► Set WeaponState = Ready
  └─► Broadcast OnFireStopped

[StartReload]
  └─► If WeaponState != Ready → return
  └─► Set WeaponState = Reloading
  └─► Broadcast OnReloadStarted
  └─► Start animation or timer for reload duration
  └─► On completion → FinishReload

[FinishReload]
  └─► BPC_AmmoComponent.RefillAmmo(WeaponData.MagazineSize)
  └─► Set WeaponState = Ready
  └─► Broadcast OnReloadCompleted

[StartAim / StopAim]
  └─► Set bIsAiming
  └─► Get BPC_PlayerCameraManager from owner
  └─► Set FOV with interp speed
  └─► Broadcast OnAimStarted / OnAimStopped

Communications With

Target System	Method	Why
BPC_EquipmentSystem	Direct	Get/return weapon socket assignment
BPC_AmmoComponent	Get Component	Check / consume / refill ammo
BPC_DamageHandler	Get Component	Delegate damage processing
BPC_CombatFeedbackComponent	Get Component	Play muzzle flash, hit FX, sounds
BPC_PlayerCameraManager	Get from Owner	ADS FOV blend
BPC_InventoryComponent	Get from Owner	Check ammo inventory
HUD Widget	Dispatcher (via GM)	Update crosshair, ammo display
Owner (Player Character)	Direct	Animation blueprint queries weapon state

Reuse Notes

Subclass for ranged or melee specific fire implementations. The state machine prevents firing during reload, equip, or holster sequences. Weapons are data-driven via DA_WeaponData — design changes never require blueprint edits.