マルチプレイヤータスク

• Multiplayer Session Directory (MPSD) セッション変更通知の購読
• MPSD セッションを作成する
• MPSD セッションの arbiter を設定する
• タイトルアクティベーションを管理する
• ユーザーが参加できる状態にする
• ゲーム招待を送信する
• ロビーセッションからゲームセッションに参加する
• タイトルアクティベーションから MPSD セッションに参加する
• ユーザーの現在のアクティビティを設定する
• MPSD セッションを更新する
• MPSD セッションから離脱する
• マッチメーキング中に空いているセッションスロットを埋める
• マッチチケットを作成する
• マッチチケットのステータスを取得する

​

Multiplayer Session Directory (MPSD) セッション変更通知の購読

1. 同じユーザーによるすべての呼び出しに対して、同じ XblContextHandle オブジェクトを使用します。購読はこのオブジェクトの有効期間に紐付いています。ローカルユーザーが複数いる場合は、各ユーザーに対して個別の XblContextHandle オブジェクトを使用します。
2. XblMultiplayerAddSessionChangedHandler および XblMultiplayerSessionSubscriptionLostHandler のイベントハンドラーを実装します。
3. 複数のユーザーの変更を購読する場合は、不要な作業を避けるために XblMultiplayerAddSessionChangedHandler イベントハンドラーにコードを追加します。XblMultiplayerSessionChangeEventArgs::Branch プロパティと XblMultiplayerSessionChangeEventArgs::ChangeNumber プロパティを使用します。これらのプロパティを使用すると、最後に確認した変更を追跡し、古い変更を無視できます。
4. XblMultiplayerSetSubscriptionsEnabled を呼び出して購読を許可します。
5. ローカルセッションオブジェクトを作成してから、そのセッションにアクティブとして参加します。
6. 通知を受けるセッション変更タイプを渡して、各ユーザーに対して XblMultiplayerAddSessionChangedHandler を呼び出します。
7. このトピックの MPSD セッションを更新する セクションで説明されているように、セッションを MPSD に書き込みます。

​

重複したセッション変更通知の解析

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

​

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 セッションの arbiter を設定する

1. XblMultiplayerSessionMembers を呼び出して、ホスト候補のデバイストークンを MPSD から取得します。

   [!NOTE] セッションが SmartMatch マッチメーキングによって作成された場合、クライアントは XblMultiplayerSessionHostCandidates を呼び出して MPSD から利用可能なホスト候補を使用できます。

2. ホスト候補のリストから必要なホストを選択します。
3. XblMultiplayerSessionSetHostDeviceToken を呼び出して、MPSD のローカルキャッシュにデバイストークンを設定します。ホストデバイストークンを設定する呼び出しが成功すると、ローカルのデバイストークンがホストのトークンを置き換えます。
4. ホストデバイストークンを設定しようとしたときに HTTP/412 ステータスコードを受信した場合は、セッションデータをクエリします。ホストデバイストークンがローカルコンソール用であるかどうかを確認します。ローカルコンソール用でない場合、別のコンソールが arbiter として指定されています。

   [!NOTE] HTTP/412 は標準的な失敗を示さないため、クライアントは HTTP/412 ステータスコードを他の HTTP コードとは別に処理する必要があります。このステータスコードの詳細については、マルチプレイヤーセッションのステータスコード を参照してください。

5. このトピックの MPSD セッションを更新する セクションで説明されているように、MPSD 内のセッションを更新します。

   [!NOTE] より良いアルゴリズムがない場合、クライアントは各ホスト候補がまだ誰も自分自身をホストとして設定していない場合に、自分自身をホストとして設定しようとする貪欲アルゴリズムを実装できます。詳細については、Multiplayer Session advanced topics トピックの Session arbiter セクションを参照してください。

​

タイトルアクティベーションを管理する

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

​

ユーザーが参加できる状態にする

1. セッションオブジェクトを作成してから、必要に応じて属性を変更します。
2. ユーザーをセッションにアクティブとして参加させます。詳細については、このトピックの タイトルアクティベーションから MPSD セッションに参加する を参照してください。
3. ユーザーがセッションの arbiter として指定されているかどうかを判断します。
4. ユーザーが arbiter でない場合は、手順 7 に進みます。
5. ユーザーが arbiter の場合は、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 に設定します。詳細については、Multiplayer Session Directory overview トピックの Synchronization of session updates セクションを参照してください。 write メソッドは、参加をサーバーに書き込み、他のセッションメンバーとそのコンソールのセキュアデバイスアドレス (SDA) を発見するための最新のセッションを取得します。これらのコンソール間でネットワーク接続を確立する方法の詳細については、Introduction to Winsock on XBOX One を参照してください。
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 オブジェクトを確認して、マッチメーキングプロセスのステータス、セッションの典型的な待機時間、およびマッチが見つかった場合のターゲットセッション参照を判断します。