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.

---

Manual Implementation Guide

Class Setup

1. Create Blueprint Class: Parent = Actor, Name = BP_WeaponBase
2. Save to: Content/Framework/Weapons/
3. Add components in Construction Script:
   • WeaponRoot (SceneComponent) — root
   • SkeletalMesh (SkeletalMeshComponent) — attached to root
4. Set Replicates = true in Class Defaults

Variable Defaults (Class Defaults)

Variable	Type	Default
WeaponState	EWeaponState	Holstered
HolsterSocket	Name	weapon_holster
EquipSocket	Name	weapon_equip
AimDownSightsFOV	Float	55.0
DefaultFOV	Float	90.0
ADSInterpSpeed	Float	10.0
bIsAiming	Boolean	false
bCanFire	Boolean	true
EquipDuration	Float	0.5
HolsterDuration	Float	0.5
RecoilPitch	Float	2.0
RecoilYaw	Float	0.5

Function Implementations

Equip(CharacterOwner: Character) → void

[Function: Equip]
  Step 1: Branch on WeaponState == Holstered → If not, return (can't equip twice)
  Step 2: SetWeaponState(Equipping)
  Step 3: AttachToComponent(CharacterOwner.Mesh, EquipSocket)
    - Set Relative Location = (0,0,0)
    - Set Relative Rotation = (0,0,0)
  Step 4: Set Actor Hidden In Game = false
  Step 5: Play equip animation on SkeletalMesh (if montage exists)
  Step 6: Start timer for EquipDuration:
    └─ On timer complete:
      - SetWeaponState(Ready)
      - Set bCanFire = true
      - Fire OnWeaponEquipped(Self)

Nodes: Switch on EWeaponState, Attach Actor to Component, Set Actor Hidden In Game, Play Animation, Set Timer by Event

Holster() → void

[Function: Holster]
  Step 1: Branch on WeaponState == Ready OR Firing → If not, return
  Step 2: If WeaponState == Firing: StopFire first
  Step 3: SetWeaponState(Holstering)
  Step 4: Play holster animation on SkeletalMesh
  Step 5: Start timer for HolsterDuration:
    └─ On timer complete:
      - AttachToComponent(CharacterOwner.Mesh, HolsterSocket)
      - SetWeaponState(Holstered)
      - Fire OnWeaponHolstered(Self)

StartFire() → void

[Function: StartFire]
  Step 1: Branch on WeaponState == Ready (only fire from Ready state):
    False → Return
  Step 2: Call CanFire() → Branch on result:
    False → Return
  Step 3: SetWeaponState(Firing)
  Step 4: Fire OnFireStarted
  Step 5: Call OnFire() — this is the subclass override point (virtual function)
  Step 6: Switch on WeaponData.FireMode:
    Case SemiAutomatic:
      - Set bCanFire = false
      - Set timer by WeaponData.FireRate → on complete: Set bCanFire = true
    Case FullAutomatic:
      - Start looping timer (interval = WeaponData.FireRate)
      - Each tick: Call OnFire()
    Case BurstFire:
      - Loop 3 times with WeaponData.FireRate delay between each
      - On burst complete: SetWeaponState(Ready)

Important: OnFire() is a BlueprintImplementableEvent — it has NO body in BP_WeaponBase. Subclasses (BP_RangedWeapon, BP_MeleeWeapon) override it with their own fire logic.

StopFire() → void

[Function: StopFire]
  Step 1: Branch on WeaponState == Firing:
    False → Return
  Step 2: If FireMode == FullAutomatic OR BurstFire:
    - Clear all FireRate timers
  Step 3: SetWeaponState(Ready)
  Step 4: Fire OnFireStopped

CanFire() → Boolean

[Function: CanFire] (Pure)
  Step 1: Branch on WeaponState == Ready → If not, return false
  Step 2: Branch on bCanFire → If not, return false (on cooldown)
  Step 3: Get AmmoComponent from Owner → Call HasAmmo()
    - If no ammo: return false (subclass may trigger auto-reload)
  Step 4: Get Owner → Get BPC_StateManager → Call IsActionPermitted(GameplayTag: "Action.Fire")
    - If not permitted: return false
  Step 5: Return true

StartReload() → void

[Function: StartReload]
  Step 1: Branch on WeaponState == Ready:
    False → Return (can't reload while firing/holstered)
  Step 2: Branch on AmmoComponent.IsMagazineFull():
    True → Return (no need to reload)
  Step 3: Branch on AmmoComponent.HasReserveAmmo():
    False → Return (no ammo to load)
  Step 4: SetWeaponState(Reloading)
  Step 5: Fire OnReloadStarted
  Step 6: Play reload animation montage:
    - Use AnimNotify "OnReloadComplete" at the ammo-insert frame
    - AnimNotify handler: call FinishReload()

FinishReload() → void

[Function: FinishReload]
  Step 1: Get AmmoComponent → Call RefillAmmo(MagazineSize from WeaponData)
  Step 2: SetWeaponState(Ready)
  Step 3: Fire OnReloadCompleted

StartAim() → void

[Function: StartAim]
  Step 1: Set bIsAiming = true
  Step 2: Get Owner → Get PlayerController → Get PlayerCameraManager
  Step 3: Set PlayerCameraManager Field of View to AimDownSightsFOV with interp speed
  Step 4: Fire OnAimStarted

StopAim() → void

[Function: StopAim]
  Step 1: Set bIsAiming = false
  Step 2: Get PlayerCameraManager → Set FOV to DefaultFOV with interp
  Step 3: Fire OnAimStopped

SetWeaponState(NewState: EWeaponState) → void

[Function: SetWeaponState]
  Step 1: OldState = WeaponState
  Step 2: If NewState == OldState → Return
  Step 3: WeaponState = NewState
  Step 4: Mark variable dirty (for replication)
  Step 5: Fire OnWeaponStateChanged(NewState, OldState)

Event Dispatcher Bindings

Bind to Dispatcher	Custom Event	Logic
IA_Fire (Pressed)	OnFirePressed	Call StartFire()
IA_Fire (Released)	OnFireReleased	Call StopFire()
IA_Reload (Pressed)	OnReloadPressed	Call StartReload()
IA_Aim (Pressed)	OnAimPressed	Call StartAim()
IA_Aim (Released)	OnAimReleased	Call StopAim()

Networking

• WeaponState replicated with OnRep_WeaponState → plays matching animation on remote clients
• All state transitions are server-authoritative via Server_StartFire, Server_StartReload, etc.
• Client predicts: fire animation, muzzle flash, recoil (cosmetic only)
• Server validates: ammo count, fire rate cooldown, state machine transitions

Blueprint Build Checklist

• Create BP_WeaponBase actor with WeaponRoot + SkeletalMesh components
• Add EquipmentSocket component on Player Character (weapon_equip, weapon_holster)
• Add all variables with correct types and defaults
• Implement Equip/Holster with attach/detach and animation timers
• Implement StartFire/StopFire with fire rate timer loop
• Create OnFire as BlueprintImplementableEvent (empty — subclasses override)
• Implement CanFire checks: state, cooldown, ammo, StateManager permission
• Implement StartReload/FinishReload with animation notify
• Implement StartAim/StopAim with FOV interpolation
• Implement SetWeaponState with old state tracking and dispatcher
• Bind all input actions (Fire, Reload, Aim)
• Add networking: replicated WeaponState, Server_ RPCs for all mutators