> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 功能](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/enable-party.md)。

> [!NOTE]
>
> 如果您打算使用此外掛程式開發以 Microsoft Game Development Kit (GDK) 為基礎的遊戲，需要另外取得並安裝 GDK。另請參閱 XBOX 主機上 Game Core 的 Unity 附加元件詳細資料。

## 需求

* [PlayFab 開發人員帳戶](https://developer.playfab.com)。

* 已安裝的 Unity Editor。若要透過 Unity Hub 安裝個人使用的 Unity，或專業使用的 Unity+，請參閱[下載 Unity](https://unity3d.com/get-unity/download)。必要時，請在特定平台的文件中確認 Unity 支援情況。支援的最低 Unity 版本為 Unity 2017 LTS。

* Unity 專案，可以是下列任一選項：

  * 全新專案：如需詳細資訊，請參閱[第一次啟動 Unity](https://docs.xbox.com/zh-TW/services/playfab/sdks/unity3d/quickstart.md)。
  * 引導式教學課程專案。如需詳細資訊，請參閱[開始使用 Unity](https://learn.unity.com/)。
  * 現有專案。

* PlayFab「核心」Unity3D SDK。如需安裝 Unity3D SDK 的資訊，請參閱[快速入門：Unity 中的 C# 版 PlayFab 用戶端程式庫](https://docs.xbox.com/zh-TW/services/playfab/sdks/unity3d/quickstart.md#download-and-install-playfab-sdk)的「下載並安裝 PlayFab SDK」一節。

## 下載並安裝 PlayFab Party Unity 外掛程式

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

1. 下載 PlayFab [Party Unity 外掛程式](https://github.com/playfab/PlayFabPartyUnity)資產套件 (依您的平台使用對應的散發點)。
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 呼叫](https://docs.xbox.com/zh-TW/services/playfab/sdks/unity3d/quickstart.md#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" 並按 Enter，以顯示新指令碼功能表。

7. 再按一次 Enter 以建立新指令碼 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".`

Microsoft GDK 和 Windows 僅支援 x64。

若要解決這些問題：

1. 在 Unity Editor 中，選取 **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 Editor 中選取 Play。網路識別碼會顯示在 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!");
       }
   ```

   有許多方式可以將網路識別碼從主機傳遞給其他想要加入的玩家。如需如何執行此作業的範例，請參閱此 Unity 外掛程式中的範例。

4. 儲存並在 Unity Editor 中選取 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 Editor 中選取 Play。

1. 在第二個用戶端中，重複[連線到網路](#connecting-to-a-network)中的步驟，以建立並加入網路。
2. 將傳回的網路識別碼複製到第一個用戶端，並連線到網路。
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 Editor 中按 Play。

1. 在第二個用戶端中，重複[連線到網路](#connecting-to-a-network)中的步驟，以建立並加入網路。
2. 將傳回的網路識別碼複製到第一個用戶端，並連線到網路。
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](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/unity-party-api-reference/enums/partyunitydirectpeerconnectivityoptions.md)。此範例顯示如何設定 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()](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunityresetparty.md) 來達成

### Switch 和 GDK

在 Nintendo Switch 和 Microsoft GDK 上，您必須清除 PlayFab Party 以及與 PlayFabMultiplayerManager 相關聯的所有資源，然後等候遊戲恢復執行，再重新初始化 PlayFab Party 並重新連線到網路。

若要在遊戲暫停期間清除 PlayFab Party，請呼叫 [Suspend()](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunitysuspend.md)。遊戲恢復執行後，請呼叫 [Resume()](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/methods/playfabunityresume.md) 以重新初始化 PlayFab Party。

成功初始化 PlayFab Party 以及與 PlayFabMultiplayerManager 相關聯的所有資源後，請重複[加入現有網路](#joining-an-existing-network)的步驟。


## Related topics

- [Multiplayer Unity 外掛程式快速入門](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [PlayFab SDK Unreal Engine Marketplace 外掛程式整合指南](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/party-unreal-engine-oss-playfab-plugin-integration.md)
- [Unity 快速入門](https://docs.xbox.com/zh-TW/services/playfab/sdks/unity3d/quickstart.md)
- [Party Unity 外掛程式概觀](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/party-unity-overview.md)
- [PlayFab Party Unity 外掛程式版本資訊](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/party-unity-release-notes.md)