> ## 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.

# PlayFab Online Subsystem (OSS) 快速入門

> Unreal Engine 中 PlayFab Online Subsystem 的快速入門，涵蓋使用 Multiplayer SDK 設定 Party 語音聊天、大廳和配對。

# 快速入門：PlayFab Online Subsystem

本文可協助您為使用 Unreal Engine 4 或 Unreal Engine 5 建置的遊戲，設定及使用 Lobby、Matchmaking 和 Party 等 PlayFab Multiplayer 功能。如需 Unreal Engine 4 或 Unreal Engine 5 中支援之平台和版本的完整清單，請參閱[支援的平台](/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-overview)。

依照本頁針對目標平台概述的相關步驟操作後，您就可以開始使用 PlayFab Online Subsystem (PF OSS)。驗證、網路、VOIP、大廳分組和配對都會替您處理，不需要其他變更。

## 下載並安裝 PlayFab Online Subsystem

前往 [PlayFab Online Subsystem](https://github.com/PlayFab/PlayFabMultiplayerUnreal) 下載或複製 PF OSS 原始碼。下載或複製的存放庫名稱為 PlayFabMultiplayerUnreal。必須將存放庫重新命名為 OnlineSubsystemPlayFab。

## 您需要的項目

* **PlayFab TitleID：** 如果您沒有為 PlayFab Party 和 Multiplayer 軟體開發套件 (SDK) 設定的 TitleID，請參閱[啟用 PlayFab Party](/zh-TW/services/playfab/multiplayer/networking/enable-party).

### Microsoft Game Development Kit (GDK)、PC、Switch、PlayStation®5 和 PlayStation®4

* **特定平台的 PlayFab Party 以及 Lobby 和 Matchmaking 程式庫：** 請參閱[取得 PlayFab Party 和 Multiplayer 程式庫](/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-obtaining-playfab-party-libraries).

## 初始設定

### Unreal Engine 程式碼基底

* 將 OnlineSubsystemPlayFab 資料夾及其內容複製到 Unreal Engine 目錄下的 **Engine\Plugins\Online**。
* 執行 `GenerateProjectFiles.bat` 以建立引擎的專案檔。
* 選取新的 `UE5.sln` 檔案，將專案載入 Visual Studio。
* 將方案組態設為 **Development Editor**，並將方案平台設為 **Win64**。選取 **Unreal Engine 5** 目標，然後選取 **Build**。

### 遊戲程式碼基底

* 若要將 OnlineSubsystemPlayFab 新增至外掛程式清單，請對專案檔的 Plugins 區段套用下列變更。
  * 移除您不會推出的任何平台
  * 如果您使用 Unreal Engine 4，請使用 XboxOneGDK 而非 XB1。Unreal Engine 5 已淘汰 XboxOneGDK

```json theme={null}
{
    "Name": "OnlineSubsystemPlayFab",
    "Enabled": true,
    "PlatformAllowList": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ],
    "SupportedTargetPlatforms": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ]
}
```

* 選取 `{ProjectName}.uproject` 檔案，然後選取 **Switch Unreal Engine Version** 並切換至 Unreal Engine 程式碼路徑，以產生遊戲方案檔。

<a id="game-configuration" />

## 遊戲設定

* 無論您的目標平台為何，遊戲都需要在預定平台目標的 INI 檔案 (位於 \[yourGameDirectory]/Platforms/\[yourPlatform]/Config) 中設定某些 PlayFab 專屬值。
  * **XBOX Series X GDK:** XSXEngine.ini
  * **PC GDK:** WinGDKEngine.ini
  * **XBOX One GDK:** XB1Engine.ini (如果您使用 Unreal Engine 4，則為 XboxOneGDKEngine.ini)
  * **PC Steam:** WindowsEngine.ini (或在 \[yourGameDirectory]/Config/Windows 中尋找)
  * **Nintendo Switch** SwitchEngine.ini
  * **PS4™** PS4Engine.ini
  * **PS5™** PS5Engine.ini
* 如果設定中已存在 INI 區段 (例如 Engine.GameEngine)，請以下列各節中提供的區段取代。
* 請確定已將所有 *\<REPLACE ME>* 欄位取代為您的資料：
* 在 UE 5.6 及更新版本上，`DriverClassName` 參數需要 "/Script/" 前置詞。例如，使用 `"/Script/OnlineSubsystemPlayFab.PlayFabNetDriver"` 而非 `"OnlineSubsystemPlayFab.PlayFabNetDriver"`。

```ini theme={null}
[OnlineSubsystemPlayFab]
bEnabled=true
PlayFabTitleID=<REPLACE ME with your PlayFab title ID>
MaxDeviceCount=<REPLACE ME with your max player count (note: split screen is still 1 device). In the example of an 8 player game, this would be 8.>
MaxDevicesPerUserCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device) In the example of an 8 player game, this would be 1.>
MaxEndpointsPerDeviceCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device)  In the example of an 8 player game, this would be 1.>
MaxUserCount=<REPLACE ME with your max player count (note: split screen is still 1 device)  In the example of an 8 player game, this would be 8.>
MaxUsersPerDeviceCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device)  In the example of an 8 player game, this would be 1.>
DirectPeerConnectivityOptions=<REPLACE ME with your connectivity options, in the form of an array of strings. The default case corresponds to the following:
+DirectPeerConnectivityOptions=AnyPlatformType
+DirectPeerConnectivityOptions=AnyEntityLoginProvider.
If you want to disable P2P and use cloud relay instead, set DirectPeerConnectivityOptions=None>
bHasPlayFabVoiceEnabled=<REPLACE ME with true/false>

[/Script/OnlineSubsystemPlayFab.PlayFabNetDriver]
NetConnectionClassName="OnlineSubsystemPlayFab.PlayFabNetConnection"
ReplicationDriverClassName="<REPLACE ME with your existing replication driver class name>" . Skip if the game doesn't have a replication driver class (https://docs.unrealengine.com/5.2/en-US/replication-graph-in-unreal-engine/).
ConnectionTimeout=15.0
InitialConnectTimeout=30.0

[/Script/Engine.GameEngine]
!NetDriverDefinitions=ClearArray
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/OnlineSubsystemPlayFab.PlayFabNetDriver",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")
```

<a id="platform-specific-considerations" />

## 平台專屬考量

完成上述所有步驟後，就快大功告成了。只剩下幾個必須設定的重要平台專屬參數。

### GDK

使用 GDK 開發遊戲時，請設定平台服務。

```ini theme={null}
[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=GDK
```

### Steam

如果您要使用 Steam 開發 Win64 遊戲，請定義您的平台服務。

```ini theme={null}
[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=Steam
```

### Switch

如需 Switch 的詳細資訊，請參閱 Switch PlayFab OSS 隨附的 [ReadMe.md](https://dev.azure.com/PlayFabPrivate/Switch/_git/PlayFabMultiplayerUnrealSwitch?path=/README.md) 檔案。如果您沒有存取權，可以[要求存取](/zh-TW/services/playfab/sdks/request-access-for-sdks-samples)我們的私人存放庫。

### PS5™ 和 PS4™

如需 PS5™ 和 PS4™ 的詳細資訊，請參閱 PS5™ 和 PS4™ PlayFab OSS 隨附的 [ReadMe.md](https://dev.azure.com/PlayFabPrivate/PS5/_git/PlayFabMultiplayerUnrealPlayStation?path=/README.md) 檔案。如果您沒有存取權，可以[要求存取](/zh-TW/services/playfab/sdks/request-access-for-sdks-samples)我們的私人存放庫。

### 跨平台

如果您的遊戲使用 PlayFab 的跨平台網路支援，請定義您允許連線的平台。

```ini theme={null}
[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
!CompatibleUniqueNetIdTypes=ClearArray
+CompatibleUniqueNetIdTypes=STEAM
+CompatibleUniqueNetIdTypes=GDK
+CompatibleUniqueNetIdTypes=SWITCH
+CompatibleUniqueNetIdTypes=PS4
+CompatibleUniqueNetIdTypes=PS5
```

根據預設，所有平台都允許 VoIP。若要為特定平台停用 VoIP，請如下列範例所示，將平台型號名稱新增至 Unreal Engine 設定檔。

```ini theme={null}
[OnlineSubsystemPlayFabVoiceChatDisabledPlatforms]
!Platforms=ClearArray
+Platforms=WIN64
+Platforms=STEAM
+Platforms=SWITCH
+Platforms=PS4
+Platforms=PS5
```

這些步驟完成了在遊戲中使用 OSS 所需的設定。

## 在遊戲程式碼中使用

<Note>
  PlayFab Online Subsystem 僅支援將遊戲工作階段命名為 `NAME_GameSession`
</Note>

與使用其他 Online Subsystem 外掛程式類似：

在 Game.Build.cs 中新增 `PublicDependencyModuleNames.AddRange(new string[] { "OnlineSubsystem", "OnlineSubsystemUtils" });`，然後以與其他遊戲外掛程式相同的方式使用它。

GameSession.cpp 中的範例程式碼：

```cpp theme={null}
#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"

...

bool Game::JoinSession(const FUniqueNetIdPtr UserId, FName SessionName, const FOnlineSessionSearchResult& SearchResult)
{

    IOnlineSubsystem* OnlineSub = Online::GetSubsystem(GetWorld()); // Using OnlineSubsystemPlayFab plugin
    if (OnlineSub)
    {
        IOnlineSessionPtr Sessions = OnlineSub->GetSessionInterface(); // Using OnlineSessionInterfacePlayFab.h
        if (Sessions.IsValid() && UserId.IsValid())
        {
            // ...
        }
    }
    // ...
}
```

GameFriends.cpp 中的範例程式碼：

```cpp theme={null}
#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"

...

void Game::ViewFriendProfile()
{
    IOnlineSubsystem* OnlineSub = Online::GetSubsystem(GetWorld()); // Using OnlineSubsystemPlayFab plugin
    if (OnlineSub)
    {
        IOnlineIdentityPtr Identity = OnlineSub->GetIdentityInterface(); // Using OnlineIdentityInterfacePlayFab.h
        if (Identity.IsValid() && Friends.IsValidIndex(FriendIndex))
        {
            // ....
        }
    }
}
```

## 疑難排解

協助您針對問題進行疑難排解的方式。

### Unreal Engine 已安裝組建

使用者嘗試在 GDK 組建版本上使用 OnlineSubsystemPlayFab 建立 Unreal Engine 已安裝組建時，可能會遇到問題。在有更完整的解決方案之前，我們提供下列指引，協助您順利克服此問題。

**如果您使用 Unreal Engine 5.4、5.5、5.6 或 5.7：**

* 您可能會遇到下列執行階段錯誤：`Runtime dependency Party.dll is configured to be staged from C:\Program Files (x86)\Microsoft GDK\<version>\Party.dll and Engine\Plugins\Online\OnlineSubsystemPlayFab\Platforms\GDK\Redist\Party.dll`
* 瀏覽至 Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\\
* 開啟 OnlineSubsystemGDK.uplugin，並將 `PlayFabParty` 設為停用：

```json theme={null}
{
    "Name": "PlayFabParty",
    "Enabled": false
}
```

* 瀏覽至 Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\Source\\
* 開啟 OnlineSubsystemGDK.Build.cs，並將包含 `PlayFabParty` 的程式碼註解化：

```csharp theme={null}
if (Target.bCompileAgainstEngine)
{
    //PublicDependencyModuleNames.Add("PlayFabParty");
}
```

**如果您使用 Unreal Engine 5.0 - 5.3：**

* 找到電腦上安裝 Unreal Engine 的目錄。
* 瀏覽至 Engine\Platforms\GDK\Plugins\Online\PlayFabParty
* 開啟 PlayFabParty.uplugin，並使用 **PlatformDenyList** 更新 Modules 設定：

```ini theme={null}
"Modules": [
        {
            "Name": "PlayFabParty",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "HasExplicitPlatforms": true,
            "PlatformDenyList": [ "WinGDK", "Win64" ]
        }
    ],
```

* 如果已安裝組建需要 XB1 (PlayFabParty\_XB1.uplugin) 和 XSX (PlayFabParty\_XSX.uplugin) 平台，請為這些平台重複此程序。如果已安裝組建也需要 Win64 平台，請在 **PlatformDenyList** 陣列中新增 Win64。

**如果您使用 Unreal Engine 4.27+：**

* 找到電腦上安裝 Unreal Engine 的目錄。
* 瀏覽至 Engine\Platforms\GDK\Plugins\Online\PlayFabParty
* 開啟 PlayFabParty.uplugin
* 將索引鍵 **WhitelistPlatforms** 取代為 **BlacklistPlatforms**
* 如果已安裝組建需要 XboxOneGDK (PlayFabParty\_XboxOneGDK.uplugin) 和 XSX (PlayFabParty\_XSX.uplugin) 平台，請為這些平台重複此程序。如果已安裝組建也需要 Win64 平台，請在 **BlacklistPlatforms** 陣列中新增 Win64。

Unreal Engine 4.27+ 的 PlayFabParty.uplugin 中的 Modules 設定範例：

```ini theme={null}
"Modules": [
       {
            "Name": "PlayFabParty",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "BlacklistPlatforms": ["WinGDK", "Win64"]
        }
    ],
```

### Steam 上的交握失敗

如果您看到交握失敗 (例如 `LogHandshake: IncomingConnectionless: Error reading handshake packet`)，請參閱此 [Unreal Engine 論壇文章](https://forums.unrealengine.com/t/ue-5-1-steam-sockets-problem/696726)檢查設定。

## OnlineSubsystemPlayFab 的工作流程

[平台專屬考量](#platform-specific-considerations)一節中概述的步驟要求您包含：

```ini theme={null}
[OnlineSubsystem]
DefaultPlatformService=PlayFab
```

Unreal Engine OnlineSubsystemModule 會為 PlayFab 建立線上子系統執行個體，並開始建立 PlayFabSingleton。此時，SDK 會在 `FOnlineSubsystemPlayFab::Init()` 中初始化，
並使用 PlayFab TitleID (此 titleID 定義於[遊戲設定](#game-configuration)檔案中) 同時初始化 Party 和 Multiplayer SDK。在初始化期間，我們會 `CreatePlayFabSocketSubsystem()` 作為主要的線上子系統。

Multiplayer SDK 的工作流程：`FOnlineSubsystemPlayFab::Init()` 會為您的遊戲初始化 `InitializeMultiplayer()` 多人遊戲 SDK 單一執行個體。在 `PlayFabLobby.cpp` 中，`FPlayFabLobby::DoWork()` 會處理 Multiplayer API 觸發的狀態變更 (如需 API，請檢視 `Platforms/GDK/Include/PFLobby.h`)。

Party SDK 的工作流程：`FOnlineSubsystemPlayFab::Init()` 會為您的遊戲初始化 `InitializeParty()` 多人遊戲 SDK 單一執行個體。在 `OnlineSubsystemPlayFab.cpp` 中，`FOnlineSubsystemPlayFab::DoWork()` 會處理 Party API 觸發的狀態變更 (如需 API，請檢視 `Platforms/GDK/Include/Party.h`)。

「PlayStation」是 Sony Interactive Entertainment Inc. 的註冊商標或商標。

「PS4」是 Sony Interactive Entertainment Inc. 的註冊商標或商標。

「PS5」是 Sony Interactive Entertainment Inc. 的註冊商標或商標。


## Related topics

- [適用於 Unreal Engine 的 PlayFab OnlineSubsystem 版本資訊](/zh-TW/services/playfab/multiplayer/networking/unreal-release-notes.md)
- [PlayFab Online Subsystem (OSS) 專用伺服器設定](/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-dedicated-servers.md)
- [整合 PlayFab Unreal Engine Marketplace 外掛程式](/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-playfab-plugin-integration.md)
- [適用於 Unreal 的 Azure PlayFab Party Online Subsystem](/zh-TW/build/console-features/networking/game-mesh/party-unreal-online-subsystem.md)
- [PlayFab Online Subsystem (OSS)](/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-overview.md)