# Replay Viewer Controls Guide

The replay system builds on `InputRecorder`, `StateSnapshotter`, `ReplayPlayer`,
and `ReplayExporter` with a higher-level file and viewer layer.

## File Format

`createReplayFile` wraps `ReplayData` in an `OSHRPLY` header containing:

- file format version
- replay ID and game version
- creation time, duration, frame count
- checksum
- compression flag

Compressed files delta-encode input frame numbers and timestamps while keeping
actions readable for tooling and anti-cheat review.

## Viewer Controls

Use `ReplayViewerController` for viewer state:

- `play`, `pause`, `seek`, `setSpeed`
- speed presets: 0.25x, 0.5x, 1x, 2x, 4x
- `getControls()` for timeline, camera, and overlay render descriptors
- `setFreeCamera(position, yaw, pitch)`
- `trackEntity(entityId, distance)`

The controller returns UI-ready data only. Engine, web, or native renderers
should draw their own timeline and controls from the render descriptors.

## Cameras And Overlays

Replay cameras support:

- player/default camera
- free camera
- tracked entity camera
- kill cam camera from attacker to victim

Overlay models include player/entity names, health, positions, team labels, and
wireframe/outline preferences.

## Highlights And Clips

`detectReplayHighlights` identifies notable windows from recorded event actions:

- multi-kills
- near-death survival
- clutch plays

`createClipExportJob` produces MP4/WebM export jobs for a selected time range
and camera angle. The job is a deterministic descriptor that a platform-specific
renderer/encoder can execute.

## Sharing, Compatibility, And Review

`createShareManifest` produces a download URL manifest with checksum, expiry,
and size. `checkReplayCompatibility` compares replay game versions to the
current runtime and reports whether migration is needed.
`scanReplayForAntiCheat` flags suspicious aim snap velocity and movement speed
for moderation review.
