mangotune/docs/GAME_CONFIG_DB.md

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:

[[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:

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.