# Game Profiles

Game profiles are editable JSON files in `profiles/`. They tell GGSight which visible game surfaces to scan, which common UI words to ignore, and which username shapes are likely valid for each game.

For the full research map, see `docs/SCAN_ZONE_RESEARCH.md`.

Each profile includes:

- `game_name`
- `supported_scan_zones`
- `default_keywords_to_ignore`
- `username_patterns`
- `common_feed_phrases`
- `minimum_confidence`
- `scan_interval_seconds`

## Included Profiles

| Game | Best first zones | Important caveat |
| --- | --- | --- |
| Fortnite | `bus_driver_feed`, `kill_feed`, `knock_feed`, `ranked_leaderboard`, `spectating_name` | Streamer/privacy settings can hide display names. Ranked/leaderboard names may use stylized Unicode. |
| Call of Duty | `pregame_lobby`, `team_roster`, `scoreboard`, `kill_feed`, `deathcam_killed_by` | Some modes/settings can obscure gamer tags in lobby, kill feed, and scoreboard. |
| Apex Legends | `legend_select_roster`, `champion_squad`, `kill_feed`, `death_recap`, `mixtape_scoreboard` | Some in-match UI can replace special characters or show placeholder names. |
| Valorant | `agent_select_roster`, `scoreboard`, `kill_feed`, `combat_report`, `post_match_scoreboard` | Privacy settings can replace names with agent names or local labels. |
| Rocket League | `scoreboard`, `post_goal_scoreboard`, `goal_replay_banner`, `post_match_scoreboard` | Moving nameplates are noisy; prefer static scoreboard and replay surfaces. |

## Scan Zone Naming

Use specific names instead of generic labels. For example, prefer `deathcam_killed_by` over `banner`, and `bus_driver_feed` over `left_text`. Specific zones make accuracy reports easier to read and help users tune one bad region without changing the whole profile.

## Adding A Profile

1. Copy an existing JSON file in `profiles/`.
2. Change `game_name`.
3. Add visible scan zones from stable UI surfaces first.
4. Add UI labels and action words to `default_keywords_to_ignore`.
5. Add username patterns only when the parser truly needs a new shape.
6. Add labeled screenshots under `test_data/<game>/...`.
7. Run the parser and accuracy tests before claiming support.

## OCR Notes

- Static scoreboards and lobbies should be the first accuracy target.
- Feeds need multi-frame OCR before lookup because names can blur or expire.
- Moving nameplates should be treated as experimental.
- Obscured, hidden, anonymous, or generic privacy names should not produce identity matches.
