Initial import

2026-03-30 22:51:56 -04:00
commit 08e2910b9d
103 changed files with 35475 additions and 0 deletions
@@ -0,0 +1,129 @@
+# 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.