快速入門：PlayFab Online Subsystem

本文可協助您為使用 Unreal Engine 4 或 Unreal Engine 5 建置的遊戲，設定及使用 Lobby、Matchmaking 和 Party 等 PlayFab Multiplayer 功能。如需 Unreal Engine 4 或 Unreal Engine 5 中支援之平台和版本的完整清單，請參閱支援的平台。依照本頁針對目標平台概述的相關步驟操作後，您就可以開始使用 PlayFab Online Subsystem (PF OSS)。驗證、網路、VOIP、大廳分組和配對都會替您處理，不需要其他變更。

下載並安裝 PlayFab Online Subsystem

前往 PlayFab Online Subsystem 下載或複製 PF OSS 原始碼。下載或複製的存放庫名稱為 PlayFabMultiplayerUnreal。必須將存放庫重新命名為 OnlineSubsystemPlayFab。

您需要的項目

PlayFab TitleID： 如果您沒有為 PlayFab Party 和 Multiplayer 軟體開發套件 (SDK) 設定的 TitleID，請參閱啟用 PlayFab Party.

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

特定平台的 PlayFab Party 以及 Lobby 和 Matchmaking 程式庫： 請參閱取得 PlayFab Party 和 Multiplayer 程式庫.

初始設定

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

{
    "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 程式碼路徑，以產生遊戲方案檔。

遊戲設定

無論您的目標平台為何，遊戲都需要在預定平台目標的 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"。

[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")

平台專屬考量

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

GDK

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

[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=GDK

Steam

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

[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=Steam

Switch

如需 Switch 的詳細資訊，請參閱 Switch PlayFab OSS 隨附的 ReadMe.md 檔案。如果您沒有存取權，可以要求存取我們的私人存放庫。

PS5™ 和 PS4™

如需 PS5™ 和 PS4™ 的詳細資訊，請參閱 PS5™ 和 PS4™ PlayFab OSS 隨附的 ReadMe.md 檔案。如果您沒有存取權，可以要求存取我們的私人存放庫。

跨平台

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

[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
!CompatibleUniqueNetIdTypes=ClearArray
+CompatibleUniqueNetIdTypes=STEAM
+CompatibleUniqueNetIdTypes=GDK
+CompatibleUniqueNetIdTypes=SWITCH
+CompatibleUniqueNetIdTypes=PS4
+CompatibleUniqueNetIdTypes=PS5

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

[OnlineSubsystemPlayFabVoiceChatDisabledPlatforms]
!Platforms=ClearArray
+Platforms=WIN64
+Platforms=STEAM
+Platforms=SWITCH
+Platforms=PS4
+Platforms=PS5

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

在遊戲程式碼中使用

PlayFab Online Subsystem 僅支援將遊戲工作階段命名為 NAME_GameSession

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

#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 中的範例程式碼：

#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 設為停用：

{
    "Name": "PlayFabParty",
    "Enabled": false
}

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

if (Target.bCompileAgainstEngine)
{
    //PublicDependencyModuleNames.Add("PlayFabParty");
}

如果您使用 Unreal Engine 5.0 - 5.3：

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

"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 設定範例：

"Modules": [
       {
            "Name": "PlayFabParty",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "BlacklistPlatforms": ["WinGDK", "Win64"]
        }
    ],

Steam 上的交握失敗

如果您看到交握失敗 (例如 LogHandshake: IncomingConnectionless: Error reading handshake packet)，請參閱此 Unreal Engine 論壇文章檢查設定。

OnlineSubsystemPlayFab 的工作流程

平台專屬考量一節中概述的步驟要求您包含：

[OnlineSubsystem]
DefaultPlatformService=PlayFab

Unreal Engine OnlineSubsystemModule 會為 PlayFab 建立線上子系統執行個體，並開始建立 PlayFabSingleton。此時，SDK 會在 FOnlineSubsystemPlayFab::Init() 中初始化，並使用 PlayFab TitleID (此 titleID 定義於遊戲設定檔案中) 同時初始化 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. 的註冊商標或商標。

XBOX Services

PlayFab

PlayFab Online Subsystem (OSS) 快速入門

快速入門：PlayFab Online Subsystem

下載並安裝 PlayFab Online Subsystem

您需要的項目

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

初始設定

Unreal Engine 程式碼基底

遊戲程式碼基底

遊戲設定

平台專屬考量

GDK

Steam

Switch

PS5™ 和 PS4™

跨平台

在遊戲程式碼中使用

疑難排解

Unreal Engine 已安裝組建

Steam 上的交握失敗

OnlineSubsystemPlayFab 的工作流程

​快速入門：PlayFab Online Subsystem

​下載並安裝 PlayFab Online Subsystem

​您需要的項目

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

​初始設定

​Unreal Engine 程式碼基底

​遊戲程式碼基底

​遊戲設定

​平台專屬考量

​GDK

​Steam

​Switch

​PS5™ 和 PS4™

​跨平台

​在遊戲程式碼中使用

​疑難排解

​Unreal Engine 已安裝組建

​Steam 上的交握失敗

​OnlineSubsystemPlayFab 的工作流程

快速入門：PlayFab Online Subsystem

下載並安裝 PlayFab Online Subsystem

您需要的項目

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

初始設定

Unreal Engine 程式碼基底

遊戲程式碼基底

遊戲設定

平台專屬考量

GDK

Steam

Switch

PS5™ 和 PS4™

跨平台

在遊戲程式碼中使用

疑難排解

Unreal Engine 已安裝組建

Steam 上的交握失敗

OnlineSubsystemPlayFab 的工作流程