# V2 Camera Manager

The V2 camera manager is a data-driven gameplay camera stack in `V2Gameplay`. It
evaluates camera modes by priority, blends from the previous mode to the
selected active mode, and reports blocking and non-blocking authoring issues for
automation and Blueprint tools.

## Runtime Surface

- `FV2CameraModeSpec` defines one camera mode with a stable `ModeId`, mode type,
  priority, target transform, field of view, blend timing, input flags, and
  cinematic flags.
- `FV2CameraManagerStackSpec` owns the stack and default mode. Active modes are
  selected by priority. If multiple active modes share the highest priority,
  `RequestedModeId` is used as a deterministic tie-break when it names one of
  those modes.
- `FV2CameraManagerBlendRequest` carries the previous mode, requested mode,
  elapsed blend time, frame delta, and forced-cut flag.
- `FV2CameraManagerEvaluation` is the resolved camera pose. It includes the
  active mode id, mode type, location, rotation, FOV, blend alpha, remaining
  blend time, gameplay-input state, cinematic state, and validation issues.

## Activation Rules

1. The stack must have a non-empty `StackId`, a valid `DefaultModeId`, and
   unique valid mode ids.
2. Only modes with `bActive` set participate in activation.
3. The highest-priority active mode wins.
4. `RequestedModeId` can disambiguate an equal-priority tie. It cannot override
   a higher-priority active mode.
5. If the selected mode has `bBlocksLowerPriority`, lower-priority requested
   modes are reported with `PriorityConflict`.
6. If no mode is active, the evaluator falls back to the default mode and emits
   `MissingActiveMode` as a non-blocking issue when the default is valid.

## Blending

The target mode controls blend duration and curve:

- `Cut` or `bForceCut` resolves immediately to the active mode.
- `Linear` uses elapsed blend time divided by the target blend duration.
- `CubicEaseInOut` uses a smoothstep curve for designer-friendly transitions.

Missing previous modes cut to the active mode and emit a non-blocking
`MissingMode` issue so gameplay can recover without producing an invalid pose.

## Default Stack

`BuildDefaultCameraManagerStack` includes:

- `camera.third_person.orbit`, active by default for regular gameplay.
- `camera.first_person`, inactive until a first-person flow activates it.
- `camera.dialogue`, high-priority cinematic dialogue framing.
- `camera.cinematic`, highest-priority cinematic framing that blocks lower
  priority gameplay modes.
- `camera.spectator`, low-priority free camera fallback.

## Validation Commands

Run these targeted checks when touching the camera manager:

```bash
python3 V2/ue/Tools/check-v2-camera-manager.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Camera/CameraManager_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-camera-manager.py
```