ccd1872e59
- Added C++ status updates for player systems (02-player-systems.md) indicating the implementation status of systems 08-11 and their relation to BPC_StateManager. - Enhanced inventory systems documentation (04-inventory-systems.md) with C++ status for BPC_InventorySystem and DA_ItemData, clarifying their implementation details. - Updated weapons systems documentation (08-weapons-systems.md) to reflect the C++ implementation status of BPC_DamageReceptionSystem and stubs for hit reaction and shield defense systems.
179 lines
12 KiB
Markdown
179 lines
12 KiB
Markdown
# 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.*
|