​

快速入門：PlayFab Multiplayer Unity 外掛程式

開始使用 PlayFab Multiplayer Unity 外掛程式。請依照下列步驟安裝套件，並試用基本工作的範例程式碼。 本快速入門可協助您使用適用於 Unity 的 PlayFab Multiplayer SDK 進行第一個 API 呼叫。繼續之前，請確認您已完成快速入門：Unity 中適用於 C# 的 PlayFab 用戶端程式庫，這可確保您擁有 PlayFab 帳戶，並熟悉如何從遊戲和 PlayFab Game Manager 登入 PlayFab。

​

需求

• PlayFab 開發人員帳戶。
• 已安裝的 Unity 編輯器。若要透過 Unity Hub 安裝供個人使用的 Unity，或供專業使用的 Unity+，請參閱下載 Unity。如有需要，請查看您特定平台文件中的 Unity 支援。支援的最低 Unity 版本為 Unity 2017 LTS。
• Unity 專案 – 可以是下列任何一種：
  • 全新專案：如需詳細資訊，請參閱第一次啟動 Unity。
  • 引導式教學課程專案。如需詳細資訊，請參閱 Getting Started with Unity。
  • 現有專案。
• PlayFab「核心」Unity3D SDK (也包含在 Multiplayer Unity 外掛程式中)。如需安裝 Unity3D SDK 的相關資訊，請參閱快速入門：Unity 中適用於 C# 的 PlayFab 用戶端程式庫的「下載並安裝 PlayFab SDK」一節。

​

下載並安裝 PlayFab Multiplayer Unity 外掛程式

依照下列步驟下載並安裝 PlayFab Multiplayer Unity 外掛程式。

1. 下載 PlayFab Multiplayer Unity 外掛程式 Asset 套件 (依您的平台使用對應的散發點)。
2. 重要！ 請參閱與外掛程式一起發佈的 README 檔案中的資訊。它是針對每個特定版本量身打造的，可能包含您平台專屬的重要指示。
3. 開啟您的 Unity 專案。
4. 瀏覽至您儲存 .unitypackage 的位置，然後按兩下以開啟匯入對話方塊。
5. 若要將 PlayFab Multiplayer Unity 外掛程式匯入您的專案，請選取 Import。

注意：如有必要，您可能需要安裝較新版本的 PlayFab「核心」Unity SDK。

​

設定您的場景

本指南的這一部分說明如何將 PlayfabMultiplayerEventProcessor 新增至您的場景，讓您能夠從 Unity 呼叫 PlayFab Multiplayer API。 在使用 Multiplayer API 之前，您必須有已登入的 PlayFab 玩家。如需登入玩家的相關資訊，請參閱快速入門：Unity 中適用於 C# 的 PlayFab 用戶端程式庫中的進行您的第一個 API 呼叫。

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 陳述式新增至您的指令碼：
   using PlayFab;
   using PlayFab.Multiplayer;
   using PlayFab.ClientModels;
   
10. 在 Start 方法中新增下列程式碼以登入 PlayFab。
    // Log into playfab
    var request = new LoginWithCustomIDRequest { CustomId = UnityEngine.Random.value.ToString(), CreateAccount = true };
    PlayFabClientAPI.LoginWithCustomID(request, OnLoginSuccess, OnLoginFailure);
    
11. 將下列方法新增至類別。
    private void OnLoginSuccess(LoginResult result)
    {
    }
    
    private void OnLoginFailure(PlayFabError error)
    {
    }
    

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 方法中，新增下列程式碼以建立並加入大廳：
   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 事件處理常式，請將下列程式碼新增至類別：
   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 事件處理常式，請將下列程式碼新增至類別：
   private void PlayFabMultiplayer_OnLobbyDisconnected(Lobby lobby)
   {
       // Disconnected from lobby
       Debug.Log("Disconnected from lobby!");
   }
   
4. 儲存並在 Unity 編輯器中選取 Play。大廳連接字串會顯示在 Console 視窗中。

​

加入大廳

本指南的這一部分說明如何加入其他用戶端所建立的現有大廳。

1. 開啟 HelloMultiplayerLogic.cs 指令碼。在 OnLoginSuccess 方法中，新增下列程式碼以加入大廳：
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   
   string connectionString = "<your lobby connection string>";
   
   PlayFabMultiplayer.JoinLobby(
           entityKey,
           connectionString,
           null);
   
2. 若要定義在本機用戶端加入大廳時觸發的事件，請將下列程式碼新增至 OnLoginSuccess 方法：
   PlayFabMultiplayer.OnLobbyJoinCompleted += this.PlayFabMultiplayer_OnLobbyJoinCompleted;
   
3. 若要定義 OnLobbyJoinCompleted 事件處理常式，請將下列程式碼新增至類別：
   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 方法中，新增下列程式碼以尋找大廳：
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   
   LobbySearchConfiguration config = new LobbySearchConfiguration();
   PlayFabMultiplayer.FindLobbies(entityKey, config);
   
2. 若要定義在本機用戶端找到大廳時觸發的事件，請將下列程式碼新增至 OnLoginSuccess 方法：
   PlayFabMultiplayer.OnLobbyFindLobbiesCompleted += this.PlayFabMultiplayer_OnLobbyFindLobbiesCompleted;
   
3. 若要定義 OnLobbyFindLobbiesCompleted 事件處理常式，請將下列程式碼新增至類別：
   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 方法中，新增下列程式碼以建立配對票證：
   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 事件處理常式，請將下列程式碼新增至類別：
   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 方法中，新增下列程式碼以加入配對票證：
   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 事件處理常式，請將下列程式碼新增至類別：
   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，且 Status 為 WaitingForMatch。

​

完成配對票證

本指南的這一部分說明配對是如何完成的。請在另一個用戶端上搭配上方的「建立配對票證」情境執行。您也可以選擇搭配「加入配對票證」情境執行。

1. 一旦同一佇列中的多張票證符合配對資格，就會找到比賽。在此情況下， 會觸發 OnMatchmakingTicketCompleted 事件處理常式。
2. 訂閱 OnMatchmakignTicketCompleted 處理常式
   PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketCompleted;
   
3. 若要定義 OnMatchmakingTicketCompleted 事件處理常式，請將下列程式碼新增至類別：
   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");
       }
   }