# V2 First-Person Camera

The first-person camera resolves a camera pose from a character head-bone
transform. It also computes deterministic head bob, weapon sway, FOV clamping,
and a camera-manager mode spec for first-person gameplay flows.

## Runtime Surface

- `FV2FirstPersonCameraConfig` configures the required head bone, local eye
  offset, FOV bounds, sprint FOV offset, head-bob parameters, weapon-sway
  parameters, and blend time.
- `FV2FirstPersonCameraState` carries the current head bone name, head-bone
  availability, head transform, movement speed, and stride phase.
- `FV2FirstPersonCameraInput` carries look deltas, movement axes, delta time,
  and sprint state.
- `FV2FirstPersonCameraEvaluation` returns the camera pose, resolved stride
  phase, head-bob offset, weapon-sway offset and rotation, FOV, mode spec, and
  validation issues.

## Attachment Rules

1. The configured `RequiredHeadBoneName` must be present in the state.
2. `LocalEyeOffset` is transformed by the supplied head rotation and added to
   the head location.
3. Head bob advances stride phase by movement speed, bob speed scale, frequency,
   and delta seconds.
4. Weapon sway uses look deltas, location scale, rotation scale, and clamp
   limits. The sway output is intended for weapon/viewmodel animation, not for
   rotating the camera pose.
5. Sprint FOV applies `SprintFieldOfViewOffset` and clamps to configured min and
   max FOV, emitting `FovClamped` when clamped.
6. Invalid config, invalid state, invalid input, or a missing head bone are
   blocking issues.

## Camera Manager Export

`EvaluateFirstPersonCamera` fills `ModeSpec` with
`EV2CameraModeType::FirstPerson` using id `camera.first_person`.
`BuildFirstPersonCameraMode` can export a custom id, priority, and active flag
for a camera manager stack.

## Validation Commands

Run these targeted checks when touching the first-person camera:

```bash
python3 V2/ue/Tools/check-v2-first-person-camera.py
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/FirstPersonCamera_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-first-person-camera.py
```