Démarrage rapide (Windows) - Party et Multiplayer - XBOX Game Development Documentation

Ce guide vous montre comment intégrer PlayFab Party pour la voix, le chat et la mise en réseau de données, ainsi que PlayFab Multiplayer pour les services de lobby et de matchmaking, à l’aide du SDK unifié.

Prérequis

Avant de commencer, assurez-vous d’avoir :

Terminé la configuration du SDK Core et l’authentification
Un PFEntityHandle authentifié issu du processus de connexion
Votre ID de titre PlayFab configuré dans Game Manager
Une connaissance de base des modèles de programmation asynchrone

Ce guide suppose que vous avez déjà initialisé le SDK PlayFab et authentifié un joueur en suivant le guide de démarrage rapide Core. Si ce n’est pas le cas, suivez d’abord ce guide.

Ce que vous allez accomplir

À la fin de ce démarrage rapide, vous aurez :

Initialisé PlayFab Party pour la mise en réseau et le chat
Créé un utilisateur local et un contrôle de chat
Configuré un réseau Party pour la communication
Initialisé PlayFab Multiplayer et créé un lobby
Compris les procédures de nettoyage des ressources Party et Multiplayer

En-têtes et inclusions

En-têtes requis

Incluez les en-têtes du SDK dans vos fichiers d’en-tête pour accéder aux fonctionnalités de PlayFab Party et Multiplayer :

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

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

#include <playfab/services/PFServices.h>

Fichiers d’implémentation

Incluez PartyImpl.h dans vos fichiers d’implémentation et utilisez l’espace de noms Party :

#include <PartyImpl.h>

using namespace Party;

Étape 1 : initialiser PlayFab Party

Initialisez PlayFab Party en créant une référence singleton au PartyManager et en le configurant avec votre ID de titre et, éventuellement, des files d’attente de tâches pour un contrôle avancé des 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;

Les paramètres audioTaskQueue et networkingTaskQueue vous permettent de fournir des instances XTaskQueue personnalisées pour un contrôle précis des threads. Définissez-les sur nullptr pour utiliser le comportement de threading par défaut.

Étape 2 : créer un utilisateur local

Créez un objet utilisateur local pour représenter le joueur authentifié sur l’appareil. Cet utilisateur est requis pour toutes les opérations de mise en réseau et de 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;

Étape 3 : créer un contrôle de chat

Créez un contrôle de chat pour gérer les opérations de chat vocal et textuel de l’utilisateur sur cet appareil.

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;

Le contrôle de chat gère l’entrée et la sortie audio et active les fonctionnalités de communication vocale.

Étape 4 : créer un réseau Party

Créez un réseau Party, c’est-à-dire un ensemble sécurisé d’appareils et d’utilisateurs qui peuvent échanger des messages de chat et des données. Un réseau Party correspond généralement au concept de session multijoueur ou de lobby de votre jeu.

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;

Veillez à fournir un identificateur de réseau (GUID) valide et unique dans PartyInvitationConfiguration. Cet ID est utilisé par les autres joueurs pour rejoindre votre réseau.

🎉 Félicitations ! Vous avez configuré avec succès la mise en réseau et le chat de PlayFab Party.

Étape 5 : initialiser PlayFab Multiplayer

Initialisez le service PlayFab Multiplayer pour activer les fonctionnalités de lobby et de 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;

Étape 6 : créer un lobby

Créez un lobby pour gérer les groupes de joueurs avant le début d’une partie. Les lobbies prennent en charge des fonctionnalités telles que la migration du propriétaire et le contrôle d’accès.

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;

🎉 Excellent ! Vous avez maintenant configuré à la fois la mise en réseau Party et les services de lobby Multiplayer.

Nettoyage des ressources

Lorsque votre jeu s’arrête ou que vous devez nettoyer les ressources PlayFab, effectuez le nettoyage dans le bon ordre :

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

Nettoyez toujours les ressources dans cet ordre : Party, Multiplayer, handles d’entité, configuration de service, puis PlayFab Services.

Étapes suivantes

Maintenant que vous avez configuré Party et Multiplayer, découvrez ces fonctionnalités supplémentaires :

Fonctionnalités de mise en réseau Party

Chat vocal : activez la communication vocale en temps réel avec l’intégration d’Azure Cognitive Services
Chat textuel : implémentez la messagerie textuelle avec traduction et modération
Canaux de données : envoyez des données de jeu personnalisées entre les joueurs
Gestion du réseau : gérez les connexions et déconnexions des joueurs ainsi que les événements réseau

Fonctionnalités de lobby Multiplayer

Intégration du matchmaking : connectez les lobbies au matchmaking PlayFab
Propriétés du lobby : stockez et synchronisez les paramètres et les métadonnées du jeu
Données des membres : partagez des informations propres à chaque joueur au sein du lobby
Recherche et découverte : trouvez et rejoignez des lobbies publics

Concepts de base

Opérations asynchrones : comprendre le modèle de programmation asynchrone de PlayFab
Gestion de la mémoire : bonnes pratiques de gestion de la mémoire du SDK
Traçage et diagnostics : déboguer et surveiller votre intégration

XBOX Services

PlayFab

Démarrage rapide (Windows) - Party et Multiplayer

Prérequis

Ce que vous allez accomplir

En-têtes et inclusions

En-têtes requis

Fichiers d’implémentation

Étape 1 : initialiser PlayFab Party

Étape 2 : créer un utilisateur local

Étape 3 : créer un contrôle de chat

Étape 4 : créer un réseau Party

Étape 5 : initialiser PlayFab Multiplayer

Étape 6 : créer un lobby

Nettoyage des ressources

Étapes suivantes

Fonctionnalités de mise en réseau Party

Fonctionnalités de lobby Multiplayer

Concepts de base

Documentation de référence

​Prérequis

​Ce que vous allez accomplir

​En-têtes et inclusions

​En-têtes requis

​Fichiers d’implémentation

​Étape 1 : initialiser PlayFab Party

​Étape 2 : créer un utilisateur local

​Étape 3 : créer un contrôle de chat

​Étape 4 : créer un réseau Party

​Étape 5 : initialiser PlayFab Multiplayer

​Étape 6 : créer un lobby

​Nettoyage des ressources

​Étapes suivantes

​Fonctionnalités de mise en réseau Party

​Fonctionnalités de lobby Multiplayer

​Concepts de base

​Documentation de référence

Prérequis

Ce que vous allez accomplir

En-têtes et inclusions

En-têtes requis

Fichiers d’implémentation

Étape 1 : initialiser PlayFab Party

Étape 2 : créer un utilisateur local

Étape 3 : créer un contrôle de chat

Étape 4 : créer un réseau Party

Étape 5 : initialiser PlayFab Multiplayer

Étape 6 : créer un lobby

Nettoyage des ressources

Étapes suivantes

Fonctionnalités de mise en réseau Party

Fonctionnalités de lobby Multiplayer

Concepts de base

Documentation de référence