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:

sudo pacman -S mangohud lib32-mangohud

Then:

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:

install -Dm755 mangohud-logger.sh ~/.local/bin/mangohud-logger
mangohud-logger

Usage

./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) — gamescope-session-plus based, Omarchy-only.
• super-alt-S (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