Multiplayer Manager での SmartMatch の使用によるマルチプレイヤー ゲームの検索を有効にする

この記事では、Multiplayer Manager を使用して SmartMatch マッチメイキングを実装するために必要な基本手順を説明します。

ゲームをプレイしたいがオンラインのフレンドの人数が足りない場合や、ゲーマーが単にランダムなプレイヤーを相手にオンラインでプレイしたい場合があります。 SmartMatch サービスを使用して、他の Xbox プレイヤーを見つけることができます。

マッチを探す

Multiplayer Manager を使用してユーザーのフレンドに招待を送信し、そのフレンドが進行中のゲームに参加するには、次の手順のようにします。

1. Multiplayer Manager を初期化する
2. ローカル ユーザーを追加することでロビー セッションを作成する
3. フレンドに招待を送信する (オプション)
4. 招待を受け入れる (オプション)
5. マッチを探す

手順 1、2、3、5 は、招待を実行したデバイス上で行います。 手順 4 は通常、プロトコルのアクティブ化によるアプリ起動の後、招待されたユーザーのデバイスで開始されます。

詳細については、「SmartMatch マッチメイキングを使用してゲームをプレイする (フローチャート)」をご覧ください。

Multiplayer Manager を初期化する

Multiplayer Manager が有効なセッション テンプレート名で初期化されると、ロビー セッション オブジェクトが自動的に作成されます。 セッション テンプレートはサービス構成でも定義されます。

フラット C API

HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);

詳細については、XblMultiplayerManagerInitialize をご覧ください。

このトピックの先頭に戻る。

ローカル ユーザーを追加することでロビー セッションを作成する

ローカルでサインインしている Xbox サービス ユーザーをロビー セッションに追加します。 最初のユーザーが追加されたときに新しいロビーがホストされます。 他のすべてのユーザーは、セカンダリー ユーザーとして既存のロビーに追加されます。

Multiplayer Manager は、フレンドが参加するシェルのロビーも公開します。 招待の送信、ロビーのプロパティの設定、ロビー メンバーへのアクセスは、ローカル ユーザーの追加後にのみ可能です。

ローカル ユーザーがロビーに参加するときは、接続アドレスとカスタム プロパティを設定することをお勧めします。

ローカルにサインインしたすべてのユーザーに対して、このプロセスを繰り返す必要があります。

1 人のローカル ユーザーを追加する

フラット 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.
}
...

詳細については、以下を参照してください。

• XblMultiplayerManagerLobbySessionAddLocalUser
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress
• XblMultiplayerManagerLobbySessionSetProperties

このトピックの先頭に戻る。

複数のローカル ユーザーを追加する

フラット 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);
    ...
}

詳細については、以下を参照してください。

• XblMultiplayerManagerLobbySessionAddLocalUser
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress
• XblMultiplayerManagerLobbySessionSetProperties

変更は、次の XblMultiplayerManagerDoWork 呼び出しでバッチ処理されます。 Multiplayer Manager は、ユーザーがロビー セッションに追加されるたびに XblMultiplayerEventType::UserAdded イベントを生成します。

イベントのエラー コードを調べて、そのユーザーが正常に追加されたかどうかを確認することをお勧めします。 障害が発生した場合は、障害の詳細な理由がエラー メッセージで提供されます。

Multiplayer Manager は、ローカル ユーザーを追加してロビー セッションを作成するために、次の機能を実行します。

• リアルタイム アクティビティおよびマルチプレイヤーのサブスクリプションを Xbox サービス マルチプレイヤー サービスに登録します。
• ローカル ユーザーを追加することでロビー セッションを作成します。
• すべてのローカル プレイヤーをアクティブとして参加させます。
• セキュリティで保護されたデバイスのアドレス (SDA) をアップロードします。
• メンバーのプロパティを設定します。
• セッション変更イベントに登録します。
• ロビー セッションをアクティブ セッションとして設定します。

このトピックの先頭に戻る。

フレンドに招待を送信する (オプション)

標準 Xbox UI を表示して、プレイヤーはフレンドや最近遊んだプレイヤーを選んでゲームに招待できるようにします。 プレーヤーが選択を確認すると、Multiplayer Manager は選択したプレイヤーに招待を送信します。

また、ゲームでは XblMultiplayerManagerLobbySessionInviteUsers 方式を使用して、Xbox サービス ユーザー ID によって定義された一連のプレイヤーに招待を送信することもできます。 この方式は、ストック Xbox UI の代わりに独自のゲーム内 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 をご覧ください。

Multiplayer Manager は、フレンドに招待を送信するために次の機能を実行します。

• Xbox 標準のタイトルが呼び出せる UI (TCUI) を表示する。
• 選択されたプレイヤーに直接、招待を送信する

このトピックの先頭に戻る。

招待を受け入れる (オプション)

招待されたプレイヤーがゲームの招待を受け入れると、またはシェル UI でフレンドのゲームに参加すると、プロトコルのアクティブ化を使用してデバイスでゲームが起動されます。 ゲームが開始したら、Multiplayer Manager はプロトコルがアクティブ化されたイベント引数を使用してロビーに参加できます。

招待されたユーザーが XblMultiplayerManagerLobbySessionAddLocalUser によって追加されていない場合 XblMultiplayerManagerJoinLobby はエラー終了し、JoinLobbyCompleted イベントで XblMultiplayerEventArgsXuid を呼び出すことにより、招待の送信先の xuid を提供します。

ロビーに参加した後、ローカル メンバーの接続アドレスに加えて、メンバーのカスタム プロパティを設定することを推奨します。 ホストが存在しない場合は XblMultiplayerManagerLobbySessionSetSynchronizedHost 経由で設定することもできます。

最後に、ゲームが既に進行中であり、招待されたユーザーを受け入れる余裕がある場合、Multiplayer Manager はユーザーをゲーム セッションに自動的に参加させます。 タイトルには、適切なエラー コードとメッセージを提供する 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);

詳細については、以下を参照してください。

• XblMultiplayerManagerJoinLobby
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress

Multiplayer Manager は、招待を受け入れるために次の機能を実行します。

• リアルタイム アクティビティとマルチプレイヤー サブスクリプションを登録します。
• ロビー セッションに参加します。
• 既存のロビー状態のクリーンアップ。
• すべてのローカル プレイヤーをアクティブとして参加させます。
• SDA をアップロードします。
• メンバーのプロパティを設定します。
• セッション変更イベントに登録します。
• ロビー セッションをアクティブ セッションとして設定します。
• ゲーム セッションに参加します (存在する場合)。
• 転送ハンドルを使用します。

マッチを探す

招待が受け入れられ、ホストがゲームのプレイを開始する準備ができたら、SmartMatch を使用して次のいずれかを実行できます。

• XblMultiplayerManagerFindMatchを呼び出すことにより、ロビー セッションのすべてのメンバーに対して十分な空きプレイヤー スロットがあるゲームを探す。
• XblMultiplayerManagerJoinGameFromLobby に続いて XblMultiplayerManagerAutoFillMembersDuringMatchmakingを呼び出すことにより、ロビー セッションのメンバー全員を含む新しいゲーム セッションを作成して、同じゲーム タイプのマッチを探している他のプレイヤーで空きスロットを埋める。

XblMultiplayerManagerFindMatchを呼び出す前に、まずサービス構成で hoppers を構成する必要があります。 Hopper は、SmartMatch がプレイヤーのマッチングに使用する規則を定義します。

フラット C API

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

詳細については、XblMultiplayerManagerFindMatch をご覧ください。

Multiplayer Manager は、マッチを探すために次の機能を実行します。

• マッチ チケットを作成します。
• すべてのサービスの品質 (QoS) ステージを処理します。
• 参加者一覧の変更を処理します。
• 再送信します (必要な場合)。
• ターゲット ゲーム セッションに参加します。
• ロビー セッションを介してゲームを公開します。

このトピックの先頭に戻る。