快速入门 (Windows) - Party 和 Multiplayer - XBOX Game Development Documentation

本指南向你展示如何使用统一 SDK 集成 PlayFab Party 以实现语音、聊天和数据网络传输,并集成 PlayFab Multiplayer 以实现大厅和匹配服务。

前提条件

在开始之前,请确保你已:

完成核心 SDK 设置和身份验证
在登录过程中获得经过身份验证的 PFEntityHandle
已在 Game Manager 中配置 PlayFab 标题 ID
熟悉基本的异步编程模式

本指南假定你已按照核心快速入门指南初始化 PlayFab SDK 并对玩家进行了身份验证。如果尚未完成,请先完成该指南。

你将完成的内容

完成本快速入门后,你将:

初始化 PlayFab Party 以实现网络和聊天
创建本地用户和聊天控件
设置用于通信的 Party 网络
初始化 PlayFab Multiplayer 并创建大厅
了解 Party 和 Multiplayer 资源的清理流程

头文件和 include

必需的头文件

在头文件中包含 SDK 头文件,以访问 PlayFab Party 和 Multiplayer 功能:

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

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

#include <playfab/services/PFServices.h>

实现文件

在实现文件中包含 PartyImpl.h 并使用 Party 命名空间:

#include <PartyImpl.h>

using namespace Party;

第 1 步:初始化 PlayFab Party

通过创建 PartyManager 的单例引用来初始化 PlayFab Party,并使用你的标题 ID 及可选的任务队列(用于高级线程控制)对其进行配置。

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;

audioTaskQueue 和 networkingTaskQueue 参数允许你提供自定义 XTaskQueue 实例以精细控制线程。将它们设置为 nullptr 可使用默认线程行为。

第 2 步:创建本地用户

创建本地用户对象以在设备上表示经过身份验证的玩家。所有网络和聊天操作都需要此用户。

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;

第 3 步:创建聊天控件

创建聊天控件来管理该设备上用户的语音和文字聊天操作。

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;

聊天控件处理音频输入/输出并启用语音通信功能。

第 4 步:创建 Party 网络

创建 Party 网络——一个可以交换聊天和数据的安全设备和用户集合。Party 网络通常与你游戏的多人会话或大厅概念相对应。

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;

请确保在 PartyInvitationConfiguration 中提供有效且唯一的网络标识符 (GUID)。其他玩家将使用此 ID 加入你的网络。

🎉 恭喜! 你已成功设置 PlayFab Party 网络和聊天。

第 5 步:初始化 PlayFab Multiplayer

初始化 PlayFab Multiplayer 服务以启用大厅和匹配功能。

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;

第 6 步:创建大厅

创建大厅以在开始比赛之前管理玩家群组。大厅支持所有者迁移和访问控制等功能。

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;

🎉 太好了! 你现在已经设置好 Party 网络和 Multiplayer 大厅服务。

清理资源

当你的游戏关闭或需要清理 PlayFab 资源时,请确保按正确顺序进行清理:

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

始终按此顺序清理资源:Party、Multiplayer、实体句柄、服务配置,然后是 PlayFab Services。

后续步骤

现在你已经设置好 Party 和 Multiplayer,可以探索以下其他功能:

Party 网络功能

语音聊天 - 通过 Azure Cognitive Services 集成启用实时语音通信
文字聊天 - 实现带翻译和审核功能的文字消息
数据通道 - 在玩家之间发送自定义游戏数据
网络管理 - 处理玩家连接、断开连接和网络事件

XBOX Services

PlayFab

快速入门 (Windows) - Party 和 Multiplayer

前提条件

你将完成的内容

头文件和 include

必需的头文件

实现文件

第 1 步:初始化 PlayFab Party

第 2 步:创建本地用户

第 3 步:创建聊天控件

第 4 步:创建 Party 网络

第 5 步:初始化 PlayFab Multiplayer

第 6 步:创建大厅

清理资源

后续步骤

Party 网络功能

Multiplayer 大厅功能

核心概念

参考文档

​前提条件

​你将完成的内容

​头文件和 include

​必需的头文件

​实现文件

​第 1 步:初始化 PlayFab Party

​第 2 步:创建本地用户

​第 3 步:创建聊天控件

​第 4 步:创建 Party 网络

​第 5 步:初始化 PlayFab Multiplayer

​第 6 步:创建大厅

​清理资源

​后续步骤

​Party 网络功能

​Multiplayer 大厅功能

​核心概念

​参考文档

前提条件

你将完成的内容

头文件和 include

必需的头文件

实现文件

第 1 步:初始化 PlayFab Party

第 2 步:创建本地用户

第 3 步:创建聊天控件

第 4 步:创建 Party 网络

第 5 步:初始化 PlayFab Multiplayer

第 6 步:创建大厅

清理资源

后续步骤

Party 网络功能

Multiplayer 大厅功能

核心概念

参考文档