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:

cargo run

Release build and install:

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:

cargo run --bin mangotune-preview

Standalone preview examples:

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:

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.