Overview

Follow the instructions below to learn how you can debug your game's Windows binaries (running via Proton) on a Steam Deck developer kit. You'll need to bundle the Windows debug runtime with your game when you upload it to your developer kit, and Visual Studio & remote debugging tools running on your Windows development box.

Setup

Be sure to see How to load and run games on Steam Deck to upload and run your game on your developer kit. Make sure to bundle the Windows debug runtime (details below).

Bundling the Windows debug runtime:

The Windows debug runtime is not distributed with Proton. You will need to bundle the debug runtime DLLs with your build. See https://docs.microsoft.com/en-us/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable for details. For Visual Studio, a Debug deploy configuration should work. The project properties has an advanced option to 'Copy c++ Runtime to OutDir' that can be helpful for C++ projects.

Visual Studio remote debugging tools in Proton:

Visual Studio's remote debugging tools are not distributed with Proton. When you upload a title with the Steam Play button checked, the devkit tool will copy the remote debugging tools from your Windows development host to the devkit system.

Currently the devkit will search for the installed debugging tools from Visual Studio 2019 and Visual Studio 2017. In order to have the remote debugging tools available, when you install Visual Studio, be sure to include a development Workload like the "Desktop development with C++"

Usage

Vulkan Examples

The project Vulkan Examples is a good starting point for getting used to remotely debug games uploaded to the Steam Deck devkit.

Clone the project and change the current directory:

The project contains several different small Vulkan samples located in the examples directory. For documentation purposes we will just use imgui. Generate and build the project:

Note: the Cmake build downloads additional assets by running a small script, you will need Python on your build host.

This will create a build/windows/bin/Debug directory that contains the imgui executable, the required Windows debug DLLs and the data assets.

At this point you can upload the resulting Debug directory.

Be sure to select "This title requires Steam Play", because this is not a Linux native build, and also select "Start Visual Studio C++ debugger service on launch" to enable a remote debugger.

If attaching once your game is running is not adequate, and you wish to debug the startup and initialization of your title, use "Wait for a debug client to attach" and see the "early attach" section in this document.



Once the transfer completes, if for example you chose the name vulkan_examples_debug, you should find a new game called Devkit Game: vulkan_examples_debug in the Steam game library.

By launching the game a msvsmon server for remote debugging will automatically start too.



Finally you are now able to attach a debugger to the running game.

In Visual Studio press Ctrl+Alt+P to open the Debug > Attach to Process. In Connection target set the IP and port of the msvsmon server, and then select the imgui.exe process.



For a detailed step-by-step guide you can follow the Microsoft debugging documentation.

Unreal Engine 4 examples

Create an Epic Games account, if you don't have one already, and then download and install the Unreal Engine 4.

As an example we are going to use one of the sample projects that the Unreal Editor offers. Create a new project and choose the "Puzzle" template



Select a project name and a location



Go to Edit->Project settings->Packaging and choose either "Debug" or "DebugGame" as the build configuration. You can find more information in the official documentation. If you tick "Include Debug Files", the debug files will be included in the packaged game.



If you are not able to compile a native Linux build, e.g. if your game has external dependencies that don't support Linux, you can start a Windows build by using File->Package Project->Windows (64-bit). This will create a build in a new directory called "WindowsNoEditor".

Upload your compiled game using the SteamOS Devkit Client.



In the Steam library you should have a new entry with a name similar to Devkit Game: puzzle. By launching the game a msvsmon server for remote debugging will automatically start too.

As the last step you can now attach a debugger to the running game.

In Visual Studio press Ctrl+Alt+P to open the Debug > Attach to Process. In Connection target set the IP and port of the msvsmon server, and then select the puzzle.exe process.

For a detailed step-by-step guide you can follow the Microsoft debugging documentation.

Remote debugging process startup: "early attach" support:

The remote debug service can be configured to wait for the user to attach before launching the title. This allows you to set a breakpoint in WinMain or other initialization code.

This requires that you first install a Microsoft extension in Visual Studio on your development host: https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool



Once the extension is installed, enable child process debugging per the documentation (Debug > Other Debug Targets > Child Process Debugging Settings)

Check "Wait for a debug client to attach" in your devkit tool, and upload your title.

Launch your title normally.

When attaching to the remote process, attach to steam.exe - once you attach, Proton will immediately launch your title as a child process, the extension will kick in and start debugging your title from its startup with your breakpoints activated.