Inicio rápido (Windows): Party y Multiplayer

Esta guía muestra cómo integrar PlayFab Party para voz, chat y redes de datos, junto con PlayFab Multiplayer para los servicios de sala (lobby) y emparejamiento mediante el SDK unificado.

Requisitos previos

Antes de comenzar, asegúrese de tener:

Completada la configuración básica del SDK y la autenticación
Un PFEntityHandle autenticado obtenido del proceso de inicio de sesión
Su Title ID de PlayFab configurado en Game Manager
Familiaridad básica con los patrones de programación asincrónica

Esta guía asume que ya inicializó el SDK de PlayFab y autenticó a un jugador siguiendo la guía de inicio rápido básica. Si aún no lo ha hecho, complete primero esa guía.

Lo que va a lograr

Al final de este inicio rápido, habrá:

Inicializado PlayFab Party para redes y chat
Creado un usuario local y un control de chat
Configurado una red de Party para la comunicación
Inicializado PlayFab Multiplayer y creado una sala (lobby)
Comprendido los procedimientos de limpieza de los recursos de Party y Multiplayer

Encabezados e inclusiones

Encabezados necesarios

Incluya los encabezados del SDK en sus archivos de encabezado para acceder a la funcionalidad de PlayFab Party y Multiplayer:

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

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

#include <playfab/services/PFServices.h>

Archivos de implementación

Incluya PartyImpl.h en sus archivos de implementación y use el espacio de nombres Party:

#include <PartyImpl.h>

using namespace Party;

Paso 1: Inicializar PlayFab Party

Inicialice PlayFab Party creando una referencia singleton a PartyManager y configurándola con su Title ID y colas de tareas opcionales para un control avanzado de subprocesos.

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;

Los parámetros audioTaskQueue y networkingTaskQueue le permiten proporcionar instancias personalizadas de XTaskQueue para un control detallado de los subprocesos. Establézcalos en nullptr para usar el comportamiento de subprocesos predeterminado.

Paso 2: Crear un usuario local

Cree un objeto de usuario local para representar al jugador autenticado en el dispositivo. Este usuario es necesario para todas las operaciones de red y 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;

Paso 3: Crear un control de chat

Cree un control de chat para administrar las operaciones de chat de voz y texto del usuario en este 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;

El control de chat gestiona la entrada y salida de audio y habilita las características de comunicación por voz.

Paso 4: Crear una red de Party

Cree una red de Party: una colección protegida de dispositivos y usuarios que pueden intercambiar chat y datos. Una red de Party suele corresponderse con el concepto de sesión multijugador o sala (lobby) de su juego.

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;

Asegúrese de proporcionar un identificador de red único y válido (GUID) en PartyInvitationConfiguration. Otros jugadores usan este identificador para unirse a su red.

🎉 ¡Enhorabuena! Ha configurado correctamente las redes y el chat de PlayFab Party.

Paso 5: Inicializar PlayFab Multiplayer

Inicialice el servicio PlayFab Multiplayer para habilitar la funcionalidad de sala (lobby) y emparejamiento.

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;

Paso 6: Crear una sala (lobby)

Cree una sala (lobby) para administrar grupos de jugadores antes de iniciar una partida. Las salas admiten características como la migración del propietario y el control de acceso.

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! Ya ha configurado tanto las redes de Party como los servicios de sala de Multiplayer.

Limpieza de recursos

Cuando su juego se cierre o necesite limpiar los recursos de PlayFab, asegúrese de realizar la limpieza en el orden correcto:

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

Limpie siempre los recursos en este orden: Party, Multiplayer, identificadores de entidad, configuración del servicio y, por último, PlayFab Services.

Pasos siguientes

Ahora que ha configurado Party y Multiplayer, explore estas características adicionales:

Características de redes de Party

Chat de voz: habilite la comunicación por voz en tiempo real con la integración de Azure Cognitive Services
Chat de texto: implemente mensajería de texto con traducción y moderación
Canales de datos: envíe datos de juego personalizados entre jugadores
Administración de red: gestione las conexiones y desconexiones de jugadores y los eventos de red

Características de sala de Multiplayer

Integración con el emparejamiento: conecte las salas con el emparejamiento de PlayFab
Propiedades de la sala: almacene y sincronice la configuración y los metadatos del juego
Datos de miembros: comparta información específica de cada jugador dentro de la sala
Búsqueda y detección: busque salas públicas y únase a ellas

Conceptos básicos

Operaciones asincrónicas: comprensión del modelo de programación asincrónica de PlayFab
Administración de memoria: procedimientos recomendados para administrar la memoria del SDK
Seguimiento y diagnóstico: depuración y supervisión de su integración

XBOX Services

PlayFab

Requisitos previos

Lo que va a lograr

Encabezados e inclusiones

Encabezados necesarios

Archivos de implementación

Paso 1: Inicializar PlayFab Party

Paso 2: Crear un usuario local

Paso 3: Crear un control de chat

Paso 4: Crear una red de Party

Paso 5: Inicializar PlayFab Multiplayer

Paso 6: Crear una sala (lobby)

Limpieza de recursos

Pasos siguientes

Características de redes de Party

Características de sala de Multiplayer

Conceptos básicos

Documentación de referencia

​Requisitos previos

​Lo que va a lograr

​Encabezados e inclusiones

​Encabezados necesarios

​Archivos de implementación

​Paso 1: Inicializar PlayFab Party

​Paso 2: Crear un usuario local

​Paso 3: Crear un control de chat

​Paso 4: Crear una red de Party

​Paso 5: Inicializar PlayFab Multiplayer

​Paso 6: Crear una sala (lobby)

​Limpieza de recursos

​Pasos siguientes

​Características de redes de Party

​Características de sala de Multiplayer

​Conceptos básicos

​Documentación de referencia

Requisitos previos

Lo que va a lograr

Encabezados e inclusiones

Encabezados necesarios

Archivos de implementación

Paso 1: Inicializar PlayFab Party

Paso 2: Crear un usuario local

Paso 3: Crear un control de chat

Paso 4: Crear una red de Party

Paso 5: Inicializar PlayFab Multiplayer

Paso 6: Crear una sala (lobby)

Limpieza de recursos

Pasos siguientes

Características de redes de Party

Características de sala de Multiplayer

Conceptos básicos

Documentación de referencia