快速入门：PlayFab Party Unity 插件

项目
02/02/2024

本快速入门可帮助你安装 Party SDK for Unity，并进行首次 API 调用，以便将玩家加入群网络。在继续之前，请确保已通过 PlayFab 帐户的 Game Manager 完成“启用群”功能。

注意

如果你打算使用此插件开发基于 Microsoft 游戏开发工具包 (GDK) 的游戏，则需要单独获取并安装 GDK。另请参阅有关 Xbox 主机上适用于 Game Core 的 Unity 附加内容的详细信息。

要求

一个 PlayFab 开发者帐户。
Unity 编辑器的已安装副本。若要通过 Unity Hub 或 Unity+ 安装 Unity 以供个人使用，请参阅下载 Unity。如果需要，请在特定平台的文档中查看 Unity 支持。支持的最低 Unity 版本是 Unity 2017 LTS。
Unity 项目，可以是以下任一选项：
- 一个全新的项目：有关详细信息，请参阅首次启动 Unity。
- 引导式教程项目。有关详细信息，请参阅 Unity 入门。
- 一个现有项目。
PlayFab“核心” Unity3D SDK。有关安装 Unity3D SDK 的信息，请参阅快速入门：Unity 中适用于 C# 的 PlayFab 客户端库中的“下载并安装 PlayFab SDK”部分。

下载并安装 PlayFab Party Unity 插件

按照步骤下载并安装 PlayFab Party Unity 插件。

下载 PlayFab Party Unity Plugin 资产包（根据你的平台使用分发点）。
重要事项！ 请参阅随插件发布的自述文件中的信息。它针对每个特定版本量身定制，并且可能包含特定于你的平台的重要说明。
打开你的 Unity 项目。
导航到保存 .unitypackage 的位置并双击它以打开导入对话框。
若要将 PlayFab Party Unity 插件导入项目，请选择“导入”。

设置场景

指南的这一部分介绍了如何将 PlayFabMultiplayerManager 添加到你的场景，以便你能够从 Unity 调用 PlayFab Party API。

必须登录 PlayFab 播放器，然后才能创建网络。有关登录播放器的信息，请参阅快速入门：Unity 中适用于 C# 的 PlayFab 客户端库中的“进行首次 API 调用”。

在 Unity 编辑器的“项目”窗口中，导航到“资产 > PlayFabPartySDK > 预制件”。
在 Prefabs 文件夹中，将 PlayFabMultiplayerManager 拖放到“层次结构”窗口中的场景。
在场景中创建名为“HelloPartyLogic”的空游戏对象。
选择 HelloPartyLogic 游戏对象以打开检查器。
选择“添加组件”。
键入“HelloPartyLogic”，然后按 Enter 以显示新的脚本菜单。
再次按 Enter 创建新脚本 HelloPartyLogic.cs。
在“项目”窗口中找到脚本并双击它以编辑脚本。

将以下 using 语句添加至脚本：

using PlayFab;
using PlayFab.Party;
using PlayFab.ClientModels;

在 Start 方法中添加以下代码以登录 PlayFab。

// Log into playfab
var request = new LoginWithCustomIDRequest { CustomId = UnityEngine.Random.value.ToString(), CreateAccount = true };
PlayFabClientAPI.LoginWithCustomID(request, OnLoginSuccess, OnLoginFailure);

将以下方法添加到类。

private void OnLoginSuccess(LoginResult result)
{
}

private void OnLoginFailure(PlayFabError error)
{
}

注意

你可能会收到以下错误：

Error    CS0227    Unsafe code may only appear if compiling with /unsafe
The plugin requires unsafe code because it interops with a native DLL.

Mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference "XGamingRuntime", "AMD64".

Microsoft GDK 和 Windows 仅支持 x64。

若要解决这些问题，请执行以下操作：

在 Unity 编辑器中，选择“文件 > 生成设置”。
选择你的平台。然后，从“体系结构”下拉列表中选择 x86_64 或 x64。
选择“玩家设置”。
在右窗格中，选择“其他设置”。
找到“允许不安全的代码”设置并将其选中。
关闭“生成设置”和“项目设置”窗口。

连接到网络

指南的这一部分介绍如何创建和加入网络。

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以创建和加入网络：

PlayFabMultiplayerManager.Get().CreateAndJoinNetwork();
PlayFabMultiplayerManager.Get().OnNetworkJoined += OnNetworkJoined;

若要定义 OnNetworkJoined 事件处理程序，请将以下代码添加到类：

private void OnNetworkJoined(object sender, string networkId)
{
    // Print the Network ID so you can give it to the other client.
    Debug.Log(networkId);
}

在 Unity 编辑器中保存并选择“播放”。此时会在主机窗口中显示网络 ID。

加入现有网络

指南的这一部分将介绍如何加入另一个客户端创建的现有网络。

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以加入网络：
```
string networkId = "<your network id>";
PlayFabMultiplayerManager.Get().JoinNetwork(networkId);
```
若要定义本地客户端加入网络时触发的事件，请将以下代码添加到 OnLoginSuccess 方法：
```
PlayFabMultiplayerManager.Get().OnNetworkJoined += OnNetworkJoined;
```
若要定义 OnNetworkJoined 事件处理程序，请将以下代码添加到类：
```
    private void OnNetworkJoined(object sender, string networkId)
    {
        // Print the Network ID so you can give it to the other client.
        Debug.Log("Network joined!");
    }
```
可通过多种方式从主机获取网络 ID 并提供给其他想要加入的玩家。有关如何执行此操作的示例，请参阅此 Unity 插件中的示例。
在 Unity 编辑器中保存并选择“播放”。字符串“已加入网络！”显示在控制台窗口中。

访问其他玩家

指南的这一部分将介绍如何访问网络上的其他玩家，包括本地玩家。

若要侦听是否有新玩家加入和离开网络，请注册 OnRemotePlayerJoined 和 OnRemotePlayerLeft 事件。

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以创建和加入网络：

PlayFabMultiplayerManager.Get().OnRemotePlayerJoined += OnRemotePlayerJoined;
PlayFabMultiplayerManager.Get().OnRemotePlayerLeft += OnRemotePlayerLeft;

将以下方法添加到类：

private void OnRemotePlayerLeft(object sender, PlayFabPlayer player)
{
}

private void OnRemotePlayerJoined(object sender, PlayFabPlayer player)
{
}

若要访问本地播放器，请将以下代码添加到 OnRemotePlayerJoined 方法：
```
var localPlayer = PlayFabMultiplayerManager.Get().LocalPlayer;
```

PlayFabPlayer 类包含用于在聊天 UI 中标识玩家、静音和呈现其聊天状态的属性。

发送和接收数据消息

指南的这一部分将介绍如何发送和接收数据消息。必须先加入网络，然后才能开始发送和接收数据消息。

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以侦听数据消息：
```
PlayFabMultiplayerManager.Get().OnDataMessageReceived += LocalPlayer_OnDataMessageReceived;
```

将 OnDataMessageRecieved 事件处理程序添加到类：

private void OnDataMessageReceived(object sender, PlayFabPlayer from, byte[] buffer)
{
    Debug.Log(Encoding.Default.GetString(buffer));
}

要发送数据消息，请将以下代码添加到 Update 方法：

if (Input.GetButtonDown("Fire1"))
{
    byte[] requestAsBytes = Encoding.UTF8.GetBytes("Hello (data message)");
    PlayFabMultiplayerManager.Get().SendDataMessageToAllPlayers(requestAsBytes);
}

在 Unity 编辑器中保存 HelloPartyLogic.cs 并选择“播放”。

在第二个客户端中，重复“连接到网络”中的步骤，以创建和加入网络。
复制返回到第一个客户端的网络 ID 并连接到网络。
选择场景以发送消息。此时会在主机窗口中显示“Hello (数据消息)”。

发送和接收聊天消息

指南的这一部分将介绍如何发送和接收聊天消息以及将远程玩家静音。除了文本聊天，Party 还会自动在玩家之间启用语音聊天。

必须先加入网络，然后才能开始发送和接收聊天消息。

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以侦听聊天消息：
```
PlayFabMultiplayerManager.Get().OnChatMessageReceived += OnChatMessageReceived;
```

将事件处理程序 OnChatMessageReceived 添加到类；

private void OnChatMessageReceived(object sender, PlayFabPlayer from, string message, ChatMessageType type)
{
    Debug.Log(message);
}

在 Unity 编辑器中保存 HelloPartyLogic.cs 并按下“播放”。

在第二个客户端中，重复“连接到网络”中的步骤，以创建和加入网络。
复制返回到第一个客户端的网络 ID 并连接到网络。
选择场景时，它会发送一条消息，并在主机窗口中显示该消息。

如果要为玩家提供将其他玩家静音的选项，请将 IsMuted 属性设置为 true。

private void OnRemotePlayerJoined(object sender, PlayFabPlayer player)
{
    // This player will not be able to send text or voice communication.
    // Data messages can still be sent.+
    player.IsMuted = true;
}

使用自定义对等连接配置选项连接到网络

本指南的这一部分演示如何使用自定义对等连接配置选项创建和加入网络。默认选项是 P2P，但是，使用此处显示的标志的任何组合： DirectPeerConnectivityOptions，用户可以修改此选项。此示例演示如何设置 P2P：

打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以创建和加入网络：

PlayfabNetworkConfiguration networkConfiguration = new PlayfabNetworkConfiguration();
networkConfiguration.DirectPeerConnectivityOptions = PARTY_DIRECT_PEER_CONNECTIVITY_OPTIONS_ANY_PLATFORM_TYPE |
                                                     PARTY_DIRECT_PEER_CONNECTIVITY_OPTIONS_ANY_ENTITY_LOGIN_PROVIDER;
PlayFabMultiplayerManager.Get().CreateAndJoinNetwork(networkConfiguration);
PlayFabMultiplayerManager.Get().OnNetworkJoined += OnNetworkJoined;

处理游戏暂停

某些平台支持暂时暂停游戏执行：iOS、Switch 和 GDK。当游戏暂停时，网络堆栈将失效，PlayFab Party 无法保持与 PlayFab Party 网络的连接。使用 PlayFab Party 时，需要特别注意如何处理游戏暂停和恢复执行。

iOS

在 iOS 上，必须离开并重新连接到 PlayFab Party 网络，这可以通过调用 ResetParty() 来实现

Switch 和 GDK

在 Nintendo Switch 和 Microsoft GDK 上，必须清理 PlayFab Party 以及所有与 PlayFabMultiplayerManager 相关的资源，然后等待游戏执行继续，然后重新初始化 PlayFab Party 并重新连接到网络。

“在游戏暂停期间清理 PlayFab Party，并调用 Suspend () 。游戏继续执行后，调用 Resume () 以重新初始化 PlayFab Party。

成功初始化 PlayFab Party 和与 PlayFabMultiplayerManager 关联的所有资源后，重复这些步骤以加入现有网络。

通过