> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门 (Windows) - Party 和 Multiplayer

> 使用 PlayFab 统一 SDK 在 Windows 上集成 PlayFab Party 的语音、聊天和网络功能,以及 PlayFab Multiplayer 的大厅和匹配服务。

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

## 前提条件

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

* 完成[核心 SDK 设置和身份验证](/services/playfab/sdks/unified-sdk/quickstart-core)
* 在登录过程中获得经过身份验证的 `PFEntityHandle`
* 已在 Game Manager 中配置 PlayFab 标题 ID
* 熟悉基本的异步编程模式

<Note>
  本指南假定你已按照[核心快速入门指南](/services/playfab/sdks/unified-sdk/quickstart-core)初始化 PlayFab SDK 并对玩家进行了身份验证。如果尚未完成,请先完成该指南。
</Note>

## 你将完成的内容

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

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

## 头文件和 include

### 必需的头文件

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

```cpp theme={null}
#include <Party.h>
#include <Party_c.h>

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

#include <playfab/services/PFServices.h>
```

### 实现文件

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

```cpp theme={null}
#include <PartyImpl.h>

using namespace Party;
```

## 第 1 步:初始化 PlayFab Party

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

```cpp theme={null}
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;
```

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

## 第 2 步:创建本地用户

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

```cpp theme={null}
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 步:创建聊天控件

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

```cpp theme={null}
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 网络通常与你游戏的多人会话或大厅概念相对应。

```cpp theme={null}
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;
```

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

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

## 第 5 步:初始化 PlayFab Multiplayer

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

```cpp theme={null}
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 步:创建大厅

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

```cpp theme={null}
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 资源时,请确保按正确顺序进行清理:

```cpp theme={null}
// 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
}
```

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

## 后续步骤

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

### Party 网络功能

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

### Multiplayer 大厅功能

* **匹配集成** - 将大厅与 PlayFab 匹配连接
* **大厅属性** - 存储和同步游戏设置和元数据
* **成员数据** - 在大厅内共享玩家特定信息
* **搜索和发现** - 查找并加入公共大厅

### 核心概念

* [异步操作](/services/playfab/sdks/unified-sdk/async-model) - 了解 PlayFab 的异步编程模型
* [内存管理](/services/playfab/sdks/unified-sdk/memory-management) - 管理 SDK 内存的最佳实践
* [跟踪和诊断](/services/playfab/sdks/unified-sdk/debug-trace) - 调试和监控你的集成

## 参考文档

* [PlayFab Party SDK 文档](/services/playfab/multiplayer/networking/party-sdks/overview)
* [PlayFab Multiplayer SDK 文档](/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks)


## Related topics

- [Party Unity 插件快速入门](/zh-CN/services/playfab/multiplayer/networking/party-unity-plugin-quickstart.md)
- [iOS 和 macOS 快速入门](/zh-CN/services/playfab/multiplayer/networking/apple-specific-requirements.md)
- [快速入门 (Windows) - Core SDK 设置](/zh-CN/services/playfab/sdks/unified-sdk/quickstart-core.md)
- [Multiplayer Unity 插件快速入门](/zh-CN/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [使用 Economy v2、Unity IAP 和 Android 快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/tutorials/getting-started-with-unity-and-android.md)