快速入门：PlayFab Online 子系统

2025-06-12

本文可帮助你为使用 Unreal Engine 4 或 Unreal Engine 5 构建的游戏设置和使用 Azure PlayFab 多人游戏功能，例如大厅、匹配和群。有关 Unreal Engine 4 或 Unreal Engine 5 中支持的平台和版本的完整列表，请参阅支持的平台。

按照本页中针对目标平台概述的相关步骤作后，即可开始使用 PlayFab Online 子系统 (PF OSS) 。身份验证、网络、VOIP、分组到大厅和匹配均代表你进行处理，无需进行其他更改。

下载并安装 PlayFab Online 子系统

转到 PlayFab Online 子系统以下载或克隆 PF OSS 源。下载或克隆的存储库名称为 PlayFabMultiplayerUnreal。存储库必须重命名为 OnlineSubsystemPlayFab。

你所需要的有

PlayFab TitleID： 如果没有为 PlayFab Party 和多人游戏软件开发工具包配置 TitleID， (SDK) ，请参阅启用 PlayFab Party。

Microsoft游戏开发工具包 (GDK) 、电脑、交换机、PlayStation®5 和 PlayStation®4

特定平台 PlayFab Party、大厅和匹配库：请参阅获取 PlayFab Party 和多人游戏库。

初始设置

Unreal Engine 代码库

将 OnlineSubsystemPlayFab 文件夹及其内容复制到 Engine\Plugins\Online 下的 Unreal Engine 目录。
运行 GenerateProjectFiles.bat 以创建引擎的项目文件。
通过选择新 UE5.sln 文件将项目加载到 Visual Studio 中。
将解决方案配置设置为开发编辑器并将解决方案平台设置为 Win64。选择Unreal Engine 5 目标，然后选择“生成”。

游戏代码库

若要将 OnlineSubsystemPlayFab 添加到插件列表，请对项目文件的“插件”部分应用以下更改。
- 删除未寄送的任何平台
- 如果使用 Unreal Engine 4，请使用 XboxOneGDK 而不是 XB1。 Unreal Engine 5 个弃用 XboxOneGDK

{
    "Name": "OnlineSubsystemPlayFab",
    "Enabled": true,
    "WhitelistPlatforms": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ],
    "SupportedTargetPlatforms": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ]
}

通过选择{ProjectName}.uproject文件，然后选择“将版本Unreal Engine切换到Unreal Engine代码路径”来生成游戏解决方案文件。

游戏配置

无论面向哪个平台，游戏都需要在目标平台目标的 INI 文件 (位于 [yourGameDirectory]/Platform/[yourPlatform]/Config) 中配置某些 PlayFab 特定值。
- Xbox Series X GDK： XSXEngine.ini
- PC GDK： WinGDKEngine.ini
- Xbox One GDK：如果你使用的是 Unreal Engine 4) ，XB1Engine.ini (或 XboxOneGDKEngine.ini
- PC Steam：WindowsEngine.ini（或在 [yourGameDirectory]/Config/Windows 中找到）
- 任天堂 Switch SwitchEngine.ini
- PS4™ PS4Engine.ini
- PS5™ PS5Engine.ini
如果配置中已存在 INI 部分 (例如 Engine.GameEngine)，请将其替换为以下部分中所述的部分。
确保将所有 <REPLACE ME> 字段替换为数据：

[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="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 子系统仅支持将游戏会话命名为 NAME_GameSession

类似于使用其他联机子系统插件：

添加 PublicDependencyModuleNames.AddRange(new string[] { "OnlineSubsystem", "OnlineSubsystemUtils" }); Game.Build.cs，然后按照与其他游戏插件相同的方式使用它。

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.5 或 Unreal Engine 5.4：

可能会遇到以下运行时错误： 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": [
        {
            "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。

PlayFabParty.uplugin for Unreal Engine 4.27+ 中的模块配置示例：

"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 初始化群和多人游戏 SDK， (游戏配置文件中定义了此 titleID。在初始化期间，我们将 ⁠CreatePlayFabSocketSubsystem() 作为主联机子系统。

多人游戏 SDK 的工作流：FOnlineSubsystemPlayFab::Init() 初始化游戏的 InitializeMultiplayer() 多人游戏 SDK 单一实例。在 PlayFabLobby.cpp 中，FPlayFabLobby::DoWork() 处理多人游戏 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”是索尼互动娱乐公司的注册商标或商标。

“PS4”是索尼交互娱乐公司的注册商标或商标。

“PS5”是索尼交互娱乐公司的注册商标或商标。