通过

PlayFab Party对象及其关系

  • 项目

要成功使用 PlayFab Party API 的功能和灵活性，首先需要了解其范围内定义的下列关键对象：

  • 设备 - 在物理设备上执行的游戏的不同实例。 每当使用 API 时，就会存在本地设备。
  • 用户 - 个人登录玩家，或者更确切地说，游戏提供给 PlayFab title_player_account Party 用于身份验证和标识的 PlayFab 实体。 一个或多个用户与给定设备相关联。
  • 网络 - 游戏创建用于交换聊天或数据通信的一个或多个设备及其授权用户的安全集合。 网络通常与游戏的多人游戏会话或聊天群概念保持一致。
  • 终结点 - 用于在网络内发送和接收数据的抽象概念。 终结点可能表示设备、用户或任何所需的特定规则。
  • 聊天控件 - 一种用户表示形式，专门用于在一个或多个网络中配置、发起和定位语音和文字聊天。

对象关系

作为一个简化的概念层次结构， 网络 包含 设备，设备又包含 用户、可选 终结点和可选的 聊天控件。 例如：

简化的 PlayFab 方对象层次结构

虽然简单易懂，但前面的关系图实际上是对 PlayFab Party 功能的不完整描述，如果单独使用可能会产生误导。 现实中，Party API 支持一次连接到 多个 的设备。 例如，随着时间的推移，人们可能希望与一组朋友保持通信，因为同一组也加入和离开与陌生人分开的更大的游戏会话。 考虑此范围更广的方案，让我们可以更好地把握这些对象之间的关系。

将设备概念化为 属于 网络可能感觉直观，但情况并非如此。 更正确的是意识到设备 参与 网络。 因此，当遇到特定实例时，Party 库仅创建单个设备 API 对象（无论是远程还是本地），而不管它与本地设备共享的网络数量如何。

例如，下图显示包含用户、聊天控件和终结点的两个网络和三个设备。 设备 A 及其两个聊天控件 (与关联用户) 正在参与网络 1，而设备 B 和 C 已使用单个聊天控件连接到网络 1和网络 2， (和关联用户) 。 所有设备在连接它们的每个网络中都创建了一个或两个终结点：

多个网络中的 PlayFab 群对象

在关系图中，每个设备都看到所有三台设备及其聊天控件的单个实例，因为它们至少有一个网络相互共享。 设备 A 只知道网络 1 中的端点 1-4，但设备 B 和 C 也可以看到他们在网络 2 中创建的端点 5-7。

如果 设备 C 只参与 网络 2 ，而不是同时参与两个网络，则：

  • 设备 C 显然无法在网络 1 中创建终结点 4，也无法看到终结点 1-3。
  • 设备 C 仅在网络 1 中不知道设备 A 或其两个聊天控件。
  • 类似地，设备 A 只会在网络 2 中看不到设备 C 或其聊天控件。

但是，设备 B 仍会看到所有设备及其聊天控件，因为它仍在两个网络中。

因此，尽管设备和聊天控件"在外部"与网络保持严格分层树关系，但需要注意的是，如果没有随附网络的上下文，游戏实例从不会真正遇到远程设备或聊天控件。 如果本地和远程设备或聊天控件具有至少一个网络，则远程对象可能可见。 但如果没有常用网络，则绝不会创建远程对象。

注意

游戏无需同时连接到多个网络即可成功使用 PlayFab Party。 您可以在后续的高级主题中了解有关是否以及如何使用多个网络的更多信息。

常见对象属性

所有对象都有明确定义的生存期。 本地游戏实例直接创建和销毁每个对象，或使用仅在游戏选择的时间窗口内发出信号的标准化通知机制。 在后面的主题中更详细地描述了使用通知。

所有 PlayFab Party API 对象都支持 自定义上下文的概念，它只是一种存储对象可选的仅本地"快捷方式"指针或值的方法。 借助自定义上下文，可以轻松地从 PlayFab Party 对象返回到内存中的相应专用游戏对象 (（如果有任何) ，而无需执行低效查找）。 这些值不会远程传输，因为指针值仅对本地游戏实例有意义。

最后，除 网络对象 之外的所有上述所有对象都有一个专用的"本地"子对象，包含仅对拥有该对象的本地 设备 可用的方法和属性。

例如，有一个基本 PartyEndpoint 对象用于表示任何本地或远程 终结点，以及一个更为具体的 PartyLocalEndpoint 对象，只有该终结点是由本地设备实际创建才能通过 PartyEndpoint::GetLocal() 检索的。 这是公开用于传输游戏数据的方法的地方 PartyLocalEndpoint::SendMessage() ，因为一台设备无法以某种方式从其他远程设备的源终结点传输数据。

使用 C++ PlayFab Party 界面（推荐）时，对象会以 C++ 课堂实例公开。 使用平面 C 界面时，对象由控点值表示。

详细介绍所有主要对象的角色

  1. 经理 （PartyManager）
  2. 网络 （PartyNetwork）
  3. 设备 （PartyDevice 和 PartyLocalDevice）
  4. 用户 （用户实体 ID 和 PartyLocalUser）
  5. 终结点 （PartyEndpoint 和 PartyLocalEndpoint）
  6. 聊天控制 （PartyChatControl 和 PartyLocalChatControl）
  7. 状态更改 （PartyStateChange）

经理

除了之前总结的对象，PlayFab Party API 还会公开单个对象 PartyManager 对象。

此实用工具/组织对象很大程度上是开始处理其他对象的起点。 例如，Tha Manager 是最初创建新 网络 和本地 用户 的位置。 所有异步操作完成和通知也在此处集中显示。 最根本的是，管理器是在使用前初始化 PlayFab Party 库本身并在不再需要时进行清理的位置。

网络

PartyNetwork对象表示参与 设备、其授权 用户以及任何随附的 终结点或 聊天控件。 网络 最初创建为空，但设备会连接到它们，并在 网络中至少对一个本地用户进行身份验证。 没有任何经过身份验证的用户的网络会在超时后自动销毁。

为了连接到它们，使用网络描述符引用网络。 网络描述符 主要是不透明的二进制结构，其中包含 PlayFab Party 在内部识别和定位 网络所需的信息。 该 API 提供了将结构序列为支持 Web 服务的字符串和返回的方法，以便可以使用常见的社交平台邀请机制、 PlayFab Matchmaking或 PlayFab Party 本身范围之外的其他外部集合机制与其他设备交换。

注意

在极少数情况下，网络的网络描述符可能会发生变化。 应准备游戏以接收此类更改的通知，然后为现有 网络 更新或重新播发新的 网络描述 以避免其他设备连接问题。

即使使用 网络描述符，对 网络 的访问也仅限于授权用户。 此用户授权在 网络 创建期间以及随后创建和吊销邀请期间完成，如主题 邀请和安全模型请求中所述。

游戏可以选择使用邀请，将输入限制为只向用户的朋友输入，或阻止恶意播放器加入 网络。

设备一次可以连接到多个网络。 您可以在后面的主题中了解有关是否以及如何使用多个网络的更多信息。

可以在 PartyNetwork 对象上执行的操作类型包括向其中验证本地用户、连接和枚举聊天控件、创建和枚举终结点，或者获取 网络性能信息。

设备

对象 PartyDevice 表示游戏及其在物理设备上执行的 PlayFab 方库代码不同的实例。 大多数操作不自行 PartyDevice 对象;而是一种组织机制，用于定义哪些 终结点 或 聊天控件 属于该游戏实例，特别是同时支持多个本地 用户 的平台和游戏。 PlayFab Party 利用此关系知识优化游戏数据和聊天的传输，只需发送一封邮件副本（即使设备中的多个目标需要接收该邮件）。

远程 PartyDevice 对象是连接到网络和验证用户进入该网络的“副产品”。 它们仅在与设备关联的有效、经过身份验证的远程用户参与本地设备也连接到的网络时创建。 相应地，一旦不再正确，它们也会被销毁。

另一方面，只要 PlayFab Party 已初始化，PartyLocalDevice专用子对象始终可供本地游戏实例引用。 不会显式创建或销毁文件。

用户

PlayFab Party 用户是游戏执行 PlayFab 玩家登录以获取实体 ID 和令牌的唯一title_player_account人类玩家。

远程用户通过 PlayFab Party API 中与 聊天控件相关联的实体 ID 字符串（可选） 标识出 终结点。 它们不是使用专用对象表示的。 这是因为 PlayFab Party 没有可与任意用户有效交互的功能，除用于原始标识和作为与这些其他对象相关联的标签外。

相反，对于本地 用户 具有显式 PartyLocalUser 对象，因为游戏在 PlayFab Party 内管理他们的生存期。 如果游戏成功登录 PlayFab 播放器使用适用的 登录 方法，这通常会创建一个 PartyLocalUser，并适当方式在用户注销时销毁 PartyLocalUser。 对于支持多个本地玩家登录的平台和游戏，应该为每个玩家创建额外的 PartyLocalUser 对象。

PartyLocalUser 对象也很重要，因为它们是所有身份验证的基础。 必须存在有效的本地用户，才能创建新的 网络 身份验证。

在涵盖邀请和安全模型的主题中更详细地描述了授权用户。

几乎每个操作都需要提供或存在 PartyLocalUser，即使很少对 PartyLocalUser 对象本身执行操作。

PartyLocalUser 对象是使用 PartyManager 对象创建的。 他们只能被创建者显式销毁。 虽然远程 设备上没有直接对象表示形式，但如果拥有的设备删除 PartyLocalUser 或断开网络连接，与其关联的聊天控件和终结点将全部销毁。

终结点

PartyEndpoint 对象是可选的，但它是利用其进行游戏的 PlayFab Party 数据通信的核心。 与典型的网络套接字一样，端点是一种抽象的寻址机制，用于在网络内发起或定位数据消息。 它们可能表示要唯一标识的 设备、单个 用户或任何任意任意规则定义的概念（例如，单位）。

专用 PartyLocalEndpoint 子对象 用于 规则实例在网络中创建的终结点。 这是大多数终结点功能所在的地方。 其 PartyLocalEndpoint::SendMessage() 将游戏数据有效负载从 PartyLocalEndpoint 传输到同一个 PartyEndpoint 中一个或多个其他目标。 它还提供多种选项，用于选择如何最好地处理 Internet 数据包损失（例如，保证送达和/或订购），控制低延迟与从相同或其他本地终结点分配多条消息以降低带宽使用量之间的平分，以及当连接质量不足以支持策略发送的速度时进行响应。 您可以在后面的主题中了解有关使用端点传输游戏数据的更多信息。

除了是数据消息本身的源或目标，每个 PartyEndpoint 对象还分配有由 PlayFab 方分配的 16 位 终结点唯一标识符，允许从网络内单独 PartyEndpoint 对象接收或发送的邮件有效负载中引用特定的 终结点。 这是一种便捷方式，可避免发送完整的、较大的用户 实体 ID 字符串或可能表示的其他标识符的开销，例如，无需构建你自己的点对点身份协议协商。

PartyLocalEndpoint 对象是使用其包含的 PartyNetwork 对象创建的。 这样做会导致在远程设备上创建相应的 PartyEndpoint 对象。 一个 端点 可能会由创建者显式销毁，当拥有的设备与网络断开连接或关联的 PartyLocalUser 对象（如果已指定）从网络中删除时，就会被销毁。

聊天控制

PartyChatControl 对象是使用 PlayFab Party 的可选聊天通信功能的机制。 它们代表特定用户的相关音频输入/输出设备、首选项和通信策略。

专用 PartyLocalChatControl 子对象也可用于本地游戏实例创建的聊天控件。 可在这里配置允许与远程 PartyChatControl 对象进行聊天通信的权限，例如选择全网络聊天与仅团队聊天，或应用平台策略限制。 本地 语音控制 用于发送聊天文本、将文本制作成语音、请求脚本和语音流翻译、静音等。

PartyLocalChatControl 对象必须连接到 网络 ，然后才能将其创建为 PartyChatControl 同一网络中远程 设备上的 对象。 设备将始终只能看到 PartyChatControl 一代表对象，即使该设备和 聊天控制 连接到多个网络时。 这有助于避免语音和文本聊天消息的不必要的重复或中断。

PartyLocalChatControl 对象是使用包含的 PartyLocalDevice 对象创建的。 聊天控制可能会受其创建者显式销毁，当拥有的设备与网络断开连接或将关联的 PartyLocalUser 对象从网络中删除时，就会被销毁。

状态更改

PartyStateChange 结构用于通知游戏所有异步操作完成、传入消息、更新通知和其他 API 相关事件。

为简化在 Internet 上处理复杂多计算机交互的方式以及不可预料的计时，PlayFab Party 保证它不会修改从 API 报告的任何状态，只是由于游戏的显式调用。 但是，由于你仍然需要一种了解修改本地州/省远程启动的操作或非计划发生的方式，PlayFab Party 和游戏通过一对特殊的方法、 PartyManager::StartProcessingStateChanges() 和 PartyManager::FinishProcessingStateChanges()。 这些是在游戏工作循环中方便处理此类更新的点上调用的。 新的事件以零或更多 PartyManager::StartProcessingStateChanges() 结构数组从 PartyStateChange 报告。 一旦游戏处理了 状态，数组就通过使用 PartyManager::FinishProcessingStateChanges()。

结构 PartyStateChange 本身不是完整的对象。 这是一个基础页眉，其类型为更详细的结构，其中包含有关完成或通知的文件类型、相关对象的指针以及任何错误信息的信息。

在后面的主题中详细描述了如何处理状态更改。

后续步骤