# BPC_RecoilSystem — Actor Component

**File:** [`Content/Framework/Weapons/BPC_RecoilSystem`](Content/Framework/Weapons/BPC_RecoilSystem.uasset)
**Parent Class:** `UActorComponent`
**Dependencies:** [`DA_WeaponData`](49_BP_WeaponBase.md), [`BPC_FirearmSystem`](BPC_FirearmSystem.md), [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md)

**Purpose:** Handles procedural recoil: camera kick, recovery curve, and ADS recoil reduction. Works with `BPC_FirearmSystem` to apply per-weapon recoil patterns.

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `RecoilPattern` | CurveVector | Per-weapon kick pattern (X=pitch, Y=yaw) |
| `RecoverySpeed` | Float | How fast camera returns to rest |
| `ADSRecoilMultiplier` | Float | Recoil reduction while aiming (0.3-0.7) |
| `CurrentRecoilOffset` | Vector2D | Accumulated recoil offset |
| `bIsRecovering` | Bool | Recovery in progress |

## Functions / Events

| Name | Inputs | Outputs | What it does |
|------|--------|---------|--------------|
| `ApplyRecoil` | ShotCount: Integer, bADS: Bool | — | Applies recoil kick based on weapon pattern |
| `ResetRecoil` | — | — | Clears accumulated offset |
| `TickRecovery` | DeltaTime: Float | — | Lerps CurrentRecoilOffset back toward zero |
| `SetRecoilPattern` | Pattern: CurveVector | — | Loads per-weapon recoil data from DA_WeaponData |

## Blueprint Flow

```
[FirearmSystem fires] -> ApplyRecoil(shotCount, bADS)
  -> Look up RecoilPattern value at shotCount index
  -> Apply ADSRecoilMultiplier if bADS
  -> Add to CurrentRecoilOffset
  -> Push offset to BPC_CameraStateLayer
  -> Start recovery timer on tick
```

## Communications With

| Target System | Method | Why |
|---------------|--------|-----|
| `BPC_FirearmSystem` | Direct call from ApplyRecoilRequest | Receives fire events |
| `BPC_CameraStateLayer` | Direct ApplyFOVModifier | Camera kick application |

## Reuse Notes

- RecoilPattern is a CurveVector from DA_WeaponData — swap per weapon
- For hitscan weapons, call ApplyRecoil on every shot. For projectile, call on fire release
- Recovery runs on tick when bIsRecovering; disable tick at rest for performance

---

## Manual Implementation Guide

### Class Setup
1. Create Blueprint Class: Parent = `ActorComponent`, Name = `BPC_RecoilSystem`
2. Attach to `BP_RangedWeapon` or Player Character
3. **⚠️ Local only** — recoil is cosmetic, not replicated

### Variable Init (BeginPlay)
```
Event BeginPlay
  ├─ Set CurrentRecoilOffset = (0, 0)
  ├─ Set bIsRecovering = false
  ├─ Read RecoilPattern from DA_WeaponData
  └─ Cache: BPC_CameraStateLayer (from Player)
```

### Function Node-by-Node

#### `ApplyRecoil(ShotCount: Integer, bADS: Boolean)` → `void`
```
Step 1: Sample RecoilPattern curve at ShotCount (or accumulated counter)
Step 2: Get curve output: Pitch = X channel, Yaw = Y channel
Step 3: If bADS: Pitch *= ADSRecoilMultiplier, Yaw *= ADSRecoilMultiplier
Step 4: CurrentRecoilOffset.X += Pitch, CurrentRecoilOffset.Y += Yaw
Step 5: Push to camera:
  BPC_CameraStateLayer.AddControllerPitch(Pitch)  ← or PlayCameraShake
  BPC_CameraStateLayer.AddControllerYaw(Yaw)
Step 6: Set bIsRecovering = true
Step 7: Set Timer (0.05s loop) → TickRecovery  ← timer runs while recovering
```

#### `TickRecovery(DeltaTime: Float)` → `void`
```
Step 1: CurrentRecoilOffset = Lerp(CurrentRecoilOffset, Vector2D(0,0), RecoverySpeed * DeltaTime)
Step 2: If CurrentRecoilOffset nearly zero (< 0.01):
  ResetRecoil()
  Clear Recovery timer
```

### Build Checklist
- [ ] Create BPC_RecoilSystem, attach to Player
- [ ] Create RecoilPattern CurveVector per weapon (X=pitch, Y=yaw)
- [ ] Implement ApplyRecoil with curve sampling + ADS multiplier
- [ ] Implement TickRecovery with lerp toward zero
- [ ] Wire to BPC_FirearmSystem.OnFire
- [ ] Test: fire weapon → camera kicks up → recovers to center