快速入门:PlayFab Online Subsystem

本文帮助你为使用 Unreal Engine 4 或 Unreal Engine 5 构建的游戏设置和使用大厅、匹配和 Party 等 PlayFab 多人功能。有关 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 上的 HandShake 失败

如果你看到握手失败(例如 LogHandshake: IncomingConnectionless: Error reading handshake packet),请参阅此 Unreal Engine 论坛帖子以检查设置。

OnlineSubsystemPlayFab 的工作流

平台特定注意事项部分中列出的步骤要求你包含:

[OnlineSubsystem]
DefaultPlatformService=PlayFab

Unreal Engine OnlineSubsystemModule 会为 PlayFab 创建一个 online subsystem 实例并开始创建 PlayFabSingleton。此时,SDK 会在 FOnlineSubsystemPlayFab::Init() 中初始化, 使用 PlayFab TitleID(此 titleID 在游戏配置文件中定义)初始化 Party 和 Multiplayer SDK。在初始化期间,我们将 ⁠CreatePlayFabSocketSubsystem() 作为主要 online subsystem。 Multiplayer SDK 的工作流:FOnlineSubsystemPlayFab::Init() 为你的标题初始化 InitializeMultiplayer() multiplayer SDK 单例。在 PlayFabLobby.cpp 中,FPlayFabLobby::DoWork() 处理由 Multiplayer API 触发的状态更改(有关 API,请查看 Platforms/GDK/Include/PFLobby.h)。 Party SDK 的工作流:FOnlineSubsystemPlayFab::Init() 为你的标题初始化 InitializeParty() multiplayer 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 上的 HandShake 失败

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 上的 HandShake 失败

​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 上的 HandShake 失败

OnlineSubsystemPlayFab 的工作流