# Gameplay Camera Framework Guide

The gameplay camera framework adds renderer-neutral helpers for third-person,
first-person, rail, VR, split-screen, and debug camera workflows. It shares the
package's `CameraState`, `Vec3`, easing, and spline primitives.

## Camera Manager

Create modes with `createGameplayCameraMode` and manage them with
`createGameplayCameraManager`, `upsertGameplayCameraMode`,
`setGameplayCameraModeEnabled`, `removeGameplayCameraMode`, and
`updateGameplayCameraManager`. The manager chooses the highest-priority enabled
mode and blends into it using the mode's configured blend duration.

## Third-Person and Collision

`updateThirdPersonOrbitCamera` evaluates orbit yaw, pitch, zoom distance,
shoulder offset, and height offset around a gameplay target. Use
`resolveCameraSpringArm` to trace from target pivot to desired camera position
against spherical obstacles, then use `applyCameraCollisionAvoidance` to apply
the resolved position and report obstacles that should be transparent near the
camera.

## First-Person and Lock-On

`createFirstPersonCamera` attaches the camera to a head position or head offset
and applies head bob plus weapon sway from look input. `applyCameraSoftLock`
biases the camera target toward a lock-on target without forcing a full target
snap.

## Interpolation, Shake, Rails, and Zoom

`blendCameraStates` blends position, target, up vector, FOV, focal length, roll,
and clip distances. Shake layers support perlin-style value noise, spring
oscillation, and directional impacts through `createGameplayCameraShakeState`,
`updateGameplayCameraShake`, `sampleGameplayCameraShake`, and
`applyGameplayCameraShake`.

Use `createGameplayCameraRail` and `evaluateGameplayCameraRail` for scripted
spline paths. Use `createGameplayCameraZoomState`, `updateGameplayCameraZoom`,
and `applyGameplayCameraZoom` for hip-fire, aim-down-sights, scope, and
binocular FOV transitions.

## Movement Assist

`applyCameraDeadZoneAndLookAhead` keeps small target movement inside a dead zone
and offsets framing in the target velocity direction. This keeps traversal
cameras stable while still showing intent during sustained movement.

## Split-Screen and VR

`createSplitScreenViewports` returns normalized viewports for one to four
players with horizontal, vertical, or grid layouts. `createVrCameraRig` creates
a head-tracked camera, eye positions from IPD, snap or smooth turn deltas, and a
comfort vignette strength from movement speed.

## Zones and Debugging

`evaluateCameraPostProcessZones` selects the highest-priority zone containing
the camera and returns blend weight plus fog, color grade, depth-of-field, and
exposure settings.

`createCameraDebugVisualization` returns frustum rays, spring arm lines,
collision traces, look-at targets, and labels for runtime debug overlays.
