UE5-Modular-Game-Framework/docs/blueprints/02-player/14_BPC_CameraStateLayer.md

# 14 — Camera State Layer (`BPC_CameraStateLayer`)

## Purpose
Manages the first-person camera's dynamic behaviour: field-of-view changes based on movement speed, camera shake from impacts/events, head bob intensity, and location offsets for crouch/prone/hide. Centralises all camera-modifying logic so other systems can request camera changes without directly manipulating the camera.

## Dependencies
- **Requires:** `BPC_MovementStateSystem` (speed-based FOV), `BPC_StressSystem` (stress-based distortion)
- **Required By:** `PC_PlayerController` (camera management), `BPC_HidingSystem` (peek camera offsets), `WBP_HUD` (post-process materials)
- **Engine/Plugin Requirements:** Camera Shake patterns, Post-Process Materials, Material Parameter Collections

## Class Info
| Property | Value |
|----------|-------|
| **Parent Class** | `ActorComponent` |
| **Class Type** | Blueprint Component |
| **Asset Path** | `Content/Framework/Player/BPC_CameraStateLayer` |
| **Implements Interfaces** | None |

---

## 1. Enums

### `E_CameraState`
| Value | Description |
|-------|-------------|
| `Default = 0` | Normal gameplay FOV |
| `Aiming = 1` | Zoomed in (weapon aim, inspection) |
| `Sprinting = 2` | FOV widened for speed |
| `Crouching = 3` | Slight downward offset |
| `Peeking = 4` | Offset sideways from cover |
| `Hiding = 5` | Constricted FOV, darkness from inside |
| `Stressed = 6` | FOV pulsing, chromatic aberration |
| `Injured = 7` | FOV wobble, blood tint |
| `Death = 8` | Fade to black, camera drop |
| `Cutscene = 9` | Fixed camera, no player control |

### `E_CameraShakePriority`
| Value | Description |
|-------|-------------|
| `Low = 0` | Ambient shake (footstep, wind) |
| `Medium = 1` | Impact shake (damage, explosion) |
| `High = 2` | Critical shake (near-death, supernatural event) |
| `Cinematic = 3` | Scripted shake, overrides everything |

---

## 2. Structs

### `S_CameraShakeRequest`
| Field | Type | Description |
|-------|------|-------------|
| `ShakeClass` | `TSubclassOf<UCameraShakeBase>` | Camera shake blueprint class |
| `Scale` | `Float` | Intensity scale [0..1] |
| `Priority` | `E_CameraShakePriority` | Priority level |
| `Duration` | `Float` | How long the shake lasts |
| `bIsLooping` | `Boolean` | Whether the shake loops |
| `Tag` | `GameplayTag` | Unique identifier to prevent stacking same shake |

### `S_CameraStateConfig`
| Field | Type | Description |
|-------|------|-------------|
| `TargetFOV` | `Float` | FOV value for this state |
| `BlendSpeed` | `Float` | How fast to blend to this FOV |
| `HeadOffset` | `Vector` | Location offset for head/camera |
| `HeadRotation` | `Rotator` | Rotation offset |
| `bConstrainPitch` | `Boolean` | Limit vertical look in this state |
| `MinPitch` | `Float` | Minimum pitch angle |
| `MaxPitch` | `Float` | Maximum pitch angle |
| `bEnableHeadBob` | `Boolean` | Enable head bob in this state |
| `HeadBobAmplitude` | `Float` | Head bob strength |
| `HeadBobFrequency` | `Float` | Head bob speed |

### `S_PostProcessOverride`
| Field | Type | Description |
|-------|------|-------------|
| `bOverrideVignette` | `Boolean` | Override vignette intensity |
| `VignetteIntensity` | `Float` | Vignette strength [0..1] |
| `bOverrideChromaticAberration` | `Boolean` | Override CA intensity |
| `ChromaticAberrationIntensity` | `Float` | CA strength [0..1] |
| `bOverrideColorGrading` | `Boolean` | Override color grading |
| `ColorGradingLUT` | `Texture` | LUT texture for color grading |
| `BlendTime` | `Float` | Time to blend to new post-process settings |

---

## 3. Variables

### Configuration (Instance Editable, Expose On Spawn)

| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `DefaultFOV` | `Float` | `90.0` | `Camera Config` | Default first-person FOV |
| `StateConfigs` | `Map<E_CameraState, S_CameraStateConfig>` | `all states` | `Camera Config` | FOV/offset values per state |
| `DefaultPostProcess` | `S_PostProcessOverride` | `-` | `Camera Config` | Default post-process settings |
| `BaseHeadBobAmplitude` | `Float` | `0.1` | `Camera Config` | Default head bob strength |
| `BaseHeadBobFrequency` | `Float` | `1.0` | `Camera Config` | Default head bob speed |
| `SprintFOVMultiplier` | `Float` | `1.1` | `Camera Config` | FOV multiplied by this when sprinting |
| `StressFOVPulseAmount` | `Float` | `5.0` | `Camera Config` | FOV pulse range when stressed (degrees) |
| `StressFOVPulseSpeed` | `Float` | `0.5` | `Camera Config` | Speed of stress FOV pulse |

### Internal (Private / Protected, No Expose)

| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `CurrentCameraState` | `E_CameraState` | `Default` | `Camera State` | Active camera state |
| `CurrentTargetFOV` | `Float` | `90.0` | `Camera State` | Current FOV target being blended to |
| `CurrentFOV` | `Float` | `90.0` | `Camera State` | Actual current FOV |
| `ActiveShakeRequests` | `Map<FName, S_CameraShakeRequest>` | `{}` | `Camera State` | Active shakes by tag |
| `HighestShakePriority` | `E_CameraShakePriority` | `Low` | `Camera State` | Current highest priority shake |
| `CameraOffsetTarget` | `Vector` | `(0,0,0)` | `Camera State` | Target head offset being blended to |
| `CameraRotationTarget` | `Rotator` | `(0,0,0)` | `Camera State` | Target rotation offset |
| `bIsPitchConstrained` | `Boolean` | `false` | `Camera State` | Whether pitch is currently constrained |
| `PostProcessBlendAlpha` | `Float` | `0.0` | `Camera State` | Current post-process blend |
| `FOVTimerHandle` | `FTimerHandle` | `-` | `Camera State` | Timer for FOV pulse when stressed |
| `PlayerCameraManager` | `APlayerCameraManager` | `None` | `Camera State` | Cached camera manager reference |

### Replicated (if multiplayer)

| Variable | Type | Condition | Description |
|----------|------|-----------|-------------|
| `CurrentCameraState` | `E_CameraState` | `Replicated` | Synced camera state |

---

## 4. Functions

### Public Functions

#### `RequestCameraState` → `void`
- **Description:** Sets the camera to a state config. Multiple states can stack; highest priority wins.
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `NewState` | `E_CameraState` | Desired camera state |
  | `bImmediate` | `Boolean` | Skip blend |
- **Blueprint Authority:** Any
- **Flow:**
  1. Store CurrentCameraState as PreviousState
  2. CurrentCameraState = NewState
  3. Get S_CameraStateConfig for NewState
  4. Set CurrentTargetFOV to config.TargetFOV
  5. Set CameraOffsetTarget to config.HeadOffset
  6. Set CameraRotationTarget to config.HeadRotation
  7. Set pitch constraints from config
  8. Begin blending toward targets over BlendSpeed
  9. Fire OnCameraStateChanged

#### `PlayCameraShake` → `void`
- **Description:** Plays a camera shake, respecting priority to prevent shake stacking.
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `ShakeRequest` | `S_CameraShakeRequest` | Shake parameters |
- **Flow:**
  1. If ShakeRequest.Tag already in ActiveShakeRequests:
     - If new priority >= existing: replace existing shake
     - If new priority < existing: ignore
  2. Ask PlayerCameraManager to play shake
  3. Store in ActiveShakeRequests
  4. If Duration > 0: start timer to auto-stop shake after Duration

#### `StopCameraShake` → `void`
- **Description:** Stops a specific camera shake.
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `ShakeTag` | `GameplayTag` | Tag identifying the shake |
- **Flow:**
  1. If ShakeTag exists in ActiveShakeRequests:
     - Stop the shake in PlayerCameraManager
     - Remove from ActiveShakeRequests

#### `ApplyPostProcessOverride` → `void`
- **Description:** Applies temporary post-process settings (vignette, CA, color grading).
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `Override` | `S_PostProcessOverride` | Post-process settings |
  | `bInstant` | `Boolean` | If true, blend instantly |
- **Flow:**
  1. If bInstant: apply immediately
  2. Else: start blend over Override.BlendTime
  3. Update Material Parameter Collection values

#### `ClearPostProcessOverride` → `void`
- **Description:** Returns post-process to default settings.
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `BlendTime` | `Float` | Seconds to blend back to default |
- **Flow:**
  1. Blend all post-process parameters to 0 / neutral over BlendTime

#### `GetCameraStateConfig` → `S_CameraStateConfig`
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `State` | `E_CameraState` | Which state to query |
- **Flow:** Return StateConfigs[State]

### Protected / Private Functions

#### `BlendToTargetFOV (Tick)` → `void`
- **Description:** Each tick, blend CurrentFOV toward CurrentTargetFOV.
- **Flow:**
  1. Delta = CurrentTargetFOV - CurrentFOV
  2. If Abs(Delta) < 0.1: CurrentFOV = CurrentTargetFOV
  3. Else: CurrentFOV += Delta * BlendSpeed * DeltaTime
  4. Apply CurrentFOV to PlayerCameraManager

#### `BlendCameraOffset (Tick)` → `void`
- **Description:** Each tick, blend camera location/rotation toward target.
- **Flow:**
  1. InterpVTo(CameraOffsetTarget) for location
  2. InterpRTo(CameraRotationTarget) for rotation
  3. Apply offset to camera boom or view target

#### `UpdateStressPulse` → `void`
- **Description:** If stressed, pulse FOV for uneasy effect.
- **Flow:**
  1. If CurrentCameraState != Stressed: return
  2. PulseValue = Sin(Time * StressFOVPulseSpeed * PI * 2) * StressFOVPulseAmount
  3. CurrentTargetFOV = StateConfigs[Stressed].TargetFOV + PulseValue

---

## 5. Event Dispatchers

| Dispatcher | Parameters | Bind Access | Description |
|------------|-----------|-------------|-------------|
| `OnCameraStateChanged` | `E_CameraState OldState`, `E_CameraState NewState` | `Public` | Fired when camera state changes |
| `OnFOVChanged` | `float OldFOV`, `float NewFOV` | `Public` | Fired when FOV changes |
| `OnShakeStarted` | `GameplayTag ShakeTag`, `float Scale` | `Public` | Fired when a camera shake begins |
| `OnShakeEnded` | `GameplayTag ShakeTag` | `Public` | Fired when a camera shake ends |
| `OnPostProcessChanged` | `float Vignette`, `float ChromaticAb` | `Public` | Fired on post-process change |
| `OnCameraConstrained` | `bool bIsConstrained`, `float MinPitch`, `float MaxPitch` | `Public` | Fired when pitch constraints change |

---

## 6. Overridden Events / Custom Events

### Event: `BeginPlay`
- **Description:** Cache camera manager, set initial FOV, bind to state systems.
- **Flow:**
  1. Get PlayerCameraManager from owner's controller
  2. Set CurrentFOV = DefaultFOV
  3. Apply to camera
  4. Bind to BPC_MovementStateSystem.OnMovementModeChanged
  5. Bind to BPC_StressSystem.OnStressTierChanged

### Custom Event: `OnMovementModeChangedHandler`
- **Description:** Reacts to movement changes for FOV adjustments.
- **Flow:**
  1. If Sprinting: RequestCameraState(Sprinting)
  2. If Crouching: RequestCameraState(Crouching)
  3. If Idle/Walking: RequestCameraState(Default)

### Custom Event: `OnStressTierChangedHandler`
- **Description:** Reacts to stress tier changes for camera effects.
- **Flow:**
  1. If tier >= Panicked: RequestCameraState(Stressed), apply CA post-process
  2. If tier < Distressed: return to Default camera, clear post-process

---

## 7. Blueprint Graph Logic Flow

```mermaid
flowchart TD
    A[RequestCameraState called] --> B{NewState == Current?}
    B -->|Yes| C[Return]
    B -->|No| D[Look up S_CameraStateConfig]
    D --> E[Set FOV target]
    E --> F[Set head offset/rotation targets]
    F --> G[Set pitch constraints]
    G --> H[Fire OnCameraStateChanged]
    H --> I[BlendTick: each frame]
    I --> J[Interp FOV toward target]
    J --> K[Interp offset toward target]
    K --> L[Apply to PlayerCameraManager]
    L --> M{Is Stressed state?}
    M -->|Yes| N[Apply FOV pulse via sine wave]
    M -->|No| O[Clear pulse effect]
```

---

## 8. Communication Matrix

| Who Talks | How | What Is Sent |
|-----------|-----|-------------|
| `BPC_CameraStateLayer` | `Dispatcher` | `OnCameraStateChanged` -> `ABP_GASP` (anim offset), `WBP_HUD` (post-process) |
| `BPC_CameraStateLayer` | `Dispatcher` | `OnShakeStarted` / `OnShakeEnded` -> `BP_AudioManager` |
| `BPC_CameraStateLayer` | `Listener` | Binds to `BPC_MovementStateSystem.OnMovementModeChanged` for FOV |
| `BPC_CameraStateLayer` | `Listener` | Binds to `BPC_StressSystem.OnStressTierChanged` for distortion |
| `BPC_CameraStateLayer` | `Listener` | Binds to `BPC_HealthSystem.OnDamageTaken` for injury shake |
| `External (Any)` | `Direct` | Calls `PlayCameraShake` for any gameplay event |
| `BPC_HidingSystem` | `Direct` | Calls `RequestCameraState(Peeking)` with peek offset |
| `BPC_HidingSystem` | `Direct` | Calls `RequestCameraState(Hiding)` with hide FOV |

---

## 9. Validation / Testing Checklist

- [ ] FOV blends smoothly between states at configured speed
- [ ] Sprinting FOV wider than Default, returns on stop
- [ ] Camera shake priority prevents lower-priority shakes from overriding high-priority ones
- [ ] Stress pulsing creates smooth FOV oscillation without jitter
- [ ] Post-process overrides blend in/out correctly
- [ ] Pitch constraints apply correctly in hiding/peeking states
- [ ] Multiple state changes are queued — last request wins
- [ ] Edge case: Rapid state switching between sprint and crouch transitions smoothly
- [ ] Edge case: Camera shake with same tag replaces shake without stacking
- [ ] Edge case: ClearPostProcessOverride returns to default with correct blend
- [ ] All active shakes stop on component destroy or pawn unpossess

---

## 10. Reuse Notes

- Camera shake patterns should be authored as Blueprint Camera Shake classes in Content/Framework/Player/Shakes/.
- Post-process settings use a Material Parameter Collection (MPC_CameraEffects) for real-time parameter updates.
- The stress FOV pulse creates a subtle "unease" effect — pair with audio breathing changes for best results.
- For multiplayer: camera shakes are local-only; state changes replicate for shared visual consistency.
- Custom camera states can be added by extending E_CameraState and adding a config entry.

---

## 11. Multiplayer Networking

**Replication: State only — effects are local.** Camera FOV blending, shake, and post-processing are per-client experiences. Only the state enum syncs.

| Variable | Condition | Purpose |
|----------|-----------|---------|
| `CurrentCameraState` | `Replicated` | Synced for shared context (e.g., all players know someone is aiming) |

### Authority
- `RequestCameraState` can be called by client; state replicates to all.
- `PlayCameraShake`, `ApplyPostProcessOverride`, `BlendToTargetFOV` are **local only**.
- FOV pulse, head bob, camera offset blending are **local only**.

### Client Prediction
- Camera is inherently local — no prediction needed. State changes replicate for other players' awareness.

---

*Blueprint Spec: Camera State Layer. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*