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

23 KiB Raw Blame History Unescape Escape

MangoHud Option Behavior Reference

Parsing Rules

Positioning And Layout Rules

Precedence And Special Cases

MangoTune Coverage Audit

Verified Option Table

23 KiB

Raw Blame History