# MangoHud Schema Reference

Superseded as the user-facing/help-source reference by
[`docs/MANGOHUD_OPTION_BEHAVIOR.md`](/home/aaron/Programming/mangotune/docs/MANGOHUD_OPTION_BEHAVIOR.md).
Keep this file only as schema-planning context for `src/config/schema.rs`.

Source: Official MangoHud repository `data/MangoHud.conf` cross-referenced with
the MangoHud README and source code. Last verified against MangoHud 0.7.x.

This file is no longer the authoritative help text source and does not currently
cover every upstream MangoHud option.

## Schema Entry Structure

Each option in `schema.rs` must encode:
```rust
pub struct SchemaEntry {
    pub key: &'static str,
    pub option_type: OptionType,
    pub default: DefaultValue,
    pub description: &'static str,
    pub category: Category,
    pub dependencies: &'static [&'static str],  // options that must be enabled for this to work
    pub conflicts_with: &'static [&'static str], // mutually exclusive options
    pub gpu_vendor_only: Option<GpuVendor>,      // None = all, Some(Amd) = AMD only
    pub gamescope_only: bool,
    pub mangoapp_only: bool,
}

pub enum OptionType {
    Flag,                          // bare key, no value — presence means enabled
    Bool,                          // key=0 or key=1
    Int { min: i64, max: i64 },
    Float { min: f64, max: f64 },
    String { max_len: usize },
    Color,                         // 6-char hex RRGGBB, no #
    Enum { variants: &'static [&'static str] },
    FpsLimitList,                  // comma-separated ints e.g. "0,30,60"
    KeyBind,                       // e.g. "Shift_R+F12"
    CommaSeparatedInts,
    CommaSeparatedFloats,
    CommaSeparatedStrings,
    Path,                          // filesystem path, validated to exist or be writable
}
```

---

## Category: PERFORMANCE

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `fps_limit` | FpsLimitList | `0` | 0 = unlimited; comma-separated list e.g. `0,30,60` |
| `fps_limit_method` | Enum[`early`,`late`] | `""` | early = wait before present |
| `vsync` | Int[-1..3] | `-1` | -1=unset; 0=adaptive; 1=off; 2=mailbox; 3=on |
| `gl_vsync` | Int[-2..N] | `-2` | OpenGL only; -2=unset; 0=off; >=1=wait N vblanks |
| `picmip` | Int[-17..16] | `-17` | Mip-map LoD bias; negative=sharper |
| `af` | Int[-1..16] | `-1` | Anisotropic filtering; -1=unset |
| `bicubic` | Flag | absent | Force bicubic filtering |
| `trilinear` | Flag | absent | Force trilinear filtering |
| `retro` | Flag | absent | Disable linear filtering (blocky textures) |

---

## Category: DISPLAY — FPS & FRAMETIME

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `fps` | Flag | present | Show FPS counter — enabled by default |
| `fps_only` | Flag | absent | CONFLICTS WITH: all other display params |
| `fps_sampling_period` | Int[100..60000] | `500` | ms |
| `fps_color_change` | Flag | absent | Enable FPS color thresholds |
| `fps_value` | CommaSeparatedInts | `30,60` | Two thresholds: warn,ok |
| `fps_color` | CommaSeparatedStrings | `B22222,FDFD09,39F900` | Three hex colors: low,mid,high |
| `fps_text` | String | `""` | Custom label for FPS row |
| `fps_metrics` | CommaSeparatedStrings | `""` | e.g. `avg,0.01,1,97` — `AVG` or decimal percentiles |
| `frametime` | Flag | present | Show frametime — enabled by default |
| `frame_count` | Flag | absent | Show frame counter |
| `frame_timing` | Flag | present | Frametime graph — enabled by default |
| `frame_timing_detailed` | Flag | absent | More detailed frametime graph |
| `dynamic_frame_timing` | Flag | absent | Dynamic scale frametime graph |
| `histogram` | Flag | absent | CONFLICTS WITH frame_timing |
| `throttling_status` | Flag | present | GPU throttling indicator |
| `throttling_status_graph` | Flag | absent | Show throttling on frametime graph |
| `show_fps_limit` | Flag | absent | Display current FPS limit value |

---

## Category: DISPLAY — GPU

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `gpu_stats` | Flag | present | Master GPU section toggle |
| `gpu_temp` | Flag | absent | |
| `gpu_junction_temp` | Flag | absent | |
| `gpu_core_clock` | Flag | absent | |
| `gpu_mem_temp` | Flag | absent | DEPENDS ON: `vram` |
| `gpu_mem_clock` | Flag | absent | DEPENDS ON: `vram` |
| `gpu_power` | Flag | absent | |
| `gpu_power_limit` | Flag | absent | |
| `gpu_text` | String[32] | `""` | Custom GPU label |
| `gpu_load_change` | Flag | absent | Color GPU load |
| `gpu_load_value` | CommaSeparatedInts | `60,90` | Two load thresholds |
| `gpu_load_color` | CommaSeparatedStrings | `39F900,FDFD09,B22222` | Three hex colors |
| `gpu_fan` | Flag | absent | RPM on AMD, percent on NVIDIA |
| `gpu_voltage` | Flag | absent | AMD ONLY |
| `gpu_list` | CommaSeparatedInts | `""` | Select GPUs by index e.g. `0,1` |
| `gpu_efficiency` | Flag | absent | |
| `gpu_name` | Flag | absent | Show GPU model name |
| `vulkan_driver` | Flag | absent | Show Vulkan driver string |
| `engine_version` | Flag | absent | |
| `engine_short_names` | Flag | absent | |
| `present_mode` | Flag | absent | |
| `pci_dev` | String | `""` | Format: `domain:bus:slot.function` e.g. `0000:03:00.0` |

---

## Category: DISPLAY — CPU

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `cpu_stats` | Flag | present | Master CPU section toggle |
| `cpu_temp` | Flag | absent | |
| `cpu_power` | Flag | absent | |
| `cpu_text` | String[32] | `""` | Custom CPU label |
| `cpu_mhz` | Flag | absent | Average MHz across cores |
| `cpu_load_change` | Flag | absent | Color CPU load |
| `cpu_load_value` | CommaSeparatedInts | `60,90` | Two thresholds |
| `cpu_load_color` | CommaSeparatedStrings | `39F900,FDFD09,B22222` | Three hex colors |
| `cpu_efficiency` | Flag | absent | |
| `core_load` | Flag | absent | Per-core load bars |
| `core_load_change` | Flag | absent | Color per-core load |
| `core_bars` | Flag | absent | Graphical core bars |
| `core_type` | Flag | absent | Show P/E core type labels |

---

## Category: DISPLAY — MEMORY

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `vram` | Flag | absent | Required by gpu_mem_clock, gpu_mem_temp |
| `ram` | Flag | absent | |
| `swap` | Flag | absent | |
| `procmem` | Flag | absent | Per-process resident memory |
| `procmem_shared` | Flag | absent | DEPENDS ON: `procmem` |
| `procmem_virt` | Flag | absent | DEPENDS ON: `procmem` |
| `proc_vram` | Flag | absent | Per-process VRAM |

---

## Category: DISPLAY — I/O & NETWORK

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `io_read` | Flag | absent | Per-app I/O read |
| `io_write` | Flag | absent | Per-app I/O write |
| `network` | CommaSeparatedStrings | `""` | Network interfaces e.g. `eth0,wlo1`; empty = all |

---

## Category: DISPLAY — MISC INDICATORS

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `wine` | Flag | absent | Wine/Proton version |
| `winesync` | Flag | absent | Wine sync method |
| `exec_name` | Flag | absent | Show executable name |
| `arch` | Flag | absent | MangoHud architecture |
| `gamemode` | Flag | absent | GameMode running status |
| `vkbasalt` | Flag | absent | vkBasalt running status |
| `engine_version` | Flag | absent | |
| `version` | Flag | absent | Show MangoHud version in overlay |
| `resolution` | Flag | absent | Current display resolution |
| `display_server` | Flag | absent | Wayland/X11 indicator |
| `temp_fahrenheit` | Flag | absent | Use °F instead of °C |
| `flip_efficiency` | Flag | absent | Joules per frame |
| `fex_stats` | Flag | absent | FEX-Emu stats (ARM64 only) |

---

## Category: DISPLAY — GRAPHS

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `graphs` | CommaSeparatedStrings | `""` | Valid values: `gpu_load,cpu_load,gpu_core_clock,gpu_mem_clock,vram,ram,cpu_temp,gpu_temp` |

---

## Category: DISPLAY — BATTERY

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `battery` | Flag | absent | |
| `battery_icon` | Flag | absent | DEPENDS ON: `battery` |
| `device_battery` | CommaSeparatedStrings | `""` | e.g. `gamepad,mouse` |
| `device_battery_icon` | Flag | absent | |
| `battery_watt` | Flag | absent | DEPENDS ON: `battery` |
| `battery_time` | Flag | absent | DEPENDS ON: `battery` |

---

## Category: DISPLAY — MEDIA PLAYER

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `media_player` | Flag | absent | Enable media player metadata |
| `media_player_name` | String | `""` | e.g. `spotify` — DEPENDS ON: `media_player` |
| `media_player_format` | String | `""` | e.g. `{title};{artist};{album}` — DEPENDS ON: `media_player` |

---

## Category: DISPLAY — GAMESCOPE

All options in this category: `gamescope_only = true`

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `fsr` | Flag | absent | FSR status |
| `hide_fsr_sharpness` | Flag | absent | DEPENDS ON: `fsr` |
| `hdr` | Flag | absent | HDR status |
| `refresh_rate` | Flag | absent | Current refresh rate |
| `debug` | Flag | absent | Gamescope app frametimes graph |

---

## Category: DISPLAY — STEAM DECK

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `fan` | Flag | absent | Steam Deck fan RPM |
| `mangoapp_steam` | Flag | absent | mangoapp only |

---

## Category: DISPLAY — TIME & MISC TEXT

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `time` | Flag | absent | Current time |
| `time_no_label` | Flag | absent | DEPENDS ON: `time` |
| `time_format` | String | `"%T"` | strftime format |
| `custom_text_center` | String | `""` | Centered header text |
| `custom_text` | String | `""` | Custom text line |
| `exec` | String | `""` | Shell command — output shown in next column |

---

## Category: APPEARANCE — LAYOUT

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `legacy_layout` | Bool | `0` | |
| `preset` | Int[-1..4] | `-1` | -1=default; 0=off; 1=fps only; 2=horizontal; 3=extended; 4=high detail |
| `full` | Flag | absent | Enable most toggleable params |
| `no_display` | Flag | absent | Start hidden |
| `horizontal` | Flag | absent | Horizontal layout |
| `horizontal_stretch` | Flag | absent | DEPENDS ON: `horizontal` |
| `hud_compact` | Flag | absent | Compact mode |
| `hud_no_margin` | Flag | absent | Remove margins |
| `position` | Enum[`top-left`,`top-right`,`bottom-left`,`bottom-right`,`top-center`,`middle-left`,`middle-right`,`bottom-center`] | `top-left` | |
| `offset_x` | Int[0..9999] | `0` | pixels |
| `offset_y` | Int[0..9999] | `0` | pixels |
| `width` | Int[0..9999] | `0` | 0 = auto |
| `height` | Int[0..9999] | `140` | |
| `table_columns` | Int[1..10] | `3` | |
| `cellpadding_y` | Float[-2.0..2.0] | `-0.085` | |
| `round_corners` | Int[0..50] | `0` | |
| `background_alpha` | Float[0.0..1.0] | `0.5` | |
| `alpha` | Float[0.0..1.0] | `1.0` | Overall HUD transparency |

---

## Category: APPEARANCE — COLORS

All color values: 6-char hex string RRGGBB (no `#`). Validate: must match `^[0-9A-Fa-f]{6}$`.

| Key | Default |
|-----|---------|
| `text_color` | `FFFFFF` |
| `gpu_color` | `2E9762` |
| `cpu_color` | `2E97CB` |
| `vram_color` | `AD64C1` |
| `ram_color` | `C26693` |
| `engine_color` | `EB5B5B` |
| `io_color` | `A491D3` |
| `frametime_color` | `00FF00` |
| `background_color` | `020202` |
| `media_player_color` | `FFFFFF` |
| `wine_color` | `EB5B5B` |
| `battery_color` | `FF9078` |
| `network_color` | `E07B85` |
| `horizontal_separator_color` | `AD64C1` |

Also:
| Key | Type | Default |
|-----|------|---------|
| `text_outline` | Flag | present (default on) |
| `text_outline_color` | Color | `000000` |
| `text_outline_thickness` | Float[0.5..5.0] | `1.5` |

---

## Category: APPEARANCE — TYPOGRAPHY

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `font_size` | Int[8..72] | `24` | |
| `font_scale` | Float[0.1..5.0] | `1.0` | |
| `font_size_text` | Int[8..72] | `24` | For text elements |
| `font_scale_media_player` | Float[0.1..5.0] | `0.55` | |
| `no_small_font` | Flag | absent | Disable small font for secondary info |
| `font_file` | Path | `""` | TTF/OTF path — validated to exist if set |
| `font_file_text` | Path | `""` | |
| `font_glyph_ranges` | CommaSeparatedStrings | `""` | Valid: `korean,chinese,chinese_simplified,japanese,cyrillic,thai,vietnamese,latin_ext_a,latin_ext_b` |

---

## Category: BEHAVIOR — KEYBINDINGS

All keybind values: format is `Key` or `Modifier+Key` or `Mod1+Mod2+Key`.
Valid modifiers: `Shift_L`, `Shift_R`, `Control_L`, `Control_R`, `Alt_L`, `Alt_R`, `Super_L`, `Super_R`.

| Key | Default |
|-----|---------|
| `toggle_hud` | `Shift_R+F12` |
| `toggle_hud_position` | `Shift_R+F11` |
| `toggle_preset` | `Shift_R+F10` |
| `toggle_fps_limit` | `Shift_L+F1` |
| `toggle_logging` | `Shift_L+F2` |
| `reload_cfg` | `Shift_L+F4` |
| `upload_log` | `Shift_L+F3` |
| `reset_fps_metrics` | `Shift_R+F9` |

---

## Category: BEHAVIOR — LOGGING

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `autostart_log` | Int[0..3600] | absent | Seconds before auto-start |
| `log_duration` | Int[1..86400] | absent | Seconds |
| `log_interval` | Int[0..10000] | `0` | ms; 0 = default |
| `output_folder` | Path | `""` | Must be writable directory |
| `output_file` | String | `""` | |
| `permit_upload` | Bool | `0` | Upload to flightlessmango.com |
| `benchmark_percentiles` | CommaSeparatedStrings | `97,AVG` | |
| `log_versioning` | Flag | absent | |
| `upload_logs` | Flag | absent | DEPENDS ON: `permit_upload=1` |

---

## Category: BEHAVIOR — MISC

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `blacklist` | CommaSeparatedStrings | `""` | App names to suppress overlay |
| `control` | String | `-1` | Socket name; -1=disabled; `%p` replaced with PID |

---

## Category: WORKAROUNDS — OPENGL

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `gl_size_query` | Enum[`viewport`,`scissorbox`,`disabled`] | `""` | Default: glXQueryDrawable |
| `gl_bind_framebuffer` | Int[0..999] | absent | Rebind framebuffer before draw |
| `gl_dont_flip` | Bool | absent | Don't swap origin for GL_UPPER_LEFT |

---

## Category: ADVANCED — FCAT

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `fcat` | Flag | absent | Enable FCAT overlay |
| `fcat_overlay_width` | Int[20..200] | `24` | DEPENDS ON: `fcat` |
| `fcat_screen_edge` | Int[0..3] | `0` | DEPENDS ON: `fcat` |

---

## Category: ADVANCED — FTRACE

| Key | Type | Notes |
|-----|------|-------|
| `ftrace` | String | Complex format: `type/event[+type/event2]`; validated by regex |

ftrace format regex: `^(histogram|linegraph|label)/[a-zA-Z0-9_]+(\/[a-zA-Z0-9_]+)?(\+(histogram|linegraph|label)/[a-zA-Z0-9_]+(\/[a-zA-Z0-9_]+)?)*$`

---

## Validation Rules Summary

### Cross-option dependencies (enabling B requires A to also be enabled):
```
gpu_mem_clock    → requires vram
gpu_mem_temp     → requires vram
hide_fsr_sharpness → requires fsr
battery_icon     → requires battery
battery_watt     → requires battery
battery_time     → requires battery
media_player_name → requires media_player
media_player_format → requires media_player
procmem_shared   → requires procmem
procmem_virt     → requires procmem
upload_logs      → requires permit_upload = 1
horizontal_stretch → requires horizontal
time_no_label    → requires time
```

### Mutual exclusions (A and B cannot both be active):
```
fps_only  ↔  (any other display param)
histogram ↔  frame_timing
```

### Vendor restrictions:
```
gpu_voltage → AMD only (warn if non-AMD GPU detected)
```

### Gamescope-only (warn if not running gamescope):
```
fsr, hide_fsr_sharpness, hdr, refresh_rate, debug
```

### Value format validations:
- All Color fields: must match `^[0-9A-Fa-f]{6}$`
- All Path fields: if non-empty, path must exist (for input files) or parent dir must be writable (for output)
- `fps_limit`: each comma-separated value must be non-negative integer
- `font_glyph_ranges`: each value must be in the valid set
- `graphs`: each value must be in the valid set
- `device_battery`: each value must be in `[gamepad, mouse, controller, headset]`
- `fps_metrics`: each value must be `AVG` or a valid decimal between 0.0 and 100.0
- `benchmark_percentiles`: same as fps_metrics
- `time_format`: must be a valid strftime format string
- `pci_dev`: must match `^[0-9a-fA-F]{4}:[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-9a-fA-F]$`
- `control`: must be `-1` or a valid socket name string
- Keybind fields: must match `^(Shift_[LR]\+|Control_[LR]\+|Alt_[LR]\+|Super_[LR]\+)*(F[1-9]|F1[0-2]|[A-Z])$`