Início rápido do Party

Este início rápido descreve a funcionalidade principal do PlayFab Party, junto com trechos de código. O PlayFab Party foi projetado desde o início para ser multiplataforma. Estruturamos estes inícios rápidos da mesma forma: a maioria das informações se aplica a todas as plataformas, e os pré-requisitos e etapas específicos de cada plataforma são descritos nos documentos vinculados. Para uma compreensão mais aprofundada, consulte a documentação de referência e conceitual vinculada e os aplicativos de exemplo de cada plataforma.

Este guia de início rápido aborda o uso do SDK C++ do Party * Usuários do Unity devem consultar o Início rápido do Unity * Usuários do Unreal Engine que desejam usar o PlayFab Online Subsystem para o Unreal Engine devem consultar o Início rápido do Unreal.

Pré-requisitos

Você precisa de uma conta do PlayFab e deve habilitar o recurso Party para começar a usar o Party.

Crie ou entre na sua conta do PlayFab. Para obter instruções, confira Início rápido: Game Manager.
Habilite o recurso Party por meio do Game Manager na sua conta do PlayFab.

Pré-requisitos da plataforma

Antes de iniciar este início rápido, execute qualquer configuração específica da plataforma necessária, conforme especificado nos seguintes tópicos:

<!—3. Nintendo Switch prerequisites—>

Pré-requisitos do Linux

Ao concluir as etapas específicas da plataforma, continue com as demais etapas deste tópico para configurar o PlayFab Party.

Baixar e configurar o SDK do Party

Há SDKs do Party para diferentes plataformas e mecanismos de jogo. Selecione e baixe o de que você precisa. Para obter os links de download, confira SDKs do Party. Depois de instalar o SDK, talvez você queira executar um exemplo para ver como o Party funciona antes de começar a escrever código. Para baixar um exemplo, acesse Exemplos do Party. Se estiver usando o Party em títulos para XBOX e PC, recomendamos que você use a Party XBOX Live Helper Library para garantir funcionalidade e comportamento consistentes. Essa biblioteca ajuda seu título a atender aos requisitos do XBOX Live. Para saber mais, confira Requisitos do XBOX. Para inicializar e usar o Party, você precisa fazer login no PlayFab. Você pode usar PlayFabClientAPI::LoginWithCustomID ou um método de login específico da plataforma. Depois que você executa o login, o PlayFab retorna uma ID de entidade e um token de entidade como parte do LoginResult. Essas duas informações essenciais são usadas para inicializar uma instância de usuário local do PlayFab Party. Um exemplo de login com uma ID personalizada, conforme implementado em PlayFabManager.cpp, é mostrado neste trecho de código:

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;
        }

Depois de obter com êxito a ID de entidade e o token de entidade do PlayFab, você pode prosseguir com a habilitação e, em seguida, com a inicialização do Party.

Se estiver usando o XBOX Live, você também pode usar a Party XBOX Live Helper Library para fazer login.

Inicializar o PlayFab Party

Em linhas gerais, a inicialização do Party envolve as seguintes etapas:

Obter uma referência singleton ao PartyManager e inicializá-lo.
Essa é a principal classe de gerenciamento para interagir com a biblioteca do 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;
    }

Criar um objeto de usuário local.
Esse objeto de usuário local é usado para representar um usuário local no dispositivo (PC, console, telefone etc.) ao realizar operações de rede e de chat. O objeto de usuário local é inicializado com a ID de entidade do 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;
        }
    }

Criar um controle de chat e definir o canal de entrada e saída de áudio em que o Party receberá ou encaminhará os dados.
O objeto de controle de chat gerencia as operações de chat do usuário no dispositivo específico.

    // 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));
        }

Definir as opções de transcrição e tradução.
A transcrição e a tradução são recursos de chat opcionais que podem aumentar significativamente a acessibilidade do seu jogo. Você pode encontrar mais informações sobre esses recursos na Visão geral do chat.

        // 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
        );

Neste ponto, o PlayFab Party está inicializado no seu aplicativo ou jogo. Consulte o código de NetworkManager::Initialize() em NetworkManager.cpp no aplicativo de demonstração para ver um exemplo completo. A próxima etapa é criar uma rede do Party e se conectar a ela.

Criar uma rede do Party

Uma rede do Party é um conjunto protegido de um ou mais dispositivos e seus usuários autorizados que o jogo cria para trocar comunicação de chat ou de dados. Uma rede do Party normalmente corresponde ao conceito de sessão multijogador ou de “lobby” de chat de um jogo. Você só pode enviar mensagens para jogadores dentro da sua própria rede. O trecho de código a seguir mostra como podemos criar uma rede do 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.
    );

Depois que a chamada à função CreateNewNetwork() é bem-sucedida, um objeto de descritor de rede PartyNetworkDescriptor é retornado/preenchido. O descritor contém os dados necessários para que outros jogadores se conectem a uma rede. Consulte a Documentação de referência da API para obter informações sobre os outros parâmetros da função. Depois que uma rede do Party é criada, os convites são usados para controlar quais usuários podem ingressar na rede. O PlayFab Matchmaking, o PlayFab Lobby, convites da plataforma ou serviços de jogo personalizados podem ser usados para compartilhar os detalhes de conexão com outros jogadores. O tipo de convite mais simples é um convite aberto, que consiste em um descritor de rede. Para obter informações detalhadas sobre todos os tipos de convite e o modelo de segurança, consulte Convites e o modelo de segurança.

Compartilhar o descritor de rede do Party

Neste ponto, você tem um descritor de rede do Party e está pronto para compartilhá-lo com outros jogadores. Há muitos mecanismos de sincronização que você pode usar para compartilhar essas informações, mas, para fins de testes rápidos, você pode copiar e colar manualmente o descritor de rede do Party da sessão do Party do host para a sessão do Party do convidado. Recomendamos usar o PlayFab Lobby para compartilhar o descritor de rede no seu jogo multijogador, mas você também pode usar seu próprio serviço de lobby, convites ou outros mecanismos de compartilhamento, de acordo com as necessidades do seu jogo.

Compartilhar manualmente o descritor de rede do Party

Na sessão do host, use PartyManager::SerializeNetworkDescriptor() para serializar o descritor de rede em uma cadeia de caracteres e imprimi-la no console.
Copie e cole a cadeia de caracteres do descritor de rede em outro jogo, local ou remotamente.
Na sessão do convidado, use PartyManager::DeserializeNetworkDescriptor() para desserializar o descritor de rede a partir da cadeia de caracteres do descritor de rede.
Conecte-se à rede do Party.

Usar o PlayFab Lobby para compartilhar o descritor de rede do Party

O PlayFab Lobby pode ser usado para agrupar temporariamente os jogadores à medida que eles entram e saem de partidas e pode ser usado para sincronizar o descritor de rede para que os jogadores possam ingressar na mesma rede. O PlayFab Lobby é altamente personalizável para dar suporte a uma grande variedade de necessidades de jogabilidade em todas as plataformas com suporte e entre plataformas. Consulte o Início rápido do Multiplayer SDK para obter mais detalhes sobre o uso do PlayFab Lobby com mensagens em tempo real. Para obter detalhes sobre o uso do PlayFab Lobby junto com o PlayFab Party, consulte Criar um lobby com o PlayFab Multiplayer SDK.

Habilitar redes escalonáveis

As redes do PlayFab Party podem ser dimensionadas para dar suporte a entre 2 e 128 dispositivos. O serviço escolherá uma configuração de retransmissão otimizada para o seu cenário, portanto, é importante configurar o maxDeviceCount em PartyNetworkConfiguration para corresponder ao número máximo esperado de dispositivos na sua rede. Para obter uma descrição das redes escalonáveis, confira Redes escalonáveis.

Conectar-se a uma rede do Party

Siga as etapas abaixo para ingressar na rede do Party depois de obter o descritor de rede do Party:

Use PartyManager::DeserializeNetworkDescriptor() para desserializar o descritor de rede a partir da cadeia de caracteres do descritor de rede.
Conecte-se à rede do Party.
Autentique o usuário local na rede.
Conecte o controle de chat local à rede para que possamos usar o VOIP.
Estabeleça um ponto de extremidade de rede do Party para o tráfego de mensagens do jogo.

    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;
    }

Enviar uma mensagem para outro dispositivo ou ponto de extremidade da rede

Depois de se conectar à rede do Party, você pode enviar uma mensagem usando o objeto de ponto de extremidade local.

    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));
        }
    }

O código completo está disponível em NetworkManager.cpp.

Receber uma mensagem e renderizá-la no dispositivo local

A etapa final é receber as mensagens enviadas pelos membros remotos do Party e renderizá-las (reproduzi-las) no seu dispositivo.

Ao criar o controle de chat em uma das etapas anteriores, você já configurou os dispositivos de entrada e saída de áudio usados pelo Party para enviar, receber e renderizar dados de áudio. Para receber as mensagens de áudio, você também precisará definir a permissão de chat apropriada entre cada controle de chat se quiser que o áudio flua. Por padrão, as permissões de chat são definidas como NONE. Para obter mais informações, confira o artigo Permissões de chat.

O processamento de outras mensagens da camada do Party é mais bem realizado em um thread de atualização dedicado ou em um loop de jogo de alta frequência. O loop do jogo deve ser configurado para ser executado a cada quadro e receber mensagens do Party Manager por meio da função StartProcessingStateChanges(). Para obter uma descrição completa de todas as alterações de estado, consulte a Documentação de referência do Party. Como alternativa, você pode consultar o NetworkManager.cpp para ver um exemplo de como processar cada alteração de estado.

Lidando com a suspensão do título

Algumas plataformas dão suporte à suspensão temporária da execução do seu título: iOS, Switch e GDK. Quando seu título é suspenso, a pilha de rede é invalidada e o PlayFab Party não consegue manter uma conexão com a rede do PlayFab Party. É necessária uma atenção especial para lidar com a suspensão e a retomada da execução do seu título ao usar o PlayFab Party.

iOS

No iOS, você deve sair da rede do PlayFab Party e se reconectar a ela Para sair da rede do Party, chame LeaveNetwork(). Depois que a rede for reativada, chame ConnectToNetwork() com o descritor de rede do Party anterior.

Switch e GDK

No Nintendo Switch e no Microsoft GDK, você deve limpar o PlayFab Party e aguardar a retomada da execução do título antes de reinicializar o PlayFab Party e se reconectar à sua rede. Para encerrar o Party, chame Cleanup().

Chamar Cleanup() recupera todos os recursos da biblioteca e destrói todos os objetos da biblioteca. Depois de reinicializar o Party, você precisará recriar todos os objetos da biblioteca, como usuários locais e controles de chat, além de restabelecer qualquer estado de rede anterior reautenticando os usuários locais, reconectando os controles de chat e recriando os pontos de extremidade.

Depois que a rede for reativada, chame Initialize(). Depois que o Party for inicializado com êxito, as seguintes etapas serão necessárias para ingressar novamente em uma rede do PlayFab Party anterior:

Conectar-se à rede do Party com o descritor de rede do Party anterior.
Recriar todos os objetos de usuário local e reautenticar esses usuários locais na rede.
Recriar todos os controles de chat locais e reconectá-los à rede para habilitar o VOIP
Recriar todos os pontos de extremidade de rede do Party para o tráfego de mensagens do jogo.

    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;
    }

Se a reconexão for concluída com êxito, a party poderá se comunicar com os outros pares; mas, se a rede anterior não existir mais, a reconexão falhará. Nesse caso, você deve tratar o erro de conexão apropriado.

Próximas etapas

Leia mais sobre os objetos do PlayFab Party e suas relações e consulte a documentação de referência da API do Party para que seu jogo aproveite ao máximo esses recursos. Para obter mais orientações específicas do XBOX, consulte os Requisitos do XBOX desde o início e com frequência.

XBOX Services

PlayFab

Pré-requisitos

Pré-requisitos da plataforma

Baixar e configurar o SDK do Party

Inicializar o PlayFab Party

Criar uma rede do Party

Compartilhar o descritor de rede do Party

Compartilhar manualmente o descritor de rede do Party

Usar o PlayFab Lobby para compartilhar o descritor de rede do Party

Habilitar redes escalonáveis

Conectar-se a uma rede do Party

Enviar uma mensagem para outro dispositivo ou ponto de extremidade da rede

Receber uma mensagem e renderizá-la no dispositivo local

Lidando com a suspensão do título

iOS

Switch e GDK

Próximas etapas

Confira também

​Pré-requisitos

​Pré-requisitos da plataforma

​Baixar e configurar o SDK do Party

​Fazer login no seu título do PlayFab e obter um token de entidade e uma ID de entidade

​Inicializar o PlayFab Party

​Criar uma rede do Party

​Compartilhar o descritor de rede do Party

​Compartilhar manualmente o descritor de rede do Party

​Usar o PlayFab Lobby para compartilhar o descritor de rede do Party

​Habilitar redes escalonáveis

​Conectar-se a uma rede do Party

​Enviar uma mensagem para outro dispositivo ou ponto de extremidade da rede

​Receber uma mensagem e renderizá-la no dispositivo local

​Lidando com a suspensão do título

​iOS

​Switch e GDK

​Próximas etapas

​Confira também

Pré-requisitos

Pré-requisitos da plataforma

Baixar e configurar o SDK do Party

Fazer login no seu título do PlayFab e obter um token de entidade e uma ID de entidade

Inicializar o PlayFab Party

Criar uma rede do Party

Compartilhar o descritor de rede do Party

Compartilhar manualmente o descritor de rede do Party

Usar o PlayFab Lobby para compartilhar o descritor de rede do Party

Habilitar redes escalonáveis

Conectar-se a uma rede do Party

Enviar uma mensagem para outro dispositivo ou ponto de extremidade da rede

Receber uma mensagem e renderizá-la no dispositivo local

Lidando com a suspensão do título

iOS

Switch e GDK

Próximas etapas

Confira também