Initial import

2026-03-30 22:51:56 -04:00
commit 08e2910b9d
103 changed files with 35475 additions and 0 deletions
@@ -0,0 +1,142 @@
+# 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`.