143 lines
5.0 KiB
Markdown
143 lines
5.0 KiB
Markdown
# MangoTune
|
||
|
||
MangoTune is a GTK4 + libadwaita desktop configurator for MangoHud on Linux.
|
||
|
||
It focuses on correctness and maintainability over ad-hoc editing: schema-aware validation,
|
||
config-layer conflict visibility, and comment-preserving writes.
|
||
|
||
Recent UX direction:
|
||
|
||
- Dashboard-first landing screen instead of a plain settings browser
|
||
- Managed live preview using MangoTune’s built-in Studio renderer
|
||
- Companion `mangotune-preview` renderer for a dedicated studio-style preview scene
|
||
- Dashboard controls for Studio load, FPS cap, VSync, and runtime tuning
|
||
- Dashboard controls for Studio preview window width/height
|
||
- Socket-driven studio preview reloads without touching the user’s real config
|
||
- One-click starter presets for minimal, competitive, balanced, and streamer-style overlays
|
||
- Sidebar search plus collapsed-by-default deeper sections so the first-run shell feels less crowded
|
||
- Workspace-status card for save state, validation summary, runtime info, and quick actions
|
||
- Accordion-style sidebar sections and safer studio-preview refresh behavior
|
||
- Common appearance tuning controls up front, with advanced pages still available in the sidebar
|
||
- A custom control-deck shell for the main deep settings pages instead of untouched stock preferences layouts
|
||
- Inline layer-conflict inspection instead of a second popup window
|
||
- Dashboard profile save, restore, and delete actions
|
||
|
||
## Why use MangoTune instead of GOverlay
|
||
|
||
- Strong option validation across MangoHud types and value ranges
|
||
- Config layer resolver showing which value wins (global, per-app, env, app-local)
|
||
- Safer writes with backup and atomic replacement behavior
|
||
- Managed live preview using the built-in Studio renderer without forcing you to save first
|
||
- Native Rust + GTK4/libadwaita app with predictable behavior
|
||
|
||
## Install
|
||
|
||
### Distro package (when available)
|
||
|
||
Use your distribution package manager for `mangotune`.
|
||
|
||
### Build from source
|
||
|
||
Requirements:
|
||
|
||
- Rust stable toolchain
|
||
- GTK4 and libadwaita development packages
|
||
- `glib-compile-schemas`
|
||
|
||
Build and run:
|
||
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
Release build and install:
|
||
|
||
```bash
|
||
cargo build --release
|
||
sudo make install
|
||
```
|
||
|
||
## Config priority model
|
||
|
||
MangoTune follows MangoHud's effective config layering. Higher priority overrides lower priority:
|
||
|
||
1. `MANGOHUD_CONFIG` / `MANGOHUD_CONFIGFILE` (environment)
|
||
2. App-local `MangoHud.conf`
|
||
3. Per-app XDG config (`~/.config/MangoHud/<app>.conf`)
|
||
4. Global XDG config (`~/.config/MangoHud/MangoHud.conf`)
|
||
5. Compiled defaults
|
||
|
||
Use the **Layer Conflicts** page to inspect shadowed values and winning layers.
|
||
|
||
## Live preview
|
||
|
||
From the dashboard, start a live preview window using MangoTune’s built-in Studio renderer.
|
||
|
||
How it works:
|
||
|
||
- MangoTune writes your current in-memory config to a temporary preview-only file
|
||
- It launches the Studio preview against that temporary file
|
||
- Reload/restart lets you iterate on appearance settings without touching your saved config
|
||
- The dashboard tunes the Studio renderer directly: load factor, FPS cap, VSync, particle density, VRAM pressure, and pause state
|
||
- The dashboard tunes Studio preview window width/height
|
||
- Studio preview changes are written to a temporary config and sent into the preview over its control socket
|
||
- The dashboard preview status auto-refreshes and failed hot reloads fall back to restart more safely
|
||
- Preview sessions temporarily force the HUD visible even if your saved config uses `no_display`
|
||
- Docked preview windows now clamp back inside the screen instead of disappearing off the edge more easily
|
||
- Right-aligned HUD previews now get extra width and skip side-docking so the overlay is less likely to vanish off-screen
|
||
|
||
Environment set by launcher:
|
||
|
||
- `MANGOHUD=1`
|
||
- `MANGOHUD_CONFIGFILE=<temporary preview config path>`
|
||
|
||
Studio preview behavior:
|
||
|
||
- direct-process tracking so live preview reload/restart targets the real preview app
|
||
- dashboard-driven load/FPS/VSync defaults that are passed into the preview at launch
|
||
- socket API for runtime load/FPS/VSync/config reload commands
|
||
- advanced runtime controls for particle density, VRAM pressure, and pause state
|
||
|
||
`mangotune-preview` also supports standalone use:
|
||
|
||
```bash
|
||
cargo run --bin mangotune-preview
|
||
```
|
||
|
||
Standalone preview examples:
|
||
|
||
```bash
|
||
MANGOHUD=1 \
|
||
MANGOHUD_CONFIGFILE=/tmp/mangotune-preview.conf \
|
||
MANGOTUNE_SOCKET=/tmp/mangotune-preview.sock \
|
||
MANGOTUNE_PREVIEW_SCENE=motion \
|
||
MANGOTUNE_PREVIEW_LOAD=2.5 \
|
||
MANGOTUNE_PREVIEW_FPS_CAP=500 \
|
||
cargo run --bin mangotune-preview
|
||
```
|
||
|
||
Notes:
|
||
|
||
- `0` FPS cap means uncapped
|
||
- standalone preview needs a graphical session (`DISPLAY` or Wayland variables available)
|
||
- standalone control happens through the Unix socket declared in `MANGOTUNE_SOCKET`
|
||
|
||
## Contributing
|
||
|
||
- Run formatting and checks before proposing changes:
|
||
|
||
```bash
|
||
cargo fmt
|
||
cargo clippy --all-targets -- -D warnings
|
||
cargo test
|
||
```
|
||
|
||
- Keep behavior aligned with the planning docs in `docs/plan/`.
|
||
- Add tests for parser, validation, resolver, integrations, and launcher changes.
|
||
|
||
## License
|
||
|
||
MangoTune is licensed under the MIT License. See `LICENSE`.
|
||
|
||
Dependency licenses are documented in `THIRD_PARTY_LICENSES.md`.
|