Party 快速入門

本快速入門搭配程式碼片段說明 PlayFab Party 的核心功能。PlayFab Party 從一開始就設計為跨平台。我們以相同的方式建構這些快速入門，其中大部分資訊適用於所有平台，而平台專屬的先決條件和步驟則在連結的文件中說明。如需更深入的了解，請參閱連結的參考和概念文件，以及各平台的範例應用程式。

本快速入門指南涵蓋 C++ Party SDK 的使用方式 * Unity 使用者請參閱 Unity 快速入門 * 想要使用 Unreal Engine 的 PlayFab Online Subsystem 的 Unreal Engine 使用者，請參閱 Unreal 快速入門。

先決條件

您需要 PlayFab 帳戶，而且必須啟用 Party 功能才能開始使用 Party。

建立或登入您的 PlayFab 帳戶。如需指示，請參閱快速入門：Game Manager。
從您的 PlayFab 帳戶透過 Game Manager 啟用 Party 功能。

平台先決條件

開始本快速入門之前，請依照下列主題中的指定執行任何必要的平台專屬設定：

<!—3. Nintendo Switch prerequisites—>

Linux 先決條件

完成平台專屬步驟後，請繼續進行本主題中的其餘步驟以設定 PlayFab Party。

下載並設定 Party SDK

Party SDK 適用於不同的平台和遊戲引擎。請選取並下載您需要的 SDK。如需下載連結，請參閱 Party SDK。安裝 SDK 之後，您可能會想要在開始撰寫程式碼之前執行範例，以了解 Party 的運作方式。若要下載範例，請前往 Party 範例。如果您在 XBOX 和 PC 遊戲中使用 Party，建議使用 Party XBOX Live 協助程式庫，以確保一致的功能和行為。此程式庫可協助您的遊戲符合 XBOX Live 需求。若要深入了解，請參閱 XBOX 需求。

登入您的 PlayFab 遊戲並取得實體權杖和實體識別碼

若要初始化及使用 Party，您必須登入 PlayFab。您可以使用 PlayFabClientAPI::LoginWithCustomID 或平台專屬的登入方法。執行登入之後，PlayFab 會在 LoginResult 中傳回實體識別碼和實體權杖。這兩項關鍵資訊用於初始化 PlayFab Party 的本機使用者執行個體。此程式碼片段顯示 PlayFabManager.cpp 中實作的自訂識別碼登入範例：

PlayFabClientAPI::LoginWithCustomID(
    loginRequest,
    [this, callback, userId](const LoginResult& loginResult, void*)
    {
        // Sign in was successful.
        DEBUGLOG("PlayFab::signin -- Login with custom id callback\n");

        // Save the PlayFab id and entity data for Party authentication.
        m_playfabId = loginResult.PlayFabId;
        if (loginResult.EntityToken.notNull() && loginResult.EntityToken->Entity.notNull())
        {
            m_entityKey = loginResult.EntityToken->Entity;
            m_entityToken = loginResult.EntityToken->EntityToken;
        }

成功從 PlayFab 取得實體識別碼和實體權杖之後，就可以繼續啟用並初始化 Party。

如果您使用 XBOX Live，也可以使用 Party XBOX Live 協助程式庫登入。

初始化 PlayFab Party

概括來說，初始化 Party 包含下列步驟：

取得 PartyManager 的單一參考並加以初始化。
這是與 Party 程式庫互動的主要管理類別。

    auto& partyManager = PartyManager::GetSingleton();
    PartyError err;

    //Only initialize the party manager once.
    if (m_partyInitialized == false)
    {
        // Initialize PlayFab Party
        err = partyManager.Initialize(titleId);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Initialize failed: %s\n", GetErrorMessage(err));
            return;
        }

        m_partyInitialized = true;
    }

建立本機使用者物件。
執行網路和聊天作業時，此本機使用者物件用來代表裝置 (PC、主機、手機等) 上的本機使用者。本機使用者物件會以 PlayFab 實體識別碼初始化。

    //Only create a local user object if it doesn't exist.
    if (m_localUser == nullptr)
    {
        PartyString entityId = Managers::Get<PlayFabManager>()->EntityId().c_str();
        PartyString entityToken = Managers::Get<PlayFabManager>()->EntityToken().c_str();

        // Create a local user object
        err = partyManager.CreateLocalUser(
            entityId,                                   // User id
            entityToken,                                // User entity token
            &m_localUser                                // OUT local user object
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("CreateLocalUser failed: %s\n", GetErrorMessage(err));
            return;
        }
    }

建立聊天控制項，並設定 Party 接收或轉送資料的音訊輸入和輸出通道。
聊天控制項物件會管理特定裝置上使用者的聊天作業。

    // Only create local chat controls if they don't exist.
    if (m_localChatControl == nullptr)
    {
        PartyLocalDevice* localDevice = nullptr;

        // Retrieve the local device
        err = partyManager.GetLocalDevice(&localDevice);

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("GetLocalDevice failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Create a chat control for the local user on the local device
        err = localDevice->CreateChatControl(
            m_localUser,                                // Local user object
            m_languageCode,                             // Language id
            nullptr,                                    // Async identifier
            &m_localChatControl                         // OUT local chat control
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("CreateChatControl failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Use system default settings for the audio input device
        err = m_localChatControl->SetAudioInput(
            PartyAudioDeviceSelectionType::SystemDefault,   // Selection type
            nullptr,                                        // Device id
            nullptr                                         // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetAudioInput failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Use system default settings for the audio output device
        err = m_localChatControl->SetAudioOutput(
            PartyAudioDeviceSelectionType::SystemDefault,   // Selection type
            nullptr,                                        // Device id
            nullptr                                         // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetAudioOutput failed: %s\n", GetErrorMessage(err));
        }

設定轉譯和翻譯選項。
轉譯和翻譯是選用的聊天功能，可大幅提高遊戲的無障礙程度。您可以在聊天概觀中找到這些功能的詳細資訊。

        // Get the available list of text to speech profiles
        err = m_localChatControl->PopulateAvailableTextToSpeechProfiles(nullptr);

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Populating available TextToSpeechProfiles failed: %s \n", GetErrorMessage(err));
        }

        // Set transcription options for transcribing other users regardless of language, and ourselves.
        PartyVoiceChatTranscriptionOptions transcriptionOptions =
            PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithMatchingLanguages |
            PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithNonMatchingLanguages |
            PartyVoiceChatTranscriptionOptions::TranslateToLocalLanguage |
            PartyVoiceChatTranscriptionOptions::TranscribeSelf;

        // Set the transcription options on our chat control.
        err = m_localChatControl->SetTranscriptionOptions(
            transcriptionOptions,                       // Transcription options
            nullptr                                     // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetTranscriptionOptions failed: %s\n", GetErrorMessage(err));
        }

        // Enable translation to local language in chat controls.
        err = m_localChatControl->SetTextChatOptions(
            PartyTextChatOptions::TranslateToLocalLanguage,
            nullptr
        );

此時，您已在應用程式或遊戲中初始化 PlayFab Party。如需完整範例，請參閱示範應用程式 NetworkManager.cpp 中的 NetworkManager::Initialize() 程式碼。下一個步驟是建立 Party 網路並連線到該網路。

建立 Party 網路

Party 網路是遊戲為交換聊天或資料通訊而建立的安全集合，包含一或多個裝置及其授權的使用者。Party 網路通常對應遊戲的多人遊戲工作階段或聊天「大廳」概念。您只能傳送訊息給自己網路內的玩家。下列程式碼片段顯示如何建立 Party 網路。

    // Set the maximum number of devices allowed in a network to 16 devices
    constexpr uint8_t c_maxSampleNetworkDeviceCount = 16;
    static_assert(c_maxSampleNetworkDeviceCount <= c_maxNetworkConfigurationMaxDeviceCount, "Must be less than or equal to c_maxNetworkConfigurationMaxDeviceCount.");

    // Initialize network configuration for Party Network.
    PartyNetworkConfiguration cfg = {};
    cfg.maxDeviceCount = c_maxSampleNetworkDeviceCount;
    cfg.maxUserCount = c_maxSampleNetworkDeviceCount;
    ...
    
    // Initialize an empty network descriptor to hold the result of the following call.
    PartyNetworkDescriptor networkDescriptor = {};

    // Create a new network descriptor
    err = PartyManager::GetSingleton().CreateNewNetwork(
        m_localUser,                                // Local User
        &cfg,                                       // Network Config
        0,                                          // Region List Count
        nullptr,                                    // Region List
        &invitationConfiguration,                   // Invitation configuration
        nullptr,                                    // Async Identifier
        &networkDescriptor,                         // OUT network descriptor
        nullptr                                     // applied initialinvitationidentifier.
    );

CreateNewNetwork() 函式呼叫成功後，會傳回/填入網路描述元 PartyNetworkDescriptor 物件。描述元包含其他玩家連線到網路所需的資料。如需其他函式參數的資訊，請參閱 API 參考文件。建立 Party 網路之後，會使用邀請來控制哪些使用者可以加入網路。可以使用 PlayFab Matchmaking、PlayFab Lobby、平台邀請或自訂遊戲服務，與其他玩家分享連線詳細資料。最簡單的邀請類型是由網路描述元組成的開放邀請。如需所有邀請類型和安全性模型的詳細資訊，請參閱邀請與安全性模型。

分享 Party 網路描述元

此時，您已擁有 Party 網路描述元，並準備好與其他玩家分享。有許多同步機制可用來分享此資訊，但為了快速測試，您可以手動將 Party 網路描述元從主機 Party 工作階段複製並貼上到來賓 Party 工作階段。建議在多人遊戲中使用 PlayFab Lobby 分享網路描述元，但您也可以根據遊戲需求使用自己的大廳服務、邀請或其他分享機制。

手動分享 Party 網路描述元

從主機工作階段使用 PartyManager::SerializeNetworkDescriptor() 將網路描述元序列化為字串，並將其輸出到主控台。
將網路描述元字串複製並貼上到本機或遠端的另一個遊戲。
在來賓工作階段中，使用 PartyManager::DeserializeNetworkDescriptor() 從網路描述元字串還原序列化網路描述元。
連線到 Party 網路。

使用 PlayFab Lobby 分享 Party 網路描述元

PlayFab Lobby 可在玩家進出比賽時暫時將玩家分組，並可用來同步網路描述元，讓玩家能加入同一個網路。 PlayFab Lobby 具有高度可自訂性，可支援所有支援平台上和跨平台的各種遊戲玩法需求。如需搭配即時訊息使用 PlayFab Lobby 的詳細資訊，請參閱 Multiplayer SDK 快速入門。如需同時使用 PlayFab Lobby 與 PlayFab Party 的詳細資料，請參閱使用 PlayFab Multiplayer SDK 建立大廳。

啟用可調整規模的網路

PlayFab Party 網路可以調整規模，支援 2 到 128 個裝置。服務會選擇針對您的案例最佳化的轉送設定，因此請務必將 PartyNetworkConfiguration 中的 maxDeviceCount 設定為符合網路中預期的裝置數目上限。如需可調整規模網路的說明，請參閱可調整規模的網路。

連線到 Party 網路

取得 Party 網路描述元之後，請依照下列步驟加入 Party 網路：

使用 PartyManager::DeserializeNetworkDescriptor() 從網路描述元字串還原序列化網路描述元。
連線到 Party 網路。
在網路上驗證本機使用者。
將本機聊天控制項連線到網路，以便使用 VOIP。
為遊戲訊息流量建立 Party 網路端點。

    PartyNetworkDescriptor networkDescriptor = {};

    // Deserialize the remote network's descriptor
    PartyError err = PartyManager::DeserializeNetworkDescriptor(descriptor, &networkDescriptor);

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed to deserialize descriptor: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return;
    }

    // This portion of connecting to the network is the same for
    // both creating a new and joining an existing network.

    PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
        &descriptor,                                // Network descriptor
        nullptr,                                    // Async identifier
        &m_network                                  // OUT network
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Authenticate the local user on the network so we can participate in it
    err = m_network->AuthenticateLocalUser(
        m_localUser,                                // Local user
        networkId,                                  // Invitation Id
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Connect the local user chat control to the network so we can use VOIP
    err = m_network->ConnectChatControl(
        m_localChatControl,                         // Local chat control
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Establish a network endoint for game message traffic
    err = m_network->CreateEndpoint(
        m_localUser,                                // Local user
        0,                                          // Property Count
        nullptr,                                    // Property name keys
        nullptr,                                    // Property Values
        nullptr,                                    // Async identifier
        &m_localEndpoint                            // OUT local endpoint
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

傳送訊息至另一個網路裝置或端點

連線到 Party 網路之後，就可以使用本機端點物件傳送訊息。

    if (m_localEndpoint && m_state == NetworkManagerState::NetworkConnected)
    {
        auto packet = message.Serialize();

        // Form the data packet into a data buffer structure
        PartyDataBuffer data[] = {
            {
                static_cast<const void*>(packet.data()),
                static_cast<uint32_t>(packet.size())
            },
        };

        // Set delivery options for guaranteed and sequential delivery.
        PartySendMessageOptions deliveryOptions =
            PartySendMessageOptions::GuaranteedDelivery |
            PartySendMessageOptions::SequentialDelivery;

        // Send out the message to all other peers
        PartyError err = m_localEndpoint->SendMessage(
            0,                                      // endpoint count; 0 = broadcast
            nullptr,                                // endpoint list
            deliveryOptions,                        // send message options
            nullptr,                                // configuration
            1,                                      // buffer count
            data,                                   // buffer
            nullptr                                 // async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Failed to SendMessage: %s\n", GetErrorMessage(err));
        }
    }

完整程式碼可在 NetworkManager.cpp 中取得。

接收訊息並在本機裝置上轉譯

最後一個步驟是接收遠端 Party 成員傳送的訊息，並在您的裝置上轉譯 (播放) 這些訊息。

在先前步驟中建立聊天控制項時，您已設定 Party 用來傳送、接收和轉譯音訊資料的音訊輸入和輸出裝置。若要接收音訊訊息，如果您想要讓音訊流通，還需要在每個聊天控制項之間設定適當的聊天權限。根據預設，聊天權限設定為 NONE。如需詳細資訊，請參閱聊天權限一文。

處理來自 Party 層的其他訊息，最好在專用的更新執行緒或高頻率的遊戲迴圈中完成。遊戲迴圈應設定為每個畫面執行一次，並透過 StartProcessingStateChanges() 函式從 Party 管理員接收訊息。如需所有狀態變更的完整說明，請參閱 Party 參考文件。或者，您也可以參閱 NetworkManager.cpp，以取得如何處理每個狀態變更的範例。

處理遊戲暫停

某些平台支援暫時暫停遊戲的執行：iOS、Switch 和 GDK。當您的遊戲暫停時，網路堆疊會失效，且 PlayFab Party 無法維持與 PlayFab Party 網路的連線。使用 PlayFab Party 時，需要特別考量如何處理遊戲執行的暫停和繼續。

iOS

在 iOS 上，您必須離開並重新連線到 PlayFab Party 網路若要離開 Party 網路，請呼叫 LeaveNetwork()。網路重新啟用後，使用先前的 Party 網路描述元呼叫 ConnectToNetwork()。

Switch 和 GDK

在 Nintendo Switch 和 Microsoft GDK 上，您必須清除 PlayFab Party，並等候遊戲恢復執行，再重新初始化 PlayFab Party 並重新連線到網路。若要關閉 Party，請呼叫 Cleanup()。

呼叫 Cleanup() 會回收所有程式庫資源並終結所有程式庫物件。重新初始化 Party 之後，您需要重新建立任何程式庫物件 (例如本機使用者和聊天控制項)，並藉由重新驗證本機使用者、重新連線聊天控制項和重新建立端點，重新建立任何先前的網路狀態。

網路重新啟用後，呼叫 Initialize()。Party 成功初始化後，需要執行下列步驟，才能成功再次加入先前的 PlayFab Party 網路：

使用先前的 Party 網路描述元連線到 Party 網路。
重新建立任何本機使用者物件，並將這些本機使用者重新驗證到網路中。
重新建立任何本機聊天控制項，並將這些聊天控制項重新連線到網路以啟用 VOIP
為遊戲訊息流量重新建立任何 Party 網路端點。

    PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
        &descriptor,                                // Network descriptor
        nullptr,                                    // Async identifier
        &m_network                                  // OUT network
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Authenticate the local user on the network so we can participate in it
    err = m_network->AuthenticateLocalUser(
        m_localUser,                                // Local user
        networkId,                                  // Invitation Id
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Connect the local user chat control to the network so we can use VOIP
    err = m_network->ConnectChatControl(
        m_localChatControl,                         // Local chat control
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Establish a network endoint for game message traffic
    err = m_network->CreateEndpoint(
        m_localUser,                                // Local user
        0,                                          // Property Count
        nullptr,                                    // Property name keys
        nullptr,                                    // Property Values
        nullptr,                                    // Async identifier
        &m_localEndpoint                            // OUT local endpoint
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

如果重新連線成功完成，Party 現在就能與其他對等端通訊，但如果先前的網路已不存在，重新連線將會失敗。在這種情況下，您應該處理適當的連線錯誤。

後續步驟

深入了解 PlayFab Party 物件及其關聯，並參閱 Party API 參考文件，讓您的遊戲能充分運用這些功能。如需更多 XBOX 專屬指引，請儘早並經常參閱 XBOX 需求。

XBOX Services

PlayFab

先決條件

平台先決條件

下載並設定 Party SDK

登入您的 PlayFab 遊戲並取得實體權杖和實體識別碼

初始化 PlayFab Party

建立 Party 網路

分享 Party 網路描述元

手動分享 Party 網路描述元

使用 PlayFab Lobby 分享 Party 網路描述元

啟用可調整規模的網路

連線到 Party 網路

傳送訊息至另一個網路裝置或端點

接收訊息並在本機裝置上轉譯

處理遊戲暫停

iOS

Switch 和 GDK

後續步驟

另請參閱

​先決條件

​平台先決條件

​下載並設定 Party SDK

​登入您的 PlayFab 遊戲並取得實體權杖和實體識別碼

​初始化 PlayFab Party

​建立 Party 網路

​分享 Party 網路描述元

​手動分享 Party 網路描述元

​使用 PlayFab Lobby 分享 Party 網路描述元

​啟用可調整規模的網路

​連線到 Party 網路

​傳送訊息至另一個網路裝置或端點

​接收訊息並在本機裝置上轉譯

​處理遊戲暫停

​iOS

​Switch 和 GDK

​後續步驟

​另請參閱

先決條件

平台先決條件

下載並設定 Party SDK

登入您的 PlayFab 遊戲並取得實體權杖和實體識別碼

初始化 PlayFab Party

建立 Party 網路

分享 Party 網路描述元

手動分享 Party 網路描述元

使用 PlayFab Lobby 分享 Party 網路描述元

啟用可調整規模的網路

連線到 Party 網路

傳送訊息至另一個網路裝置或端點

接收訊息並在本機裝置上轉譯

處理遊戲暫停

iOS

Switch 和 GDK

後續步驟

另請參閱