# V2 VR Camera Rig

The VR camera rig layer resolves a head-tracked camera pose from a base camera
mode, applies comfort vignette strength from fast movement, and supports snap or
smooth turn input. The runtime is deterministic and data-driven so gameplay
systems can evaluate VR camera behavior without depending on editor-only XR
devices.

## Runtime Surface

- `FV2VRCameraRigConfig` configures tracking scale, maximum head offset,
  comfort-vignette thresholds, vignette blend speed, snap and smooth turn
  settings, turn input dead zone, feature toggles, and blend duration.
- `FV2VRCameraRigState` carries the base camera mode, tracking origin, current
  accumulated yaw, and current comfort-vignette strength.
- `FV2VRCameraRigInput` carries local head pose, movement velocity, turn input,
  delta seconds, and tracking validity.
- `FV2VRCameraRigEvaluation` returns resolved head pose, applied yaw, movement
  speed, comfort-vignette strength, turn flags, base and exported mode specs,
  and validation issues.

## VR Rules

1. Invalid config, state, or input timing is blocking.
2. Valid head tracking applies local head offset and rotation to the base camera
   mode.
3. Head offset is scaled by `TrackingScale` and clamped by
   `MaxHeadOffsetDistance`.
4. Tracking loss reports `TrackingLost` and falls back to the base camera pose.
5. Comfort vignette strength ramps toward a speed-based target when movement
   exceeds `ComfortVignetteSpeedThreshold`.
6. Snap turn applies `SnapTurnDegrees` when turn input exceeds the dead zone.
7. Smooth turn integrates
   `SmoothTurnDegreesPerSecond * TurnInput * DeltaSeconds`.
8. Turn input is clamped to the normalized `[-1, 1]` range.

## Camera Manager Export

`EvaluateVRCameraRig` fills `ModeSpec` from the base camera mode with the
resolved head-tracked location, rotation, and configured blend duration.
`BuildVRCameraRigMode` can export a custom id, priority, and active flag while
preserving base FOV, blend function, input, and cinematic metadata.

## Validation Commands

Run these targeted checks when touching the VR camera rig:

```bash
python3 V2/ue/Tools/check-v2-vr-camera-rig.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/VRCameraRig_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-vr-camera-rig.py
```