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

本指南說明如何使用 Unified SDK 整合 PlayFab Party 以進行語音、聊天和資料網路通訊，以及整合 PlayFab Multiplayer 以使用大廳和配對服務。

必要條件

開始之前，請確定您已：

完成 Core SDK 設定和驗證
從登入程序取得已驗證的 PFEntityHandle
在 Game Manager 中設定好您的 PlayFab 遊戲識別碼
對非同步程式設計模式有基本的了解

本指南假設您已依照 Core 快速入門指南初始化 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。

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)。其他玩家會使用此識別碼加入您的網路。

🎉 恭喜！ 您已成功設定 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 認知服務
文字聊天 - 實作具備翻譯和仲裁功能的文字訊息
資料通道 - 在玩家之間傳送自訂遊戲資料
網路管理 - 處理玩家連線、中斷連線和網路事件

Multiplayer 大廳功能

配對整合 - 將大廳與 PlayFab 配對連接
大廳屬性 - 儲存和同步遊戲設定和中繼資料
成員資料 - 在大廳內分享玩家特定的資訊
搜尋和探索 - 尋找並加入公用大廳

核心概念

非同步作業 - 了解 PlayFab 的非同步程式設計模型
記憶體管理 - 管理 SDK 記憶體的最佳做法
追蹤和診斷 - 偵錯和監視您的整合

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 大廳功能

核心概念

參考文件