> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GSDK 项目测试和调试

> 使用 LocalMultiplayerAgent 在本地测试和调试您的 Unreal GSDK ThirdPersonMP 多人游戏服务器,并在上传到 PlayFab 之前附加调试器。

# ThirdPersonMP 示例项目本地部署和调试

本指南的目的是演示以符合 MPS 的方式在您的本地计算机上运行游戏服务器,以便您可以在将其上传到 PlayFab 之前测试和调试服务器。

## 目标

* 测试 ThirdPersonMP+GSDK 项目的本地部署选项。
* 使用 LocalMultiplayerAgent 运行时验证您的服务器正确执行
* 验证您可以将调试器附加到您的服务器实例

## 要求

* 下载 Visual Studio。[社区版](https://visualstudio.microsoft.com/vs/community/)是免费的。
  * 所需的工作负载:.NET 桌面开发和使用 C++ 的桌面开发
* 下载 Unreal Engine 源代码。有关说明,请参见[下载 Unreal Engine 源代码(外部)](https://docs.unrealengine.com/ProgrammingAndScripting/ProgrammingWithCPP/DownloadingSourceCode/)。
* 已安装并配置了 [PlayFab Unreal GSDK](/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-gsdk-project-setup) 的[已完成的 Unreal 项目](/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-setup)
* 从 Visual Studio 构建的项目的 ["Development Server"](/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/building-the-third-person-mp-example-project) 配置
* \[可选] 下载 [LocalMultiplayerAgent](https://github.com/PlayFab/MpsAgent/releases)
  * \[可选] 或者,下载 [LocalMultiplayerAgent 源代码](https://github.com/PlayFab/MpsAgent/tree/main/LocalMultiplayerAgent)。
* 使用 Visual Studio 从此仓库构建的 LocalMultiplayerAgent 的 "Debug" 或 "Release" 配置
  * 使用 Visual Studio,打开 [MpsAgent.sln](https://github.com/PlayFab/MpsAgent/blob/main/MpsAgent.sln),选择 Debug 或 Release 配置,然后构建 LocalMultiplayerAgent。
* \[可选] 安装 [Docker for Windows](https://www.docker.com/products/docker-desktop)

## 符号说明

\{depot} 将指代您下载 Git 项目所在位置的完整 windows 路径。这些可以是您喜欢的任何位置,例如:C:\depot、S:\depot、Z:\gitrepos 或您方便的任何驱动器和路径。通常建议(特别是对于 Unreal),您的 \{depot} 路径尽可能短。对于作者来说,\{depot} 解析为:`M:\depot\GSDK`。例如,根据上面的要求列表,您可能会有以下一些或全部内容:

* \{depot}/ThirdPersonMP
* \{depot}/MpsAgent
* \[可选] \{depot}/gsdk \[这包含之前安装到 ThirdPersonMP 中的 PlayFab Unreal GSDK 插件]
* \[可选] \{depot}/UnrealMarketplacePlugin \[这包含 PlayFab Unreal Marketplace 插件,本指南不需要它,但大多数 PlayFab 功能都需要它]

不要求您将所有这些都放在同一位置,但这样做很可能有用,并且为了组织起见,本指南鼓励您这样做。

## 说明

### 本地执行,无容器

首先,您需要配置 LocalMultiplayerAgent 以执行您的服务器项目。第一次迭代直接在您的本地 PC 上运行进程,没有任何隔离。

在资源管理器中,找到并打开文件:`{depot}\MpsAgent\LocalMultiplayerAgent\MultiplayerSettings.json`。此文件的简化版本(包含对本指南很重要的部分)如下 \[请注意 json 中路径的转义 \ - 这是一个 json 文件,因此必须将所有 \ 转义为 \\]:

```json theme={null}
{
  "RunContainer": false,
  "OutputFolder": "<Local absolute path that will be used to store the required output artifacts>",
  ...
  "AssetDetails": [
    {
      "MountPath": "C:\\Assets",
      "LocalFilePath": "{PATH-TO-ZIP}"
    }
  ],
  ...
  "PortMappingsList": [
    [
      {
        "NodePort": 30000,
        "GamePort": {
          "Name": "gameport",
          "Number": 8888,
          "Protocol": "UDP"
        }
      }
    ]
  ],
  "ProcessStartParameters": {
    "StartGameCommand": "{PATH-TO-EXE} -log"
  },
  "ContainerStartParameters": {
    "StartGameCommand": "C:\\Assets\\ThirdPersonMPServer.exe -log",
    ...
  }
}
```

出于本指南的目的,上面被 `...` 隐藏的 json 文件部分只使用项目默认值。重要字段的用途和值如下:

* RunContainer:对于本指南,这将始终为 false。将其设置为 true 需要 Docker。
  * 当为 true 时,ProcessStartParameters/StartGameCommand 将被忽略,而使用 ContainerStartParameters/StartGameCommand
  * 当为 true 时,所有内容都在 docker 容器中构建和运行,而不是在本地机器上下文中
  * 本指南涵盖 RunContainer 为 false 的场景,以便我们能够更轻松地调试服务器进程
  * 将其设置为 true 需要 Shipping Server 构建,以及额外的 [Docker for Windows](https://www.docker.com/products/docker-desktop)
* OutputFolder:`"<Local absolute path that will be used to store the required output artifacts>"`
  * 此位置必须完全定义,并且在此位置必须存在有效目录。
* AssetDetails/LocalFilePath:\{PATH-TO-ZIP}
  * 此位置必须完全定义,并且此位置必须存在有效的 zip 文件
  * 此 zip 文件应包含完全构建的 "Shipping Server" 构建
* PortMappingsList:
  * 这是 Game Manager 中定义端口的 LocalMultiplayerAgent 等效项
  * GSDK 插件被硬编码为查找名为 gameport 的端口
  * GSDK 插件的 [SetDefaultServerHostPort](https://github.com/PlayFab/gsdk/blob/master/UnrealPlugin/Source/PlayfabGSDK/Private/GSDKUtils.cpp#L147) 方法将在内部覆盖内部 Unreal 服务器托管端口以匹配此端口
  * 使用 LocalMultiplayerAgent 时,GSDK 插件将\_仅\_使用 **PortMappingsList** 中配置的名为 **gameport** 的端口。
  * 此 json 可让您本地测试从 MPS 驱动此端口号,并确保您的 GSDK 插件将正确接收它
* ContainerStartParameters/StartGameCommand:当 RunContainer 为 false 时,不使用此项。
  * 当 RunContainer==true 时,它将取代 ProcessStartParameters/StartGameCommand
  * 此路径是 docker 容器内的内部路径,将是 AssetDetails/MountPath 加上由 AssetDetails/LocalFilePath 定义的 zip 文件内 exe 的内部路径之和
  * 对于此示例,这可能是:`C:\\Assets\\ThirdPersonMPServer.exe -log`
* ProcessStartParameters/StartGameCommand:此命令实际上是到您的 exe 的路径,以及用于启动您的游戏服务器的任何命令行参数
  * -log 是一个 Unreal 命令,用于指示游戏服务器保存执行日志
  * \{PATH-TO-EXE} 可以是两种选择之一:
    * 到您游戏服务器 exe 的任何绝对路径(甚至是开发游戏服务器),以及您服务器的任何命令行参数
      * 此选择会忽略 zip 文件的内容,而是执行任何位置的任意 exe
      * 这是一个本地调试选项,仅适用于您的本地机器以调试开发构建:它不会帮助您验证您的 zip 文件是否已准备好上传到 MPS
      * 测试开发服务器时应使用此选择,适合附加 VS 调试器
      * 对于此示例,这可能是:`{depot}\\ThirdPersonMP\\Binaries\\Win64\\ThirdPersonMPServer.exe -log`
      * 对于作者,这是:`M:\\depot\\GSDK\\ThirdPersonMPGSDK\\Binaries\\Win64\\ThirdPersonMPServer.exe -log`
    * 相对路径,应指示进入您 zip 文件的相对路径,以运行您的服务器
      * 这是反映 MPS 云实例上运行方式的标准工作流程
      * 测试 shipping 服务器时应使用此选择,并有助于验证您的 zip 是否已准备好上传到 MPS
      * 对于此示例,这可能是:`ThirdPersonMPServer.exe -log`

创建 zip 文件并将所有这些行设置为适当的值后,您可以重新构建 LocalMultiplayerAgent,并准备调试您的服务器。

### 调试您的服务器

您可以使用 "Start New Instance" 命令(有时绑定到 F5)从 Visual Studio 运行 LocalMultiplayerAgent,或者您可以导航到 `{depot}\LocalMultiplayerAgent\bin\{configuration}\netcoreapp3.1` 并双击 "LocalMultiplayerAgent.exe"。您也可以在 cmd 窗口内运行它以观察或捕获调试日志信息。

运行 LocalMultiplayerAgent.exe 应会启动您的游戏服务器。您通常会希望为此打开任务管理器。您可以在任务管理器的 Details 选项卡中找到您的游戏服务器进程 ID。

一旦您在任务管理器中看到您的 ThirdPersonMPServer 进程运行,您就可以返回 Visual Studio,选择 Debug 下拉菜单 -> Attach to Process。从弹出窗口中,您可以搜索您的进程名称:ThirdPersonMPServer,然后选择从任务管理器识别的正确进程 ID。

此时,您应该能够对游戏服务器执行典型的调试。

注意:Unreal 提供了多种构建配置和多种构建服务器的方式。为获得最佳结果,请使用 "Development Server" 配置,并直接从 Visual Studio 构建。Shipping 构建或来自 Development Editor 的构建可能在其他情况下效果更好,但直接从 Visual Studio 构建的 "Development Server" 配置将更易于在 Visual Studio 中附加和调试。

## 故障排除

### 任务管理器中有许多 ThirdPersonMPServer 实例

如果列出了多个实例(通常为 3 个或更多),您可能需要使用任务管理器强制关闭从先前尝试中残留的实例。

### LocalMultiplayerAgent 启动两个 ThirdPersonMPServer 实例

如果您的 LocalMultiplayerAgent \_启动\_多个实例,请查找具有相对较高内存使用的进程 ID。游戏服务器的某些配置会生成两个可执行文件,它们成对运行。您需要附加到具有较高内存使用的那个。

## 后续步骤

您现在已经准备好[将您的服务器部署到云中](/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-cloud-deployment)。

或者,您可以返回到主要的 [Unreal GSDK 插件](/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk#deploy-to-playfab)指南。


## Related topics

- [GSDK 项目云部署](/zh-CN/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-cloud-deployment.md)
- [使用 Azure Functions 的 Cloudscript 本地调试](/zh-CN/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/local-debugging-for-cloudscript-using-azure-functions.md)
- [仅通过向后兼容支持的跨世代游戏](/zh-CN/build/console-features/cross-gen/cross-gen-backcompat-only.md)
- [构建您的 Unreal 示例项目](/zh-CN/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/building-the-third-person-mp-example-project.md)
- [在 Visual Studio 中远程调试 Windows 设备上的 PC 项目](/zh-CN/tools/tools-pc/visualstudio/gr-vs-debugging-with-visualstudio-remote-windows.md)