Debugging Games Running Under Proton

These are the steps I've been following to debug games under proton (or rather debug a mod loaded into the game via dll shadowing). It works ok, it's not amazing, but it's the best I've managed to work out.

To start, use a known good build and just get the game running stably. You don't want to be messing with proton options at the same time.

Once the game runs, add PROTON_DUMP_DEBUG_COMMANDS=1 %command% to your launch args, and run it once. This will create a bunch of files in /tmp/proton_$USER/, which dump the entire proton configuration. From here, copy gdb_run to your project folder. After doing this you can remove the launch arg and delete all the other files.

Now this script still doesn't do quite everything we need. Add --no-start --port 2159 to the last line.

-"<path_to_wine>/wine" winedbg --gdb "${@:-${DEF_CMD[@]}}"
+"<path_to_wine>/wine" winedbg --gdb --no-start --port 2159 "${@:-${DEF_CMD[@]}}"

Running it should now start a gdb server attached to the game, paused at it's entry point.

As a final extra, of course make sure you've compiled with gdb debug information - -ggdb3.

Debugging in VSCode

To attach to the server in vscode, add the following launch configuration.

        {
            "name": "proton gbd",
            "type": "cppdbg",
            "request": "launch",
            "program": "<path_to_executable>",
            "stopAtEntry": true,
            "stopAtConnect": false,
            "MIMode": "gdb",
            "miDebuggerPath": "gdb",
            "miDebuggerServerAddress": "localhost:2159",
        },

If you run the script, then start debugging in vscode, it should connect to your local server, inject any breakpoints you've set, and then let the game continue execution.

Once you quit the game, the script will exit. We can automate running it before starting the debugger too. Add the following task:

        {
            "label": "launch proton gdb server",
            "type": "shell",
            "command": "<path to launch script>",
            "hide": true,
            "isBackground": true,
            // Need a dummy problem matcher to prevent the launch configuration waiting for complete
            "problemMatcher": [
                {
                    "pattern": [
                        {
                            "regexp": ".",
                            "file": 1,
                            "location": 2,
                            "message": 3
                        }
                    ],
                    "background": {
                        "activeOnStart": true,
                        "beginsPattern": ".",
                        "endsPattern": ".",
                    }
                }
            ]
        }

Then in your launch configuration, add "preLaunchTask": "launch proton gdb server".

apple1417/proton_debugging.md

Debugging Games Running Under Proton

Debugging in VSCode