> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # PlayFab Online Subsystem (OSS) 快速入门 > Unreal Engine 中 PlayFab Online Subsystem 的快速入门,涵盖 Party 语音聊天、大厅以及基于 Multiplayer SDK 的匹配设置。 # 快速入门:PlayFab Online Subsystem 本文帮助你为使用 Unreal Engine 4 或 Unreal Engine 5 构建的游戏设置和使用大厅、匹配和 Party 等 PlayFab 多人功能。有关 Unreal Engine 4 或 Unreal Engine 5 中支持的平台和版本的完整列表,请参阅[支持的平台](/services/playfab/multiplayer/networking/party-unreal-engine-oss-overview)。 在按照本页中列出的针对目标平台的相关步骤操作后,你就可以开始使用 PlayFab Online Subsystem (PF OSS) 了。身份验证、网络、VOIP、加入大厅分组和匹配都会由系统代为处理,无需其他更改。 ## 下载并安装 PlayFab Online Subsystem 前往 [PlayFab Online Subsystem](https://github.com/PlayFab/PlayFabMultiplayerUnreal) 下载或克隆 PF OSS 源代码。下载或克隆的存储库名称为 PlayFabMultiplayerUnreal。存储库需重命名为 OnlineSubsystemPlayFab。 ## 你需要的内容 * \*\*PlayFab TitleID:\*\*如果你还没有为 PlayFab Party 和 Multiplayer 软件开发工具包 (SDK) 配置 TitleID,请参阅[启用 PlayFab Party](/services/playfab/multiplayer/networking/enable-party)。 ### Microsoft Game Development Kit (GDK)、PC、Switch、PlayStation®5 和 PlayStation®4 * \*\*特定平台的 PlayFab Party 和 Lobby 及 Matchmaking 库:\*\*请参阅[获取 PlayFab Party 和 Multiplayer 库](/services/playfab/multiplayer/networking/party-unreal-engine-oss-obtaining-playfab-party-libraries)。 ## 初始设置 ### 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 ```json theme={null} { "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),请将其替换为以下部分中提供的内容。 * 确保将所有 *\* 字段替换为你自己的数据: * 在 UE 5.6 及更高版本上,`DriverClassName` 参数需要 "/Script/" 前缀。例如,使用 `"/Script/OnlineSubsystemPlayFab.PlayFabNetDriver"` 而非 `"OnlineSubsystemPlayFab.PlayFabNetDriver"`。 ```ini theme={null} [OnlineSubsystemPlayFab] bEnabled=true PlayFabTitleID= MaxDeviceCount= MaxDevicesPerUserCount= MaxEndpointsPerDeviceCount= MaxUserCount= MaxUsersPerDeviceCount= DirectPeerConnectivityOptions= bHasPlayFabVoiceEnabled= [/Script/OnlineSubsystemPlayFab.PlayFabNetDriver] NetConnectionClassName="OnlineSubsystemPlayFab.PlayFabNetConnection" ReplicationDriverClassName="" . 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 开发游戏时,请设置平台服务。 ```ini theme={null} [OnlineSubsystem] DefaultPlatformService=PlayFab NativePlatformService=GDK ``` ### Steam 如果你正在使用 Steam 为 Win64 开发游戏,请定义你的平台服务。 ```ini theme={null} [OnlineSubsystem] DefaultPlatformService=PlayFab NativePlatformService=Steam ``` ### Switch 有关 Switch 的更多信息,请参阅 Switch PlayFab OSS 附带的 [ReadMe.md](https://dev.azure.com/PlayFabPrivate/Switch/_git/PlayFabMultiplayerUnrealSwitch?path=/README.md) 文件。如果你没有访问权限,可以[申请访问](/services/playfab/sdks/request-access-for-sdks-samples)我们的私有存储库。 ### PS5™ 和 PS4™ 有关 PS5™ 和 PS4™ 的更多信息,请参阅 PS5™ 和 PS4™ PlayFab OSS 附带的 [ReadMe.md](https://dev.azure.com/PlayFabPrivate/PS5/_git/PlayFabMultiplayerUnrealPlayStation?path=/README.md) 文件。如果你没有访问权限,可以[申请访问](/services/playfab/sdks/request-access-for-sdks-samples)我们的私有存储库。 ### 跨平台 如果你的游戏使用 PlayFab 的跨平台网络支持,请定义你允许连接的平台。 ```ini theme={null} [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] !CompatibleUniqueNetIdTypes=ClearArray +CompatibleUniqueNetIdTypes=STEAM +CompatibleUniqueNetIdTypes=GDK +CompatibleUniqueNetIdTypes=SWITCH +CompatibleUniqueNetIdTypes=PS4 +CompatibleUniqueNetIdTypes=PS5 ``` 所有平台默认都允许 VoIP。若要为特定平台禁用 VoIP,请将平台型号名称添加到 Unreal Engine 配置文件中,如以下示例所示。 ```ini theme={null} [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 中的示例代码: ```cpp theme={null} #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 中的示例代码: ```cpp theme={null} #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\\Party.dll and Engine\Plugins\Online\OnlineSubsystemPlayFab\Platforms\GDK\Redist\Party.dll` * 导航到 Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\\ * 打开 OnlineSubsystemGDK.uplugin 并将 `PlayFabParty` 设置为禁用: ```json theme={null} { "Name": "PlayFabParty", "Enabled": false } ``` * 导航到 Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\Source\\ * 打开 OnlineSubsystemGDK.Build.cs 并注释掉对 `PlayFabParty` 的包含: ```csharp theme={null} if (Target.bCompileAgainstEngine) { //PublicDependencyModuleNames.Add("PlayFabParty"); } ``` **如果你使用的是 Unreal Engine 5.0 - 5.3:** * 找到计算机上 Unreal Engine 的安装目录。 * 导航到 Engine\Platforms\GDK\Plugins\Online\PlayFabParty * 打开 PlayFabParty.uplugin,并使用 **PlatformDenyList** 更新 Modules 配置: ```ini theme={null} "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 配置示例: ```ini theme={null} "Modules": [ { "Name": "PlayFabParty", "Type": "Runtime", "LoadingPhase": "Default", "BlacklistPlatforms": ["WinGDK", "Win64"] } ], ``` ### Steam 上的 HandShake 失败 如果你看到握手失败(例如 `LogHandshake: IncomingConnectionless: Error reading handshake packet`),请参阅此 [Unreal Engine 论坛帖子](https://forums.unrealengine.com/t/ue-5-1-steam-sockets-problem/696726)以检查设置。 ## OnlineSubsystemPlayFab 的工作流 [平台特定注意事项](#platform-specific-considerations)部分中列出的步骤要求你包含: ```ini theme={null} [OnlineSubsystem] DefaultPlatformService=PlayFab ``` Unreal Engine OnlineSubsystemModule 会为 PlayFab 创建一个 online subsystem 实例并开始创建 PlayFabSingleton。此时,SDK 会在 `FOnlineSubsystemPlayFab::Init()` 中初始化, 使用 PlayFab TitleID(此 titleID 在[游戏配置](#game-configuration)文件中定义)初始化 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. 的注册商标或商标。