Xbox 要件
ゲームが Xbox 本体をターゲットにしている場合は、Xbox Live とやり取りする際に一貫した機能と動作を確保するために、一連の要件に従う必要があります。 この一連の要件は、 Xbox 要件 (略して XR) に記載されています。 XR は、PC やその他のプラットフォーム上のゲームで Xbox Live を利用するために必要なポリシーでやり取りし、重複します。 ここでは、これらの要件に準拠するのに役立つ PlayFab パーティー のベスト プラクティスについて説明します。
クイック リファレンスについては、PlayFab パーティーのシナリオと対応する XR に一致する次の表を参照してください。
PlayFab パーティー向け Xbox Live ヘルパー ライブラリ
主要な PlayFab パーティー ライブラリと共に、Xbox Live ポリシーと拡張機能によって XR に準拠できるように設計された Xbox Live Helper ライブラリ を提供しています。 このヘルパー ライブラリの使用は必須ではありませんが、強く推奨され、ベスト プラクティスと見なされます。 ここで示す例では、Xbox Live ヘルパー ライブラリを使用することを前提としています。
PlayFab パーティーを Xbox Live ユーザーのチャット設定と権限に合わせる
PlayFab パーティーはチャット通信のオプトイン モデルを使用し、既定では、2 つの チャット コントロール間のすべての通信を、両方の参加者が有効にした通信のセットに制限します。 詳細については、チャットのアクセス許可とミューティングに関するドキュメントを参照してください。
PlayFab パーティーの Xbox Live ヘルパー ライブラリは、パーティー セッションで現在通信している Xbox Live ユーザーの基本設定と権限に一致させるために有効にする必要があるチャットアクセス許可のセットを示します。 詳細については、Xbox Live ユーザーのプライバシー設定とアクセス許可を尊重するドキュメントを参照してください。
PlayFab パーティーと Xbox Live ヘルパー ライブラリを適切に使用することで、ゲームは XR-015 で指定された要件を完全に満たすことができます。また、 XR-045 で指定された関連する通信要件を満たすことができます。 PlayFab パーティーの範囲外のその他の要件については、 XR-045 技術ドキュメントを参照してください。
マルチプレイヤー セッション ドキュメントを保持する
PlayFab パーティーでは、Xbox ユーザー名簿は提供されません。 マルチプレイヤー セッション ディレクトリ サービス (MPSD) を使用してゲームに依存し、名簿を維持し、パーティー ネットワーク アクティビティをゲーム セッションのユーザーに関連付けます。 PlayFab パーティーは、リモート エンドポイントおよびチャット コントロールがパーティー ネットワークから送受信するよう宣伝します。 これらのオブジェクトに関連付けられている PlayFab エンティティ ID は、MPSD ドキュメント内の Xbox ユーザーと照合して、ゲーム セッションで Xbox ユーザーを表す PlayFab パーティー オブジェクトを認識する必要があります。 クロスプレイ シナリオでは、Xbox ユーザーに関連付けられていない PlayFab エンティティが、別のマルチプレイヤー エコシステム内のユーザーを表す場合があります。
Xbox ユーザーを認識するには、PlayFab エンティティ ID と Xbox Live ユーザーの間にマッピングを作成する必要があります。 これを実現するには、セッションの Xbox Live ユーザーの一覧を MPSD ドキュメントに格納し、Xbox Live ヘルパー ライブラリを使用してそれらの Xbox Live ユーザーを PlayFab エンティティ ID に変換することをお勧めします。 例として、「Xbox Live ユーザー ID と PlayFab エンティティ ID のマッピング」を参照してください。
MPSD ドキュメントは、パーティー ネットワークの名簿を提供するだけでなく、マッチメイキング、プラットフォームへの招待、最近のプレイヤー リスト、進行中の参加など、Xbox マルチプレイヤー エコシステムの多くのマルチプレイヤー エクスペリエンスを促進します。 これらの MPSD フローにパーティー ネットワークを組み込む方法の詳細については、「MPSDでの PlayFab パーティーの使用」を参照してください。
詳細については、 「MPSD の概要」を参照してください。
Important
このセクションでは、MPSD と共に PlayFab パーティーを使用する場合のベスト プラクティスについて説明しますが、PlayFab パーティー自体は、 XR-067の MPSD 要件を暗黙的に満たしていません。 これらの要件を満たす方法については、 XR-067 技術ドキュメントを参照してください。
クロスプレイ パーティー ネットワークで Xbox クライアントを使用する
クロスプレイ シナリオの場合は、Xbox Live エコシステムと対話する際の次のベスト プラクティスに注意してください。
Important
このセクションでは、Xbox Live を使用したクロスプレイ シナリオで PlayFab パーティーを使用するためのベスト プラクティスについて説明しますが、PlayFab パーティーの使用は、 XR-007のクロスプレイ要件を暗黙的に満たしていません。 これらの要件を満たす方法については、 XR-007 技術ドキュメントを参照してください。
クロスネットワーク ゲーム セッションにおけるプレイヤーを識別する
一意のプレイヤーは、マルチプレイヤー エコシステム全体で識別および区別できる必要があります。 このため、PlayFab パーティーは、セッション内のユーザーに関連付けられている可能性のあるさまざまなオブジェクト ( PartyLocalUser、 PartyEndpoint、 PartyChatControl) に PlayFab エンティティ ID を提供します。
ネットワーク間の表示名は、PlayFab パーティー API では提供されません。 UI で Xbox ユーザーを表示する場合は、ゲーマータグを使用する必要があります。ゲーマータグは MPSD ドキュメントの Xbox ユーザー ID から解決する必要があります。 Xbox 以外のユーザーは、XR-007のガイドラインに基づいて UI で表示する必要があります。 プラットフォームによって提供される表示名がない場合、PlayFab は GetPlayerProfile を介して表示名をサポートします。 ネットワークに参加する場合、プレイヤーは他のプレイヤーが表示できるように、共有セッション ドキュメントに表示名を投稿する必要があります。
PlayFab パーティー ライブラリは、そのオブジェクトの一部を (PlayFab エンティティ ID を介して) PlayFab ユーザーと関連付けますが、このライブラリには、PlayFab ユーザーが関連付けられている可能性のあるマルチプレイヤー エコシステムを識別する機能が用意されていません。 Xbox Live PlayFab ユーザーを他のマルチプレイヤー エコシステムのユーザーと区別するには、MPSD を使用してパーティー ネットワーク内の PlayFab エンティティ ID を相互参照することをお勧めします。 MPSD を介して Xbox Live プレイヤーと非 Xbox Live プレイヤーを区別する方法の詳細については、「マルチプレイヤー セッション ドキュメントの管理」のセクションを参照してください。
Xbox Live を使用したクロスプレイ ネットワーク内のユーザーの識別に関する要件の詳細については、「XR-007」を参照してください。
Xbox Live ユーザーのクロスネットワーク通信のアクセス許可を尊重する
PlayFab パーティーは、Xbox Live のクロスネットワーク通信制限に暗黙的に準拠していません。 そのため、PlayFab パーティー Xbox Live ヘルパー ライブラリには、Xbox Live ユーザーのクロスネットワーク通信アクセス許可を照会するための機能が用意されています。 XR-007 で指定されているクロスネットワーク通信要件に準拠するには、この情報を使用する必要があります。
詳細については、「クロスネットワーク通信を尊重する」 を参照してください。
クロスプレイが許可されていない場合に PlayFab パーティーの招待を使用してネットワークへのアクセスを制限します。
Xbox Live ユーザーは、クロスネットワーク ゲーム セッションで Xbox Live 以外のユーザーと対話するために、クロスネットワーク特権を必要とします。 PlayFab パーティーは、これらのクロスネットワーク制限 (XR-007で説明) に暗黙的に準拠していないため、PlayFab パーティー ライブラリの外部でこの特権を照会する必要があります。 これらの特権が与えられていない場合は、ゲーム セッションの MPSD ドキュメントで認識されている Xbox Live ユーザーのみを許可するようにパーティー ネットワークを制限する必要があります。 これを実現するには、既知の Xbox ユーザーのみがネットワークに参加できるようにするパーティーへの招待を使用するように、サンプル join-in-progress フローを拡張します。
まず、パーティー ネットワークが制限された招待で作成されていることを確認します。
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);
join-in-progress フローと同様に、新しい Xbox ユーザーがネットワークに参加する場合は、最初にセッション ドキュメントに自分自身を追加します。 ネットワークへの参加を許可するプレイヤーが更新を確認すると、招待のセットが更新されてセッション ドキュメントが反映されます。 これにより、セッション ドキュメント内のユーザー (Xbox Live ユーザーであることが保証されます) のみがネットワークに参加できるようになります。
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<PartyString> 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 の間で変換する必要があるため、2 つの間にマッピングを作成することをお勧めします。 このやり方の例については、「Xbox Live ユーザー ID と PlayFab エンティティ ID のマッピング」を参照してください。
Xbox Live プロファイル設定との同期を維持する
PlayFab パーティーは、既定では XR-048 のプロファイル設定要件に準拠しています。 ライブラリは、Xbox Live プロファイル設定の永続的なキャッシュを保持しません。 PlayFab パーティーの使用にプロファイル設定が必要な場合、設定は Xbox Live からクエリされ、設定に関連付けられている PlayFab パーティー API オブジェクトの有効期間中は有効なままになりますが、オブジェクトの複数のインスタンス間では保持されません。
PlayFab パーティーの外部で Xbox Live プロファイル設定データを使用する方法については、XR-048 技術ドキュメントを参照してください。
プラットフォーム マルチプレイヤー参加フローをサポートする
Xbox では、join-in-progress とプラットフォーム招待機能を使用してマルチプレイヤー ゲームに参加できます。 PlayFab パーティは、これらのプラットフォーム昨日を直接統合しませんが、 PartyNetworkDescriptor と PartyInvitation のオブジェクトを通じてその使用をサポートします。 PartyNetworkDescriptor オブジェクトは、リモート ユーザーが パーティー ネットワークを検索して接続するために必要な接続情報を提供し、PartyManager::SerializeNetworkDescriptor を介してシリアル化できます。 PartyInvitation オブジェクトは、パーティー ネットワークへの認証と参加に使用される ID をリモート ユーザーに提供します。 リモート ユーザーが join-in-progress とプラットフォームへの招待を介してマルチプレイヤー ゲームに参加できるようにするには、シリアル化されたネットワーク記述子とパーティー招待識別子を事前に既存のフローに統合します。 フローの例は、「MPSD で PlayFab を使用する」 ドキュメントでも確認できます。
プラットフォーム マルチプレイヤーの参加フローの要件の詳細については、XR-064 と XR-124 の技術ドキュメントを参照してください。
フレンド リスト
PlayFab パーティーはどのプラットフォームでもフレンド リストとネイティブに対話しませんが、マルチプレイヤー ゲームでは、さまざまなシナリオでフレンド リストを検討する必要がある場合があります。 Xbox Live およびクロスネットワークのフレンド リストを操作するときの要件とガイダンスについては、次のドキュメントを参照してください。
- Xbox Live フレンド リストの要件 (XR-070)
- クロスネットワークフレンド リストの要件 (XR-007)
- Xbox ソーシャル マネージャー
- Xbox Live サービス API (XSAPI)
Xbox Live サービス再試行ポリシーとサービス アクセス制限を遵守する。
PlayFab パーティーは、 Xbox Live ヘルパー ライブラリ外の Xbox Live サービスと直接対話しません。 Xbox Live ヘルパー ライブラリは、内部的には、 XR-074 および XR-132 で説明されているように、関連するXbox Live サービスの再試行ポリシーとアクセス制限に準拠しています。 また、Xbox Live ヘルパー ライブラリによって報告される次のエラー コードを通じて、これらのサービス ポリシーに準拠した結果として API エラーを認識できます。 PartyXblChatPermissionMaskReason::XboxLiveServiceError と PartyXblStateChangeResult::PartyServiceError。
Xbox Live ヘルパー ライブラリの外部でこれらのサービス ポリシーに準拠する方法の詳細については、XR-074 および XR-132 の技術ドキュメントを参照してください。