# 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