ScopeBuddy

A manager script to make gamescope easier to use on the desktop (or if you use it in desktop mode and gamemode)

Originally made for Bazzite, released here so more projects can make use of it! ❤️

Turn this

Into this (you can also replace scopebuddy with scb if you set that up)

Features:

• Fixes the Steam Overlay when used in nested/desktop mode
• Fixes SteamInput when used in nested/desktop mode
• Does not launch gamescope when it detects being started inside gamemode/gamescope-session
• Enables you to define global defaults arguments for gamescope in desktop mode
• Enables you to define per-game arguments for gamescope
• Enables you to define global and per-game ENV variables
• Optionally use scb just for ENV var management
• Automatically infer display output args (output width, height, refresh rate, HDR, or VRR flags) from primary display (KDE Plasma and GNOME)

Documentation and usage

Look at https://docs.bazzite.gg/Advanced/scopebuddy/

Auto-Detection Features (SCB_AUTO_*)

ScopeBuddy can automatically detect your display settings and configure gamescope accordingly:

• SCB_AUTO_RES=1: Automatically detect and set display resolution (-W and -H)
• SCB_AUTO_HDR=1: Automatically enable HDR if your display has HDR enabled
• SCB_AUTO_VRR=1: Automatically enable adaptive sync if VRR is active on your display
• SCB_AUTO_REFRESH=1: Automatically set an explicit refresh rate (-r) to your current monitor refresh rate. NOTE: this has known limitations, and often doesn't work if --adaptive-sync or SCB_AUTO_VRR is set.
• SCB_AUTO_FRAME_LIMIT=1: Automatically set a gamescope's framerate limiter (--framerate-limit) to your current monitor refresh rate. NOTE: this has known limitations, and often doesn't work if --adaptive-sync or SCB_AUTO_VRR is set.

Desktop Environment Support

• KDE Plasma: Uses kscreen-doctor (requires jq)
• GNOME: Uses either gdctl (requires jq and upstream version with --format=json support) or gnome-randr as fallback
• Wlroots Compositor: Uses "wlr-randr" (requires jq)

Usage Examples

In Steam launch options:

SCB_AUTO_RES=1 SCB_AUTO_HDR=1 SCB_AUTO_VRR=1 scopebuddy -- %command%

In config file (~/.config/scopebuddy/scb.conf):

# Enable auto-detection for resolution, HDR, and VRR
SCB_AUTO_RES=1
SCB_AUTO_HDR=1
SCB_AUTO_VRR=1
SCB_AUTO_REFRESH=1
SCB_AUTO_FRAME_LIMIT=1

GNOME Support

ScopeBuddy supports two methods for GNOME display detection:

Option 1: gdctl (Preferred - may require manual steps)

For GNOME users with an upstream version of gdctl that supports --format=json. ScopeBuddy will automatically test if your gdctl version supports this.

You can check if you have a version that supports this by running

gdctl show --format=json in your terminal. If you see output about your display, your version is supported.

If you see

usage: gdctl [-h] COMMAND ...
gdctl: error: unrecognized arguments: --format=json

Then your distribution's version doesn't support JSON output yet. You can either proceed to option 2 (gnome-randr) or download the upstream version of gdctl from this merge request:

Note: The GNOME GitLab may require authentication to download files directly. If you encounter a permissions error, log in to your GitLab account in your browser, navigate to the merge request, and download the gdctl file manually. Save it as ~/.local/bin/gdctl-mr4708 and make it executable:

chmod +x ~/.local/bin/gdctl-mr4708

Then use it with the GDCTL_COMMAND variable:

In Steam launch options:

GDCTL_COMMAND=$HOME/.local/bin/gdctl-mr4708 SCB_AUTO_RES=1 SCB_AUTO_HDR=1 SCB_AUTO_VRR=1 scopebuddy -- %command%

In config file:

export GDCTL_COMMAND="$HOME/.local/bin/gdctl-mr4708"
SCB_AUTO_RES=1
SCB_AUTO_HDR=1
SCB_AUTO_VRR=1

Option 2: gnome-randr (Automatic Fallback)

If gdctl is not available or doesn't support --format=json, ScopeBuddy will automatically fall back to using gnome-randr.

gnome-randr is shipped by default with Bazzite's GNOME-based images, and should be available through package managers on most other distros.

You can also specify a custom gnome-randr path:

In config file:

export GNOME_RANDR_COMMAND="$HOME/.local/bin/gnome-randr"
SCB_AUTO_RES=1
SCB_AUTO_HDR=1
SCB_AUTO_VRR=1

Wlroots Compositor Support

Wlroots compositors do not have any concept of a primary monitor, so the monitor must be specified with gamescope's -O or --prefer-output flag. See Multi-Monitor Support for more info.

Multi-Monitor Support

If you're using multiple monitors and want to target a specific display, use gamescope's -O or --prefer-output flag:

SCB_AUTO_RES=1 scopebuddy -O DP-3 -- %command%

Installation

Requirements

• bash
• gamescope
• perl

Optional for $SCB_AUTO_RES/$SCB_AUTO_HDR/$SCB_AUTO_VRR:

• KDE Plasma: kscreen-doctor (usually pre-installed) and jq (installed by default on Bazzite)
• GNOME: Either gdctl with --format=json support (requires jq) OR gnome-randr (see GNOME Support section above)

• Wlroots Compositor: Uses "wlr-randr" (requires jq)

Using curl:

sudo curl -Lo /usr/local/bin/scopebuddy https://raw.githubusercontent.com/HikariKnight/ScopeBuddy/refs/heads/main/bin/scopebuddy
sudo chmod +x /usr/local/bin/scopebuddy

Using wget:

sudo wget -O /usr/local/bin/scopebuddy https://raw.githubusercontent.com/HikariKnight/ScopeBuddy/refs/heads/main/bin/scopebuddy
sudo chmod +x /usr/local/bin/scopebuddy

Make scb symlink because we love short commands

NOTE: You only need to do this once

sudo ln -s scopebuddy /usr/local/bin/scb

Specific version:

• Download the versioned release from github releases
• Extract the script
• Move to /usr/local/bin or /usr/bin
• make scb symlink

NixOS

Using flakes:

Home Manager (flake-based), add an input:

inputs.scopebuddy.url = "github:HikariKnight/ScopeBuddy";

Then add the package:

home.packages = [
  inputs.scopebuddy.packages.${pkgs.system}.default
];

GUI Configuration

TealMango in the Bazzite community has made a GUI tool to configure scopebuddy. Well worth to check it out here: ScopeBuddy-GUI