Wayscope

Profile-based gamescope wrapper for gaming on Linux.

Why wayscope?

Gamescope can be a guessing game and insanely frustrating to use; variables, CLI flags, and workarounds. And when you finally figure out the commands you have to apply them in too many places and you better not forget them. Wayscope is a tool that helps with this.

• Environment setup - Configures RADV, Wayland, Proton, and SDL variables automatically
• HDR configuration - Sets DXVK_HDR, ENABLE_HDR_WSI, PROTON_ENABLE_HDR and the required CLI flags
• HDR workaround - Automatically applies DISABLE_HDR_WSI=1 to child processes when using Wayland + WSI + HDR together (a weird wayland quirk)
• VRR/Adaptive sync - Enables --adaptive-sync based on your monitor's capabilities
• Resolution & refresh - Derives --output-width, --output-height, --nested-refresh from your monitor config
• WSI layer - Manages ENABLE_GAMESCOPE_WSI for proper Vulkan integration
• Profile switching - Easily swap between HDR, SDR, performance, etc configs
• Skip gamescope - Use --skip-gamescope to apply profile environment setup without the gamescope wrapper
• Unset variables - Remove inherited environment variables per-profile for fine-grained control

Quick Start

# Initialize config files
wayscope init

# Edit your monitor settings
$EDITOR ~/.config/wayscope/monitors.yaml

# Run a game
wayscope run steam
wayscope run -p hdr heroic

Configuration

Two files in ~/.config/wayscope/:

monitors.yaml - Your displays and their capabilities:

monitors:
  main:
    width: 2560
    height: 1440
    refresh: 165
    vrr: true
    hdr: true
    default: true

config.yaml - Gaming profiles:

profiles:
  default:
    useWSI: true

  hdr:
    useHDR: true
    useWSI: true

  performance:
    useHDR: false
    options: # Any gamescope --flag
      nested-width: 1920
      nested-height: 1080
      filter: fsr

Profile values override monitor defaults. Run wayscope init to create a default configuration with all available options.

Commands

wayscope init                           # Create config files with examples
wayscope run <command>                  # Run through gamescope (default profile)
wayscope run -p hdr steam               # Run with specific profile
wayscope run -s bash                    # Skip gamescope, run command directly with profile env
wayscope run -sp wayland %command%      # Skip gamescope, use profile env with gamemode
wayscope list                           # List profiles
wayscope show <profile>                 # Show resolved settings
wayscope monitors                       # List monitors

Installation

# From source
cargo build --release
cp target/release/wayscope ~/.local/bin/

# With Nix
nix build

Home Manager Module

Wayscope provides a Home Manager module for declarative configuration. Add it to your flake:

# flake.nix
{
  inputs.wayscope.url = "github:TophC7/wayscope";

  outputs = { wayscope, ... }: {
    homeConfigurations.you = home-manager.lib.homeManagerConfiguration {
      modules = [
        wayscope.homeManagerModules.wayscope
        # your other modules...
      ];
    };
  };
}

Then configure profiles and wrappers:

# home.nix
{ config, osConfig, lib, pkgs, ... }:
{
  programs.wayscope = {
    enable = true;

    # Wayscope derives resolution, refresh, HDR, VRR from this (can be overridden by profile)
    monitors.main = {
      width = 2560;
      height = 1440;
      refreshRate = 165;
      hdr = true;
      vrr = true;
      primary = true;
    };

    # Define reusable profiles
    profiles = {
      default = {
        useHDR = true;
        useWSI = true;
        options.backend = "wayland";
        # unset = [ "SOME_VARIABLE" ];
      };

      steam = {
        useHDR = true;
        useWSI = true;
        options = {
          backend = "wayland";
          steam = true;
        };
        environment = {
          STEAM_FORCE_DESKTOPUI_SCALING = "1";
          STEAM_GAMEPADUI = "1";
        };
      };
    };

    # Generate wrapped executables
    wrappers = {
      steam-wayscope = { # You can name this as "steam" to effectively replace the steam command and always use wayscope even in unmodified .desktop files 
        enable = true;
        profile = "steam";
        command = "${lib.getExe osConfig.programs.steam.package} -bigpicture -tenfoot";
      };

      heroic = {
        enable = true;
        profile = "auto-hdr";
        package = pkgs.heroic;
      };
    };
  };
}

play.nix

Wayscope started as gamescoperun inside play.nix, a NixOS flake I use for my own gaming setup. If you want Steam with Proton-CachyOS, Gamemode, ananicy, LACT for AMD GPUs, etc. already wired up, it might save you some time.

Advanced Usage

Skip Gamescope with --skip-gamescope

Use the --skip-gamescope flag (short form: -s) to apply profile environment variables without wrapping your command in gamescope. This is useful for games that run well/better without gamescope but still need some environment setup.

All environment variables from the profile are applied, including base variables (RADV, Wayland setup, etc.) and any HDR/WSI configuration.

Remove Variables with unset

Use the unset field in profiles to remove specific environment variables from executed process. This is useful for removing inherited variables that interfere with games.

Example:

profiles:
  wayland-native:
    useWSI: true
    unset:
      - DISPLAY # Unset X11 display

Then assuming you have a Proton version that supports Wayland natively, you can use this profile to spawn the game in a pure Wayland environment:

wayscope run -sp wayland-native %command%

Steam and Backend Limitations

Steam has specific quirks when running inside gamescope that affect how you can use wayscope:

The Problem: Steam does not support --backend sdl when passed through game launch options (%command%), but it does work when Steam itself is launched with that backend.

This creates two distinct HDR workflows:

Mode 1: Native HDR (Wayland Backend + WSI)

profiles:
  hdr-native:
    useHDR: true
    useWSI: true
    options:
      backend: wayland

• Wayscope automatically disables WSI HDR for child processes (DISABLE_HDR_WSI=1) so native HDR games can output HDR directly
• Do NOT use hdr-itm-enabled: true with this mode—it causes a dark/black screen
• Best for games with native HDR support

Mode 2: Tone-Mapped HDR (SDL Backend + ITM)

profiles:
  hdr-tonemapped:
    useHDR: true
    useWSI: true
    options:
      backend: sdl
      hdr-itm-enabled: true

• Forces HDR tone mapping on all content (SDR games get converted to HDR)
• Must launch Steam itself through wayscope, not individual games:

# This works - Steam launched through wayscope
wayscope run -p hdr-tonemapped steam steam://rungameid/3228590

# This does NOT work - wayscope sdl profile in game launch options
wayscope run -p hdr-tonemapped %command% # Steam launch options for a game, NOT a usual terminal command

Recommended Steam Setup

There are two main approaches to using wayscope with Steam, each with its own trade-offs:

---

Option A: Per-Game Launch Parameters (More Control)

Set up game launch parameters for individual games in Steam the way you normally would, but use wayscope in the launch commands.

In Steam: Right-click a game > Properties > Launch Options:

wayscope run -p hdr %command%

Advantages:

• Fine-grained control over each game's profile
• Easy to switch profiles per-game
• Steam runs normally outside of gamescope

Disadvantages:

• More manual setup for each game
• No support for --backend flag (see Mode 2 above)

---

Option B: Launch Steam Through Wayscope (Set and Forget)

Launch Steam itself through wayscope so everything runs inside gamescope from the start.

wayscope run -p hdr-tonemapped steam -bigpicture

Advantages:

• One consistent experience for all games
• Has support for --backend flag
• No need to configure individual game launch options

Disadvantages:

• You must restart Steam to change the profile
• Steam itself runs inside gamescope, so theres no window navigation
  • I recommend using Big Picture mode
• Better suited for users that want a more consistent HDR experience

NixOS Home Manager Example (Option B):

Create desktop actions to launch Steam in different modes:

steam = lib.mkDefault {
  name = "Steam";
  comment = "Steam Client";
  exec = "${lib.getExe osConfig.programs.steam.package}";
  icon = "steam";
  type = "Application";
  terminal = false;
  categories = [ "Game" ];
  mimeType = [
    "x-scheme-handler/steam"
    "x-scheme-handler/steamlink"
  ];
  settings = {
    StartupNotify = "true";
    StartupWMClass = "Steam";
    PrefersNonDefaultGPU = "true";
    X-KDE-RunOnDiscreteGpu = "true";
    Keywords = "gaming;";
  };
  actions = {
    hdr-native = {
      name = "Steam Big Picture (Wayscope Default Profile)";
      exec = "${lib.getExe config.programs.wayscope.wrappers.hdr-native.wrappedPackage}"; # Remember to create the wrappers
    };
    hdr-tonemapped = {
      name = "Steam Big Picture (Wayscope Auto HDR Profile)";
      exec = "${lib.getExe config.programs.wayscope.wrappers.hdr-tonemapped.wrappedPackage}";
    };
  };
};

---

HDR TL;DR

• Want auto-HDR for everything? Use Option B and launch Steam itself through wayscope with the SDL/ITM profile
• Have a native HDR game? Use Option A with a Wayland profile: wayscope run -p hdr-native %command%
• Why not both? Use desktop actions (Option B) for your default mode, and override specific games with launch options (Option A) when needed

Wayscope detects when it's already running inside gamescope and passes through what it can without re-wrapping. This means you don't need to worry about conflicting launch options. However, this doesn't restart gamescope or reapply settings; it uses the existing instance. Don't expect profile or HDR mode changes to take effect on the fly.

License

MIT