Gaming

Gaming

SynapseOS runs a 7B model as a system service, which means something has to give when you launch a game — the model pins around 4 GB of VRAM and a pile of worker threads. Game mode (Super+G) is that negotiation, and synui-game-run is the launcher wrapper that goes with it.

The two solve different halves of the problem and it is worth knowing which is which:

	When it applies	What it does
Game mode (Super+G)	a game that is already running	frees the GPU, holds off idle
synui-game-run	at launch	FPS overlay, CPU/GPU governor, optional gamescope

You cannot inject an overlay into a process that is already up, which is why the launcher exists separately.

---

Game mode

What triggers it

A fullscreen XWayland client, minus an exclusion list. That is the whole signal, and it works because of what the desktop looks like: Steam titles, Proton/Wine and native X11 games all present as fullscreen X11 clients, while modern desktop apps are Wayland-native and never match.

It is automatic — Super+G toggles the feature, not each game.

What it does while a game is up

• Stops synapd. It holds ~4 GB of VRAM and llama.cpp worker threads, and the wire protocol has no unload or sleep message — only RELOAD and SHUTDOWN — so stopping the service is the only way to hand the GPU and those cores over. It starts again on exit and reloads the model then.
• Stops the synapd poller, which would otherwise spin on connect failures and log them forever.
• Holds off the idle stages. A gamepad is not a seat input device, so to the compositor a controller-only session looks perfectly idle — without this the screen dims and then blanks mid-game.

Everything is restored on exit, including when synui itself shuts down. Leaving the machine with a stopped synapd because the compositor died mid-game would be a poor way to lose the AI.

The bar shows an indicator while it is active. synui publishes the state to $XDG_RUNTIME_DIR/synui-game (0700, session-user owned, so nothing else can forge it) and the bar module reads it.

The exclusion list

Fullscreen X11 things that are not games:

firefox · chibi · tepris · nexus-chat · kitty · foot

A fullscreen video is the case this exists for. Without it, going fullscreen on a YouTube video would stop the AI daemon — a genuinely nasty surprise. The Firefox-app-mode apps report their own app_id via MOZ_APP_REMOTINGNAME, so they need naming separately from firefox.

Add your own with game_exclude in synuirc; matching is case-insensitive substring against the app id.

Settings

Key	Default	What it does
game_mode	on	The feature as a whole
game_suspend_ai	on	Stop synapd while a game is up
game_inhibit_idle	on	Don't dim or blank during a game
game_ai_stop_cmd / game_ai_start_cmd	systemctl	How the AI is stopped and started
game_exclude	see above	One entry per line; adds to the defaults

Stopping synapd needs root, and the session has no polkit agent — so it goes through a tightly-scoped sudo -n rule (/etc/sudoers.d/synapd-gamemode). See Commands.

---

Launching a game: synui-game-run

Wraps a command in gamemoderun (CPU/GPU governor), MangoHud (the overlay), and optionally gamescope (a nesting micro-compositor for clean scaling and a frame cap).

synui-game-run -- ./game.x86_64
synui-game-run --gamescope=2560x1440@60 -- steam -gamepadui

In Steam, set it as a launch option — the %command% form:

synui-game-run -- %command%

Flags: --gamescope[=WxH[@R]] · --no-hud · --no-gamemode · --ensure-config

Every wrapper is optional and guarded. A missing tool is dropped rather than being fatal, so the command still launches, just without that layer. gamescope ships on the ISO; mangohud, lib32-mangohud and gamemode are optdepends:

sudo pacman -S mangohud lib32-mangohud gamemode

The overlay is hidden until you ask

/etc/MangoHud.conf ships with no_display, so the overlay is loaded but invisible. Shift_R+F12 toggles it — right Shift, not left.

That file is in the package's backup= array, so your edits survive upgrades.

MANGOHUD=1 only hooks Vulkan. An OpenGL game needs the wrapper: mangohud %command%, or synui-game-run, which does it for you. This is the single most common reason the overlay "doesn't work".

---

Things that will confuse you

"Fullscreen" is a lie

Some games' fullscreen is borderless windowed: they never send _NET_WM_STATE_FULLSCREEN, so the compositor correctly tiles them, game mode never triggers, and it looks like synui is broken.

Doom KEX is the standing example — v_windowmode=1 is borderless, 2 is true fullscreen. Either fix it in the game, or force it with Super+Shift+F.

A game opens on the wrong monitor

Xwayland with no primary output leaves SDL falling back to connector order. Set one: Super+D → p, or primary=1 in outputs.conf.

A correctly-sized window that renders nothing

Usually the game, not the compositor. Unity titles persist a screen-resolution index rather than a resolution, so moving a game between monitors with different mode lists can leave the saved index out of range — which resolves to a 1×1 viewport inside a properly sized window. Delete or fix the game's prefs entry.

A blank window at the right size is a client resolution bug far more often than a compositor bug.

Windows games

wine and wine-mono ship on the ISO, and there is a Run with Wine action in the file manager's context menu (synui-wine-run).

Two traps worth knowing if you use Lutris or a prefix by hand:

• A 32-bit game needs arch: win32 in the config, not just a 32-bit prefix.
• gamescope and Wine do not always mix — if a Wine title misbehaves under --gamescope, run it without.

The AI came back and the network didn't

synnet has a Requires= on synapd. Stopping synapd therefore used to stop synnet too. Fixed, but the shape is worth remembering: check Requires= before you stop a unit.

---

See also: synui, synapd, Keybindings, Troubleshooting.