# V2 Camera Spring Arm

The camera spring arm resolves a desired camera position against supplied trace
hits. Gameplay code performs the world trace from the pivot toward the desired
camera location, then passes the trace data into this deterministic evaluator.

## Runtime Surface

- `FV2CameraSpringArmConfig` defines arm length limits, probe radius, collision
  buffer, pull-in speed, recovery speed, collision enablement, recovery
  smoothing, aim behavior, and blend time.
- `FV2CameraSpringArmState` carries the pivot, desired camera location, current
  arm length from the previous frame, and FOV.
- `FV2CameraSpringArmTraceHit` mirrors the trace data the spring arm needs:
  blocking flag, impact point, hit distance, surface normal, and penetration.
- `FV2CameraSpringArmEvaluation` returns desired, target, and adjusted arm
  lengths, the adjusted camera pose, collision and recovery flags, camera
  manager mode spec, and validation issues.

## Collision Rules

1. Desired arm length is the distance from pivot to desired camera, clamped to
   `MinArmLength` and `MaxArmLength`.
2. The nearest blocking trace hit wins.
3. The collision target length is `HitDistance - CollisionBuffer`, clamped
   between `MinArmLength` and the desired arm length.
4. Penetrating hits resolve to `MinArmLength`.
5. Collision pull-in uses `PullInSpeed * DeltaSeconds` so the camera moves
   forward quickly but deterministically.
6. With no collision, shorter current arms recover toward the desired arm using
   `RecoverySpeed * DeltaSeconds` when `bSmoothRecovery` is enabled.
7. Blocking issues are emitted for invalid config, invalid state, invalid trace
   data, or negative delta time.

## Camera Manager Export

`EvaluateCameraSpringArm` fills `ModeSpec` with a third-person camera mode using
id `camera.third_person.spring_arm`. `BuildCameraSpringArmMode` can export a
custom id, priority, and active flag for the camera manager stack.

## Validation Commands

Run these targeted checks when touching the spring arm:

```bash
python3 V2/ue/Tools/check-v2-camera-spring-arm.py
python3 V2/ue/Tools/check-v2-third-person-orbit-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/CameraSpringArm_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-camera-spring-arm.py
```