MPSD で PlayFab Party を使用する

XBOX のマルチプレイヤーシナリオは、Multiplayer Session Directory (MPSD) サービスと MPSD ドキュメントの使用に依存しています。MPSD ドキュメントは現在のゲームセッションの名簿として機能し、マッチメイキング、プラットフォーム招待、最近のプレイヤーリスト、ジョインインプログレスなどのマルチプレイヤー体験を支えます。 このドキュメントでは、MPSD を必要とする一般的なマルチプレイヤーフローに PlayFab Party を組み込む方法を説明します。 このドキュメントでは、MPSD とそのすべての機能について詳しく説明することはしません。詳細については、MPSD のドキュメント を参照してください。

​

マッチメイキング

以下は、PlayFab Party と共にマッチメイキングと MPSD を使用する簡略化されたフローです。

1. プレイヤーは、マッチメイキングセッションをまたいで一緒にプレイしたいグループを表す MPSD セッションを作成し、そこに集まります。プレイヤーは XBOX の招待および参加機能を使用してこれらのセッションに集まります。
2. これらのプレイヤーグループはマッチメイキングサービスにチケットを送信し、互換性のあるプレイヤーグループがマッチメイキングセッションにまとめられます。このマッチメイキングセッション自体は、新しいセッションドキュメントで表され、その後プレイヤーが参加します。プレイヤーはまた、このセッションドキュメントの変更を監視する必要があります。
3. マッチメイキングセッションが確定し、名簿がロックされたら、タイトルは PlayFab Party ネットワークをセットアップするマッチメイキングセッションのメンバーのうち 1 人を選出する必要があります。Party ネットワーク作成者を選択するシンプルな戦略は、マッチメイキング MPSD セッションドキュメントの最初のメンバーを使用することです。
4. 選出されたメンバーは、マッチメイキングセッションのメンバーのみにネットワークアクセスを制限する初期 PartyInvitation を使用してネットワークを作成します。ネットワークの作成が正常に完了したら、選出されたメンバーは結果のネットワーク記述子と Party 招待をセッションドキュメントにセッションプロパティとして投稿し、他のメンバーが使用できるようにする必要があります。
   void
   OnMatchmakingSessionFinalized(
       uint32_t usersInSessionCount,
       const uint64_t* usersInSession
       )
   {
       PartyInvitationConfiguration initialInvite{};
       initialInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity
       initialInvite.revocability = PartyInvitationRevocability::Anyone; // must be revocable by anyone
   
       // the updated invite should contain all users in the matchmaking session
       std::vector<PartyString> entityIdsInSession;
       for (uint32_t i = 0; i < usersInSessionCount; ++i)
       {
           uint64_t xboxUserId = usersInSession[i];
           // Call title-defined xuid->entityid mapping helper
           PartyString xboxUserEntityId = GetEntityIdFromXboxUserId(xboxUserId);
           if (xboxUserEntityId != nullptr)
           {
               entityIdsInSession.push_back(xboxUserEntityId);
           }
           else
           {
               DEBUGLOG("User %llu did not have a matching entity ID.", xboxUserId);
           }
       }
       initialInvite.entityIdCount = entityIdsInSession.size();
       initialInvite.entityIds = entityIdsInSession.data();
   
       // This is an asynchronous call. It will be completed when StartProcessingStateChanges generates a
       // PartyCreateNewNetworkCompletedStateChange struct
       PartyError error = PartyManager::GetSingleton().CreateNewNetwork(
           m_localPartyUser,
           &networkConfiguration,
           0,
           nullptr,
           &initialInvite,
           nullptr,
           nullptr,
           nullptr);
       if (FAILED(error))
       {
           DEBUGLOG("PartyManager::CreateNetwork failed! 0x%08x\n", error);
           return;
       }
   }
   
   void
   HandleCreateNewNetworkCompleted(
       const PartyCreateNewNetworkCompletedStateChange& createNewNetworkCompletedStateChange
       )
   {
       if (createNewNetworkCompletedStateChange.result == PartyStateChangeResult::Succeeded)
       {
           // The network was created successfully! Post the networks descriptor and invitation
   
           char serializedDescriptor[c_maxSerializedNetworkDescriptorStringLength + 1];
           PartyError error = PartyManager::SerializeNetworkDescriptor(
               &createNewNetworkCompletedStateChange.networkDescriptor,
               serializedDescriptor);
           if (PARTY_FAILED(error))
           {
               DEBUGLOG("PartyManager::SerializeNetworkDescriptor failed: 0x%08x\n", error);
               return;
           }
   
           UpdateSessionProperty(
               "PartyNetworkDescriptor", // arbitrary property name
               serializedDescriptor);
   
           UpdateSessionProperty(
               "PartyInitialInvitation", // arbitrary property name
               createNewNetworkCompletedStateChange.appliedInitialInvitationIdentifier);
       }
       else
       {
           // The network was not created successfully.
           // Please refer to CreateNewNetwork reference documentation for retry guidance
       }
   }
   
5. 各メンバーはセッションドキュメントの更新を確認したら、ネットワーク記述子と招待を使用してネットワークに接続し、参加できます。
   void
   OnNetworkInformationPostedToSessionDocument(
       PartyString serializedNetworkDescriptor,
       PartyString invitationId
       )
   {
       PartyNetworkDescriptor networkDescriptor;
       PartyError error = PartyManager::DeserializeNetworkDescriptor(serializedNetworkDescriptor, &networkDescriptor);
       if (PARTY_FAILED(error))
       {
           DEBUGLOG("PartyManager::DeserializeNetworkDescriptor failed: 0x%08x\n", error);
           return;
       }
   
       // attempt to connect to the network
       PartyNetwork* network;
       error = PartyManager::GetSingleton().ConnectToNetwork(
           &networkDescriptor,
           nullptr,
           &network);
       if (PARTY_FAILED(error))
       {
           DEBUGLOG("PartyManager::ConnectToNetwork failed: 0x%08x\n", error);
           return;
       }
   
       // immediately queue an authentication on the network we've attempted to connect to.
       error = network->AuthenticateLocalUser(
           m_localUser,
           invitationId,
           nullptr);
       if (PARTY_FAILED(error))
       {
           DEBUGLOG("PartyNetwork::AuthenticateLocalUser failed: 0x%08x\n", error);
           return;
       }
   }
   

​

プラットフォーム招待

以下は、XBOX プラットフォームの招待を PlayFab Party に組み込むフローです。

1. PlayerA が MPSD セッションドキュメントを作成し、セッションの変更を監視し、Party ネットワークを作成します。Party ネットワークの作成が完了したら、PlayerA はネットワーク記述子と初期招待（必要な場合）を MPSD セッションドキュメントに投稿します。
   void
   OnSessionDocumentCreated()
   {
       // This is an asynchronous call. It will be completed when StartProcessingStateChanges generates a
       // PartyCreateNewNetworkCompletedStateChange struct
       PartyError error = PartyManager::GetSingleton().CreateNewNetwork(
           m_localPartyUser,
           &networkConfiguration,
           0,
           nullptr,
           nullptr,
           nullptr,
           nullptr,
           nullptr);
       if (FAILED(error))
       {
           DEBUGLOG("PartyManager::CreateNetwork failed! 0x%08x\n", error);
           return;
       }
   }
   
   void
   HandleCreateNewNetworkCompleted(
       const PartyCreateNewNetworkCompletedStateChange& createNewNetworkCompletedStateChange
       )
   {
       if (createNewNetworkCompletedStateChange.result == PartyStateChangeResult::Succeeded)
       {
           // The network was created successfully! Post the networks descriptor and invitation
   
           char serializedDescriptor[c_maxSerializedNetworkDescriptorStringLength + 1];
           PartyError error = PartyManager::SerializeNetworkDescriptor(
               &createNewNetworkCompletedStateChange.networkDescriptor,
               serializedDescriptor);
           if (PARTY_FAILED(error))
           {
               DEBUGLOG("PartyManager::SerializeNetworkDescriptor failed: 0x%08x\n", error);
               return;
           }
   
           UpdateSessionProperty(
               "PartyNetworkDescriptor", // arbitrary property name
               serializedDescriptor);
       }
       else
       {
           // The network was not created successfully.
           // Please refer to CreateNewNetwork reference documentation for retry guidance
       }
   }
   
2. PlayerA が PlayerB を Party ネットワークに招待したい場合、PlayerA はゲーム内またはコンソール UI 経由でプラットフォーム招待を PlayerB に開始します。
3. PlayerB は、PlayerA の MPSD セッションドキュメントを検索するために使用できる「招待ハンドル」を含むプラットフォーム招待を受け取ります。
4. PlayerB はセッションドキュメントに参加し、変更を監視します。
5. PlayerA は PlayerB がセッションドキュメントに参加したことを確認します。PlayerA は PlayerB が使用するための新しい招待を作成し、その招待をセッションドキュメントに投稿します
   void
   OnUserJoinedSessionDocument(
       PartyNetwork* network,
       uint64_t newSessionMemberXboxUserId
       )
   {
       std::string newMemberIdString = std::to_string(newSessionMemberXboxUserId);
   
       // Specify our own invitation id so we don't have to query for it after the invitation has been created.
       // Here we will specify the invite id with the format "InviterXboxUserID_InviteeXboxUserID" so that we can
       // ensure this invitation ID doesn't clash with the invitations other members might try and create for this user.
       std::string invitationId = std::to_string(m_localXboxUserId) + "_" + newMemberIdString;
   
       PartyInvitationConfiguration newInvite{};
       newInvite.identifier = invitationId.c_str();
       newInvite.revocability = PartyInvitationRevocability::Creator; // must be revocable by the creator only
   
       // Call title-defined xuid->entityid mapping helper
       PartyString newSessionMemberEntityId = GetEntityIdFromXboxUserId(newSessionMemberXboxUserId);
       newInvite.entityIdCount = 1;
       newInvite.entityIds = &newSessionMemberEntityId;
   
       // 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 to the local user's member property store in the session document, key'd by the invitee's
       // xbox user id. This will let the invitee recognize when an invitation is intended for them.
       UpdateMemberProperty(
           newMemberIdString.c_str(),
           invitationId.c_str());
   }
   
6. PlayerB はセッションドキュメントに投稿された招待を確認し、それを使用して Party ネットワークに参加します。
   void
   OnRemoteMemberPropertyUpdated(
       PartyString memberPropertyKey,
       PartyString memberPropertyValue
       )
   {
       // The member property update signifies a new invitation, if the remote member updated a property that matches
       // our xbox user id.
       if (memberPropertyKey == std::to_string(m_localXboxUserId))
       {
           OnUserInvitationPostedToSessionDocument(memberPropertyValue);
       }
   
       // ...
   }
   
   void
   OnUserInvitationPostedToSessionDocument(
       PartyString invitationId
       )
   {
       // The network descriptor should have already been posted to the session document before the invitation.
       // Call title-defined function to pull it from the session document.
       PartyNetworkDescriptor networkDescriptor = QueryNetworkDescriptorFromSessionDocument();
   
       // attempt to connect to the network
       PartyNetwork* network;
       error = PartyManager::GetSingleton().ConnectToNetwork(
           &networkDescriptor,
           nullptr,
           &network);
       if (PARTY_FAILED(error))
       {
           DEBUGLOG("PartyManager::ConnectToNetwork failed: 0x%08x\n", error);
           return;
       }
   
       // immediately queue an authentication on the network we've attempted to connect to.
       error = network->AuthenticateLocalUser(
           m_localUser,
           invitationId,
           nullptr);
       if (PARTY_FAILED(error))
       {
           DEBUGLOG("PartyNetwork::AuthenticateLocalUser failed: 0x%08x\n", error);
           return;
       }
   }
   

​

ジョインインプログレス

進行中のゲームセッションへの参加は、プラットフォーム招待 のシナリオと非常によく似ています。中核となる違いは、PlayerA が PlayerB に「招待ハンドル」を送信する代わりに、PlayerB がプラットフォーム UI からジョインインプログレスを開始したときに「参加ハンドル」を取得することです。この「参加ハンドル」を使用して、PlayerB はセッションドキュメントに参加し、変更を監視します。PlayerA は、新しい Party 招待を作成してセッションドキュメントに投稿することでこれに応答します。PlayerB は、ネットワーク記述子と共にこの新しい招待を確認し、それを使用して Party ネットワークに参加します。

​

切断とクリーンアップ

プレイヤーが Party ネットワークを離れる、または何らかの形で切断された場合、その Party ネットワークに関連付けられた MPSD セッションからも自身を削除する必要があります。PartyNetwork::LeaveNetwork 操作によって開始されない Party ネットワークの切断は、致命的とみなされます。致命的な切断を経験した後、プレイヤーはネットワークへの再接続と再認証を試みることができますが、MPSD セッションにも再参加する必要があります。 プレイヤーの MPSD セッションへの接続が一時的に中断された場合、そのセッションから切断される可能性があります。プレイヤーはセッションへの再参加を試みることができますが、失敗した場合は、PartyNetwork::LeaveNetwork を呼び出して自発的に Party ネットワークから離脱するべきです。 ゲームがシャットダウンすると、プレイヤーは Party ネットワークと MPSD ドキュメントから自動的に切断され、それ以上のクリーンアップは必要ありません。