Início rápido (Windows) - Party e Multiplayer - XBOX Game Development Documentation

Este guia mostra como integrar o PlayFab Party para voz, chat e rede de dados, junto com o PlayFab Multiplayer para os serviços de lobby e matchmaking, usando o SDK unificado.

Pré-requisitos

Antes de começar, verifique se você:

Concluiu a configuração e autenticação do SDK Core
Tem um PFEntityHandle autenticado obtido no processo de logon
Configurou o ID do seu título do PlayFab no Game Manager
Tem familiaridade básica com padrões de programação assíncrona

Este guia pressupõe que você já inicializou o SDK do PlayFab e autenticou um jogador seguindo o guia de início rápido do Core. Se ainda não fez isso, conclua esse guia primeiro.

O que você vai realizar

Ao final deste início rápido, você terá:

Inicializado o PlayFab Party para rede e chat
Criado um usuário local e um controle de chat
Configurado uma rede do Party para comunicação
Inicializado o PlayFab Multiplayer e criado um lobby
Entendido os procedimentos de limpeza dos recursos do Party e do Multiplayer

Cabeçalhos e inclusões

Cabeçalhos necessários

Inclua os cabeçalhos do SDK nos seus arquivos de cabeçalho para acessar a funcionalidade do PlayFab Party e do Multiplayer:

#include <Party.h>
#include <Party_c.h>

#include <PFMultiplayer.h>
#include <PFLobby.h>

#include <playfab/services/PFServices.h>

Arquivos de implementação

Inclua PartyImpl.h nos seus arquivos de implementação e use o namespace Party:

#include <PartyImpl.h>

using namespace Party;

Etapa 1: Inicializar o PlayFab Party

Inicialize o PlayFab Party criando uma referência singleton ao PartyManager e configurando-o com o ID do seu título e, opcionalmente, filas de tarefas para controle avançado de threads.

PartyManager& partyManager = PartyManager::GetSingleton();
PartyInitializationConfiguration partyInitConfig = {};
PartyError err;

partyInitConfig.titleId = (PartyString) m_titleId; // Your PlayFab Title ID
partyInitConfig.audioTaskQueue = nullptr; // Optional: Custom XTaskQueue for audio operations, or nullptr for default
partyInitConfig.networkingTaskQueue = nullptr; // Optional: Custom XTaskQueue for networking operations, or nullptr for default

err = partyManager.Initialize(&partyInitConfig);
if (PARTY_FAILED(err))
{
    std::wcerr << L"Failed to initialize PartyManager: 0x" << std::hex << err << std::endl;
    return err;
}

std::wcout << L"PartyManager initialized successfully" << std::endl;

Os parâmetros audioTaskQueue e networkingTaskQueue permitem fornecer instâncias personalizadas de XTaskQueue para ter controle refinado sobre as threads. Defina-os como nullptr para usar o comportamento de threads padrão.

Etapa 2: Criar um usuário local

Crie um objeto de usuário local para representar o jogador autenticado no dispositivo. Esse usuário é necessário para todas as operações de rede e chat.

PartyLocalUser* localUser{};
PartyError userErr;

// Use the entityHandle obtained from authentication
userErr = partyManager.CreateLocalUser(entityHandle, &localUser);
if (PARTY_FAILED(userErr))
{
    std::wcerr << L"Failed to create local user: 0x" << std::hex << userErr << std::endl;
    return userErr;
}

std::wcout << L"Local user created successfully" << std::endl;

Etapa 3: Criar um controle de chat

Crie um controle de chat para gerenciar as operações de chat de voz e de texto do usuário neste dispositivo.

PartyLocalDevice* localDevice;
PartyError deviceErr = partyManager.GetLocalDevice(&localDevice);
if (PARTY_FAILED(deviceErr))
{
    std::wcerr << L"Failed to get local device: 0x" << std::hex << deviceErr << std::endl;
    return deviceErr;
}

PartyLocalChatControl* chatControl;
PartyError chatErr = localDevice->CreateChatControl(localUser, nullptr, nullptr, &chatControl);
if (PARTY_FAILED(chatErr))
{
    std::wcerr << L"Failed to create chat control: 0x" << std::hex << chatErr << std::endl;
    return chatErr;
}

std::wcout << L"Chat control created successfully" << std::endl;

O controle de chat processa a entrada/saída de áudio e habilita os recursos de comunicação por voz.

Etapa 4: Criar uma rede do Party

Crie uma rede do Party — um conjunto protegido de dispositivos e usuários que podem trocar chat e dados. Uma rede do Party normalmente corresponde ao conceito de sessão multiplayer ou de lobby do seu jogo.

PartyNetworkDescriptor networkDescriptor = {};
PartyNetworkConfiguration networkConfiguration = {};

// Configure network limits
networkConfiguration.directPeerConnectivityOptions = PartyDirectPeerConnectivityOptions::None;
networkConfiguration.maxDeviceCount = 8;
networkConfiguration.maxDevicesPerUserCount = 1;
networkConfiguration.maxEndpointsPerDeviceCount = 1;
networkConfiguration.maxUserCount = 8;
networkConfiguration.maxUsersPerDeviceCount = 1;

// Configure invitation settings
PartyInvitationConfiguration invitationConfiguration = {
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", // Unique network identifier (generate a GUID)
    PartyInvitationRevocability::Anyone,
    0,
    nullptr
};

PartyError networkErr = partyManager.CreateNewNetwork(
    localUser,
    &networkConfiguration,
    0,
    nullptr,
    &invitationConfiguration,
    nullptr,
    &networkDescriptor,
    nullptr);

if (PARTY_FAILED(networkErr))
{
    std::wcerr << L"Failed to create Party network: 0x" << std::hex << networkErr << std::endl;
    return networkErr;
}

std::wcout << L"Party network created successfully" << std::endl;

Forneça um identificador de rede (GUID) válido e exclusivo em PartyInvitationConfiguration. Esse ID é usado por outros jogadores para ingressar na sua rede.

🎉 Parabéns! Você configurou com sucesso a rede e o chat do PlayFab Party.

Etapa 5: Inicializar o PlayFab Multiplayer

Inicialize o serviço PlayFab Multiplayer para habilitar a funcionalidade de lobby e matchmaking.

PFMultiplayerHandle pfmHandle{};
MultiplayerInitializationConfiguration multiplayerInitConfig{};

multiplayerInitConfig.titleId = m_titleId; // Your PlayFab Title ID

HRESULT hr = PFMultiplayerInitialize(&multiplayerInitConfig, &pfmHandle);
if (FAILED(hr))
{
    std::wcerr << L"Failed to initialize Multiplayer: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"PlayFab Multiplayer initialized successfully" << std::endl;

Etapa 6: Criar um lobby

Crie um lobby para gerenciar grupos de jogadores antes de iniciar uma partida. Os lobbies oferecem suporte a recursos como migração de proprietário e controle de acesso.

PFLobbyCreateConfiguration lobbyConfiguration{};
lobbyConfiguration.maxMemberCount = 8;
lobbyConfiguration.ownerMigrationPolicy = PFLobbyOwnerMigrationPolicy::Automatic;
lobbyConfiguration.accessPolicy = PFLobbyAccessPolicy::Private;

PFLobbyJoinConfiguration memberConfiguration{};

PFLobbyHandle lobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobbyWithEntityHandle(
    pfmHandle,
    entityHandle,
    &lobbyConfiguration,
    &memberConfiguration,
    nullptr,
    &lobby);

if (FAILED(hr))
{
    std::wcerr << L"Failed to create and join lobby: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"Lobby created and joined successfully" << std::endl;

🎉 Excelente! Agora você configurou tanto a rede do Party quanto os serviços de lobby do Multiplayer.

Limpar os recursos

Quando o jogo for encerrado ou você precisar limpar os recursos do PlayFab, faça a limpeza na ordem correta:

// Clean up Party singleton
partyManager.Cleanup();

// Clean up Multiplayer handle
PFMultiplayerUninitialize(pfmHandle);

// Close entity handle
PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

// Close service config handle
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

// Uninitialize PlayFab Services
XAsyncBlock asyncBlock{};
HRESULT hr = PFServicesUninitializeAsync(&asyncBlock);
if (SUCCEEDED(hr))
{
    hr = XAsyncGetStatus(&asyncBlock, true); // Blocking wait for cleanup completion
}

Sempre limpe os recursos nesta ordem: Party, Multiplayer, identificadores de entidade, configuração de serviço e, por fim, PlayFab Services.

Próximas etapas

Agora que você configurou o Party e o Multiplayer, explore estes recursos adicionais:

Recursos de rede do Party

Chat de voz - Habilite a comunicação por voz em tempo real com integração ao Azure Cognitive Services
Chat de texto - Implemente mensagens de texto com tradução e moderação
Canais de dados - Envie dados personalizados do jogo entre jogadores
Gerenciamento de rede - Trate conexões, desconexões e eventos de rede dos jogadores

Recursos de lobby do Multiplayer

Integração com matchmaking - Conecte lobbies ao matchmaking do PlayFab
Propriedades do lobby - Armazene e sincronize configurações e metadados do jogo
Dados dos membros - Compartilhe informações específicas de cada jogador no lobby
Pesquisa e descoberta - Encontre lobbies públicos e ingresse neles

Conceitos principais

Operações assíncronas - Entendendo o modelo de programação assíncrona do PlayFab
Gerenciamento de memória - Práticas recomendadas para gerenciar a memória do SDK
Rastreamento e diagnóstico - Depuração e monitoramento da sua integração

XBOX Services

PlayFab

Início rápido (Windows) - Party e Multiplayer

Pré-requisitos

O que você vai realizar

Cabeçalhos e inclusões

Cabeçalhos necessários

Arquivos de implementação

Etapa 1: Inicializar o PlayFab Party

Etapa 2: Criar um usuário local

Etapa 3: Criar um controle de chat

Etapa 4: Criar uma rede do Party

Etapa 5: Inicializar o PlayFab Multiplayer

Etapa 6: Criar um lobby

Limpar os recursos

Próximas etapas

Recursos de rede do Party

Recursos de lobby do Multiplayer

Conceitos principais

Documentação de referência

​Pré-requisitos

​O que você vai realizar

​Cabeçalhos e inclusões

​Cabeçalhos necessários

​Arquivos de implementação

​Etapa 1: Inicializar o PlayFab Party

​Etapa 2: Criar um usuário local

​Etapa 3: Criar um controle de chat

​Etapa 4: Criar uma rede do Party

​Etapa 5: Inicializar o PlayFab Multiplayer

​Etapa 6: Criar um lobby

​Limpar os recursos

​Próximas etapas

​Recursos de rede do Party

​Recursos de lobby do Multiplayer

​Conceitos principais

​Documentação de referência

Pré-requisitos

O que você vai realizar

Cabeçalhos e inclusões

Cabeçalhos necessários

Arquivos de implementação

Etapa 1: Inicializar o PlayFab Party

Etapa 2: Criar um usuário local

Etapa 3: Criar um controle de chat

Etapa 4: Criar uma rede do Party

Etapa 5: Inicializar o PlayFab Multiplayer

Etapa 6: Criar um lobby

Limpar os recursos

Próximas etapas

Recursos de rede do Party

Recursos de lobby do Multiplayer

Conceitos principais

Documentação de referência