Initial import
This commit is contained in:
@@ -0,0 +1,274 @@
|
||||
# Integrations Spec
|
||||
|
||||
## Overview
|
||||
|
||||
MangoTune implements four integrations accessible from the Integrations page.
|
||||
Each integration is independent — a missing tool shows a "not available" state
|
||||
for that section only, without affecting the rest of the app.
|
||||
|
||||
---
|
||||
|
||||
## 1. GameMode Integration
|
||||
|
||||
**What is GameMode?** A daemon by Feral Interactive that applies CPU governor,
|
||||
scheduler, and I/O priority optimizations when games run. MangoHud can display
|
||||
whether GameMode is currently active via the `gamemode=1` config option.
|
||||
|
||||
### Detection
|
||||
```rust
|
||||
// src/integrations/gamemode.rs
|
||||
|
||||
pub struct GameModeStatus {
|
||||
pub daemon_installed: bool, // gamemoded binary found
|
||||
pub ctl_installed: bool, // gamemodectl binary found
|
||||
pub daemon_running: bool, // gamemoded process in process list
|
||||
pub current_clients: u32, // number of active gamemoded clients
|
||||
}
|
||||
|
||||
fn detect() -> GameModeStatus
|
||||
```
|
||||
Detection steps:
|
||||
1. `which gamemoded` — sets `daemon_installed`
|
||||
2. `which gamemodectl` — sets `ctl_installed`
|
||||
3. Check process list via `sysinfo` for `gamemoded` — sets `daemon_running`
|
||||
4. If ctl installed: run `gamemodectl status` and parse client count
|
||||
|
||||
### UI (on Integrations page)
|
||||
```
|
||||
AdwPreferencesGroup "GameMode"
|
||||
description: "Feral Interactive GameMode performance optimization daemon"
|
||||
|
||||
AdwActionRow "Status"
|
||||
subtitle: "gamemoded process"
|
||||
[suffix] label: "Running (3 clients)" / "Stopped" / "Not installed"
|
||||
|
||||
AdwSwitchRow "Show GameMode status in overlay"
|
||||
subtitle: "Sets gamemode=1 in current config"
|
||||
(bound to the gamemode config option)
|
||||
|
||||
AdwActionRow "Enable GameMode for all Steam games"
|
||||
subtitle: "Adds %command% to default Steam launch options helper"
|
||||
[suffix] GtkButton "Configure"
|
||||
```
|
||||
|
||||
### No direct daemon control
|
||||
MangoTune does NOT start/stop gamemoded. It only shows status and helps the user
|
||||
configure the launch options. Provide a tooltip: "Start/stop GameMode via your
|
||||
system service manager (systemctl --user start gamemoded)."
|
||||
|
||||
---
|
||||
|
||||
## 2. Steam Launch Option Helper
|
||||
|
||||
**Purpose:** Generate the correct launch option string for Steam games so that
|
||||
MangoHud (and optionally GameMode) is injected automatically.
|
||||
|
||||
### Detection
|
||||
```rust
|
||||
pub struct SteamStatus {
|
||||
pub installed: bool,
|
||||
pub flatpak: bool, // true if running as Flatpak
|
||||
pub running: bool,
|
||||
pub steam_root: Option<PathBuf>,
|
||||
pub localconfig_path: Option<PathBuf>,
|
||||
}
|
||||
```
|
||||
Detection steps:
|
||||
1. Check `which steam` and `flatpak list | grep com.valvesoftware.Steam`
|
||||
2. Find Steam root:
|
||||
- Native: `~/.steam/steam/` or `~/.local/share/Steam/`
|
||||
- Flatpak: `~/.var/app/com.valvesoftware.Steam/.steam/steam/`
|
||||
3. Find `userdata/{userId}/config/localconfig.vdf`
|
||||
|
||||
### Launch Option Generator UI
|
||||
```
|
||||
AdwPreferencesGroup "Steam Launch Options"
|
||||
|
||||
AdwComboRow "Inject method"
|
||||
options: [
|
||||
"mangohud {command}", ← standard
|
||||
"MANGOHUD=1 %command%", ← env var method
|
||||
"MANGOHUD_CONFIGFILE=~/.config/... %command%", ← explicit config
|
||||
"gamemoderun mangohud %command%", ← with GameMode
|
||||
"gamemoderun mangemoderun mangohud %command%", ← with GameMode (flatpak)
|
||||
]
|
||||
|
||||
AdwEntryRow (read-only)
|
||||
title: "Generated launch option"
|
||||
[Shows generated string based on above selection]
|
||||
[suffix] GtkButton "Copy to clipboard"
|
||||
|
||||
AdwActionRow "Instructions"
|
||||
subtitle: "In Steam: right-click game → Properties → Launch Options → paste above"
|
||||
```
|
||||
|
||||
### Important note for Flatpak Steam
|
||||
If Flatpak Steam is detected, the generated command uses the correct Flatpak-aware
|
||||
prefix and warns the user that MangoHud must also be installed inside the Flatpak
|
||||
sandbox or as a Flatpak extension.
|
||||
|
||||
### DO NOT write to localconfig.vdf
|
||||
MangoTune does NOT modify Steam's localconfig.vdf directly — too fragile and risky.
|
||||
The user copies the generated string manually. This is deliberate and safe.
|
||||
|
||||
---
|
||||
|
||||
## 3. Lutris Integration
|
||||
|
||||
**Purpose:** Help users configure MangoHud for games managed by Lutris.
|
||||
|
||||
### Detection
|
||||
```rust
|
||||
pub struct LutrisStatus {
|
||||
pub installed: bool,
|
||||
pub flatpak: bool,
|
||||
pub config_dir: Option<PathBuf>, // ~/.config/lutris/
|
||||
pub games: Vec<LutrisGame>,
|
||||
}
|
||||
|
||||
pub struct LutrisGame {
|
||||
pub name: String,
|
||||
pub slug: String,
|
||||
pub config_path: PathBuf, // ~/.config/lutris/games/{slug}.yml
|
||||
pub runner: String,
|
||||
}
|
||||
```
|
||||
Detection steps:
|
||||
1. `which lutris` or `flatpak list | grep net.lutris.Lutris`
|
||||
2. Enumerate `~/.config/lutris/games/*.yml` — parse YAML for name, slug, runner fields.
|
||||
Use a simple line-by-line parser (avoid heavy YAML dep — these files are simple).
|
||||
|
||||
### UI
|
||||
```
|
||||
AdwPreferencesGroup "Lutris"
|
||||
|
||||
AdwActionRow "Status"
|
||||
[suffix] "Installed" / "Not found"
|
||||
|
||||
(if installed):
|
||||
AdwComboRow "Game"
|
||||
[lists all detected Lutris games]
|
||||
|
||||
AdwSwitchRow "Enable MangoHud for selected game"
|
||||
subtitle: "Adds mangohud to the game's Lutris runner configuration"
|
||||
|
||||
AdwActionRow "Open game config in Lutris"
|
||||
[suffix] GtkButton "Open Lutris"
|
||||
|
||||
AdwPreferencesGroup (informational)
|
||||
AdwActionRow
|
||||
subtitle: "MangoTune can enable MangoHud in Lutris game configs.
|
||||
Per-game MangoHud config files will be placed at:
|
||||
~/.config/MangoHud/{game-slug}.conf"
|
||||
[suffix] GtkButton "Create per-game config"
|
||||
```
|
||||
|
||||
### Config modification approach for Lutris
|
||||
When "Enable MangoHud for selected game" is toggled ON:
|
||||
1. Read `~/.config/lutris/games/{slug}.yml`
|
||||
2. Find or create the `system:` section
|
||||
3. Set `mangohud: true` under the `system:` key
|
||||
4. Write back (preserve all other content, modify only the mangohud line)
|
||||
5. Show toast: "MangoHud enabled for {game name}. Restart Lutris if it's open."
|
||||
|
||||
When toggled OFF: set `mangohud: false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Heroic Games Launcher Integration
|
||||
|
||||
**Purpose:** Help users configure MangoHud for games managed by Heroic (Epic Games,
|
||||
GOG, and Amazon Prime on Linux).
|
||||
|
||||
### Detection
|
||||
```rust
|
||||
pub struct HeroicStatus {
|
||||
pub installed: bool,
|
||||
pub flatpak: bool,
|
||||
pub config_dir: Option<PathBuf>,
|
||||
pub games: Vec<HeroicGame>,
|
||||
}
|
||||
|
||||
pub struct HeroicGame {
|
||||
pub title: String,
|
||||
pub app_name: String, // Heroic's internal ID
|
||||
pub store: HeroicStore, // Epic, GOG, Amazon
|
||||
pub config_path: PathBuf, // ~/.config/heroic/GamesConfig/{app_name}.json
|
||||
}
|
||||
|
||||
pub enum HeroicStore { Epic, Gog, Amazon }
|
||||
```
|
||||
Detection steps:
|
||||
1. `which heroic` or `flatpak list | grep com.heroicgameslauncher.hgl`
|
||||
2. Config dirs to check:
|
||||
- Native: `~/.config/heroic/`
|
||||
- Flatpak: `~/.var/app/com.heroicgameslauncher.hgl/config/heroic/`
|
||||
3. Enumerate `GamesConfig/*.json` — each file = one game config.
|
||||
4. Parse JSON: extract `title`, `appName`, store type from file content.
|
||||
|
||||
### Heroic Game Config JSON structure (relevant fields)
|
||||
```json
|
||||
{
|
||||
"appName": "AppId",
|
||||
"title": "Game Title",
|
||||
"enviromentOptions": [
|
||||
{ "key": "MANGOHUD", "value": "1" }
|
||||
],
|
||||
"wrapperOptions": [
|
||||
{ "exe": "mangohud", "args": "" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### UI
|
||||
```
|
||||
AdwPreferencesGroup "Heroic Games Launcher"
|
||||
|
||||
AdwActionRow "Status"
|
||||
[suffix] "Installed (Flatpak)" / "Not found"
|
||||
|
||||
AdwComboRow "Game"
|
||||
[lists games grouped by store if > 5 games]
|
||||
|
||||
AdwSwitchRow "Enable MangoHud via wrapper"
|
||||
subtitle: "Adds mangohud as a wrapper in Heroic game settings"
|
||||
|
||||
AdwSwitchRow "Enable MangoHud via environment"
|
||||
subtitle: "Sets MANGOHUD=1 in game environment variables"
|
||||
|
||||
AdwActionRow "Per-game config"
|
||||
subtitle: "~/.config/MangoHud/{app_name}.conf"
|
||||
[suffix] GtkButton "Create / Edit"
|
||||
```
|
||||
|
||||
### Config modification approach for Heroic
|
||||
When "Enable MangoHud via wrapper" is toggled ON:
|
||||
1. Read `~/.config/heroic/GamesConfig/{app_name}.json` (handle Flatpak path too)
|
||||
2. Parse JSON using `serde_json`
|
||||
3. Add `{ "exe": "mangohud", "args": "" }` to `wrapperOptions` if not present
|
||||
4. Write back with pretty-printing
|
||||
5. Show toast: "MangoHud wrapper enabled. Restart Heroic if it's open."
|
||||
|
||||
When toggled OFF: remove the mangohud entry from `wrapperOptions`.
|
||||
|
||||
Environment method similarly adds/removes `{ "key": "MANGOHUD", "value": "1" }`.
|
||||
|
||||
---
|
||||
|
||||
## Integration Page Layout
|
||||
|
||||
```
|
||||
AdwPreferencesPage "Integrations"
|
||||
icon-name: "insert-object-symbolic"
|
||||
|
||||
[One AdwPreferencesGroup per integration, as described above]
|
||||
|
||||
AdwPreferencesGroup "Global MangoHud Enable"
|
||||
description: "Enable MangoHud system-wide for all applications"
|
||||
AdwExpanderRow "Auto-enable method"
|
||||
AdwSwitchRow "Via ~/.config/environment.d/mangohud.conf (recommended, user-scoped)"
|
||||
AdwSwitchRow "Via ~/.bashrc (shell sessions only)"
|
||||
AdwSwitchRow "Via /etc/environment (system-wide, requires sudo)"
|
||||
[Shows currently active method with green checkmark]
|
||||
[Warning: "System-wide enable may break some applications. Per-game is preferred."]
|
||||
```
|
||||
Reference in New Issue
Block a user