105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
# BPC_FirearmSystem — Firearm Component
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`ActorComponent`
|
||
|
||
### Dependencies
|
||
- [`BPC_AmmoComponent`](52_BPC_AmmoComponent.md) — Ammo management
|
||
- [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md) — Damage application
|
||
- [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) — Visual/audio feedback
|
||
- [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md) — Recoil & ADS
|
||
- [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) — Interface for hit targets
|
||
- [`DA_WeaponData`](../14-data-assets/) — Weapon definition
|
||
|
||
### Purpose
|
||
Ranged weapon specialization. Handles line trace / projectile fire, weapon spread, bullet drop simulation, and multi-hit logic. Used by firearms (pistols, rifles, shotguns) and charge weapons.
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `FireType` | EFireType | Hitscan, Projectile, Hybrid |
|
||
| `ShootEffectType` | EShotEffect | Single, Spread, Charge |
|
||
| `Range` | Float | Max effective range (cm) |
|
||
| `SpreadAngle` | Float | Base spread in degrees |
|
||
| `SpreadRecoveryRate` | Float | Per-second recovery from spread |
|
||
| `CurrentSpread` | Float | Running spread (fired recently) |
|
||
| `MaxSpread` | Float | Spread cap |
|
||
| `BulletsPerShot` | Int | e.g. shotgun = 8 |
|
||
| `ProjectileClass` | Actor (Blueprint) | Only for Projectile / Hybrid fire types |
|
||
| `FireSocket` | FName | Muzzle attachment point |
|
||
| `MuzzleLocation` | USceneComponent | Muzzle transform reference |
|
||
| `HitScanImpacts` | Array<FHitResult> | Notify component for decals |
|
||
|
||
### Enums
|
||
|
||
| Enum | Values | Description |
|
||
|------|--------|-------------|
|
||
| `EFireType` | Hitscan, Projectile, Hybrid | Ray → Instant or Bullet actor |
|
||
| `EShotEffect` | SingleShot, SpreadShot, ChargeShot | Fire pattern |
|
||
|
||
### Functions
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `PerformHitscanFire` | EWeaponFireMode | Array<FHitResult> | Line trace from camera to crosshair; no bullet |
|
||
| `SpawnProjectile` | Direction: FVector | Actor | Spawn projectile actor with initial velocity |
|
||
| `CalculateSpread` | — | FVector | Apply random offset within CurrentSpread cone |
|
||
| `OnFire_Implementation` | — | — | Override of WeaponBase::OnFire; runs hit scan or spawns projectile |
|
||
| `ApplyRecoil` | — | — | Add camera rotation via CameraStateLayer |
|
||
| `ConsumeAmmo` | — | — | Delegate to BPC_AmmoComponent |
|
||
| `GetEffectiveRange` | — | Float | Return weapon range from data asset |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[OnFire]
|
||
└─► If FireType == Hitscan
|
||
For i = 1 .. BulletsPerShot:
|
||
AimDir = OwnerCamera.ForwardVector + CalculateSpread
|
||
PerformHitscanFire returns HitResults
|
||
For each hit:
|
||
if actor implements I_Damageable:
|
||
BPC_DamageReceptionSystem.ApplyDamage(WeaponData.Damage, Hit)
|
||
BPC_CombatFeedbackComponent.SpawnImpactFX(Hit)
|
||
└─► If FireType == Projectile
|
||
For i = 1 .. BulletsPerShot:
|
||
AimDir = OwnerCamera.ForwardVector + CalculateSpread
|
||
SpawnProjectile(AimDir * WeaponData.ProjectileSpeed)
|
||
└─► If FireType == Hybrid
|
||
Perform hitscan + spawn projectile for missed overlap area
|
||
└─► ApplyRecoil
|
||
└─► ConsumeAmmo
|
||
└─► BPC_CombatFeedbackComponent.PlayMuzzleFlash
|
||
└─► BPC_CombatFeedbackComponent.PlayFireSound
|
||
|
||
[CalculateSpread]
|
||
└─► CurrentSpread = FMath::Min(CurrentSpread + WeaponData.SpreadPerShot, MaxSpread)
|
||
└─► Return random vector in cone of CurrentSpread degrees
|
||
|
||
[OnFireStopped — super]
|
||
└─► Begin spread recovery: CurrentSpread → 0 over SpreadRecoveryRate seconds
|
||
└─► BPC_CombatFeedbackComponent.StopFireSound
|
||
```
|
||
|
||
### Communications With
|
||
|
||
| Target | Method | Why |
|
||
|--------|--------|-----|
|
||
| [`BPC_AmmoComponent`](52_BPC_AmmoComponent.md) | Get Component | Ammo check / consume |
|
||
| [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md) | Get Component | Apply damage to hit targets |
|
||
| [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) | Get Component | Muzzle flash, tracers, impact FX |
|
||
| [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md) | Get from Owner | Recoil animation |
|
||
| Owner WeaponAnimBP | Animation Instance | Fire / Reload animations |
|
||
| HUD Widget | Dispatcher | Ammo count update |
|
||
|
||
### Reuse Notes
|
||
- Hit scan fire uses camera forward, not muzzle forward, for accuracy. Muzzle is for FX only.
|
||
- Spread is cumulative while firing, resets on recovery timer.
|
||
- Projectile type requires a child BP implementing `AP_BaseProjectile` with velocity and lifetime.
|
||
- Renamed from `BP_RangedWeapon` to `BPC_FirearmSystem` per Master naming convention.
|
||
- Cross-references updated: `BPC_DamageHandlerComponent` → `BPC_DamageReceptionSystem`, `BPC_PlayerCameraManager` → `BPC_CameraStateLayer`, `DA_WeaponData` → `14-data-assets/`. |