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:

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