mangotune/docs/MANGOHUD_OPTION_BEHAVIOR.md

# MangoHud Option Behavior Reference

Reference for MangoTune, verified against a local MangoHud source snapshot (`f2e45e9`) on 2026-03-24 and cross-checked against upstream `README.md` and `data/MangoHud.conf`.

Primary source files:
- `/tmp/MangoHud-src/src/overlay_params.h` for the authoritative option list (`OVERLAY_PARAMS`)
- `/tmp/MangoHud-src/src/overlay_params.cpp` for parsing, defaults, preset handling, and env/config precedence
- `/tmp/MangoHud-src/src/overlay.cpp` for positioning, margin, and horizontal sizing behavior
- `/tmp/MangoHud-src/src/config.cpp` for config-file line parsing

## Parsing Rules

- Config-file lines are trimmed and `# ...` comments are stripped before value parsing.
- A bare key with no `=` is treated as value `1`.
- `OVERLAY_PARAM_BOOL(...)` options are effectively flags: bare key or `=1` enables, `=0` disables.
- `offset_x` and `offset_y` are parsed as unsigned integers, even though upstream stores them in signed `int` fields later.
- Some custom options are still boolean-like in practice, such as `no_display`, `full`, and `help`.
- Upstream currently declares `io_read` and `io_write` twice. In normal parsing the earlier boolean branch wins, so they behave as flags in practice.

## Positioning And Layout Rules

- Base edge margin is `10px` in `position_layer()`.
- That margin becomes `0px` if `hud_no_margin` is enabled or either `offset_x > 0` or `offset_y > 0`.
- Right-side anchors (`top-right`, `middle-right`, `bottom-right`) are native in MangoHud.
- `horizontal_stretch` defaults to `true`.
- Horizontal layouts start with full display width and may shrink after layout when `horizontal_stretch` is disabled.
- `top-center` and `bottom-center` get an extra horizontal shift in horizontal non-stretch mode.

## Precedence And Special Cases

- Base defaults come from `set_param_defaults()`.
- Built-in presets are applied before later explicit options.
- `preset` is an upstream-supported special option handled before normal option assignment, even though it does not live inside the main `OVERLAY_PARAMS` macro list.
- If `MANGOHUD_CONFIG` is set, MangoHud normally uses env options directly.
- `read_cfg=1` tells MangoHud to also read the config file even when env config is present.
- `full=1` is a bulk enable mode, not a simple single-feature toggle.
- `full=1` immediately disables a curated exclusion list before later explicit options are applied again, including `histogram`, `fps_only`, `horizontal`, `hud_no_margin`, `hud_compact`, `mangoapp_steam`, `dynamic_frame_timing`, `hide_engine_names`, and `hide_fps_superscript`.
- `fps_only=1` later forces `legacy_layout` off.
- Non-horizontal auto width (`width=0`) is derived later from font size, scale, and column count, with extra widening for I/O rows and `no_small_font`.

## MangoTune Coverage Audit

- Verified upstream options in `OVERLAY_PARAMS`: `186`
- Additional upstream special options handled outside `OVERLAY_PARAMS`: `preset`, `inherit`
- Duplicate upstream declarations: `io_read`, `io_write`
- MangoTune schema entries today: `187`
- MangoTune now represents the full currently documented option surface in its live schema, including the special-case keys `preset`, `inherit`, and `help`
- Some of those options intentionally live in advanced UI sections because they are niche directives or special-case upstream behaviors rather than normal daily tuning knobs

## Verified Option Table

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `af` | Signed integer | `-1` | Anisotropic filtering; -1=unset |
| `alpha` | Float | `1.0` | Overall HUD transparency |
| `arch` | Flag (bare key or =1/=0) | `false` | MangoHud architecture |
| `autostart_log` | Unsigned integer |  | Seconds before auto-start |
| `background_alpha` | Float | `0.5` | Background transparency for the HUD window. |
| `background_color` | Hex color (RRGGBB) | `020202` | Hex color used for the Background readout or accent. |
| `battery` | Flag (bare key or =1/=0) | `false` | Shows battery status when available. |
| `battery_color` | Hex color (RRGGBB) | `FF9078` | Hex color used for the Battery readout or accent. |
| `battery_icon` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `battery` |
| `battery_time` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `battery` |
| `battery_watt` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `battery` |
| `benchmark_percentiles` | String list (legacy / deprecated) | `"97","AVG"` in current source defaults | Current source seeds `97,AVG`, but the parser logs that this option is obsolete and recommends `fps_metrics`. Upstream README still documents a broader default set (`97,AVG,1,0.1`), so published docs and current source are not fully aligned. |
| `bicubic` | Flag (bare key or =1/=0) | `false` | Force bicubic filtering |
| `blacklist` | Delimited string list |  | App names to suppress overlay |
| `cellpadding_y` | Float | `-0.085` | Vertical cell padding tweak used by the ImGui table layout. |
| `control` | String | `-1` | Creates/listens on a control socket path; `%p` is expanded to the current process ID. |
| `core_bars` | Flag (bare key or =1/=0) | `false` | Graphical core bars |
| `core_load` | Flag (bare key or =1/=0) | `false` | Per-core load bars |
| `core_load_change` | Flag (bare key or =1/=0) | `false` | Color per-core load |
| `core_type` | Flag (bare key or =1/=0) | `false` | Show P/E core type labels |
| `cpu_color` | Hex color (RRGGBB) | `2E97CB` | Hex color used for the Cpu readout or accent. |
| `cpu_custom_temp_sensor` | hwmon name,input pair |  | Custom CPU temperature source in `hwmon_name,hwmon_input` form. |
| `cpu_efficiency` | Flag (bare key or =1/=0) | `false` | Shows CPU efficiency / perf-per-watt style data when available. |
| `cpu_load_change` | Flag (bare key or =1/=0) | `false` | Color CPU load |
| `cpu_load_color` | List of 3 hex colors | `0x39f900,0xfdfd09,0xb22222` | Three hex colors |
| `cpu_load_value` | Comma-separated integers | `60,90` | Two thresholds |
| `cpu_mhz` | Flag (bare key or =1/=0) | `false` | Average MHz across cores |
| `cpu_power` | Flag (bare key or =1/=0) | `false` | Shows CPU package or socket power draw when available. |
| `cpu_stats` | Flag (bare key or =1/=0) | `true` | Master CPU section toggle |
| `cpu_temp` | Flag (bare key or =1/=0) | `false` | Shows CPU temperature. |
| `cpu_text` | String |  | Custom CPU label |
| `custom_text` | String-bearing special option | `""` / unset | Declared in the macro list like a bool, but in practice MangoHud parses and uses it as a text payload line. |
| `custom_text_center` | String-bearing special option | `""` / unset | Declared in the macro list like a bool, but in practice MangoHud parses and uses it as centered text. |
| `debug` | Flag (bare key or =1/=0) | `false` | Gamescope app frametimes graph |
| `device_battery` | Delimited string list |  | List of device battery kinds such as `controller`, `mouse`, or `headset`. |
| `device_battery_icon` | Flag (bare key or =1/=0) | `false` | Adds icons to device battery entries. |
| `display_server` | Flag (bare key or =1/=0) | `false` | Wayland/X11 indicator |
| `duration` | Flag (bare key or =1/=0) | `false` | Enables benchmark-duration style tracking; base default is off even under `full`. |
| `dx_api` | Flag (bare key or =1/=0) | `false` | Displays the DirectX API/backend label where supported. |
| `dynamic_frame_timing` | Flag (bare key or =1/=0) | `false` | Dynamic scale frametime graph |
| `engine_color` | Hex color (RRGGBB) | `EB5B5B` | Hex color used for the Engine readout or accent. |
| `engine_short_names` | Flag (bare key or =1/=0) | `false` | Uses shorter engine names when engine info is displayed. |
| `engine_version` | Flag (bare key or =1/=0) | `false` | Displays the engine version string when MangoHud can detect it. |
| `exec` | String-bearing special option | `""` / unset | Runs a shell command and shows its output in the next column; only works with `legacy_layout=0`. Like `custom_text`, it is handled more like a string payload than a normal bool-style flag. |
| `exec_name` | Flag (bare key or =1/=0) | `false` | Show executable name |
| `fan` | Flag (bare key or =1/=0) | `false` | Steam Deck fan RPM |
| `fcat` | Flag (bare key or =1/=0) | `false` | Enable FCAT overlay |
| `fcat_overlay_width` | Unsigned integer | `24` | DEPENDS ON: `fcat` |
| `fcat_screen_edge` | Unsigned integer | `0` | DEPENDS ON: `fcat` |
| `fex_stats` | Option list |  | Tokenized option list enabling selected FEX-Emu stat groups when MangoHud is built with FEX support. |
| `flip_efficiency` | Flag (bare key or =1/=0) | `false` | Joules per frame |
| `font_file` | Filesystem path |  | TTF/OTF path — validated to exist if set |
| `font_file_text` | Filesystem path |  | Custom label text for the Font File section. |
| `font_glyph_ranges` | Glyph range flags |  | Comma-separated glyph packs such as `japanese`, `cyrillic`, or `latin_ext_a`. |
| `font_scale` | Float | `1.0` | Global font scale multiplier. |
| `font_scale_media_player` | Float | `0.55` | Separate font scale for media-player text. |
| `font_size` | Float | `24` | Main font size in pixels. |
| `font_size_secondary` | Float |  | Secondary text size used by some secondary labels; parsed separately from the main `font_size`. |
| `font_size_text` | Float |  | For text elements |
| `fps` | Flag (bare key or =1/=0) | `true` | Show FPS counter — enabled by default |
| `fps_color` | List of 3 hex colors | `0xb22222,0xfdfd09,0x39f900` | Three hex colors: low,mid,high |
| `fps_color_change` | Flag (bare key or =1/=0) | `false` | Enable FPS color thresholds |
| `fps_limit` | Comma-separated numbers | `0` | 0 = unlimited; comma-separated list e.g. `0,30,60` |
| `fps_limit_method` | Enum (`early` or `late`) | `FPS_LIMIT_METHOD_LATE` | Limit strategy: `late` is the default, `early` waits earlier in the frame. |
| `fps_metrics` | Metric list |  | e.g. `avg,0.01,1,97` — `AVG` or decimal percentiles |
| `fps_only` | Flag (bare key or =1/=0) | `false` | CONFLICTS WITH: all other display params |
| `fps_sampling_period` | String | `500ms` | Sampling period in milliseconds in config/env input; MangoHud stores it internally in nanoseconds. |
| `fps_text` | String |  | Custom label for FPS row |
| `fps_value` | Comma-separated integers | `30,60` | Two thresholds: warn,ok |
| `frame_count` | Flag (bare key or =1/=0) | `false` | Show frame counter |
| `frame_timing` | Flag (bare key or =1/=0) | `true` | Frametime graph — enabled by default |
| `frame_timing_detailed` | Flag (bare key or =1/=0) | `false` | More detailed frametime graph |
| `frametime` | Flag (bare key or =1/=0) | `true` | Show frametime — enabled by default |
| `frametime_color` | Hex color (RRGGBB) | `00FF00` | Hex color used for the Frametime readout or accent. |
| `fsr` | Flag (bare key or =1/=0) | `false` | FSR status |
| `fsr_steam_sharpness` | Float | `-1` | Float sharpness control for Steam FSR integration. MangoHud default is `-1`, which means “leave unset / use app or Steam default”. |
| `ftrace` | Tracepoint spec list |  | Tracepoint specification list used only when MangoHud is built with ftrace support. |
| `full` | Boolean-like (0/1) | `false` | Enables almost every boolean option, then explicitly disables a curated exclusion list. Use with caution because it can enable many unrelated HUD sections at once. |
| `gamemode` | Flag (bare key or =1/=0) | `false` | GameMode running status |
| `gl_bind_framebuffer` | Unsigned integer |  | Rebind framebuffer before draw |
| `gl_dont_flip` | Unsigned integer |  | Don't swap origin for GL_UPPER_LEFT |
| `gl_size_query` | Enum (`drawable`, `viewport`, `scissorbox`) |  | Default: glXQueryDrawable |
| `gl_vsync` | Signed integer | `-2` | Signed integer for OpenGL swap interval; `-2` means “unset” in MangoHud defaults. |
| `gpu_color` | Hex color (RRGGBB) | `2E9762` | Hex color used for the Gpu readout or accent. |
| `gpu_core_clock` | Flag (bare key or =1/=0) | `false` | Shows GPU core clock speed. |
| `gpu_efficiency` | Flag (bare key or =1/=0) | `false` | Shows GPU efficiency / perf-per-watt style data when available. |
| `gpu_fan` | Flag (bare key or =1/=0) | `false` | RPM on AMD, percent on NVIDIA |
| `gpu_junction_temp` | Flag (bare key or =1/=0) | `false` | Shows GPU hotspot / junction temperature when available. |
| `gpu_list` | GPU index list |  | Comma-separated GPU indices to show. Useful on multi-GPU systems. |
| `gpu_load_change` | Flag (bare key or =1/=0) | `false` | Color GPU load |
| `gpu_load_color` | List of 3 hex colors | `0x39f900,0xfdfd09,0xb22222` | Three hex colors |
| `gpu_load_value` | Comma-separated integers | `60,90` | Two load thresholds |
| `gpu_mem_clock` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `vram` |
| `gpu_mem_temp` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `vram` |
| `gpu_name` | Flag (bare key or =1/=0) | `false` | Show GPU model name |
| `gpu_power` | Flag (bare key or =1/=0) | `false` | Shows GPU power draw. |
| `gpu_power_limit` | Flag (bare key or =1/=0) | `false` | Displays the current GPU power limit. |
| `gpu_stats` | Flag (bare key or =1/=0) | `true` | Master GPU section toggle |
| `gpu_temp` | Flag (bare key or =1/=0) | `false` | Shows GPU temperature. |
| `gpu_text` | Delimited string list |  | Parsed as a tokenized string list in source, so multiple GPU labels can be supplied for multi-GPU setups. |
| `gpu_voltage` | Flag (bare key or =1/=0) | `false` | AMD ONLY |
| `graphs` | Flag (bare key or =1/=0) | `false` | Valid values: `gpu_load,cpu_load,gpu_core_clock,gpu_mem_clock,vram,ram,cpu_temp,gpu_temp` |
| `hdr` | Flag (bare key or =1/=0) | `false` | HDR status |
| `height` | Unsigned integer | `140` | HUD window height. Horizontal layouts start with this height before any later width adjustments. |
| `help` | Boolean-like (prints help and exits) | `0` | Printing helper: causes MangoHud to print supported env-style params to stderr. Not a normal overlay display toggle. |
| `hide_engine_names` | Flag (bare key or =1/=0) | `false` | Hides engine names even if engine-related display items are enabled. |
| `hide_fps_superscript` | Flag (bare key or =1/=0) | `false` | Removes the small `FPS` superscript styling from the FPS readout. |
| `hide_fsr_sharpness` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `fsr` |
| `histogram` | Flag (bare key or =1/=0) | `false` | CONFLICTS WITH frame_timing |
| `horizontal` | Flag (bare key or =1/=0) | `false` | Switches the HUD into a horizontal/table layout. MangoHud initially sizes it to full display width, then may shrink it after layout based on content width. |
| `horizontal_separator_color` | Hex color (RRGGBB) | `AD64C1` | Hex color used for the Horizontal Separator readout or accent. |
| `horizontal_stretch` | Flag (bare key or =1/=0) | `true` | Defaults to true. When disabled, MangoHud shrinks horizontal HUD width after rendering to match content instead of stretching across the screen. |
| `hud_compact` | Flag (bare key or =1/=0) | `false` | Compact mode |
| `hud_no_margin` | Flag (bare key or =1/=0) | `false` | Removes MangoHud’s normal 10px edge margin. The same margin is also removed automatically whenever `offset_x` or `offset_y` is greater than zero. |
| `inherit` | Preset-file directive | `inherit` line inside `presets.conf` | Mainly used inside preset definitions, where a literal `inherit` line re-applies parent preset behavior. It is not a typical everyday overlay toggle. |
| `io_color` | Hex color (RRGGBB) | `A491D3` | Hex color used for the Io readout or accent. |
| `io_read` | Flag (bare key or =1/=0) | `false` | Shows per-process I/O read throughput. Note: upstream declares this key twice (`BOOL` and `CUSTOM`), but the boolean branch wins first, so practical config behavior is flag-like. |
| `io_write` | Flag (bare key or =1/=0) | `false` | Shows per-process I/O write throughput. Note: upstream declares this key twice (`BOOL` and `CUSTOM`), but the boolean branch wins first, so practical config behavior is flag-like. |
| `legacy_layout` | Flag (bare key or =1/=0) | `true` | Uses MangoHud’s older default ordering/layout behavior. `fps_only` forces this off. |
| `log_duration` | Unsigned integer |  | Seconds |
| `log_interval` | Unsigned integer | `0` | ms; 0 = default |
| `log_versioning` | Flag (bare key or =1/=0) | `false` | Appends version info to generated log filenames. |
| `mangoapp_steam` | Flag (bare key or =1/=0) | `false` | mangoapp only |
| `media_player` | Flag (bare key or =1/=0) | `false` | Enable media player metadata |
| `media_player_color` | Hex color (RRGGBB) | `FFFFFF` | Hex color used for the Media Player readout or accent. |
| `media_player_format` | Semicolon-separated format list | `"{title}","{artist}","{album}"` | Semicolon-separated format strings. MangoHud formats `{title}`, `{artist}`, and `{album}` tokens from MPRIS metadata. |
| `media_player_name` | String | `""` | e.g. `spotify` — DEPENDS ON: `media_player` |
| `network` | Delimited string list |  | Comma-separated network interfaces; empty/default means MangoHud decides what to show. |
| `network_color` | Hex color (RRGGBB) | `E07B85` | Hex color used for the Network readout or accent. |
| `no_display` | Boolean-like (0/1) | `0` | Boolean-style option. Starts MangoHud hidden, but toggle/reload keys still work. |
| `no_small_font` | Unsigned integer |  | Disable small font for secondary info |
| `offset_x` | Unsigned integer | `0` | Unsigned X offset. Positive values push left-anchored HUDs right and right-anchored HUDs farther right. Any positive offset also removes the normal 10px edge margin. |
| `offset_y` | Unsigned integer | `0` | Unsigned Y offset. Positive values push the HUD downward. Any positive offset also removes the normal 10px edge margin. |
| `output_file` | Filesystem path |  | Explicit output filename for benchmark/log output. |
| `output_folder` | Filesystem path |  | Must be writable directory |
| `pci_dev` | String |  | Format: `domain:bus:slot.function` e.g. `0000:03:00.0` |
| `permit_upload` | Unsigned integer | `0` | Upload to flightlessmango.com |
| `picmip` | Signed integer | `-17` | Mip-map LoD bias; negative=sharper |
| `preset` | Comma-separated preset list | `-1,0,1,2,3,4` in upstream docs/examples | Upstream special option handled before normal assignment. Supports built-in presets and user presets via `presets.conf`. |
| `position` | Enum position | `top-left` | Anchor position. Right anchors are native in MangoHud; `top-center` and `bottom-center` get extra horizontal adjustment when `horizontal` is on and `horizontal_stretch` is off. |
| `present_mode` | Flag (bare key or =1/=0) | `false` | Displays the current presentation mode in the HUD. |
| `proc_vram` | Flag (bare key or =1/=0) | `false` | Per-process VRAM |
| `procmem` | Flag (bare key or =1/=0) | `false` | Per-process resident memory |
| `procmem_shared` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `procmem` |
| `procmem_virt` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `procmem` |
| `ram` | Flag (bare key or =1/=0) | `false` | Shows system RAM usage. |
| `ram_color` | Hex color (RRGGBB) | `C26693` | Hex color used for the Ram readout or accent. |
| `ram_temp` | Flag (bare key or =1/=0) | `false` | Displays RAM temperature if MangoHud can read it from available sensors. |
| `read_cfg` | Flag (bare key or =1/=0) | `false` | Only matters when using `MANGOHUD_CONFIG` in the environment: it tells MangoHud to also read the config file instead of using env options alone. |
| `refresh_rate` | Flag (bare key or =1/=0) | `false` | Current refresh rate |
| `reload_cfg` | Keybind | `Shift_L+F4` on Linux | Reload keybind. Useful for external editors or MangoTune preview sessions. |
| `reset_fps_metrics` | Keybind | `Shift_R+F9` on Linux | Keybind that resets FPS metrics / percentiles. |
| `resolution` | Flag (bare key or =1/=0) | `false` | Current display resolution |
| `retro` | Flag (bare key or =1/=0) | `false` | Disable linear filtering (blocky textures) |
| `round_corners` | Unsigned integer | `0` | Rounded-corner radius for the HUD background. |
| `show_fps_limit` | Flag (bare key or =1/=0) | `false` | Display current FPS limit value |
| `swap` | Flag (bare key or =1/=0) | `false` | Shows swap usage. |
| `table_columns` | Unsigned integer | `3` | Number of table columns. MangoHud later clamps it to the range `1..64`. |
| `temp_fahrenheit` | Flag (bare key or =1/=0) | `false` | Use °F instead of °C |
| `text_color` | Hex color (RRGGBB) | `FFFFFF` | Hex color used for the Text readout or accent. |
| `text_outline` | Flag (bare key or =1/=0) | `true` | Draws an outline around text for readability. |
| `text_outline_color` | Hex color (RRGGBB) | `000000` | Hex color used for the Text Outline readout or accent. |
| `text_outline_thickness` | Float | `1.5` | Thickness of the text outline stroke. |
| `throttling_status` | Flag (bare key or =1/=0) | `false` | GPU throttling indicator |
| `throttling_status_graph` | Flag (bare key or =1/=0) | `false` | Show throttling on frametime graph |
| `time` | Flag (bare key or =1/=0) | `false` | Current time |
| `time_format` | String | `"%T"` | strftime format |
| `time_no_label` | Flag (bare key or =1/=0) | `false` | DEPENDS ON: `time` |
| `toggle_fps_limit` | Keybind | `Shift_L+F1` on Linux | Switches between configured FPS limit entries. |
| `toggle_hud` | Keybind | `Shift_R+F12` on Linux | Keybind list parsed via xkb key names on Linux / key codes on Windows. |
| `toggle_hud_position` | Keybind | `Shift_R+F11` on Linux | Cycles through positions with a keybind. Upstream README also spells this as `R_Shift+F11`; `data/MangoHud.conf` uses `Shift_R+F11`. |
| `toggle_logging` | Keybind | `Shift_L+F2` on Linux | Keybind that starts or stops logging. |
| `toggle_preset` | Keybind | `Shift_R+F10` on Linux | Cycles through presets with a keybind. |
| `trilinear` | Flag (bare key or =1/=0) | `false` | Force trilinear filtering |
| `upload_log` | Keybind | `Shift_L+F3` on Linux | Keybind that uploads the current log. |
| `upload_logs` | Keybind | `Control_L+F3` on Linux | DEPENDS ON: `permit_upload=1` |
| `version` | Flag (bare key or =1/=0) | `false` | Show MangoHud version in overlay |
| `vkbasalt` | Flag (bare key or =1/=0) | `false` | vkBasalt running status |
| `vram` | Flag (bare key or =1/=0) | `false` | Required by gpu_mem_clock, gpu_mem_temp |
| `vram_color` | Hex color (RRGGBB) | `AD64C1` | Hex color used for the Vram readout or accent. |
| `vsync` | Unsigned integer | `-1` | Unsigned value in the parser, but MangoHud seeds the default to `-1` before parsing config/env overrides. |
| `vulkan_driver` | Flag (bare key or =1/=0) | `false` | Show Vulkan driver string |
| `vulkan_present_mode` | String |  | String name for the Vulkan present mode preference; MangoHud accepts names like `fifo`, `mailbox`, or full `VK_PRESENT_MODE_*_KHR`. |
| `width` | Unsigned integer | `0` | Explicit window width. `0` means MangoHud decides automatically; for non-horizontal layouts MangoHud later derives a width from font size, scale, and column count. |
| `wine` | Flag (bare key or =1/=0) | `false` | Wine/Proton version |
| `wine_color` | Hex color (RRGGBB) | `EB5B5B` | Hex color used for the Wine readout or accent. |
| `winesync` | Flag (bare key or =1/=0) | `false` | Wine sync method |