マルチプレイヤータスク

[アーティクル]
05/09/2023

このトピックでは、2015 マルチプレイヤーの使用に関連する特定のタスクを実装する方法について説明します。

このトピックでは、以下の内容を説明します。

マルチプレイヤーセッションディレクトリ(MPSD) セッション変更通知をサブスクライブする
MPSD セッションの作成
MPSD セッションのアービターを設定する
タイトルのライセンス認証を管理する
ユーザーを参加可能にする
ゲームへの招待を送信する
ロビーセッションからゲームセッションへの参加
タイトルのアクティベーションからの MPSD セッションへの参加
ユーザーの現在のアクティビティの設定
MPSD セッションの更新
MPSD セッションからの退出
マッチメイキング中に空きセッションスロットを埋める
マッチチケットを作成する
マッチチケットの状態の取得

注意

セッションの変更をサブスクライブするには、関連付けられているプレイヤーがセッションでアクティブであることが必要です。セッションの /constants/system/capabilities オブジェクトでは、connectionRequiredForActiveMembers フィールドも true に設定する必要があります。このフィールドは、通常、セッションテンプレートで設定します。詳細については、「マルチプレイヤーセッションテンプレート」と「マルチプレイヤーセッションディレクトリの概要」を参照してください。

MPSD セッション変更通知を受信するには、タイトルで次の手順に従います。

同じユーザーが行うすべての呼び出しに、同じ XblContextHandle オブジェクトを使用します。サブスクリプションは、このオブジェクトの有効期間に関係します。ローカルユーザーが複数いる場合は、各ユーザーに対して個別の XblContextHandle オブジェクトを使用します。
XblMultiplayerAddSessionChangedHandler と XblMultiplayerSessionSubscriptionLostHandlerのイベントハンドラーを実装します。
複数のユーザーの変更をサブスクライブする場合は、不要な作業を避けるためのコードを XblMultiplayerAddSessionChangedHandler イベントハンドラーに追加します。 XblMultiplayerSessionChangeEventArgs::Branch プロパティと XblMultiplayerSessionChangeEventArgs::ChangeNumber プロパティを使用します。これらのプロパティを使用すると、最後に表示された変更を追跡し、それ以前の変更を無視できます。
XblMultiplayerSetSubscriptionsEnabled を呼び出して、サブスクリプションを許可します。
ローカル MPSD セッションオブジェクトを作成し、その後でそのセッションをアクティブとして参加させます。
XblMultiplayerAddSessionChangedHandler に各ユーザーの呼び出しを行います。通知するセッション変更の種類を指定します。
このトピックの「MPSD セッションの更新」セクションの説明に従って、セッションを MPSD に書き込みます。

次のフローチャートは、前の手順で説明したイベントをサブスクライブしてマルチプレイヤーを開始する方法を示しています。

前の手順で説明したイベントをサブスクライブしてマルチプレイヤーを開始する方法を示すフローチャートの画像。

重複するセッション変更通知の解析

同じセッションの通知をサブスクライブしている複数のユーザーがいる場合、そのセッションに変更を加えるたびに、各ユーザーのショルダータップがトリガーされます。これらのショルダータップの 1 つを除いてすべてが重複しています。

タイトルは、セッション内のすべてのユーザーに通知をサブスクライブすることをお勧めしますが、タイトルは、すでに通知されている変更を無視する必要があります。これを行うには、Branch プロパティと ChangeNumber プロパティを使用します。

複数のショルダータップを検出するには、次のようにします。

評価された各 Branch プロパティ値の最新の ChangeNumber プロパティ値を保存します。
ショルダータップの ChangeNumber プロパティ値がその Branch プロパティ値の最新の保存値よりも高い場合は、ショルダータップを処理してから、最新の ChangeNumber プロパティ値を更新します。
ショルダータップに、その Branch プロパティ値に対してより高い ChangeNumber プロパティ値がない場合は、ショルダータップの処理をスキップします。この変更は既に処理されています。

注意

ChangeNumber プロパティ値は、セッションではなくプロパティ値によって Branch 追跡する必要があります。 Branch プロパティ値は、セッションの存続期間内に変更され、ChangeNumber プロパティ値をリセットできます。

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

MPSD セッションの作成

注意

既定では、最初のメンバーが参加したときに MPSD セッションが作成されます。タイトルロジックが参加時にタイトルが存在するか存在しないかを予期している場合は、セッション更新時に適切な書き込みモードの値を書き込みメソッドに渡すことができます。

タイトルは、新しいセッションを作成するために次のことを行う必要があります。

新しいXblContextHandle オブジェクトを作成します。タイトルは、このオブジェクトを 1 回作成し、保存して、ソースコード全体の必要に応じて再利用します。特にセッションサブスクリプションを使用する場合は、まったく同じコンテキストを使用する必要があります。
XblMultiplayerSessionCreateHandle を使用して新しいXblMultiplayerSessionHandleを作成し、MPSD が新しいセッションを作成するために必要なすべてのセッションデータを準備します。
セッションを MPSD に書き込む前に、必要な変更を行います。たとえば、XblMultiplayerSessionJoin への呼び出しを使用して、メンバーがセッションに参加する場合、クライアントは、要求を更新するために呼び出し時に参加するように MPSD に通知する隠しローカル要求データを追加します。
ローカルでの変更が終了したら、このトピックの「MPSD セッションの更新」セクションの説明に従って MPSD に書き込みます。
MPSD から新しい XblMultiplayerSessionHandle オブジェクトを受け取り、多くのフィールドに入力します。
今後は新しいセッションオブジェクトを使用してください。新しいセッションを作成するための非表示の要求を含む古いコピーを破棄します。

例

フラット C API

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();
}

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

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

MPSD セッションのアービターを設定する

タイトルは、次の手順を使用して、作成済みのセッションのアービターを設定します。

注意

メンバーがセッションに参加して、そのユーザーのセキュリティで保護されたデバイスアドレスを含めるまで、メンバー (ホスト候補) のデバイストークンは利用できません。

MPSD からホスト候補用のデバイストークンを取得するには XblMultiplayerSessionMembersを呼び出します。

注意

セッションが SmartMatch マッチメイキングによって作成された場合、クライアントは MPSD から使用可能なホスト候補を使用して XblMultiplayerSessionHostCandidates を呼び出すことができます。
ホスト候補のリストから必要なホストを選択します。
MPSD のローカルキャッシュにデバイストークンを設定するには XblMultiplayerSessionSetHostDeviceToken を呼び出します。ホストデバイストークンを設定する呼び出しが成功すると、ローカルデバイスのトークンがホストのトークンに置き換わります。
ホストデバイストークンを設定しようとしたときに HTTP/412 ステータスコードを受信した場合は、セッションデータをクエリします。ホストデバイストークンがローカルコンソール用であるかどうかを確認します。ローカル本体用でない場合は、別の本体がアービターとして指定されています。

注意

HTTP/412 は標準的なエラーを示していないので、クライアントはその他の HTTP コードとは切り離して HTTP/412 ステータスコードを処理する必要があります。このステータスコードの詳細については、「マルチプレイヤーセッションステータスコード」を参照してください。
このトピックの「MPSD セッションの更新」セクションの説明に従って、セッションを MPSD のセッションを更新します。

注意

より良いアルゴリズムがない場合、クライアントでは、他にホストが設定されていない場合に、各ホストが自分自身をホストとして設定しようとする greedy algorithm (貪欲法) を実装できます。詳細については、「マルチプレイヤーセッションの高度なトピック」の「セッションアービター」セクションを参照してください。

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

タイトルのライセンス認証を管理する

Xbox One (以降) では、プロトコルのアクティブ化中に CoreApplicationView.Activated イベントが発生します。マルチプレイヤー API のコンテキストでは、ユーザーが招待を承諾するか、他のユーザーに参加したときに、このイベントが発生します。これらのアクションは、参加するユーザーをターゲットユーザーとのゲームプレイに加えることにより、タイトルが対応する必要があるアクティベーションをトリガーします。

注意

タイトルでは常に新しいアクティベーション引数を予期する必要があり、長さに関するコーディングを行わないようにする必要があります。

タイトルのライセンス認証を行うには、次の主な手順を実行する必要があります。

CoreApplicationView.Activated イベントのイベントハンドラーをセットアップします。このハンドラーは、タイトルが既に実行されている場合でも、プロトコルのアクティブ化が発生するたびにトリガーされます。
タイトルのライセンス認証で、セッションを開始し、セッション変更通知を購読します。詳細については、このトピックの「MPSD セッション変更通知のサブスクライブ」を参照してください。
アクティブなユーザーとしてセッションに参加します。詳細については、このトピックの「タイトルのアクティブ化から MPSD セッションに参加する」を参照してください。
プロファイル UI を使用して表示されるアクティビティセッションとしてロビーセッションを設定します。詳細については、このトピックの「ユーザーの現在のアクティビティを設定する」を参照してください。
ユーザーをアクティブとしてゲームセッションに参加させます。これで、ユーザーはピアに接続してゲームプレイまたはロビーに入ることができます。

次のフローチャートは、タイトルのアクティブ化を処理する方法を示しています。

タイトルのアクティブ化を処理する方法を示すフローチャートの画像。

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

ユーザーを参加可能にする

ユーザーを参加可能にするには、タイトルで次の手順を行う必要があります。

セッションオブジェクトを作成し、必要に応じて属性を変更します。
アクティブなユーザーとしてセッションに参加します。詳細については、このトピックの「タイトルのアクティブ化から MPSD セッションに参加する」を参照してください。
ユーザーがセッションアービターに指定されているかどうかを確認します。
ユーザーがアービターではない場合は、手順 7 に進みます。
ユーザーがアービターの場合は XblMultiplayerSessionSetHostDeviceToken を呼び出します。
XblMultiplayerWriteSessionAsyncの呼び出しを使用して、セッションの書き込みを試行します。
セッションをアクティブなセッションとして設定します。詳細については、このトピックの「ユーザーの現在のアクティビティを設定する」を参照してください。

次のフローチャートは、ゲーム中にユーザーが他のプレイヤーに参加できるようにするための手順を示しています。

ゲーム中にユーザーが他のプレイヤーに参加できるようにするための手順を示すフローチャートの画像。

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

ゲームへの招待を送信する

タイトルでは、次の方法でプレイヤーがゲームへの招待を送信することを可能にできます。

ロビーセッションの招待を送信する。
一般的な Xbox プラットフォームの招待 UI を使用して、ゲームセッションの参照と共に招待を送信します。

プレイヤーにゲームへの招待を送信するには、タイトルで次の手順を行う必要があります。

招待しているゲームプレーヤーを参加可能にします。詳細については、「このトピックでユーザーを参加可能にする」を参照してください。
ロビーセッション経由、または invite UI を使用して、招待を送信するかどうかを決定します。
ロビーセッションを使用している場合は、XblMultiplayerSendInvitesAsyncの呼び出しを使用して招待を送信します。このメソッドでは、XGameUiShowPlayerPickerAsyncを呼び出してゲーム内 UI 名簿を作成する必要がある場合があります。
Invite UI を使用している場合は XGameUiShowSendGameInviteAsync を呼び出して、招待 UI を表示します。
リモートプレーヤーが参加した後に、ローカルプレーヤーの XblMultiplayerAddSessionChangedHandler を処理します。
リモートプレーヤーには、タイトルのライセンス認証コードを実装します。詳細については、このトピックの「タイトルのアクティブ化を管理する」を参照してください。

次のフローチャートは、招待を送信する方法を例示しています。

招待状の送信方法を示すフローチャートの画像。

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

ロビーセッションからゲームセッションへの参加

Windows 10 デバイスのゲームプレイセッションが大きいセッションではない場合は、true に userAuthorizationStyle 機能が設定されている必要があります。その結果、joinRestriction プロパティを none にすることはできません。つまり、セッションを直接公開に参加させることはできません。

一般的なシナリオでは、ロビーセッションを作成してプレイヤーを集め、それらのプレイヤーをゲームプレイセッションまたはマッチメイキングセッションに移動します。ただし、ゲームプレイセッションが公開されていない場合、ゲームクライアントは joinRestriction 設定を満たさない限りゲームプレイセッションに参加できません。ほとんどの場合、このシナリオには制限が厳しすぎます。

これを解決するには、転送ハンドルを使ってロビーセッションとゲームセッションをリンクします。この操作を行うには、次の操作を行います。

ゲームセッションを作成するときに、XblMultiplayerSetTransferHandleAsync API を使用して、ロビーセッションとゲームセッションをリンクする転送ハンドルを作成します。
転送ハンドルの GUID を、ゲームセッションのセッションの参照の代わりにロビーセッションに格納します。
タイトルがロビーセッションからゲームセッションにメンバーを移動する必要がある場合、各クライアントはロビーセッションの転送ハンドルを使用して、XblMultiplayerWriteSessionByHandleAsync API 使用のゲームセッションに参加します。
MPSD は、ロビーセッションを検索し、転送ハンドルを使ってゲームセッションに参加しようとしているユーザーがロビーセッションにも存在することを確認します。
ロビーセッションに存在するメンバーであれば、ゲームセッションにアクセスできます。

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

タイトルのアクティベーションからの MPSD セッションへの参加

ユーザーが Xbox シェル UI を使用してフレンドのアクティビティに参加する、または招待を受け入れることを選択すると、タイトルは、ユーザーが参加を希望するセッションを示すパラメーターを使ってアクティブ化されます。タイトルは、このアクティベーションを処理し、対応するセッションにユーザーを追加する必要があります。

タイトルの手順は次のとおりです。

CoreApplicationView.Activated イベントのイベントハンドラーを実装します。これは、タイトルのライセンス認証を通知します。
ハンドラーが起動したら、IActivatedEventArgs.Kind プロパティを確認します。 Protocol に設定されている場合は、イベント引数を ProtocolActivatedEventArgs クラスにキャストします。
ProtocolActivatedEventArgs オブジェクトを検査します。 ProtocolActivatedEventArgs.Uriプロパティに示されている URI が inviteHandleAccept(受け入れられた招待に対応) または activityHandleJoin(シェル UI を介した結合に対応) のいずれかに一致する場合、URI のクエリ文字列を解析します。これは、キーと値のペアを持つ通常の URI クエリ文字列としてフォーマットされ、次のフィールドを抽出します。
- 招待を承諾した場合:
  1. handle
  2. invitedXuid
  3. senderXuid
- 参加の場合:
  1. handle
  2. joinerXuid
  3. joineeXuid
XblMultiplayerSetSubscriptionsEnabled のを含める必要がある、タイトルのマルチプレーヤーコードを開始します。
ローカル XblMultiplayerSessionHandle オブジェクトを作成するには XblMultiplayerSessionCreateHandleを呼び出します。
セッションに参加するには XblMultiplayerSessionJoin を呼び出します。参加をアクティブに設定するには、次のパラメーター設定を使用します。
- memberCustomConstantsJson = null
- initializeRequested = false
- joinWithActiveStatus = true
参加後、セッションが変更されたときにタップして XblMultiplayerSessionSetSessionChangeSubscription を呼び出します。
手順 3 に記載されているとおり、取得したハンドルを使用して XblMultiplayerWriteSessionByHandleAsync を呼び出します。ユーザーがセッションのメンバーになり、セッションのデータを使用してゲームに接続できるようになりました。

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

ユーザーの現在のアクティビティの設定

ユーザーの現在のアクティビティは、タイトルの Xbox ダッシュボードのユーザーエクスペリエンスに表示されます。ユーザーのアクティビティは、セッションまたはタイトルのアクティベーションを通じて設定できます。後者の場合、ユーザーはマッチメイキングを通じて、またはゲームを起動してセッションを開始します。

注意

セッションを介して設定されたアクティビティは、XblMultiplayerClearActivityAsyncを呼び出すことで削除できます。

ユーザーの現在のアクティビティとしてセッションを設定するには、タイトルが XblMultiplayerSetActivityAsyncを呼び出します。これはセッションのセッション参照を渡します。

タイトルのライセンス認証を使用してユーザーの現在のアクティビティを設定する方法については、このトピックの「タイトルのアクティブ化から MPSD セッションに参加する」を参照してください。

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

MPSD セッションの更新

注意

タイトルがマルチプレイヤー API を使用して既存のセッションを更新する場合は、セッションの書き込みを呼び出すまで、ローカルコピーを扱うことになるので注意してください。

既存のセッションを更新するには、タイトルは次の条件を満たす必要があります。

必要に応じて現在のセッションに変更を加えます。たとえば、XblMultiplayerSessionLeaveを呼び出します。
すべての変更が完了したら、次のいずれかの方法を使用して、ローカルの変更を MPSD に書き込みます。
- XblMultiplayerWriteSessionAsync
- XblMultiplayerWriteSessionByHandleAsync
他のタイトルも変更できる共有部分に書き込むには、書き込みモードを XblMultiplayerSessionWriteMode::SynchronizedUpdate に設定します。詳細については、「マルチプレイヤーセッションディレクトリ」の概要トピックの「セッション更新の同期」セクションを参照してください。

書き込みメソッドは参加をサーバーに書き込み、最新のセッションを取得して、そのセッションから他のセッションメンバーと本体のセキュアデバイスアドレス (SDA) を検出します。これらの本体間でネットワーク接続を確立する方法の詳細については、「Xbox One の Winsock の概要」を参照してください。
古いローカルセッションオブジェクトを破棄します。最新の既知のセッション状態に基づいて今後の処理を実行できるように、新たに取得したセッションオブジェクトを使用します。

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

MPSD セッションからの退出

ユーザーがセッションを終了できるようにするには、タイトルで次に追従する必要があります。

ゲームセッションのXblMultiplayerSessionLeave を呼び出します。
このトピックの「MPSD セッションの更新」セクションの説明に従って、ゲームセッションを MPSD のセッションを更新します。
必要に応じて、ロビーセッションの XblMultiplayerSessionLeave メソッドを呼び出し、そのセッションを更新します。
ロビーセッションが必要な場合は、 XblMultiplayerRemoveSubscriptionLostHandlerとXblMultiplayerRemoveSessionChangedHandlerを呼び出して、マルチプレイヤー API をシャットダウンします。

次のフローチャートは、セッションを終了してマルチプレイヤーをシャットダウンする方法を示しています。

セッションを終了してマルチプレイヤーをシャットダウンする方法を示すフローチャートの画像。

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

マッチメイキング中に空きセッションスロットを埋める

マッチメイキング中にチケットセッションの空きスロットを埋めるには、タイトルで次のような手順に従う必要があります。

マッチメイキング中に作成されたチケットセッションの最新のセッション状態にアクセスします。
ロビーセッションからゲームプレイに参加可能なプレイヤーを追加します。
チケットセッションがいっぱいになっているかどうかを確認します。
セッションがいっぱいの場合は、ゲームプレイを続けます。
セッションがまだいっぱいでない場合は、このトピックのマッチチケットの作成の説明に従って、マッチチケットを作成します。必ず、preserveSession パラメータを Always に設定してチケットを作成してください。
マッチメイキングを続行します。詳細については、「マッチメイキングの概要」を参照してください。

次のフローチャートは、マッチメイキング中に空きセッションスロットを埋める方法を示します。

マッチメイキング中に空きセッションスロットを埋める方法を示す画像。

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

マッチチケットを作成する

マッチチケットを作成するには、マッチメイキングスカウトが次の条件を満たしている必要があります。

スカウトは XblMatchmakingCreateMatchTicketAsync を呼び出し、チケットセッションの参照を渡します。このメソッドは、MPSD のチケットセッションを読み取り、そのセッションのユーザーのマッチメイキングを開始します。内部では、POST (/serviceconfigs/{scid}/hoppers/{hoppername})を呼び出します。
マッチメイキングサービスがセッションのメンバーを新しいセッションまたは別の既存のセッションにマッチングする場合は、preserveSession パラメーターを Never に設定します。タイトルがゲームプレイを続行するためのチケットセッションとして既存のゲームセッションを再利用できるようにするには、preserveSession パラメーターを Always に設定します。マッチメイキングサービスは、送信されたセッションが保持され、一致したプレーヤーがそのセッションに追加されるようにします。
CreateMatchTicketResponse オブジェクトで返された XblCreateMatchTicketResponse::EstimatedWaitTime を使用して、ユーザーによる、マッチメイキングの時間を設定します。
必要に応じて、応答オブジェクトで返却される XblCreateMatchTicketResponse::MatchTicketId を使用し、チケットを削除することで、セッションのマッチメイキングをキャンセルします。チケットの削除には XblMatchmakingDeleteMatchTicketAsyncを使用します。

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

マッチチケットの状態の取得

マッチチケットの状態を取得するには、次を追従する必要があります。

チケットセッションの XblMultiplayerSessionHandle オブジェクトを取得します。
マッチメイキングで使用された XblMultiplayerMatchmakingServer オブジェクトにアクセスするには XblMultiplayerSessionMatchmakingServer を呼び出します。
一致するものが見つかった場合、XblMultiplayerMatchmakingServer オブジェクトをチェックして、マッチメイキングプロセスのステータス、セッションの標準的な待機時間、およびターゲットセッションの参照を特定します。

次の方法で共有

マルチプレイヤータスク

重複するセッション変更通知の解析

MPSD セッションの作成

例

MPSD セッションのアービターを設定する

タイトルのライセンス認証を管理する

ユーザーを参加可能にする

ゲームへの招待を送信する

ロビーセッションからゲームセッションへの参加

タイトルのアクティベーションからの MPSD セッションへの参加

ユーザーの現在のアクティビティの設定

MPSD セッションの更新

MPSD セッションからの退出

マッチメイキング中に空きセッションスロットを埋める

マッチチケットを作成する

マッチチケットの状態の取得

その他のリソース

次の方法で共有

マルチプレイヤー タスク

マルチプレイヤー セッション ディレクトリ(MPSD) セッション変更通知をサブスクライブする

重複するセッション変更通知の解析

MPSD セッションの作成

例

MPSD セッションのアービターを設定する

タイトルのライセンス認証を管理する

ユーザーを参加可能にする

ゲームへの招待を送信する

ロビー セッションからゲーム セッションへの参加

タイトルのアクティベーションからの MPSD セッションへの参加

ユーザーの現在のアクティビティの設定

MPSD セッションの更新

MPSD セッションからの退出

マッチメイキング中に空きセッション スロットを埋める

マッチ チケットを作成する

マッチ チケットの状態の取得

その他のリソース

マルチプレイヤータスク

マルチプレイヤーセッションディレクトリ(MPSD) セッション変更通知をサブスクライブする

ロビーセッションからゲームセッションへの参加

マッチメイキング中に空きセッションスロットを埋める

マッチチケットを作成する

マッチチケットの状態の取得