搭配 MPSD 使用 PlayFab Party

XBOX 多人遊戲案例依賴多人遊戲工作階段目錄 (MPSD) 服務和 MPSD 文件。MPSD 文件可作為您目前遊戲工作階段的名冊，並驅動配對、平台邀請、最近玩家清單和中途加入等多人遊戲體驗。 本文件將說明如何將 PlayFab Party 納入需要 MPSD 的常見多人遊戲流程中。 本文件不會深入討論 MPSD 及其所有功能。如需詳細資訊，請參閱 MPSD 文件。

​

配對

以下是搭配 PlayFab Party 使用配對和 MPSD 的簡化流程：

1. 玩家會建立並聚集到 MPSD 工作階段中，這些工作階段代表他們想要在各個配對工作階段中一起遊玩的群組。玩家會使用 XBOX 的邀請和加入功能聚集到這些工作階段中。
2. 這些玩家群組會向配對服務提交票證，配對服務會將相容的玩家群組聚集到配對工作階段中。此配對工作階段本身會以新的工作階段文件表示，玩家接著會加入該文件。玩家也必須接聽此工作階段文件的變更。
3. 配對工作階段完成且名冊鎖定後，遊戲必須從配對工作階段的成員中選出一位來設定 PlayFab Party 網路。選取 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 收到平台邀請，其中包含「邀請控制代碼」，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;
       }
   }
   

​

中途加入

加入進行中的遊戲工作階段與平台邀請案例非常類似。核心差異在於，PlayerB 不是從 PlayerA 收到「邀請控制代碼」，而是在從平台 UI 發起中途加入時取得「加入控制代碼」。PlayerB 會使用此「加入控制代碼」加入工作階段文件並接聽變更。PlayerA 會透過建立新的 Party 邀請並將其發佈至工作階段文件來回應。PlayerB 會看到這個新邀請以及網路描述元，並使用它加入 Party 網路。

​

中斷連線和清除

如果玩家離開 Party 網路或因其他原因與其中斷連線，也應將自己從與該 Party 網路相關聯的任何 MPSD 工作階段中移除。非由 PartyNetwork::LeaveNetwork 作業起始的 Party 網路中斷連線會被視為嚴重錯誤。發生嚴重中斷連線後，玩家可以嘗試重新連線並重新驗證進入網路，但也必須重新加入 MPSD 工作階段。 如果玩家與 MPSD 工作階段的連線暫時中斷，他們可能會與該工作階段中斷連線。玩家可以嘗試重新加入工作階段，但如果失敗，應呼叫 PartyNetwork::LeaveNetwork 自願將自己從 Party 網路中移除。 如果遊戲關閉，玩家會自動與 Party 網路和 MPSD 文件中斷連線，不需要進一步清除。