# V2 Camera Rail

The camera rail system evaluates predefined spline camera paths for scripted
sequences. Designers provide timed rail points, and the runtime returns a
camera-manager `Rail` mode with sampled position, rotation, FOV, and blend
duration.

## Runtime Surface

- `FV2CameraRailConfig` configures rail id, duration, looping, cubic spline
  sampling, time clamping, optional tangent orientation, default FOV, and blend
  duration.
- `FV2CameraRailState` carries playback time, delta seconds, play rate, and
  playing state.
- `FV2CameraRailPoint` carries point id, timestamp, camera location, rotation,
  and FOV.
- `FV2CameraRailEvaluation` returns resolved rail time, normalized alpha,
  segment index, sampled pose, FOV, blend time, loop/end flags, mode spec, and
  validation issues.

## Rail Rules

1. Invalid config, state, point data, or fewer than two points is blocking.
2. Point times must be strictly increasing.
3. Duration comes from `DurationSeconds` when set, otherwise from the last rail
   point time.
4. Playback time advances by `DeltaSeconds * PlayRate` only while playing.
5. Looping rails wrap time with `FMath::Fmod` and report `RailLooped`.
6. Non-looping rails clamp to the rail duration and report `EndReached` at the
   end.
7. Cubic spline sampling uses Catmull-Rom interpolation for location, with
   shortest-path rotation and linear FOV interpolation.

## Camera Manager Export

`EvaluateCameraRail` fills `ModeSpec` using the rail id and
`EV2CameraModeType::Rail`. `BuildCameraRailMode` can export a custom mode id,
priority, and active flag for camera stacks while preserving the sampled rail
pose.

## Validation Commands

Run these targeted checks when touching camera rails:

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