> ## 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.

# Party Unity 插件快速入门

> 将 PlayFab Party 插件添加到 Unity 项目的快速入门:安装包、对玩家进行身份验证,并在终结点之间启用语音聊天。

# 快速入门:PlayFab Party Unity 插件

本快速入门帮助你安装适用于 Unity 的 Party SDK,并进行首次 API 调用,以将玩家加入 Party 网络。在继续之前,请确保已从你的 PlayFab 账户完成[通过 Game Manager 启用 Party 功能](/services/playfab/multiplayer/networking/enable-party)。

<Note>
  如果你打算使用此插件基于 Microsoft Game Development Kit (GDK) 开发游戏,需要单独获取并安装 GDK。此外,还请查看 XBOX 主机 Game Core 上 Unity 插件的详细信息。
</Note>

## 要求

* 一个 [PlayFab 开发者账户](https://developer.playfab.com)。

* 已安装的 Unity 编辑器副本。若要通过 Unity Hub 安装个人使用的 Unity,或安装用于专业用途的 Unity+,请参阅[下载 Unity](https://unity3d.com/get-unity/download)。如有必要,请查看你所用特定平台文档中的 Unity 支持情况。支持的最低 Unity 版本为 Unity 2017 LTS。

* 一个 Unity 项目,可以是以下任一选项:

  * 全新项目:有关详情,请参阅[首次启动 Unity](/services/playfab/sdks/unity3d/quickstart)。
  * 分步教程项目。有关详情,请参阅 [Getting Started with Unity](https://learn.unity.com/)。
  * 现有项目。

* PlayFab“核心”Unity3D SDK。有关安装 Unity3D SDK 的信息,请参阅 [Unity 中 C# 的 PlayFab 客户端库快速入门](/services/playfab/sdks/unity3d/quickstart#download-and-install-playfab-sdk)的“下载并安装 PlayFab SDK”部分。

## 下载并安装 PlayFab Party Unity 插件

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

1. 下载 PlayFab [Party Unity 插件](https://github.com/playfab/PlayFabPartyUnity) Asset 包(根据你的平台使用相应的分发点)。
2. **重要!** 请查看随插件一起发布的 [README 文件](https://github.com/PlayFab/PlayFabPartyUnity/blob/master/README.md)中的信息。它针对每个特定版本进行了定制,可能包含特定于你平台的重要说明。
3. 打开你的 Unity 项目。
4. 导航到你保存 .unitypackage 的位置,然后双击它以打开导入对话框。
5. 若要将 PlayFab Party Unity 插件导入到你的项目中,选择 **Import**。

## 设置场景

本部分指南将展示如何将 `PlayFabMultiplayerManager` 添加到你的场景中,以便你可以从 Unity 调用 PlayFab Party API。

在创建网络之前,你**必须让 PlayFab 玩家登录**。有关玩家登录的信息,请参阅 [Unity 中 C# 的 PlayFab 客户端库快速入门中的进行首次 API 调用](/services/playfab/sdks/unity3d/quickstart#making-your-first-api-call)。

1. 在 Unity 编辑器的 Project 窗口中,导航到 **Assets > PlayFabPartySDK > Prefabs**。

2. 从 Prefabs 文件夹中,将 **PlayFabMultiplayerManager** 拖放到 **Hierarchy** 窗口中的场景内。

3. 在场景中创建一个名为“HelloPartyLogic”的空 Game Object。

4. 选择 HelloPartyLogic Game Object 以打开 **Inspector**。

5. 选择 **Add Component**。

6. 键入“HelloPartyLogic”并按回车键以显示新建脚本菜单。

7. 再次按回车键创建新脚本 HelloPartyLogic.cs。

8. 在 **Project** 窗口中找到该脚本并双击以编辑脚本。

9. 将以下 using 语句添加到你的脚本中:

   ```csharp theme={null}
   using PlayFab;
   using PlayFab.Party;
   using PlayFab.ClientModels;
   ```

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

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

11. 将以下方法添加到该类中。

    ```csharp theme={null}
    private void OnLoginSuccess(LoginResult result)
    {
    }

    private void OnLoginFailure(PlayFabError error)
    {
    }
    ```

<Note>
  你可能会收到以下错误: `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".`
</Note>

Microsoft GDK 和 Windows 仅支持 x64。

若要解决这些问题:

1. 在 Unity 编辑器中,选择 **File > Build Settings.**
2. 选择你的平台。然后从 **Architecture** 下拉列表中选择 x86\_64 或 x64。
3. 选择 **Player Settings.**
4. 在右侧窗格中,选择 Other Setting。
5. 找到 **Allow unsafe Code** 设置并选中它。
6. 关闭 **Build Settings** 和 **Project Settings** 窗口。

## 连接到网络

本部分指南将展示如何创建和加入网络。

1. 打开 HelloPartyLogic.cs 脚本。在 `OnLoginSuccess` 方法中,添加以下代码以创建并加入网络:

   ```csharp theme={null}
   PlayFabMultiplayerManager.Get().CreateAndJoinNetwork();
   PlayFabMultiplayerManager.Get().OnNetworkJoined += OnNetworkJoined;
   ```

2. 若要定义 OnNetworkJoined 事件处理程序,将以下代码添加到该类:

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

3. 保存并在 Unity 编辑器中选择 Play。Network ID 将显示在 Console 窗口中。

## 加入现有网络

本部分指南将展示如何加入其他客户端创建的现有网络。

1. 打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以加入网络:

   ```csharp theme={null}
   string networkId = "<your network id>";
   PlayFabMultiplayerManager.Get().JoinNetwork(networkId);
   ```

2. 若要定义在本地客户端加入网络时触发的事件,将以下代码添加到 `OnLoginSuccess` 方法:

   ```csharp theme={null}
   PlayFabMultiplayerManager.Get().OnNetworkJoined += OnNetworkJoined;
   ```

3. 若要定义 OnNetworkJoined 事件处理程序,将以下代码添加到该类:

   ```csharp theme={null}
       private void OnNetworkJoined(object sender, string networkId)
       {
           // Print the Network ID so you can give it to the other client.
           Debug.Log("Network joined!");
       }
   ```

   有很多方法可以将 Network ID 从主机传给想要加入的其他玩家。请参考此 Unity 插件中的示例了解实现方式的一个示例。

4. 保存并在 Unity 编辑器中选择 Play。字符串“Network joined!”将显示在 Console 窗口中。

## 访问其他玩家

本部分指南将展示如何访问网络上的其他玩家,包括本地玩家。

若要监听有新玩家加入和离开网络,请注册 OnRemotePlayerJoined 和 OnRemotePlayerLeft 事件。

1. 打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以创建并加入网络:

   ```csharp theme={null}
   PlayFabMultiplayerManager.Get().OnRemotePlayerJoined += OnRemotePlayerJoined;
   PlayFabMultiplayerManager.Get().OnRemotePlayerLeft += OnRemotePlayerLeft;
   ```

2. 将以下方法添加到该类:

   ```csharp theme={null}
   private void OnRemotePlayerLeft(object sender, PlayFabPlayer player)
   {
   }

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

3. 若要访问本地玩家,将以下代码添加到 OnRemotePlayerJoined 方法:

   ```csharp theme={null}
   var localPlayer = PlayFabMultiplayerManager.Get().LocalPlayer;
   ```

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

## 发送和接收数据消息

本部分指南将展示如何发送和接收数据消息。在开始发送和接收数据消息之前,你必须先加入网络。

1. 打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以监听数据消息:

   ```csharp theme={null}
   PlayFabMultiplayerManager.Get().OnDataMessageReceived += LocalPlayer_OnDataMessageReceived;
   ```

2. 将 `OnDataMessageRecieved` 事件处理程序添加到该类:

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

3. 若要发送数据消息,将以下代码添加到 Update 方法:

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

保存 HelloPartyLogic.cs 并在 Unity 编辑器中选择 Play。

1. 在第二个客户端中,重复[连接到网络](#connecting-to-a-network)中的步骤以创建并加入网络。
2. 复制返回到第一个客户端的 Network ID 并连接到该网络。
3. 在场景上选择以发送消息。“Hello (data message)”将显示在 Console 窗口中。

## 发送和接收聊天消息

本部分指南将展示如何发送和接收聊天消息以及对远程玩家进行静音。除文本聊天外,Party 还会在玩家之间自动启用语音聊天。

在开始发送和接收聊天消息之前,你必须先加入网络。

1. 打开 HelloPartyLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以监听聊天消息:

   ```csharp theme={null}
   PlayFabMultiplayerManager.Get().OnChatMessageReceived += OnChatMessageReceived;
   ```

2. 将事件处理程序 `OnChatMessageReceived` 添加到该类:

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

保存 HelloPartyLogic.cs 并在 Unity 编辑器中按 Play。

1. 在第二个客户端中,重复[连接到网络](#connecting-to-a-network)中的步骤以创建并加入网络。
2. 复制返回到第一个客户端的 Network ID 并连接到该网络。
3. 当你在场景中选择时,会发送一条消息并显示在 Console 窗口中。
4. 如果你希望玩家能够选择对其他玩家静音,请将 IsMuted 属性设置为 true。

   ```csharp theme={null}
   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](/services/playfab/multiplayer/networking/unity-party-api-reference/enums/partyunitydirectpeerconnectivityoptions)。此示例展示了如何设置 P2P:

1. 打开 HelloPartyLogic.cs 脚本。在 `OnLoginSuccess` 方法中,添加以下代码以创建并加入网络:

   ```csharp theme={null}
   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()](/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunityresetparty) 实现

### Switch 和 GDK

在 Nintendo Switch 和 Microsoft GDK 上,你必须清理 PlayFab Party 和所有与 PlayFabMultiplayerManager 关联的资源,然后等到标题恢复执行后再重新初始化 PlayFab Party 并重新连接到你的网络。

“若要在标题挂起期间清理 PlayFab Party,请调用 [Suspend()](/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunitysuspend)。标题恢复执行后,调用 [Resume()](/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunityresume) 以重新初始化 PlayFab Party。

在 PlayFab Party 和所有与 PlayFabMultiplayerManager 关联的资源成功初始化后,重复[加入现有网络](#joining-an-existing-network)的步骤。


## Related topics

- [Multiplayer Unity 插件快速入门](/zh-CN/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [Unity 快速入门](/zh-CN/services/playfab/sdks/unity3d/quickstart.md)
- [使用 Economy v2、Unity IAP 和 Android 快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/tutorials/getting-started-with-unity-and-android.md)
- [集成 PlayFab Unreal Engine Marketplace 插件](/zh-CN/services/playfab/multiplayer/networking/party-unreal-engine-oss-playfab-plugin-integration.md)
- [快速入门 (Windows) - Party 和 Multiplayer](/zh-CN/services/playfab/sdks/unified-sdk/quickstart-windows-party.md)