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

本快速入门指南可帮助你针对使用 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”是索尼交互娱乐公司的注册商标或商标。