Steamworks 文献库
如何在 Steam Deck 上调试 Windows 游戏

概览

请遵循以下说明以了解如何在 Steam Deck 开发者套件上调试游戏的 Windows 二进制文件(通过 Proton 运行)。 当您将游戏上传到开发者套件上时,您需要将 Windows 调试运行时与您的游戏绑定到一起,并且在您的 Windows 开发环境中运行 Visual Studio 及远程调试工具。
此功能仍然正在开发中。 请在 Steam Deck 开发者论坛留下您的反馈或问题。
注意:远程调试功能仅在 Proton - Exprimental 发行版本中有效。

设置

请确保阅读如何在 Steam Deck 上加载并运行游戏,以在开发者套件上上传并运行您的游戏。 请确保绑定 Windows 调试运行时(详情见下方)。

绑定 Windows 调试运行时:

Proton 本身并不带有 Windows 调试运行时。 您需要将调试运行时 DLL 和您的生成版本绑定在一起。 请查看 https://docs.microsoft.com/zh-cn/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable?view=msvc-160,获取详细信息。 对 Visual Studio 来说,进行调试部署配置应该就可以了。 项目属性中有一个高级选项,“将 C++ 运行时复制到 OutDir”(Copy c++ Runtime to OutDir),对 C++ 项目来说会很有帮助。

Pronton 中的 Visual Studio 远程调试工具:

Proton 本身并不带有 Visual Studio 远程调试工具。 如果您在上传游戏时勾选了“Steam Play”按钮,开发者套件工具会将您 Windows 开发主机中的远程调试工具复制至开发者套件系统。

当前,开发者套件将会在 Visual Studio 2019 和 Visual Studio 2017 中搜索已安装的调试工具。 为了使远程调试工具可用,当您安装 Visual Studio 时,请确保包含一个开发工作负载,例如“Desktop development with C++”(使用 C++ 的桌面开发)。

VirtualBox_Win_10_05_08_2021_18_05_44.png

用法

Vulkan 示例

Vulkan Examples(Vulkan 示例)项目就是一个很好的出发点,让您慢慢习惯远程调试上传至 Steam Deck 开发者套件的游戏。

复制该项目并更改当前目录:
git clone --recursive https://gitlab.steamos.cloud/jupiter/vulkan-examples.git cd vulkan-examples

此项目中包含数个不同的小型 Vulkan 示例,这些示例位于示例目录中。 在本文档中,我们将仅使用 imgui。 生成并创建项目:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows cmake --build build/windows --config Debug --target imgui

注意:Cmake 生成版本会通过运行一个小型脚本下载额外的资产,您的生成版本主机上需要有 Python 才行。

这将创建一个 build/windows/bin/Debug 目录,其中包含 imgui 可执行文件、所需的 Windows 调试 DLL 和数据资产。

此时,您可以上传生成的 Debug 目录。

请务必选择“This title requires Steam Play”(此游戏需要 Steam Play),因为这不是 Linux 原生的生成版本,同时也请选择“Start Visual Studio C++ debugger service on launch”(在启动时开启 Visual Studio C++ 调试器服务)以启用远程调试器。

如果在您游戏运行时附加调试器还不够,且您想要调试游戏的启动和初始化,请选则“Wait for a debug client to attach”(等待调试客户端附加),并查看此文档中的“前期附加”部分。

devkit-tool-remote-debug-20211207.png

传输完成后,假设您选择了名称 vulkan_examples_debug,您应该会在 Steam 游戏库中找到一个名为 Devkit Game: vulkan_examples_debug 的新游戏。

启动游戏后,用于远程调试的 msvsmon 服务器也会自动启动。

Screenshot_from_2021-07-14_10-05-21.png

现在,您可以将调试器附加到正在运行的游戏了。

在 Visual Studio 中,按 Ctrl+Alt+P, 打开 Debug(调试)> Attach to Process(附加到进程)。 在 Conncection target(连接目标)中设置 msvsmon 服务器的 IP 和端口,然后选择 imgui.exe 进程。

Screenshot_2021-07-26_092207.png

您可以参见微软调试文档,获取详细的分步指南。

虚幻引擎 4 示例

如果您还没有创建 Epic Games 帐户,请创建,然后 下载并安装虚幻引擎 4。

作为示例,我们将使用虚幻编辑器提供的样本项目之一。 创建一个新项目并选择“Puzzle”模板。

Screenshot_2021-07-16_072803.png

选择项目名称及位置。

Screenshot_2021-07-15_082533.png

转到 Edit(编辑)-> Project settings(项目设置)-> Packaging(打包), 并选择 “Debug”(调试)或“DebugGame”(调试游戏)作为编译配置(build configuration)。 您可以在官方文档中找到更多信息。 如果您勾选“Include Debug Files(包含调试文件)”,则调试文件将包含在打包游戏中。

Screenshot_2021-07-16_073647.png

如果您无法编译原生 Linux 生成版本,比如,您的游戏具有不支持 Linux 的外部依赖项,您可以使用 File(文件)-> Package Project(打包项目)-> Windows (64-bit) 新建一个 Windows 生成版本。 这将在名为“WindowsNoEditor”的新目录中创建一个生成版本。

使用 SteamOS Devkit Client(SteamOS 开发者套件客户端)上传您编译好的游戏。

Screenshot_2021-07-16_074524.png

在 Steam 库中,应该会有一个名称类似于 Devkit Game: puzzle 的新条目。 启动游戏后,用于远程调试的 msvsmon 服务器也会自动启动。

最后,您现在可以将调试器附加到正在运行的游戏上了。

在 Visual Studio 中,按 Ctrl+Alt+P, 打开 Debug(调试)> Attach to Process(附加到进程)。 在 Conncection target(连接目标)中设置 msvsmon 服务器的 IP 和端口,然后选择 puzzle.exe 进程。

您可以参见微软调试文档,获取详细的分步指南。

远程调试流程启动:“前期附加”支持:


您可以配置远程调试服务,使其在启动游戏前等待用户附加。 这让您可以在 WinMain 或其他初始化代码中设置一个断点。

您需要首先在您的开发主机上为 Visual Studio 安装一个微软扩展:https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool

child-process-debug-extension.png

扩展安装完成后,按照文档中的说明启用子进程调试(child process debugging)(Debug(调试) > Other Debug Targets(其他调试目标) > Child Process Debugging Settings(子进程调试设置))

在开发者套件工具中选择“Wait for a debug client to attach”(等待调试客户端附加),并上传您的游戏。

像平常一样启动您的游戏。

在附加至远程流程时,请附加至 steam.exe;附加后,Proton 会立即将您的游戏作为子流程启动,扩展会生效并从您的作品启动时开始调试,您的断点也会处于激活状态。