275 lines
8.6 KiB
Markdown
275 lines
8.6 KiB
Markdown
# 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."]
|
|
```
|