> ## 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 專案測試和偵錯

> 在上傳至 PlayFab 之前，使用 LocalMultiplayerAgent 在本機測試和偵錯您的 Unreal GSDK ThirdPersonMP 多人遊戲伺服器，並附加偵錯工具。

# ThirdPersonMP 範例專案本機部署和偵錯

本指南的目的是示範如何以符合 MPS 的方式在本機電腦上執行遊戲伺服器，讓您可以在將伺服器上傳至 PlayFab 之前進行測試和偵錯。

## 目標

* 測試 ThirdPersonMP+GSDK 專案的本機部署選項。
* 確認您的伺服器在使用 LocalMultiplayerAgent 執行時能正確執行
* 確認您可以將偵錯工具附加至您的伺服器執行個體

## 需求

* 下載 Visual Studio。[Community 版本](https://visualstudio.microsoft.com/vs/community/)是免費的。
  * 必要的工作負載：.NET 桌面開發和使用 C++ 的桌面開發
* 下載 Unreal Engine 原始程式碼。如需指示，請參閱[下載 Unreal Engine 原始程式碼 (外部)](https://docs.unrealengine.com/ProgrammingAndScripting/ProgrammingWithCPP/DownloadingSourceCode/)。
* 已安裝並設定 [PlayFab Unreal GSDK](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-gsdk-project-setup) 的[已完成 Unreal 專案](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-setup)
* 從 Visual Studio 建置之專案的 ["Development Server"](/zh-TW/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。
* \[選用] 安裝 [Windows 版 Docker](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 以執行您的伺服器專案。第一次反覆項目會直接在本機電腦上執行處理序，不進行任何隔離。

在檔案總管中，找到並開啟檔案：`{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 需要發行伺服器組建，以及額外的 [Windows 版 Docker](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 伺服器裝載連接埠，使其與此連接埠相符
  * GSDK 外掛程式\_只會\_使用名為 **gameport** 的連接埠，使用 LocalMultiplayerAgent 時，此連接埠是在 **PortMappingsList** 中設定的。
  * 此 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 雲端執行個體運作方式的標準工作流程
      * 測試發行伺服器時應使用此選擇，有助於驗證您的 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 索引標籤中找到遊戲伺服器處理序識別碼。

在工作管理員中看到 ThirdPersonMPServer 處理序正在執行後，您可以返回 Visual Studio，選取 Debug 下拉式清單 -> Attach to Process。在快顯視窗中，您可以搜尋處理序名稱：ThirdPersonMPServer，然後選取從工作管理員中識別出的正確處理序識別碼。

此時，您應該能夠對遊戲伺服器執行一般的偵錯。

注意：Unreal 提供多種組建設定和多種建置伺服器的方式。為了獲得最佳結果，請使用直接從 Visual Studio 建置的 "Development Server" 設定和輸出。發行組建或來自 Development Editor 的組建在其他情況下可能效果更好，但直接從 Visual Studio 建置的 "Development Server" 設定在 Visual Studio 中更容易附加和偵錯。

## 疑難排解

### 工作管理員中有許多 ThirdPersonMPServer 執行個體

如果列出多個執行個體 (通常 3 個以上)，您可能需要使用工作管理員強制關閉先前嘗試遺留下來的執行個體。

### LocalMultiplayerAgent 啟動兩個 ThirdPersonMPServer 執行個體

如果您的 LocalMultiplayerAgent \_啟動\_多個執行個體，請尋找記憶體使用量相對較高的處理序識別碼。遊戲伺服器的某些設定會產生兩個可執行檔，以配對方式執行。您會想要附加至記憶體使用量較高的那一個。

## 後續步驟

您現在已準備好將[您的伺服器部署至雲端](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-cloud-deployment)。

或者，您可以返回主要的 [Unreal GSDK 外掛程式](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk#deploy-to-playfab)指南。


## Related topics

- [GSDK 專案雲端部署](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-project-cloud-deployment.md)
- [使用 Azure Functions 的 Cloudscript 本機偵錯](/zh-TW/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/local-debugging-for-cloudscript-using-azure-functions.md)
- [僅透過回溯相容性進行跨世代遊戲](/zh-TW/build/console-features/cross-gen/cross-gen-backcompat-only.md)
- [建置您的 Unreal 範例專案](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/building-the-third-person-mp-example-project.md)
- [GSDK 專案設定](/zh-TW/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/third-person-mp-example-gsdk-project-setup.md)