快速入门：PlayFab Online 子系统（OSS）

项目
06/14/2024

本快速入门指南可帮助你针对使用 Unreal Engine 4 或 Unreal Engine 5 生成的 Xbox、电脑、任天堂 Switch、PlayStation®5 和 PlayStation®4 游戏设置和使用多人游戏功能，例如大厅、匹配和群。有关 UE4 或 UE5 中受支持平台和版本的完整列表，请参阅支持的平台。

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

下载并安装 PlayFab Online 子系统

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

你所需要的有

PlayFab 游戏 ID： 如果没有为 PlayFab Party 和多人游戏 SDK 配置游戏 ID，请参阅启用 PlayFab Party。

GDK、电脑、Switch、PlayStation®5 和 PlayStation®4

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

初始设置

Unreal Engine 代码库

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

游戏代码库

将以下更改应用于“.uproject”文件的“插件”部分，将 OnlineSubsystemPlayFab 添加到插件列表。
- 可以删除未在其上发货的任何平台
- 如果你使用的是 UE4，请使用 XboxOneGDK 而不是 XB1，因为 UE5 已弃用 XboxOneGDK

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

通过右键单击 .uproject 文件并选择“切换 Unreal Engine Version”到上述 Unreal Engine 代码路径，生成游戏解决方案文件。

游戏配置

无论面向哪个平台，游戏都需要在目标平台目标的 INI 文件 (位于 [yourGameDirectory]/Platform/[yourPlatform]/Config) 中配置某些 PlayFab 特定值。
- Xbox Series X GDK： XSXEngine.ini
- PC GDK： WinGDKEngine.ini
- Xbox One GDK：XB1Engine.ini（如果使用的是 UE4，则为 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，请将平台型号名称添加到 UE 配置文件，如下所示。

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

这些步骤完成了在游戏中需要使用的 OSS 的设置。祝你好运！

在游戏代码中使用

注意

PlayFab Online 子系统仅支持将游戏会话命名为 NAME_GameSession

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

在 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 已安装内部版本时可能会遇到问题。我们提供了以下指南，以成功解决此问题，直到有更完整的解决方案。

如果你使用的是 UE5.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");
}

如果你使用的是 UE5.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。

如果你使用的是 UE4.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 UE4.27+:: 中的示例模块配置

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

Steam 上的握手失败

如果出现握手失败（如 LogHandshake: IncomingConnectionless: Error reading handshake packet），请参考此 UE 论坛帖子检查设置。

OnlineSubsystemPlayFab 的工作流

平台特定注意事项部分中概述的步骤要求你包括：

[OnlineSubsystem]
DefaultPlatformService=PlayFab

UE OnlineSubsystemModule 为 PlayFab 创建联机子系统实例，并开始创建 PlayFabSingleton。此时，SDK 在 FOnlineSubsystemPlayFab::Init() 中进行初始化，其中使用 PlayFab TitleID 初始化 Party 和多人游戏 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”是索尼交互娱乐公司的注册商标或商标。

通过

快速入门：PlayFab Online 子系统（OSS）

下载并安装 PlayFab Online 子系统

你所需要的有

GDK、电脑、Switch、PlayStation®5 和 PlayStation®4

初始设置

Unreal Engine 代码库

游戏代码库

游戏配置

平台特定注意事项

GDK

Steam

Switch

PS5™ 和 PS4™

跨平台

在游戏代码中使用

故障排除：

Unreal Engine 已安装内部版本

Steam 上的握手失败

OnlineSubsystemPlayFab 的工作流

反馈

其他资源

通过

快速入门：PlayFab Online 子系统 （OSS）

下载并安装 PlayFab Online 子系统

你所需要的有

GDK、电脑、Switch、PlayStation®5 和 PlayStation®4

初始设置

Unreal Engine 代码库

游戏代码库

游戏配置

平台特定注意事项

GDK

Steam

Switch

PS5™ 和 PS4™

跨平台

在游戏代码中使用

故障排除：

Unreal Engine 已安装内部版本

Steam 上的握手失败

OnlineSubsystemPlayFab 的工作流

反馈

其他资源

快速入门：PlayFab Online 子系统（OSS）