使用多人遊戲管理員透過 SmartMatch 啟用尋找多人遊戲

本主題說明使用多人遊戲管理員實作 SmartMatch 配對所需的基本步驟。玩家想要玩遊戲時，線上的好友可能不夠多，或者他們只是想要與線上的隨機玩家對戰。您可以使用 SmartMatch 服務尋找其他 XBOX 玩家。

尋找對戰

下列步驟使用多人遊戲管理員傳送邀請給玩家的好友，讓該好友可以加入進行中的遊戲。

初始化多人遊戲管理員
藉由新增本機使用者建立大廳工作階段
傳送邀請給好友 (選用)
接受邀請 (選用)
尋找對戰

步驟 1、2、3 和 5 在發出邀請的裝置上執行。步驟 4 通常在受邀者的裝置上，於透過通訊協定啟用啟動應用程式之後起始。如需詳細資訊，請參閱使用 SmartMatch 配對玩遊戲 (流程圖)。

初始化多人遊戲管理員

使用有效的工作階段範本名稱初始化多人遊戲管理員時，會自動建立大廳工作階段物件。工作階段範本是在服務設定中定義的。

在新增使用者之前，服務上不會建立大廳工作階段執行個體。

平面 C API

HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);

如需詳細資訊，請參閱 XblMultiplayerManagerInitialize。返回本主題頂端。

藉由新增本機使用者建立大廳工作階段

將本機已登入的 XBOX 服務使用者新增至大廳工作階段。新增第一位使用者時，會裝載新的大廳。所有其他使用者都會以次要使用者的身分新增至現有的大廳。多人遊戲管理員會在殼層中公告大廳，供好友加入。只有在新增本機使用者之後，您才能傳送邀請、設定大廳屬性，以及存取大廳成員。當本機使用者加入大廳時，建議您設定其連線位址和任何自訂屬性。您必須針對所有本機已登入的使用者重複此程序。

新增單一本機使用者

平面 C API

HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set custom member properties.
const char* propName = "Name";
const char* propValueJson = "{}";
hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}
...

如需詳細資訊，請參閱下列內容：

返回本主題頂端。

新增多個本機使用者

平面 C API

std::vector<XblUserHandle> xblUsers;
for (XblUserHandle xblUserHandle : xblUsers)
{
    HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set member connection address.
    const char* connectionAddress = "1.1.1.1";
    hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
        xblUserHandle, connectionAddress, context);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set custom member properties.
    const char* propName = "Name";
    const char* propValueJson = "{}";
    hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);
    ...
}

如需詳細資訊，請參閱下列內容：

這些變更會在下一次 XblMultiplayerManagerDoWork 呼叫時批次處理。每次將本機使用者新增至大廳工作階段時，多人遊戲管理員都會引發 XblMultiplayerEventType::UserAdded 事件。建議您檢查事件的錯誤碼，以確認是否已成功新增該使用者。如果失敗，錯誤訊息會提供失敗原因的詳細資料。多人遊戲管理員會執行下列功能，藉由新增本機使用者來建立大廳工作階段。

向 XBOX 服務多人遊戲服務註冊即時活動和多人遊戲訂閱。
建立大廳工作階段。
讓所有本機玩家以作用中狀態加入。
上傳安全裝置位址 (SDA)。
設定成員屬性。
註冊工作階段變更事件。
將大廳工作階段設定為作用中工作階段。

返回本主題頂端。

傳送邀請給好友 (選用)

顯示標準 XBOX UI，玩家可在其中選取要邀請加入遊戲的好友或最近的玩家。當玩家確認其選取項目後，多人遊戲管理員會將邀請傳送給選取的玩家。遊戲也可以使用 XblMultiplayerManagerLobbySessionInviteUsers 方法，將邀請傳送給由其 XBOX 服務使用者識別碼定義的一組玩家。如果您使用自己的遊戲內 UI 而非標準 XBOX UI，此方法會很有用。

平面 C API

size_t xuidsCount = 1;
uint64_t xuids[1] = {};
xuids[0] = 1234567891234567;
HRESULT hr = XblMultiplayerManagerLobbySessionInviteUsers(
    xblUserHandle, 
    xuids, 
    xuidsCount, 
    nullptr,    // ContextStringId 
    nullptr     // CustomActivationContext
);

如需詳細資訊，請參閱 XblMultiplayerManagerLobbySessionInviteUsers。多人遊戲管理員會執行下列功能來傳送邀請給好友。

顯示 XBOX 標準遊戲可呼叫 UI (TCUI)
直接將邀請傳送給選取的玩家

返回本主題頂端。

接受邀請 (選用)

當受邀玩家接受遊戲邀請，或透過殼層 UI 加入好友的遊戲時，系統會使用通訊協定啟用在其裝置上啟動遊戲。遊戲啟動後，多人遊戲管理員可以使用通訊協定啟用的事件引數來加入大廳。如果受邀使用者未透過 XblMultiplayerManagerLobbySessionAddLocalUser 新增，XblMultiplayerManagerJoinLobby 會失敗，而您可以搭配 JoinLobbyCompleted 事件呼叫 XblMultiplayerEventArgsXuid，以取得邀請所傳送給的 xuid。加入大廳之後，建議您設定本機成員的連線位址，以及該成員的任何自訂屬性。如果主機不存在，您也可以透過 XblMultiplayerManagerLobbySessionSetSynchronizedHost 設定主機。最後，如果遊戲已在進行中且仍有空間容納受邀者，多人遊戲管理員會自動讓使用者加入遊戲工作階段。遊戲會透過 JoinGameCompleted 事件收到通知，並提供適當的錯誤碼和訊息。錯誤或成功結果會透過 JoinLobbyCompleted 事件處理。

平面 C API

HRESULT hr = XblMultiplayerManagerJoinLobby(inviteHandleId, xblUserHandle);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

如需詳細資訊，請參閱下列內容：

多人遊戲管理員會執行下列功能來接受邀請。

註冊即時活動和多人遊戲訂閱。
加入大廳工作階段。
清除現有的大廳狀態。
讓所有本機玩家以作用中狀態加入。
上傳 SDA。
設定成員屬性。
註冊工作階段變更事件。
將大廳工作階段設定為作用中工作階段。
加入遊戲工作階段 (如果存在)。
使用轉移控制代碼。

尋找對戰

在邀請被接受且主機準備好開始玩遊戲之後，您可以使用 SmartMatch 執行下列其中一項操作：

呼叫 XblMultiplayerManagerFindMatch，尋找有足夠空位容納大廳工作階段中所有成員的現有遊戲。
呼叫 XblMultiplayerManagerJoinGameFromLobby，接著呼叫 XblMultiplayerManagerAutoFillMembersDuringMatchmaking，建立包含大廳工作階段中所有成員的新遊戲工作階段，並以其他正在尋找相同遊戲類型對戰的玩家填補空位。

您必須先在服務設定中設定漏斗，才能呼叫 XblMultiplayerManagerFindMatch。漏斗定義 SmartMatch 用來配對玩家的規則。

平面 C API

uint32_t timeoutInSeconds = 30;
HRESULT hr = XblMultiplayerManagerFindMatch(hopperName, attributesJson, timeoutInSeconds);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

如需詳細資訊，請參閱 XblMultiplayerManagerFindMatch。多人遊戲管理員會執行下列功能來尋找對戰。

建立配對票證。
處理所有服務品質 (QoS) 階段。
處理名單變更。
重新提交 (如有需要)。
加入目標遊戲工作階段。
透過大廳工作階段公告遊戲。

返回本主題頂端。

XBOX Services

PlayFab

使用多人遊戲管理員透過 SmartMatch 啟用尋找多人遊戲

尋找對戰

初始化多人遊戲管理員

平面 C API

藉由新增本機使用者建立大廳工作階段

新增單一本機使用者

平面 C API

新增多個本機使用者

平面 C API

傳送邀請給好友 (選用)

平面 C API

接受邀請 (選用)

平面 C API

尋找對戰

平面 C API

​尋找對戰

​初始化多人遊戲管理員

​平面 C API

​藉由新增本機使用者建立大廳工作階段

​新增單一本機使用者

​平面 C API

​新增多個本機使用者

​平面 C API

​傳送邀請給好友 (選用)

​平面 C API

​接受邀請 (選用)

​平面 C API

​尋找對戰

​平面 C API

尋找對戰

初始化多人遊戲管理員

平面 C API

藉由新增本機使用者建立大廳工作階段

新增單一本機使用者

平面 C API

新增多個本機使用者

平面 C API

傳送邀請給好友 (選用)

平面 C API

接受邀請 (選用)

平面 C API

尋找對戰

平面 C API