fc2f702fb2
One-touch toggle for MangoHud CSV logging on Linux gaming-launcher systems (DeckShift, super-alt-S, gamescope-session-plus). Manages three files idempotently: MangoHud.conf block, environment.d MANGOHUD=1, and a gamescope-session-plus user override that fixes Steam's mangoapp/MANGOHUD_CONFIGFILE suppression.
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# mangohud-logger
|
|
|
|
One-touch toggle for MangoHud CSV logging on Linux gaming-launcher systems
|
|
(DeckShift, super-alt-S, plain `gamescope-session-plus`, or any setup that
|
|
already uses MangoHud).
|
|
|
|
Run the script — it switches logging on if it's off, off if it's on. CSV
|
|
samples land in `~/Downloads/mango-logs/`. That's the entire interface.
|
|
|
|
## Why this exists
|
|
|
|
Getting MangoHud to *actually* write logs from a Steam-via-gamescope game
|
|
turns out to be a three-step setup, and every step has a non-obvious
|
|
gotcha. This script handles all three so you don't have to remember them.
|
|
|
|
## What it changes
|
|
|
|
The script writes three files (all marker-tagged so it can clean them up
|
|
on disable, and so it won't trample anything you wrote by hand):
|
|
|
|
1. **`~/.config/MangoHud/MangoHud.conf`** — appends a marker-bracketed block
|
|
with `output_folder`, `autostart_log=1`, `log_duration=0` (= until you
|
|
quit), `log_interval=100`, `toggle_logging=Shift_L+F2`, and a
|
|
`no_display=0` override.
|
|
|
|
2. **`~/.config/environment.d/95-mangohud-logger.conf`** — contains
|
|
`MANGOHUD=1` so the Vulkan loader auto-injects MangoHud into every game.
|
|
Requires a logout/login to take effect (systemd-user only reads
|
|
`environment.d/*.conf` at session start).
|
|
|
|
3. **`~/.config/gamescope-session-plus/sessions.d/steam`** — user-level
|
|
override that unsets the system's `MANGOHUD_CONFIGFILE` and turns off
|
|
`STEAM_USE_MANGOAPP`. See "Gotchas" below for why.
|
|
|
|
When you toggle it off, the script removes all three.
|
|
|
|
## Gotchas it works around
|
|
|
|
- **`no_display` blocks `autostart_log`.** If your MangoHud config has
|
|
`no_display` (HUD hidden by default), MangoHud's `autostart_log` rides on
|
|
the render hook that `no_display` disables — so the log never starts. The
|
|
script appends `no_display=0` at the end of its block to override.
|
|
Tradeoff: while logging is on, the HUD becomes visible during games.
|
|
|
|
- **DeckShift / gamescope-session-plus suppresses your user MangoHud config.**
|
|
The system `gamescope-session-plus` script does
|
|
`export MANGOHUD_CONFIGFILE=$(mktemp /tmp/mangohud.XXXXXXXX)` and writes
|
|
only `no_display` into that file. Result: MangoHud ignores your real
|
|
`~/.config/MangoHud/MangoHud.conf` and your `output_folder` / `autostart_log`
|
|
keys never run. The user-level session override unsets that var so
|
|
MangoHud falls back to the user file.
|
|
|
|
- **Steam uses `mangoapp` instead of the in-game MangoHud Vulkan layer.**
|
|
The system steam session exports `STEAM_USE_MANGOAPP=1`, which makes
|
|
gamescope draw the overlay via a separate `mangoapp` process — and
|
|
`mangoapp` doesn't write CSV logs the same way (and segfaults in a loop
|
|
on some boxes). The session override forces `STEAM_USE_MANGOAPP=0` so
|
|
the regular Vulkan-layer MangoHud takes over.
|
|
|
|
- **`log_duration=0` means "log forever".** The MangoHud docs aren't crystal
|
|
clear; empirically `0` = log until you quit or hit the toggle key.
|
|
|
|
- **`MANGOHUD=1` only injects the Vulkan layer.** OpenGL-only games (rare
|
|
these days) still need `mangohud %command%` in Steam launch options or
|
|
an `LD_PRELOAD` wrapper.
|
|
|
|
## Install
|
|
|
|
Requires `mangohud` (and `lib32-mangohud` for 32-bit games). On Arch:
|
|
|
|
```bash
|
|
sudo pacman -S mangohud lib32-mangohud
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
git clone https://git.no-signal.uk/nosignal/mangohud-logger.git
|
|
cd mangohud-logger
|
|
chmod +x mangohud-logger.sh
|
|
./mangohud-logger.sh
|
|
```
|
|
|
|
Or copy the script anywhere on `$PATH`:
|
|
|
|
```bash
|
|
install -Dm755 mangohud-logger.sh ~/.local/bin/mangohud-logger
|
|
mangohud-logger
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
./mangohud-logger.sh
|
|
```
|
|
|
|
That's it — no flags, no subcommands. First run enables; second run disables.
|
|
After the first enable, **log out of your desktop session and back in** so
|
|
the `MANGOHUD=1` env var becomes effective. You only need to do that once.
|
|
|
|
In-game keys (set by the script's MangoHud block):
|
|
|
|
| Key | Action |
|
|
|---|---|
|
|
| `Shift+F2` | Toggle logging on/off mid-game (useful for benchmarking a specific section) |
|
|
| Your existing `toggle_hud` key | Hide the HUD overlay (logging keeps running) |
|
|
|
|
CSV files appear in `~/Downloads/mango-logs/` as `<game>_<timestamp>.csv`.
|
|
Drop them into <https://flightlessmango.com/> for graphs, or open in a
|
|
spreadsheet.
|
|
|
|
## Compatibility
|
|
|
|
- **DeckShift** ([28allday/DeckShift](https://github.com/28allday/DeckShift))
|
|
— gamescope-session-plus based, Omarchy-only.
|
|
- **super-alt-S** ([28allday/super-alt-S-cachy-deckmode](https://github.com/28allday/super-alt-S-cachy-deckmode))
|
|
— KDE-Plasma gaming mode on CachyOS.
|
|
- **Plain `gamescope-session-plus`** on any Arch-based distro.
|
|
- **Steam without gamescope** — works too; only piece 3 (the gamescope
|
|
override) becomes a no-op.
|
|
- **Non-systemd distros** — piece 2 (the `environment.d` file) won't be
|
|
read; set `MANGOHUD=1` via your distro's preferred env-var mechanism.
|
|
|
|
## Honours XDG
|
|
|
|
Log folder is `$XDG_DOWNLOAD_DIR/mango-logs` (resolved via `xdg-user-dir`),
|
|
config dir is `$XDG_CONFIG_HOME` — works on non-English locales.
|
|
|
|
## License
|
|
|
|
MIT
|