> ## 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. # XBOX 要求 > 在 XBOX 主机上使用 PlayFab Party 时满足 XBOX 要求(XR)的最佳实践,涵盖聊天、隐私、跨网络游戏和多人会话。 如果你的游戏面向 XBOX 主机,则必须遵守一系列要求,以确保在与 XBOX Live 交互时行为和功能的一致性。这些要求列在 [XBOX Requirements](https://aka.ms/xrs)(简称 XR)中。XR 与在 PC 和其他平台上你的游戏使用 XBOX Live 所需遵守的[政策](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/live/get-started/live-xbl-overview)存在交叉和重叠。这里我们将介绍 PlayFab Party 帮助你符合这些要求的最佳实践。 作为快速参考,请参见下表,该表将 PlayFab Party 场景与其对应的 XR 匹配: | 场景 | XR | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [使 PlayFab Party 与 XBOX Live 用户的聊天设置和权限保持一致](#aligning-playfab-party-with-an-xbox-live-users-chat-settings-and-privileges) | [XR-015](https://developer.microsoft.com/games/xbox/docs/gdk/xr015)、[XR-045](https://developer.microsoft.com/games/xbox/docs/gdk/xr045) | | [维护多人会话文档](#maintaining-a-multiplayer-session-document) | [XR-067](https://developer.microsoft.com/games/xbox/docs/gdk/xr067) | | [识别跨网络游戏会话中的玩家](#identifying-players-in-a-cross-network-game-session) | [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) | | [尊重 XBOX Live 用户的跨网络通信权限](#respecting-cross-network-communication-permissions-for-xbox-live-users) | [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) | | [当不允许跨平台游戏时,使用 PlayFab Party 邀请限制对网络的访问](#use-playfab-party-invitations-to-restrict-access-to-networks-when-cross-play-is-not-allowed) | [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) | | [与 XBOX Live 配置文件设置保持同步](#keeping-in-sync-with-xbox-live-profile-settings) | [XR-048](https://developer.microsoft.com/games/xbox/docs/gdk/xr048) | | [支持平台多人游戏加入流程](#supporting-platform-multiplayer-join-flows) | [XR-064](https://developer.microsoft.com/games/xbox/docs/gdk/xr064)、[XR-124](https://developer.microsoft.com/games/xbox/docs/gdk/console-certification-requirements-and-tests) | | [好友列表](#friends-lists) | [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007)、[XR-070](https://developer.microsoft.com/games/xbox/docs/gdk/console-certification-requirements-and-tests) | | [遵守 XBOX Live 服务重试策略和服务访问限制](#honoring-xbox-live-service-retry-policy-and-service-access-limitations) | [XR-074](https://developer.microsoft.com/games/xbox/docs/gdk/xr074)、[XR-132](https://developer.microsoft.com/games/xbox/docs/gdk/xr132) | ## PlayFab Party XBOX Live 帮助程序库 除核心的 PlayFab Party 库外,我们还提供了 [XBOX Live 帮助程序库](/services/playfab/multiplayer/networking/party-xbox-live-guide),旨在帮助遵守 XBOX Live 政策以及由此延伸的 XR。使用此帮助程序库不是必需的,但强烈推荐,并被视为最佳实践。此处展示的示例假定使用了 XBOX Live 帮助程序库。 ## 使 PlayFab Party 与 XBOX Live 用户的聊天设置和权限保持一致 PlayFab Party 使用选择加入的聊天通信模型,并且默认将两个[聊天控件](/services/playfab/multiplayer/networking/concepts-objects#chat-control)之间的所有通信限制在双方参与者都启用的通信集合内。有关详细信息,请参阅[聊天权限和静音](/services/playfab/community/voice-communications/concepts-chat-permissions-and-muting)的文档。 PlayFab Party 的 [XBOX Live 帮助程序库](/services/playfab/multiplayer/networking/party-xbox-live-guide)会指示应启用哪些聊天权限,以匹配当前在 Party 会话中通信的 XBOX Live 用户的偏好和权限。有关详细信息,请参阅[尊重 XBOX Live 用户的隐私设置和权限](/services/playfab/multiplayer/networking/party-xbox-live-guide#respecting-an-xbox-live-users-privacy-settings-and-permissions)的文档。 通过正确使用 PlayFab Party 和 [XBOX Live 帮助程序库](/services/playfab/multiplayer/networking/party-xbox-live-guide),你的游戏可以完全满足 [XR-015](https://developer.microsoft.com/games/xbox/docs/gdk/xr015) 中规定的要求,并可以满足 [XR-045](https://developer.microsoft.com/games/xbox/docs/gdk/xr045) 中规定的相关通信要求。有关 PlayFab Party 范围之外的其他要求,请参阅 [XR-045](https://developer.microsoft.com/games/xbox/docs/gdk/xr045) 技术文档。 ## 维护多人会话文档 PlayFab Party 不提供任何 XBOX 用户名单。它依赖你的游戏使用 Multiplayer Session Directory 服务(MPSD)来维护名单,并将 Party 网络活动与游戏会话中的用户关联起来。PlayFab Party 会在远程[终结点](/services/playfab/multiplayer/networking/concepts-objects#endpoint)和[聊天控件](/services/playfab/multiplayer/networking/concepts-objects#chat-control)进出 Party [网络](/services/playfab/multiplayer/networking/concepts-objects#network)时进行通告。应将与这些对象关联的 PlayFab 实体 ID 与 MPSD 文档中的 XBOX 用户进行匹配,以识别哪些 PlayFab Party 对象代表游戏会话中的 XBOX 用户。对于跨平台游戏场景,与 XBOX 用户无关的 PlayFab 实体可能代表其他多人生态系统中的用户。 要识别 XBOX 用户,你应在 PlayFab 实体 ID 与 XBOX Live 用户之间建立映射。要实现此目的,建议将会话的 XBOX Live 用户列表存储在 MPSD 文档中,并使用 XBOX Live 帮助程序库将这些 XBOX Live 用户转换为 PlayFab 实体 ID。有关示例,请参阅 [XBOX Live 用户 ID 与 PlayFab 实体 ID 之间的映射](/services/playfab/multiplayer/networking/party-xbox-live-guide#mapping-between-xbox-live-user-ids-and-playfab-entity-ids)。 除了提供 Party 网络的名单外,MPSD 文档还驱动 XBOX 多人生态系统中的许多多人体验,例如匹配、平台邀请、最近玩家列表和进行中加入。有关如何将 Party 网络整合到这些 MPSD 流程中的详细信息,请参阅[将 PlayFab Party 与 MPSD 一起使用](/services/playfab/multiplayer/networking/using-mpsd)。 有关详细信息,请参阅 [MPSD 概述](/services/xbox-services/multiplayer/mpsd/live-mpsd-overview)。 本节提供了将 PlayFab Party 与 MPSD 一起使用时的最佳实践,但 PlayFab Party 本身并不隐式满足 [XR-067](https://developer.microsoft.com/games/xbox/docs/gdk/xr067) 的 MPSD 要求。有关满足这些要求的信息,请参阅 [XR-067](https://developer.microsoft.com/games/xbox/docs/gdk/xr067) 技术文档。 ## 在跨平台 Party 网络中使用 XBOX 客户端 对于跨平台游戏场景,请在与 XBOX Live 生态系统交互时牢记以下最佳实践。 本节提供了在与 XBOX Live 的跨平台游戏场景中使用 PlayFab Party 的最佳实践,但使用 PlayFab Party 并不隐式满足 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) 的跨平台游戏要求。有关满足这些要求的信息,请参阅 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) 技术文档。 ### 识别跨网络游戏会话中的玩家 在多人生态系统之间,应该可以识别和区分独立的玩家。为此,PlayFab Party 在可能与你会话中的用户关联的各种对象上提供了 PlayFab 实体 ID:`PartyLocalUser`、`PartyEndpoint`、`PartyChatControl`。 PlayFab Party API 不提供跨网络显示名称。在 UI 中显示 XBOX 用户时,应使用其玩家代号,且玩家代号应根据 MPSD 文档中的 XBOX 用户 ID 解析。非 XBOX 用户应根据 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) 中的准则在 UI 中显示。在缺少平台提供的显示名称时,PlayFab 通过 [GetPlayerProfile](xref:titleid.playfabapi.com.client.accountmanagement.getplayerprofile) 提供显示名称支持。加入网络时,玩家应将其显示名称发布到共享的会话文档中,以便其他玩家查看。 尽管 PlayFab Party 库将其某些对象与 PlayFab 用户关联(通过 PlayFab 实体 ID),但该库不提供识别 PlayFab 用户可能关联的多人生态系统的功能。为区分 XBOX Live PlayFab 用户与其他多人生态系统中的用户,建议将 Party 网络中的 PlayFab 实体 ID 与 MPSD 进行交叉引用。有关通过 MPSD 区分 XBOX Live 玩家与非 XBOX Live 玩家的更多信息,请参阅[维护多人会话文档](#maintaining-a-multiplayer-session-document)一节。 有关在与 XBOX Live 的跨平台游戏网络中识别用户的要求的详细信息,请参阅 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007)。 ### 尊重 XBOX Live 用户的跨网络通信权限 PlayFab Party 并不隐式遵守 XBOX Live 的跨网络通信限制。因此,PlayFab Party XBOX Live 帮助程序库提供了查询 XBOX Live 用户跨网络通信权限的功能。你必须使用这些信息以符合 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) 中规定的跨网络通信要求。 有关详细信息,请参阅[尊重跨网络通信](/services/playfab/multiplayer/networking/party-xbox-live-guide#respecting-cross-network-communication-permissions)。 ### 当不允许跨平台游戏时,使用 PlayFab Party 邀请限制对网络的访问。 XBOX Live 用户需要拥有跨网络权限才能在跨网络游戏会话中与非 XBOX Live 用户进行交互。PlayFab Party 并不隐式遵守这些跨网络限制(在 [XR-007](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) 中概述),因此必须在 PlayFab Party 库之外查询此权限。当未授予这些权限时,你应限制 Party 网络,仅允许游戏会话的 MPSD 文档中已知的 XBOX Live 用户。你可以通过增强我们的示例[进行中加入流程](/services/playfab/multiplayer/networking/using-mpsd#join-in-progress)来实现此目的,使用仅允许已知 XBOX 用户加入网络的 Party 邀请。 首先,请确保使用受限邀请创建 Party 网络。 ```cpp theme={null} PartyString networkCreatorEntityId; RETURN_VOID_IF_FAILED(m_localPartyUser->GetEntityId(&networkCreatorEntityId)); PartyInvitationConfiguration newNetworkInitialInvite{}; newNetworkInitialInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity newNetworkInitialInvite.revocability = PartyInvitationRevocability::Anyone; // the initial invitation must be revocable by anyone // this initial invitation only allows the original xbl user creating the network newNetworkInitialInvite.entityIdCount = 1; newNetworkInitialInvite.entityIds = &networkCreatorEntityId; PartyError error = PartyManager::GetSingleton().CreateNewNetwork( m_localPartyUser, &networkConfiguration, 0, nullptr, &newNetworkInitialInvite, nullptr, nullptr, nullptr); ``` 与[进行中加入流程](/services/playfab/multiplayer/networking/using-mpsd#join-in-progress)类似,当新的 XBOX 用户想要加入网络时,他们将首先将自己添加到会话文档中。当想要允许他们加入网络的玩家看到更新时,他们将更新邀请集合以反映会话文档。这将确保只有会话文档中的用户(保证是 XBOX Live 用户)才能加入网络。 ```cpp theme={null} void OnSessionDocumentUpdated( PartyNetwork* network, uint32_t usersInDocumentCount, const uint64_t* usersInDocument ) { PartyInvitationConfiguration newInvite{}; newInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity newInvite.revocability = PartyInvitationRevocability::Creator; // must be revocable by the creator only // the updated invite should contain all users currently in the document std::vector entityIdsInDocument; for (uint32_t i = 0; i < usersInDocumentCount; ++i) { uint64_t xboxUserId = usersInDocument[i]; // Call title-defined xuid->entityid mapping helper PartyString xboxUserEntityId = GetEntityIdFromXboxUserId(xboxUserId); if (xboxUserEntityId != nullptr) { entityIdsInDocument.push_back(xboxUserEntityId); } else { DEBUGLOG("User %llu did not have a matching entity ID.", xboxUserId); } } newInvite.entityIdCount = entityIdsInDocument.size(); newInvite.entityIds = entityIdsInDocument.data(); // Create a new invitation which includes all of the users currently in the document PartyInvitation* newInvitation; PartyError error = network->CreateInvitation( m_localUser, &newInvite, nullptr, &newInvitation); if (PARTY_FAILED(error)) { DEBUGLOG("PartyNetwork(0x%p)::CreateInvitation failed! (error=0x%x)", network, error); return; } // Post the invitation's id somewhere that it can be seen by anyone trying to join/rejoin PostInvitationToMPSD(newInvite); // Cleanup previous invitations. This isn't strictly necessary, but is a good practice. uint32_t invitationCount; PartyInvitationArray invitations; error = network->GetInvitations(&invitationCount, &invitations); if (PARTY_FAILED(error)) { DEBUGLOG("PartyNetwork(0x%p)::GetInvitations failed! (error=0x%x)", network, error); return; } for (uint32_t i = 0; i < invitationCount; ++i) { if (invitations[i] == newInvite) { continue; // don't prune the old invitation } PartyInvitation* oldInvitation = invitations[i]; error = network->RevokeInvitation(m_localUser, oldInvitation, nullptr); if (PARTY_FAILED(error)) { DEBUGLOG("PartyNetwork(0x%p)::RevokeInvitation failed! (err=0x%x)", network, error); } } } ``` 由于需要在 XBOX Live 用户 ID 与 PlayFab 实体 ID 之间进行转换,建议在两者之间构建映射。有关如何执行此操作的示例,请参阅 [XBOX Live 用户 ID 与 PlayFab 实体 ID 之间的映射](/services/playfab/multiplayer/networking/party-xbox-live-guide#mapping-between-xbox-live-user-ids-and-playfab-entity-ids)。 ## 与 XBOX Live 配置文件设置保持同步 PlayFab Party 默认符合 [XR-048](https://developer.microsoft.com/games/xbox/docs/gdk/xr048) 中的配置文件设置要求。该库不会持久缓存任何 XBOX Live 配置文件设置。当 PlayFab Party 需要使用配置文件设置时,会从 XBOX Live 查询设置,且这些设置在与该设置关联的 PlayFab Party API 对象的生命周期内保持有效,但不会在对象的多个实例之间持续存在。 有关在 PlayFab Party 之外使用 XBOX Live 配置文件设置数据的信息,请参阅 [XR-048](https://developer.microsoft.com/games/xbox/docs/gdk/xr048) 技术文档。 ## 支持平台多人游戏加入流程 在 XBOX 上,玩家可以通过进行中加入和平台邀请功能加入多人游戏。PlayFab Party 不直接与这些平台功能集成,但通过 `PartyNetworkDescriptor` 和 `PartyInvitation` 对象来支持它们的使用。`PartyNetworkDescriptor` 对象提供远程用户查找和连接到 Party 网络所需的连接信息,并可通过 `PartyManager::SerializeNetworkDescriptor` 进行序列化。`PartyInvitation` 对象为远程用户提供用于身份验证和加入 Party 网络的 ID。为使远程用户能够通过进行中加入和平台邀请加入多人游戏,请将序列化的网络描述符和 Party 邀请标识符集成到你现有的流程中。示例流程也可以在[将 PlayFab Party 与 MPSD 一起使用](/services/playfab/multiplayer/networking/using-mpsd)文档中找到。 有关平台多人游戏加入流程要求的详细信息,请参阅 [XR-064](https://developer.microsoft.com/games/xbox/docs/gdk/xr064) 和 [XR-124](https://developer.microsoft.com/games/xbox/docs/gdk/console-certification-requirements-and-tests) 技术文档。 ## 好友列表 尽管 PlayFab Party 在任何平台上都不会原生地与好友列表交互,但多人游戏在不同场景下仍可能需要考虑好友列表。有关与 XBOX Live 和跨网络好友列表交互时的要求和指南,请参阅以下文档: * [XBOX Live 好友列表要求 (XR-070)](https://developer.microsoft.com/games/xbox/docs/gdk/console-certification-requirements-and-tests) * [跨网络好友列表要求 (XR-007)](https://developer.microsoft.com/games/xbox/docs/gdk/xr007) * [XBOX Social Manager](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/live/get-started/live-xbl-overview) * [XBOX Live Services API (XSAPI)](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/live/get-started/live-xbl-overview) ## 遵守 XBOX Live 服务重试策略和服务访问限制。 除 [XBOX Live 帮助程序库](/services/playfab/multiplayer/networking/party-xbox-live-guide)外,PlayFab Party 不会直接与 XBOX Live 服务交互。XBOX Live 帮助程序库在内部会遵守 [XR-074](https://developer.microsoft.com/games/xbox/docs/gdk/xr074) 和 [XR-132](https://developer.microsoft.com/games/xbox/docs/gdk/xr132) 中概述的其相关 XBOX Live 服务的重试策略和访问限制。此外,你可以通过 XBOX Live 帮助程序库报告的以下错误代码识别因遵守这些服务策略而导致的 API 失败:[PartyXblChatPermissionMaskReason::XboxLiveServiceError](/services/playfab/multiplayer/networking/xblreference/enums/partyxblchatpermissionmaskreason) 和 [PartyXblStateChangeResult::PartyServiceError](/services/playfab/multiplayer/networking/xblreference/enums/partyxblstatechangeresult)。 有关在 XBOX Live 帮助程序库之外遵守这些服务策略的详细信息,请参阅 [XR-074](https://developer.microsoft.com/games/xbox/docs/gdk/xr074) 和 [XR-132](https://developer.microsoft.com/games/xbox/docs/gdk/xr132) 技术文档。 ## Related topics - [在合作伙伴中心提交到 XBOX 认证](/zh-CN/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-submitting-to-certification.md) - [XBOX 要求 (XR) 认证参考](/zh-CN/publishing/certification/xbox-requirements.md) - [PC 和移动游戏的 XBOX 要求测试用例](/zh-CN/publishing/certification/pc-policy-tests.md) - [PC 和移动认证要求以及最常见的失败](/zh-CN/publishing/certification/pc-certification.md) - [术语表](/zh-CN/publishing/game-publishing/glossary.md)