config.toml

~/.config/universe/config.toml holds the settings every game shares. The settings pages and universe config set write it; a key left out keeps its default. A game’s own settings live in its game.toml (see Launch keys).

[paths]

defaults follow XDG and xdg-user-dirs

Key	Default
games_root	"~/Games"	$XDG_GAMES_DIR: where sources install
prefixes_root	"~/.local/share/universe/prefixes"
saves_root	"~/.local/share/universe/saves"	ludusavi’s backups, one folder per game (see Game data)
recordings_root	"~/Videos/universe"	$XDG_VIDEOS_DIR/universe

[launch]

Key	Default
proton	"proton-ge"	a name under [proton], a path, or a family found under Lutris, Steam or Heroic (see Proton and Wine)
esync	true
fsync	true
ntsync	true	a sync mode off is PROTON_NO_*=1 (WINEESYNC/WINEFSYNC=0 for wine)
wayland	true	PROTON_ENABLE_WAYLAND=1; dropped inside gamescope unless –expose-wayland
hdr	false	PROTON_ENABLE_HDR=1, and –hdr-enabled on gamescope
sony_pad	"auto"	auto | native | dualshock4 | xinput: a PlayStation pad under GE-Proton (see Proton and Wine)
discrete_gpu	true	a hybrid laptop: the game and gamescope render on the stronger GPU, not the screen’s (DRI_PRIME or PRIME offload, –prefer-vk-device)
dlss_upgrade	"off"	PROTON_DLSS_UPGRADE, PROTON_FSR4_UPGRADE, PROTON_XESS_UPGRADE, PROTON_USE_OPTISCALER
fsr4_upgrade	"off"	auto | on | off (or a bool): auto is on where the GPU makes it a plain win; on RDNA 3 PROTON_FSR4_RDNA3_UPGRADE instead
xess_upgrade	"off"
optiscaler	false
debug_log	false	Proton, Wine and DXVK verbose logs into <state>/logs/<id>/<session>/ (see Logs)
mangohud	false	the HUD shown at launch (loaded and hidden when false, the limit still holds); flipped in game by the dock and the mangohud macro for that session alone
gamescope	true	every game inside gamescope: one window, black until the game draws
gamescope_args	""	after the flags below, and over them; –expose-wayland keeps PROTON_ENABLE_WAYLAND
gamescope_bin	"gamescope"	a name on PATH (/run/wrappers/bin included) or a path
gamescope_resolution	"auto"	the screen’s mode, or WxH: what the game renders at (-w -h); the output is always the screen
gamescope_refresh	"auto"	the screen’s rate, or Hz (-r)
gamescope_scaler	""	auto | integer | fit | fill | stretch (-S); empty: gamescope’s default
gamescope_filter	""	linear | nearest | fsr | nis | pixel (-F)
gamescope_sharpness	unset	0 (sharpest) to 20, for fsr and nis (–sharpness) (for example 2)
gamescope_adaptive_sync	"auto"	–adaptive-sync: auto when the screen has variable refresh, or on | off
fps_limit	"auto"	MangoHud’s limiter in the game: auto (the refresh the game sees), none, or frames per second
pause_on_home	true	freeze the game while the launcher covers it (HOME); off for a game that must keep running

[desktop]

Key	Default
profile	"auto"	auto | gnome | kde | cinnamon | sway | hyprland | niri | x11 | none (see Desktop)
hide_cursor	true
cursor_extension	""	empty: the Universe extension hides the pointer after 5 s at rest; another extension’s uuid is enabled for the session instead, restored to its prior state after
keep_awake	true	the desktop’s idle inhibitors held for the session (see universe keep-awake): a pad is no activity to it, and the screen would blank and suspend mid-game
whats_new	true	the first start after an update opens what changed since the version last run (whats_new()); Settings › About and Game defaults › Updates in every look, Preferences › Game Defaults in Universe Desktop

[saves]

see Game data

Key	Default
auto_backup	true	a backup of the game’s saves after each session
keep	5	backups kept per game (1 to 255), the oldest going first

[system]

the machine’s controls as last set (see System), put back at the launcher’s start outside Steam; “” leaves one as the system has it; a game’s own game.toml [system] holds the same ids, brightness too

Key	Default
tdp	""	watts
gpu	""	auto, or MHz
refresh	""	Hz, a Deck’s panel on the launcher’s own gamescope
fan	""	on | off: SteamOS’s fan curve

[proton]

name → path, none by default; a name with no path here is looked for as a family (GE-Proton10-4 for proton-ge) under Lutris, Steam, umu and Heroic

Key	Default
proton-em	unset	(for example "~/opt/proton-em")

[runners.]

per runner (universe runner set): exe (absent: detected), build (“” the system’s program first, latest, or a version Universe installed), args, gamescope, its options (none by default)

[components]

Key	Default
auto_update	true	Universe’s own builds follow the catalogue, the previous one kept (see Components)
catalogue	""	a URL or a file; empty: the project’s catalogue branch

[extensions]

Key	Default
index	""	an https:// URL or a file (UNIVERSE_EXTENSIONS_INDEX wins); empty: the registry’s (see Extensions)

[modules]

Key	Default
enabled	[]	a module is opt-in: universe module enable capture, or Settings › Features

[modules.capture]

the settings rows: universe module settings capture

Key	Default
ffmpeg_video_opts	unset	config-only: replaces the quality preset (for example "rc_mode=CQP;qp=20")
gsr_extra_args	unset	config-only: appended to gpu-screen-recorder (for example "-cr full -keyint 2")

[sources]

Key	Default
enabled	["gog"]

[sources.gog]

the settings rows: universe source settings gog

Key	Default
platform	unset	(for example "linux")

[keys]

Key	Default
sgdb	""	optional, your own: SteamGridDB’s art joins the picker; or sgdb_file, a file holding it
sgdb_file	"~/.config/steamgriddb/api_key"
prefer_sgdb	false	with a key, SteamGridDB’s art fills a slot before the stores’ and GamesDB’s

[controller]

Key	Default
enabled	true
hold_ms	600	a press this long is a hold
volume_step	2	percent of the normal volume per press, 1–100 (“precise” = 2, “normal” = 6 still read)
home_summons	true	HOME pressed in another app brings Universe’s big screen up; false drops the press

[controller.buttons.xbox-elite]

learned codes: a slot’s list replaces its seeds, [] leaves it unbound (none by default)

Key	Default
paddle_p1	unset	(for example ["BTN_GRIPR", "BTN_TRIGGER_HAPPY5"])

[controller.axes.8bitdo-pro-3]

learned axes: a role’s evdev axis, - when the pad reads it backwards (none by default)

Key	Default
rx	unset	(for example "ABS_Z")

[controller.layout]

where A sits in Nintendo games, per model: “positional” (right) or “xbox” (bottom); absent: its print (none by default)

[controller.macros]

{family, button, trigger, action} (universe controller bind); absent: the seeded workflow, macros = [] none at all (none by default)

The whole file

schema = 2                           # a file without it, or older, is migrated once when the core opens it (see Emulator controls)

[paths]                              # defaults follow XDG and xdg-user-dirs
games_root = "~/Games"               # $XDG_GAMES_DIR: where sources install
prefixes_root = "~/.local/share/universe/prefixes"
saves_root = "~/.local/share/universe/saves"      # ludusavi's backups, one folder per game (see Game data)
recordings_root = "~/Videos/universe"            # $XDG_VIDEOS_DIR/universe

[launch]
proton = "proton-ge"                 # a name under [proton], a path, or a family found under Lutris, Steam or Heroic (see Proton and Wine)
esync = true
fsync = true
ntsync = true                        # a sync mode off is PROTON_NO_*=1 (WINEESYNC/WINEFSYNC=0 for wine)
wayland = true                       # PROTON_ENABLE_WAYLAND=1; dropped inside gamescope unless --expose-wayland
hdr = false                          # PROTON_ENABLE_HDR=1, and --hdr-enabled on gamescope
sony_pad = "auto"                    # auto | native | dualshock4 | xinput: a PlayStation pad under GE-Proton (see Proton and Wine)
discrete_gpu = true                  # a hybrid laptop: the game and gamescope render on the stronger GPU, not the screen's (DRI_PRIME or PRIME offload, --prefer-vk-device)
dlss_upgrade = "off"                # PROTON_DLSS_UPGRADE, PROTON_FSR4_UPGRADE, PROTON_XESS_UPGRADE, PROTON_USE_OPTISCALER
fsr4_upgrade = "off"                # auto | on | off (or a bool): auto is on where the GPU makes it a plain win; on RDNA 3 PROTON_FSR4_RDNA3_UPGRADE instead
xess_upgrade = "off"
optiscaler = false
debug_log = false                    # Proton, Wine and DXVK verbose logs into <state>/logs/<id>/<session>/ (see Logs)
mangohud = false                     # the HUD shown at launch (loaded and hidden when false, the limit still holds); flipped in game by the dock and the mangohud macro for that session alone
gamescope = true                     # every game inside gamescope: one window, black until the game draws
gamescope_args = ""                  # after the flags below, and over them; --expose-wayland keeps PROTON_ENABLE_WAYLAND
gamescope_bin = "gamescope"          # a name on PATH (/run/wrappers/bin included) or a path
gamescope_resolution = "auto"        # the screen's mode, or WxH: what the game renders at (-w -h); the output is always the screen
gamescope_refresh = "auto"           # the screen's rate, or Hz (-r)
gamescope_scaler = ""                # auto | integer | fit | fill | stretch (-S); empty: gamescope's default
gamescope_filter = ""                # linear | nearest | fsr | nis | pixel (-F)
# gamescope_sharpness = 2            # 0 (sharpest) to 20, for fsr and nis (--sharpness)
gamescope_adaptive_sync = "auto"    # --adaptive-sync: auto when the screen has variable refresh, or on | off
fps_limit = "auto"                   # MangoHud's limiter in the game: auto (the refresh the game sees), none, or frames per second
pause_on_home = true                 # freeze the game while the launcher covers it (HOME); off for a game that must keep running

[desktop]
profile = "auto"                     # auto | gnome | kde | cinnamon | sway | hyprland | niri | x11 | none (see Desktop)
hide_cursor = true
cursor_extension = ""                # empty: the Universe extension hides the pointer after 5 s at rest; another extension's uuid is enabled for the session instead, restored to its prior state after
keep_awake = true                    # the desktop's idle inhibitors held for the session (see universe keep-awake): a pad is no activity to it, and the screen would blank and suspend mid-game
whats_new = true                     # the first start after an update opens what changed since the version last run (whats_new()); Settings › About and Game defaults › Updates in every look, Preferences › Game Defaults in Universe Desktop

[saves]                              # see Game data
auto_backup = true                   # a backup of the game's saves after each session
keep = 5                             # backups kept per game (1 to 255), the oldest going first

[system]                             # the machine's controls as last set (see System), put back at the launcher's start outside Steam; "" leaves one as the system has it; a game's own game.toml [system] holds the same ids, brightness too
tdp = ""                             # watts
gpu = ""                             # auto, or MHz
refresh = ""                         # Hz, a Deck's panel on the launcher's own gamescope
fan = ""                             # on | off: SteamOS's fan curve

[proton]                             # name → path, none by default; a name with no path here is looked for as a family (GE-Proton10-4 for proton-ge) under Lutris, Steam, umu and Heroic
# proton-em = "~/opt/proton-em"

# [runners.<id>]                     # per runner (`universe runner set`): exe (absent: detected), build ("" the system's program first, latest, or a version Universe installed), args, gamescope, its options

[components]
auto_update = true                   # Universe's own builds follow the catalogue, the previous one kept (see Components)
catalogue = ""                       # a URL or a file; empty: the project's catalogue branch

[extensions]
index = ""                           # an https:// URL or a file (UNIVERSE_EXTENSIONS_INDEX wins); empty: the registry's (see Extensions)

[modules]
enabled = []                         # a module is opt-in: `universe module enable capture`, or Settings › Features

[modules.capture]                    # the settings rows: `universe module settings capture`
# ffmpeg_video_opts = "rc_mode=CQP;qp=20"   # config-only: replaces the quality preset
# gsr_extra_args = "-cr full -keyint 2"      # config-only: appended to gpu-screen-recorder

[sources]
enabled = ["gog"]

[sources.gog]                        # the settings rows: `universe source settings gog`
# platform = "linux"

[keys]
sgdb = ""                            # optional, your own: SteamGridDB's art joins the picker; or sgdb_file, a file holding it
sgdb_file = "~/.config/steamgriddb/api_key"
prefer_sgdb = false                  # with a key, SteamGridDB's art fills a slot before the stores' and GamesDB's

[controller]
enabled = true
hold_ms = 600                        # a press this long is a hold
volume_step = 2                      # percent of the normal volume per press, 1–100 ("precise" = 2, "normal" = 6 still read)
home_summons = true                  # HOME pressed in another app brings Universe's big screen up; false drops the press
# [controller.buttons.xbox-elite]    # learned codes: a slot's list replaces its seeds, [] leaves it unbound
# paddle_p1 = ["BTN_GRIPR", "BTN_TRIGGER_HAPPY5"]
# [controller.axes.8bitdo-pro-3]     # learned axes: a role's evdev axis, `-` when the pad reads it backwards
# rx = "ABS_Z"
# [controller.layout]                # where A sits in Nintendo games, per model: "positional" (right) or "xbox" (bottom); absent: its print
# 8bitdo-pro-3 = "xbox"
# [[controller.macros]]              # {family, button, trigger, action} (`universe controller bind`); absent: the seeded workflow, `macros = []` none at all