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

# Multiplayer Unity 插件快速入门

> 安装 PlayFab Multiplayer Unity 插件并从 Unity 项目发出你的第一次 Lobby 和 Matchmaking API 调用,包括 GDK 设置注意事项。

# 快速入门:PlayFab Multiplayer Unity 插件

开始使用 PlayFab Multiplayer Unity 插件。按照以下步骤安装该包,并试用示例代码完成一个基本任务。

本快速入门可帮助你使用 PlayFab Multiplayer Unity SDK 进行首次 API 调用。在继续之前,请确保你已完成[快速入门:Unity 中的 PlayFab C# 客户端库](/services/playfab/sdks/unity3d/quickstart),以确保你拥有 PlayFab 帐户并熟悉从你的游戏和 PlayFab Game Manager 登录 PlayFab。

<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)。
  * 一个有指导的教程项目。有关更多信息,请参阅 [Unity 入门](https://learn.unity.com/)。
  * 一个现有项目。

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

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

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

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

注意:如有必要,你可能需要安装更新版本的 PlayFab“核心”Unity SDK。

## 设置你的场景

本指南的这一部分向你展示如何将 `PlayfabMultiplayerEventProcessor` 添加到你的场景中,以启用从 Unity 调用 PlayFab Multiplayer API。

在你可以使用 Multiplayer API 之前,**必须先登录一个 PlayFab 玩家**。有关登录玩家的信息,请参阅[快速入门:Unity 中的 PlayFab C# 客户端库中“进行你的第一次 API 调用”](/services/playfab/sdks/unity3d/quickstart#making-your-first-api-call)。

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

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

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

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

5. 选择 **Add Component**。

6. 键入 “HelloMultiplayerLogic” 并按 Enter 键以显示新脚本菜单。

7. 再次按 Enter 键创建新的脚本 HelloMultiplayerLogic.cs。

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

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

   ```csharp theme={null}
   using PlayFab;
   using PlayFab.Multiplayer;
   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>
  你可能会收到以下错误: `C \# 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. 打开 HelloMultiplayerLogic.cs 脚本。在 `OnLoginSuccess` 方法中,添加以下代码以创建并加入大厅:

   ```csharp theme={null}
   string entityId = ...; // PlayFab user's entity Id
   string entityType = ...; // PlayFab user's entity type

   PlayFabMultiplayer.OnLobbyCreateAndJoinCompleted += this.PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted;
   PlayFabMultiplayer.OnLobbyDisconnected += this.PlayFabMultiplayer_OnLobbyDisconnected;

   var createConfig = new LobbyCreateConfiguration()
   {
       MaxMemberCount = 10,
       OwnerMigrationPolicy = LobbyOwnerMigrationPolicy.Automatic,
       AccessPolicy = LobbyAccessPolicy.Public
   };

   createConfig.LobbyProperties["Prop1"] = "Value1";
   createConfig.LobbyProperties["Prop2"] = "Value2";

   var joinConfig = new LobbyJoinConfiguration();
   joinConfig.MemberProperties["MemberProp1"] = "MemberValue1";
   joinConfig.MemberProperties["MemberProp2"] = "MemberValue2";

   PlayFabMultiplayer.CreateAndJoinLobby(
       new PFEntityKey(
           entityId,
           entityType),
       createConfig,
       joinConfig);
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted(Lobby lobby, int result)
   {
       if (LobbyError.SUCCEEDED(result))
       {
           // Lobby was successfully created
           Debug.Log(lobby.ConnectionString);
       }
       else
       {
           // Error creating a lobby
           Debug.Log("Error creating a lobby");
       }
   }
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyDisconnected(Lobby lobby)
   {
       // Disconnected from lobby
       Debug.Log("Disconnected from lobby!");
   }
   ```

4. 保存并在 Unity 编辑器中选择 Play。大厅连接字符串会显示在 Console 窗口中。

## 加入大厅

本指南的这一部分向你展示如何加入另一个客户端创建的现有大厅。

1. 打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以加入大厅:

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key

   string connectionString = "<your lobby connection string>";

   PlayFabMultiplayer.JoinLobby(
           entityKey,
           connectionString,
           null);
   ```

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

   ```csharp theme={null}
   PlayFabMultiplayer.OnLobbyJoinCompleted += this.PlayFabMultiplayer_OnLobbyJoinCompleted;
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyJoinCompleted(Lobby lobby, PFEntityKey newMember, int reason)
   {
       if (LobbyError.SUCCEEDED(reason))
       {
           // Successfully joined a lobby
           Debug.Log("Joined a lobby");
       }
       else
       {
           // Error joining a lobby
           Debug.Log("Error joining a lobby");
       }
   }
   ```

4. 保存并在 Unity 编辑器中选择 Play。字符串 “Joined a lobby” 会显示在 Console 窗口中。

## 查找大厅

本指南的这一部分向你展示如何查找其他客户端创建的现有大厅。

1. 打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以查找大厅:

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key

   LobbySearchConfiguration config = new LobbySearchConfiguration();
   PlayFabMultiplayer.FindLobbies(entityKey, config);
   ```

2. 若要定义一个在本地客户端查找大厅时触发的事件,请将以下代码添加到 `OnLoginSuccess` 方法中:

   ```csharp theme={null}
   PlayFabMultiplayer.OnLobbyFindLobbiesCompleted += this.PlayFabMultiplayer_OnLobbyFindLobbiesCompleted;
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyFindLobbiesCompleted(
       IList<LobbySearchResult> searchResults, 
       PFEntityKey newMember, 
       int reason)
   {
       if (LobbyError.SUCCEEDED(reason))
       {
           // Successfully found lobbies
           Debug.Log("Found lobbies");

           // Iterate through lobby search results
           foreach (LobbySearchResult result in searchResults)
           {
               // Examine a search result
           }
       }
       else
       {
           // Error finding lobbies
           Debug.Log("Error finding lobbies");
       }
   }
   ```

4. 保存并在 Unity 编辑器中选择 Play。字符串 “Found lobbies” 会显示在 Console 窗口中。

## 创建匹配票据

本指南的这一部分向你展示如何创建匹配票据。请在另一个客户端上与下面的“加入匹配票据”场景一起运行。

1. 打开 HelloMultiplayerLogic.cs 脚本。在 `OnLoginSuccess` 方法中,添加以下代码以创建匹配票据:

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   PFEntityKey remoteEntityKey = ...; // another PlayFab user's entity key
   string remoteUserAttributesJson = ...; // JSON string with another PlayFab user's attributes for matchmaking

   PlayFabMultiplayer.OnMatchmakingTicketStatusChanged += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

   List<MatchUser> localUsers = new List<MatchUser>();
   localUsers.Add(new MatchUser(entityKey, remoteUserAttributesJson));

   List<PFEntityKey> membersToMatchWith = new List<PFEntityKey>();
   membersToMatchWith.Add(remoteEntityKey);

   PlayFabMultiplayer.CreateMatchmakingTicket(
       localUsers,
       "QuickMatchQueueName",
       membersToMatchWith);
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
   {
       // Store and print matchmaking ticket
       Debug.Log(ticket.TicketId);

       // Examine matchmaking ticket status
       Debub.Log(ticket.Status)

       // Share matchmaking ticket with other clients taking part in matchmaking

       // Examine ticket
   }
   ```

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

如果指定了 membersToMatchWith,将触发一次 OnMatchmakingTicketStatusChanged 事件处理程序,并且 Status 将为 WaitingForPlayers。在这种情况下,一旦另一个客户端调用 JoinMatchmakingTicketFromId,将再触发一次新的 OnMatchmakingTicketStatusChanged 事件处理程序,这次状态将为 WaitingForMatch。

或者,将触发一次 OnMatchmakingTicketStatusChanged 事件处理程序,状态将为 WaitingForMatch。

## 加入匹配票据

本指南的这一部分向你展示如何加入另一个客户端创建的现有匹配票据。请在另一个客户端上与上面的“创建匹配票据”场景一起运行。

1. 打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中,添加以下代码以加入匹配票据:

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   string ticketId = ...; // Matchmaking ticket obtained from the client that created the ticket

   PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

   // Create JSON string with PlayFab user's attributes for matchmaking. This will need to be shared with other clients taking part in matchmaking
   string uniqueId = System.Guid.NewGuid().ToString();
   string userAttributesJson = "{\"MatchIdentifier\": \"" + uniqueId + "\"}";

   PlayFabMultiplayer.JoinMatchmakingTicketFromId(
       new MatchUser(entityKey, userAttributesJson),
       ticketId,
       "QuickMatchQueueName",
       new List<PFEntityKey>());
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
   {
       // Store and print matchmaking ticket
       Debug.Log(ticket.TicketId);

       // Examine matchmaking ticket status
       Debub.Log(ticket.Status)

       // Share matchmaking ticket with other clients taking part in matchmaking

       // Examine ticket
   }
   ```

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

将触发一次 OnMatchmakingTicketStatusChanged,状态为 WaitingForMatch。

## 完成匹配票据

本指南的这一部分向你展示匹配是如何完成的。请在另一个客户端上与上面的“创建匹配票据”场景一起运行。你也可以选择与“加入匹配票据”场景一起运行。

1. 一旦同一队列中的多个票据满足匹配条件,就会找到匹配。在这种情况下,将触发 OnMatchmakingTicketCompleted 事件处理程序。

2. 订阅 OnMatchmakignTicketCompleted 处理程序

   ```csharp theme={null}
   PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketCompleted;
   ```

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

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketCompleted(MatchmakingTicket ticket, int result)
   {
       if (LobbyError.SUCCEEDED(result))
       {
           // Successfully completed matchmaking ticket
           Debug.Log("Completed matchmaking ticket");

           // Examine matchmaking details
           MatchmakingMatchDetails details = ticket.GetMatchDetails();
       }
       else
       {
           // Error completing a matchmaking ticket
           Debug.Log("Error completing a matchmaking ticket");
       }
   }
   ```


## Related topics

- [Party Unity 插件快速入门](/zh-CN/services/playfab/multiplayer/networking/party-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)
- [Photon 快速入门](/zh-CN/services/playfab/live-service-management/service-gateway/add-ons/photon/quickstart.md)