Gaming & Gamescope

This guide covers the fleet-wide gaming architecture, Proton compatibility tool integration, and the usage of Valve’s Gamescope micro-compositor across desktop and laptop form factors.

Gaming Stack Architecture

NixOS gaming configurations are declared in modules/gaming/default.nix and imported across all hosts:

Steam: Installed via programs.steam.enable = true with local network game transfer firewall ports opened and Protontricks enabled.
Proton-GE (extraCompatPackages): Pre-bundles proton-ge-bin directly into Steam’s compatibility dropdown without requiring manual GUI downloads.
Gamescope: System-wide micro-compositor enabled with Wayland WSI (programs.gamescope.enableWsi = true).
GameMode: Feral Interactive GameMode daemon configured to optimize system performance on demand during active gameplay.
Game Devices Udev Rules: Controller and joystick udev rules (game-devices-udev-rules) providing non-root access to DualSense, Xbox, Switch, and handheld controllers.

Gamescope: Micro-Compositor (`framework16`, `mini-pc-k8`)

Gamescope is Valve’s Wayland micro-compositor. It isolates games inside their own virtual display server, intercepting their input and rendering before outputting a composited Wayland surface to Hyprland.

Role: On-demand, nested client window inside Hyprland.
Mechanism: Invoked per-game through Steam launch options.
Behavior: Games run directly under Hyprland by default (leveraging Hyprland’s direct scanout for zero latency). Gamescope is opted into only when a game requires resolution sandboxing, upscaling, or display virtualization.

Why Gamescope Is Not Default on Desktops

Gamescope is intentionally not enabled as the default launcher for desktop/laptop sessions:

Display & Geometry Mismatches: Desktops and laptops run varied displays (e.g. 16:10 2560x1600 on Framework 16 vs 16:9 4K or 1440p on external monitors). Hardcoding a global resolution breaks multi-monitor and docking workflows.
Third-Party Launchers: Games with multi-window pre-launchers (EA App, Ubisoft Connect, Paradox, Larian Launcher) often hang, render blank windows, or fail to gain focus in a nested Gamescope container.
Hyprland Direct Scanout: Hyprland already performs direct scanout for fullscreen windows (Wayland and XWayland), sending frames directly to the display controller without compositor composition latency.
Cursor Trapping: Gamescope confines the cursor to its virtual boundary, complicating multi-monitor navigation and desktop workspace switching.

Steam Launch Options Cheat Sheet

To run a specific game inside Gamescope on a desktop or laptop, right-click the game in Steam, open Properties → General → Launch Options, and use one of the recipes below:

1. Standard Windowed Fullscreen

Renders the game at 1080p and displays it borderless fullscreen at your monitor’s refresh rate:

gamescope -W 1920 -H 1080 -f -r 144 -- %command%

2. AMD FSR Upscaling (Performance Boost)

Renders the game internally at 720p and upscales to 1080p using AMD FidelityFX Super Resolution (FSR):

gamescope -w 1280 -h 720 -W 1920 -H 1080 -F fsr -f -- %command%

(Adjust sharpness in-game or via --fsr-sharpness <0-20>, default is 2).

3. Pixel-Perfect Integer Scaling (Retro & Pixel Art)

Forces integer scaling without blur or bilinear filtering for low-resolution or retro titles:

gamescope -w 640 -h 480 -W 1920 -H 1080 -S integer -f -- %command%

4. Frame Rate Limiting & Latency Tuning

Caps rendering rate at 60 FPS with low-latency presentation:

gamescope -W 1920 -H 1080 -r 60 --limiter-spatial -f -- %command%

5. High Dynamic Range (HDR)

Enables HDR mastering and wide color gamut output on supported OLED/HDR monitors:

gamescope --hdr-enabled --hdr-debug-force-output -W 2560 -H 1440 -f -- %command%

Gamescope Command-Line Reference

Flag	Argument	Description
`-w`, `-h`	`<width>`, `<height>`	Internal game render resolution (what the game sees).
`-W`, `-H`	`<width>`, `<height>`	Output window/display resolution (target display size).
`-r`	`<hz>`	Target display refresh rate (e.g. `60`, `120`, `144`).
`-f`	None	Fullscreen mode.
`-b`	None	Borderless windowed mode.
`-F`	`fsr`, `nis`, `linear`, `nearest`	Upscaling filter algorithm.
`-S`	`integer`, `fit`, `fill`, `stretch`	Scaling mode for aspect ratio handling.
`--force-grab-cursor`	None	Confine cursor to Gamescope window.
`--cursor <path>`	`<file>`	Custom cursor path.
`--hdr-enabled`	None	Enable HDR metadata and compositing.

Native Wayland vs. Gamescope Comparison

Feature	Direct Hyprland (Default)	Native Wayland (`PROTON_ENABLE_WAYLAND=1`)	Gamescope (`gamescope --`)
Driver	XWayland / Native Wayland	Wine `winewayland.drv`	Gamescope internal Xwayland / Wayland
Steam Overlay	Functional	Broken	Functional
Steam Input / Menus	Functional	Inconsistent	Functional
FSR / Integer Upscaling	Game-dependent	Game-dependent	Built-in hardware scaling
Latency	Direct Scanout (Lowest)	Native (Lowest)	Minimal (~1 frame overhead)
Multi-window Launchers	Functional	Functional	Prone to focus/rendering bugs
Best For	Modern Steam titles	Benchmark latency / testing	Retro games, broken resolution pickers, FSR