# V2 Camera Collision Avoidance

The camera collision avoidance layer resolves camera placement after a desired
camera has been computed. It prevents clipping through blocking geometry by
moving the camera in front of the nearest obstacle, and it emits transparent
near-clip occluders for geometry close enough to the camera to need faded
rendering.

## Runtime Surface

- `FV2CameraCollisionAvoidanceConfig` configures probe radius, near-clip radius,
  minimum camera distance, collision buffer, pull-forward and recovery speeds,
  transparency distances, minimum opacity, enable flags, aim behavior, and mode
  blend time.
- `FV2CameraCollisionAvoidanceState` carries the pivot, desired camera location,
  current camera location, camera rotation, base camera mode type, and FOV.
- `FV2CameraCollisionAvoidanceObstacle` carries deterministic obstacle data: id,
  blocking flag, transparency support, closest point, distance from pivot,
  thickness, current opacity, and whether the camera starts inside the obstacle.
- `FV2CameraCollisionAvoidanceTransparentOccluder` returns the resolved
  near-clip fade target for each transparent occluder.
- `FV2CameraCollisionAvoidanceEvaluation` returns desired, target, and adjusted
  camera distances, adjusted pose, clipping and transparency flags, transparent
  occluders, mode spec, and validation issues.

## Clipping Rules

1. Invalid config, state, delta time, or obstacle data is blocking.
2. The desired camera vector defines the camera corridor from pivot to desired
   location.
3. The nearest blocking obstacle inside the desired corridor shortens the target
   distance to `DistanceFromPivot - CollisionBuffer`, clamped by
   `MinCameraDistance`.
4. When the camera starts inside geometry, the target distance resolves to the
   configured minimum distance.
5. Pull-forward and recovery speeds move from the current distance toward the
   target distance deterministically.
6. `NoClearCameraSpace` is reported when blocking geometry leaves no clear
   distance beyond the configured minimum.

## Transparent Near-Clip Rendering

When `bEnableNearClipTransparency` is enabled, transparent obstacles near the
adjusted camera generate `TransparentOccluders`. The fade is strongest at or
inside `TransparencyFullDistance` and blends back to each obstacle's current
opacity by `TransparencyStartDistance`. Designers can feed `TargetOpacity` into
material parameter collections, component custom depth rules, or actor fade
systems without changing camera placement.

## Camera Manager Export

`EvaluateCameraCollisionAvoidance` fills `ModeSpec` using id
`camera.collision_avoidance`. `BuildCameraCollisionAvoidanceMode` can export a
custom id, priority, and active flag while preserving the state's base mode
type.

## Validation Commands

Run these targeted checks when touching camera collision avoidance:

```bash
python3 V2/ue/Tools/check-v2-camera-collision-avoidance.py
python3 V2/ue/Tools/check-v2-camera-spring-arm.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/CameraCollisionAvoidance_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-camera-collision-avoidance.py
```