多人遊戲工作

• 訂閱多人遊戲工作階段目錄 (MPSD) 工作階段變更通知
• 建立 MPSD 工作階段
• 為 MPSD 工作階段設定仲裁者
• 管理遊戲啟用
• 讓使用者可被加入
• 傳送遊戲邀請
• 從大廳工作階段加入遊戲工作階段
• 從遊戲啟用加入 MPSD 工作階段
• 設定使用者目前的活動
• 更新 MPSD 工作階段
• 離開 MPSD 工作階段
• 在配對期間填補開放的工作階段位置
• 建立對戰票證
• 取得對戰票證狀態

​

訂閱多人遊戲工作階段目錄 (MPSD) 工作階段變更通知

1. 同一位使用者的所有呼叫都使用相同的 XblContextHandle 物件。訂閱與此物件的存留期繫結。如果有多位本機使用者，請為每位使用者使用個別的 XblContextHandle 物件。
2. 為 XblMultiplayerAddSessionChangedHandler 與 XblMultiplayerSessionSubscriptionLostHandler 實作事件處理常式。
3. 如果要為多位使用者訂閱變更，請在 XblMultiplayerAddSessionChangedHandler 事件處理常式中新增程式碼，以避免不必要的工作。請使用 XblMultiplayerSessionChangeEventArgs::Branch 屬性與 XblMultiplayerSessionChangeEventArgs::ChangeNumber 屬性。使用這些屬性可讓您追蹤最後看到的變更，並忽略較舊的變更。
4. 呼叫 XblMultiplayerSetSubscriptionsEnabled 以允許訂閱。
5. 建立本機工作階段物件，然後以作用中身分加入該工作階段。
6. 為每位使用者呼叫 XblMultiplayerAddSessionChangedHandler，並傳遞要接收通知的工作階段變更類型。
7. 依照本主題中更新 MPSD 工作階段一節的說明，將工作階段寫入 MPSD。

​

剖析重複的工作階段變更通知

• 為每個評估過的 Branch 屬性值，儲存最新的 ChangeNumber 屬性值。
• 如果肩拍通知的 ChangeNumber 屬性值高於該 Branch 屬性值所儲存的最新值，請處理該肩拍通知，然後更新最新的 ChangeNumber 屬性值。
• 如果肩拍通知的 ChangeNumber 屬性值沒有高於該 Branch 屬性值的最新值，請略過處理該肩拍通知。該工作階段變更已經處理過了。

​

建立 MPSD 工作階段

1. 建立新的 XblContextHandle 物件。您的遊戲只需建立此物件一次並加以儲存，然後在整個原始程式碼中視需要重複使用。必須使用完全相同的內容，尤其是在處理工作階段訂閱時。
2. 使用 XblMultiplayerSessionCreateHandle 建立新的 XblMultiplayerSessionHandle，以準備 MPSD 建立新工作階段所需的所有工作階段資料。
3. 在將工作階段寫入 MPSD 之前進行必要的變更。例如，呼叫 XblMultiplayerSessionJoin 將成員加入工作階段時，用戶端會新增隱藏的本機要求資料，告知 MPSD 在呼叫更新工作階段時進行加入。
4. 完成本機變更後，依照本主題中更新 MPSD 工作階段一節的說明，將變更寫入 MPSD。
5. 從 MPSD 接收已填入許多欄位的新 XblMultiplayerSessionHandle 物件。
6. 往後請使用新的工作階段物件。捨棄包含建立新工作階段之隱藏要求的舊複本。

​

範例

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

• XAsyncBlock
• XblMultiplayerSessionCreateHandle
• XblMultiplayerSessionInitArgs
• XblMultiplayerSessionReference
• XblMultiplayerSessionWriteMode
• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionResult

​

為 MPSD 工作階段設定仲裁者

1. 呼叫 XblMultiplayerSessionMembers，從 MPSD 擷取主機候選項目的裝置權杖。

   [!NOTE] 如果工作階段是由 SmartMatch 配對建立的，您的用戶端可以呼叫 XblMultiplayerSessionHostCandidates，使用 MPSD 提供的主機候選項目。

2. 從主機候選項目清單中選取所需的主機。
3. 呼叫 XblMultiplayerSessionSetHostDeviceToken，在 MPSD 的本機快取中設定裝置權杖。如果設定主機裝置權杖的呼叫成功，本機裝置權杖就會取代主機的權杖。
4. 如果在嘗試設定主機裝置權杖時收到 HTTP/412 狀態碼，請查詢工作階段資料。查看主機裝置權杖是否屬於本機主機。如果不屬於本機主機，表示已指定另一部主機作為仲裁者。

   [!NOTE] 您的用戶端應該將 HTTP/412 狀態碼與其他 HTTP 狀態碼分開處理，因為 HTTP/412 並不表示標準失敗。如需此狀態碼的詳細資訊，請參閱多人遊戲工作階段狀態碼。

5. 依照本主題中更新 MPSD 工作階段一節的說明，在 MPSD 中更新工作階段。

   [!NOTE] 如果您沒有更好的演算法，用戶端可以實作貪婪演算法，讓每個主機候選項目在尚未有其他人這麼做時，嘗試將自己設為主機。如需詳細資訊，請參閱「多人遊戲工作階段進階主題」主題中的工作階段仲裁者一節。

​

管理遊戲啟用

1. 為 CoreApplicationView.Activated 事件設定事件處理常式。即使遊戲已在執行中，每次發生通訊協定啟用時都會觸發此處理常式。
2. 在遊戲啟用時，開始工作階段並訂閱工作階段變更通知。如需詳細資訊，請參閱本主題中的訂閱 MPSD 工作階段變更通知。
3. 以作用中身分將使用者加入工作階段。如需詳細資訊，請參閱本主題中的從遊戲啟用加入 MPSD 工作階段。
4. 將大廳工作階段設為透過設定檔 UI 公開的活動工作階段。如需詳細資訊，請參閱本主題中的設定使用者目前的活動。
5. 以作用中身分將使用者加入遊戲工作階段。使用者現在可以連線至對等節點，並進入遊戲或大廳。

​

讓使用者可被加入

1. 建立工作階段物件，然後視需要修改屬性。
2. 以作用中身分將使用者加入工作階段。如需詳細資訊，請參閱本主題中的從遊戲啟用加入 MPSD 工作階段。
3. 判斷使用者是否已被指定為工作階段仲裁者。
4. 如果使用者不是仲裁者，請移至步驟 7。
5. 如果使用者是仲裁者，請呼叫 XblMultiplayerSessionSetHostDeviceToken。
6. 嘗試呼叫 XblMultiplayerWriteSessionAsync 來寫入工作階段。
7. 將該工作階段設為作用中工作階段。如需詳細資訊，請參閱本主題中的設定使用者目前的活動。

​

傳送遊戲邀請

• 傳送大廳工作階段的邀請。
• 使用一般 XBOX 平台邀請 UI 搭配遊戲工作階段參考來傳送邀請。

1. 讓發出邀請的遊戲可供玩家加入。如需詳細資訊，請參閱本主題中的讓使用者可被加入。
2. 判斷要透過大廳工作階段或使用邀請 UI 傳送邀請。
3. 如果使用大廳工作階段，請呼叫 XblMultiplayerSendInvitesAsync 傳送邀請。此方法可能需要呼叫 XGameUiShowPlayerPickerAsync 來建立遊戲內 UI 名單。
4. 如果使用邀請 UI，請呼叫 XGameUiShowSendGameInviteAsync 以顯示邀請 UI。
5. 在遠端玩家加入後，為本機玩家處理 XblMultiplayerAddSessionChangedHandler。
6. 針對遠端玩家，實作遊戲啟用程式碼。如需詳細資訊，請參閱本主題中的管理遊戲啟用。

​

從大廳工作階段加入遊戲工作階段

1. 建立遊戲工作階段時，使用 XblMultiplayerSetTransferHandleAsync API 建立連結大廳工作階段與遊戲工作階段的轉移控制代碼。
2. 將轉移控制代碼 GUID 儲存在大廳工作階段中，而不是儲存遊戲工作階段的工作階段參考。
3. 當遊戲想要將成員從大廳工作階段移至遊戲工作階段時，每個用戶端都會使用來自大廳工作階段的轉移控制代碼，透過 XblMultiplayerWriteSessionByHandleAsync API 加入遊戲工作階段。
4. MPSD 會查閱大廳工作階段，以驗證嘗試使用轉移控制代碼加入遊戲工作階段的成員也在大廳工作階段中。
5. 如果成員在大廳工作階段中，他們就可以存取遊戲工作階段。

​

從遊戲啟用加入 MPSD 工作階段

1. 為 CoreApplicationView.Activated 事件實作事件處理常式。它會通知遊戲的啟用。
2. 處理常式引發時，請檢查 IActivatedEventArgs.Kind 屬性。如果設為 Protocol，請將事件引數轉換為 ProtocolActivatedEventArgs 類別。
3. 檢查 ProtocolActivatedEventArgs 物件。如果 ProtocolActivatedEventArgs.Uri 屬性中指出的 URI 符合 inviteHandleAccept (對應已接受的邀請) 或 activityHandleJoin (對應透過殼層 UI 加入)，請剖析 URI 的查詢字串。它的格式是具有索引鍵/值組的一般 URI 查詢字串，請從中擷取下列欄位。
   • 針對已接受的邀請：
     1. handle
     2. invitedXuid
     3. senderXuid
   • 針對加入：
     1. handle
     2. joinerXuid
     3. joineeXuid
4. 啟動遊戲的多人遊戲程式碼，其中應包括呼叫 XblMultiplayerSetSubscriptionsEnabled。
5. 呼叫 XblMultiplayerSessionCreateHandle 建立本機 XblMultiplayerSessionHandle 物件。
6. 呼叫 XblMultiplayerSessionJoin 加入工作階段。請使用下列參數設定，讓加入設為作用中。
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. 呼叫 XblMultiplayerSessionSetSessionChangeSubscription，以便在加入後工作階段變更時收到肩拍通知。
8. 使用步驟 3 中取得的控制代碼呼叫 XblMultiplayerWriteSessionByHandleAsync。使用者現在是工作階段的成員，可以使用工作階段中的資料連線至遊戲。

​

設定使用者目前的活動

​

更新 MPSD 工作階段

1. 視需要對目前的工作階段進行變更，例如呼叫 XblMultiplayerSessionLeave。
2. 完成所有變更後，使用下列任一方法將本機變更寫入 MPSD。
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   如果您寫入的是其他遊戲也可以修改的共用部分，請將寫入模式設為 XblMultiplayerSessionWriteMode::SynchronizedUpdate。如需詳細資訊，請參閱「多人遊戲工作階段目錄概觀」主題中的工作階段更新的同步處理一節。 寫入方法會將加入寫入伺服器，並取得最新的工作階段，從中探索其他工作階段成員及其主機的安全裝置位址 (SDA)。如需在這些主機之間建立網路連線的詳細資訊，請參閱 XBOX One 上的 Winsock 簡介。
3. 捨棄舊的本機工作階段物件。使用新擷取的工作階段物件，讓後續動作以最新的已知工作階段狀態為基礎。

​

離開 MPSD 工作階段

1. 為遊戲工作階段呼叫 XblMultiplayerSessionLeave。
2. 依照本主題中更新 MPSD 工作階段一節的說明，在 MPSD 中更新遊戲工作階段。
3. 必要時，為大廳工作階段呼叫 XblMultiplayerSessionLeave 方法，然後更新該工作階段。
4. 如果大廳工作階段有需要，請呼叫 XblMultiplayerRemoveSubscriptionLostHandler 與 XblMultiplayerRemoveSessionChangedHandler 取消註冊，以關閉多人遊戲 API。

​

在配對期間填補開放的工作階段位置

1. 存取配對期間所建立之票證工作階段的最新工作階段狀態。
2. 從大廳工作階段新增可供遊戲的玩家。
3. 判斷票證工作階段是否已滿。
4. 如果工作階段已滿，請繼續遊戲。
5. 如果工作階段尚未滿，請依照本主題中建立對戰票證的說明建立對戰票證。請務必在建立票證時將 preserveSession 參數設為 Always。
6. 繼續進行配對。如需詳細資訊，請參閱配對概觀。

​

建立對戰票證

1. 呼叫 XblMatchmakingCreateMatchTicketAsync，並傳入票證工作階段的參考。此方法會從 MPSD 讀取票證工作階段，並為工作階段中的使用者開始配對。在內部，此方法會呼叫 POST (/serviceconfigs/{scid}/hoppers/{hoppername})。
2. 如果配對服務要將工作階段的成員配對至新的工作階段或另一個現有的工作階段，請將 preserveSession 參數設為 Never。將 preserveSession 參數設為 Always，可讓遊戲重複使用現有的遊戲工作階段作為票證工作階段以繼續遊戲。配對服務接著可以確保保留已提交的工作階段，並將任何配對到的玩家新增至該工作階段。
3. 使用 CreateMatchTicketResponse 物件中傳回的 XblCreateMatchTicketResponse::EstimatedWaitTime，設定使用者對配對時間的預期。
4. 必要時，使用回應物件中傳回的 XblCreateMatchTicketResponse::MatchTicketId，透過刪除票證來取消工作階段的配對。刪除票證會使用 XblMatchmakingDeleteMatchTicketAsync。

​

取得對戰票證狀態

1. 取得票證工作階段的 XblMultiplayerSessionHandle 物件。
2. 呼叫 XblMultiplayerSessionMatchmakingServer，以存取配對中使用的 XblMultiplayerMatchmakingServer 物件。
3. 檢查 XblMultiplayerMatchmakingServer 物件，以判斷配對程序的狀態、工作階段的一般等候時間，以及目標工作階段參考 (如果已找到對戰)。