# Game Config DB

This document describes MangoTune's bundled game/executable hint database used by the
`Create New Per-App Config…` flow.

## Purpose

The database exists to make per-app MangoHud config creation easier without pretending
MangoTune can always infer the correct process name automatically.

It is used for:

- searching by game title or alias
- suggesting likely MangoHud config names / executable stems
- prefilling the per-app config name when the user clicks a result

It is **not** the source of truth for MangoHud runtime matching. MangoHud still matches
the real process or executable name.

## File Location

Bundled database:

- `data/game_config_db.toml`

Maintenance script:

- `scripts/build_game_config_db.py`

Loader/search logic:

- `src/integrations/game_db.rs`

UI integration:

- `src/window.rs`

## Format

The database is TOML and uses repeated `[[game]]` tables.

Example:

```toml
[[game]]
appid = 730
title = "Counter-Strike 2"
aliases = ["cs2", "counter strike 2", "counter-strike 2", "csgo"]
candidates = ["cs2", "csgo", "wine-cs2"]
preferred = "cs2"
verification = "verified"
```

Fields:

- `appid`
  - Steam app ID when known
- `title`
  - game display name
- `aliases`
  - extra search terms or alternate names
- `candidates`
  - possible MangoHud config names / executable stems
- `preferred`
  - the main suggested config name the UI fills when clicked
- `verification`
  - trust level for the entry

## Verification Levels

Allowed values today:

- `verified`
  - manually confirmed from a trustworthy source such as SteamDB launch config pages
- `heuristic`
  - derived from local Steam library scanning and should be treated as a suggestion

The app currently uses the same search/display behavior for both, but the field exists so
maintainers can gradually improve the database quality over time.

## How The Database Is Built

The maintenance script currently combines:

1. Local Steam library data
   - reads Steam library roots from `libraryfolders.vdf`
   - reads installed games from `appmanifest_*.acf`
   - scans install directories for likely executable stems

2. Curated overrides
   - hand-maintained entries in `scripts/build_game_config_db.py`
   - these are where known-good preferred names should be corrected and verified

The generated file is committed to the repo and used at runtime. MangoTune does not fetch
online data at runtime.

## Updating It

When adding or refreshing entries:

1. Edit the curated overrides in `scripts/build_game_config_db.py`
2. Run:

```bash
python scripts/build_game_config_db.py
```

3. Review the generated `data/game_config_db.toml`
4. Commit both the script changes and the TOML changes

## Curation Guidance

Prefer adding or correcting entries when:

- a game's local-scan preferred name is obviously wrong
- SteamDB or another reliable source exposes a clear launch executable
- a game has known Proton/native naming differences worth surfacing as candidates

Do not add contributor names to the data file. Git history already tracks authorship.

## UX Contract

The per-app config creation dialog should continue to support both:

- direct manual typing of the exact executable name
- database-backed search by game title / alias

The database is there to help the user get to the right name faster, not to replace manual
control.