Party 快速入门

本快速入门通过代码片段介绍 PlayFab Party 的核心功能。PlayFab Party 从设计之初就是跨平台的。我们以同样的方式组织了这些快速入门,大部分信息适用于所有平台,平台特定的先决条件和步骤在链接的文档中进行了说明。如需更深入的了解,请查阅链接的参考和概念文档以及各平台的示例应用程序。

本快速入门指南涵盖 C++ Party SDK 的使用 * 对于 Unity 用户,请参阅 Unity 快速入门 * 对于希望使用 PlayFab Online Subsystem for Unreal Engine 的 Unreal Engine 用户,请参阅 Unreal 快速入门。

先决条件

你需要一个 PlayFab 账户,并且必须启用 Party 功能才能开始使用 Party。

创建或登录你的 PlayFab 账户。有关说明,请参阅 Game Manager 快速入门。
从你的 PlayFab 账户通过 Game Manager 启用 Party 功能。

平台先决条件

在开始本快速入门之前,请按照以下主题中指定的方式执行任何必要的平台特定设置:

Linux 先决条件

完成平台特定步骤后,继续执行本主题中其余的步骤以设置 PlayFab Party。

下载并设置 Party SDK

不同平台和游戏引擎有不同的 Party SDK。选择并下载你需要的 SDK。有关下载链接,请参阅 Party SDK。安装 SDK 后,你可能希望在开始编写代码前运行一个示例,了解 Party 的工作方式。若要下载示例,请转到 Party 示例。如果你在 XBOX 和 PC 标题中使用 Party,建议使用 Party XBOX Live 辅助库以确保功能和行为的一致性。此库有助于让你的标题满足 XBOX Live 要求。要了解更多信息,请参阅 XBOX 要求。

登录你的 PlayFab Title 并获取实体令牌和实体 ID

若要初始化和使用 Party,你必须登录 PlayFab。你可以使用 PlayFabClientAPI::LoginWithCustomID 或平台特定的登录方法。执行登录后,PlayFab 会将实体 ID 和实体令牌作为 LoginResult 的一部分返回。这两条关键信息用于为 PlayFab Party 初始化本地用户实例。在 PlayFabManager.cpp 中实现的使用自定义 ID 登录的示例如以下代码片段所示:

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 获取实体 ID 和实体令牌后,你可以继续启用并初始化 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 实体 ID 进行初始化。

    //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 Manager 接收消息。有关所有状态更改的完整说明,请参阅 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 Title 并获取实体令牌和实体 ID

初始化 PlayFab Party

创建 Party 网络

分享 Party 网络描述符

手动分享 Party 网络描述符

使用 PlayFab Lobby 分享 Party 网络描述符

启用可扩展网络

连接到 Party 网络

向另一个网络设备或终结点发送消息

接收消息并在本地设备上呈现

处理标题挂起

iOS

Switch 和 GDK

后续步骤

另请参阅

​先决条件

​平台先决条件

​下载并设置 Party SDK

​登录你的 PlayFab Title 并获取实体令牌和实体 ID

​初始化 PlayFab Party

​创建 Party 网络

​分享 Party 网络描述符

​手动分享 Party 网络描述符

​使用 PlayFab Lobby 分享 Party 网络描述符

​启用可扩展网络

​连接到 Party 网络

​向另一个网络设备或终结点发送消息

​接收消息并在本地设备上呈现

​处理标题挂起

​iOS

​Switch 和 GDK

​后续步骤

​另请参阅

先决条件

平台先决条件

下载并设置 Party SDK

登录你的 PlayFab Title 并获取实体令牌和实体 ID

初始化 PlayFab Party

创建 Party 网络

分享 Party 网络描述符

手动分享 Party 网络描述符

使用 PlayFab Lobby 分享 Party 网络描述符

启用可扩展网络

连接到 Party 网络

向另一个网络设备或终结点发送消息

接收消息并在本地设备上呈现

处理标题挂起

iOS

Switch 和 GDK

后续步骤

另请参阅