# 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`.