ドキュメント

サポート

Matchmaker for the Unreal Engine

Matchmaker overview

Matchmaker for the Unreal Engine

ブループリントを使用した統合

Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.
読み終わるまでの所要時間 4 分最終更新 14日前
以下のセクションでは、Unreal Engine のブループリント を使用して Matchmaker SDK を統合する方法を示します。 Unity Gaming Services SDK 内では、次の 2 つの Matchmaker インターフェースを操作できます。

Matchmaker SDK プラグインのインストール

先に進む前に、
MatchmakerSDK
をモジュールのパブリック依存関係として追加し、以下に示すようにプラグインのヘッダーファイルをクラスに加えます。 
MatchmakerServer
と 
MatchmakerClient
をモジュールの依存関係として Unreal プロジェクトのビルドファイル (
YourProjectName.Build.cs
) に追加します。 
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });PublicDependencyModuleNames.AddRange(new string[] { "MatchmakerClient", "MatchmakerServer" });PublicDependencyModuleNames.AddRange(new string[] { "Json", "JsonUtilities" });

Matchmaker Client Blueprint API

Matchmaker クライアントサブシステムが、マッチメイキングとマッチ検出のクライアント部分を制御します。これには、マッチメイキングチケットの作成、削除、ポーリングが含まれています。 
UMatchmakerClientBlueprintApi
の静的関数を使用し、以下のブループリントを通じて Matchmaker クライアントサブシステムを操作します。

CreateTicket

CreateTicket
を使用するには、ブループリントに Create Ticket ノードを配置します。チケットを作成するための入力として、Players と Options の各フィールドに入力します。 以下の例では、1 人のプレイヤーとキューを渡してチケットを作成する方法を示しています。また、応答を処理して 
TicketId
の 
FString
出力を取得するイベントも示しています。
プレイヤーの設定
CreateTicketOptions の設定
Create Ticket の呼び出し
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
CreateTicketResponse
の個々の値すべてにアクセスします。

DeleteTicket

DeleteTicket
ブループリントを使用して、Delete Ticket 呼び出しを発行し、削除する TicketId を渡します。 以下は、Delete Ticket の使用方法と応答の処理方法を示す簡単な例です。
マッチメイキングチケットの削除
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
DeleteTicketResponse
の個々の値すべてにアクセスします。

GetTicketStatus

GetTicketStatus
を使用し、CreateTicket ブループリントから取得した 
TicketId
を使ってマッチメーカーに対してマッチをポーリングします。 ポーリングが成功または失敗して完了した後、またはユーザーがマッチメイキングを手動でキャンセルした場合には、
DeleteTicket
ブループリントを使用して、プレイヤーをマッチメイキングの対象と認識することを停止します。
マッチメイキングチケットのポーリング
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
GetTicketStatusResponse]
の個々の値すべてにアクセスします。 上の画像は、
Set Timer by Event
ノードを使用したマッチメイキングチケットのポーリングの例を示しています。このノードは、ループ条件が true の場合に、Time 変数で設定された頻度でイベントを継続的にトリガーします。この例では Time が 5 に設定されているため、このイベントは、タイマーハンドラーがキャンセルされるまで 5 秒ごとに発生します。戻り値は、
Clear and Invalidate Timer by Handle
によるタイマーのキャンセルに使用できるタイマーハンドラーです。
Set Timer by Event
タイマーハンドルは、Set Timer by Event ノードから Clear and Invalidate Timer by Handle ノードに渡されます。Clear and Invalidate Timer by Handle をトリガーするには、何らかの条件付きロジックが必要です。マッチが返される前に、
GetTicketStatus
への最多連続呼び出しを実行する必要があります。InProgress のステータスが返されなくなったら、ポーリングを停止してチケットを削除しても問題ありません。 以下の画像は、ポーリング応答を処理して Clear and Invalidate Timer をトリガーする方法の基本的な例を示しています。
Clear and Invalidate Timer

Matchmaker Server Blueprint API

Matchmaker サーバーサブシステムが、マッチメイキングのサーバー部分を制御します。これには、バックフィルチケットの作成、承認、削除、更新が含まれています。 
UMatchmakerServerBlueprintApi
を使用すると、以下のことができます。

CreateBackfillTicket

あるプレイヤー (または複数のプレイヤー) が満員のマッチから退出した後には、新しいバックフィルチケットを作成する必要があります。また、サーバーは空のスロットを埋める必要があります。Create Backfill Ticket ブループリントを使用して、サーバーに新しいバックフィルチケットを作成します。
MatchProperties の設定
CreatebackfillTicketOptions の設定
CreateBackfillTicket の呼び出し
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
CreateBackfillTicketResponse
の個々の値すべてにアクセスします。

ApproveBackfillTicket

Approve Backfill Ticket ブループリントを使用し、バックフィルチケットを定期的に承認して新しいプレイヤーがサーバーに参加できるようにします。 バックフィルチケットの承認は、最速でも 1 秒に 1 回までにすることをお勧めします。チケットが承認されない状態が 20 秒続くと、そのチケットは Matchmaker サービスによって削除されます。
バックフィルチケットの承認
上の例では、承認がループで毎秒実行されます。バックフィルチケットを削除した後に Clear and Invalidate Timer by Handle ノードを使用してください。 応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
ApproveBackfillTicketResponse
の個々の値すべてにアクセスします。 Unity では、応答から値をキャッシュし、それらの値を 
UpdateBackfillTicket
での 
BackfillTicket
のビルドに使用することをお勧めしています。

UpdateBackfillTicket

バックフィルチケットは次の場合に更新します。
  • プレイヤーがサーバーを退出した場合
  • プレイヤーが対戦相手探しのロジックの外からサーバーに参加した場合
これには、パーティの招待、直接接続、友人の招待などが含まれますが、これらに限りません。 Update Backfill Ticket ブループリントを使用して、サーバーの現在のバックフィルチケットを更新します。
バックフィルチケットの更新
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
UpdateBackfillTicketResponse
の個々の値すべてにアクセスします。 これは、3 秒に 1 回よりも少ない頻度で呼び出す必要があります。または、
ApproveBackfillTicket
がバックフィルチケットの変更を認識した後に呼び出す必要があります。そうすることで、マッチメイキングサイクルの経過を保証します。 Unity では、最初に 
ApproveBackfillTicket
を呼び出し、
ApproveBackfillTicket
から返された 
BackfillTicket
を使用して必要に応じて修正し、
UpdateBackfillTicket
に渡すことをお勧めします。

DeleteBackfillTicket

マッチが満員になり、サーバーが新しいプレイヤーを受け付ける必要がなくなった後は、バックフィルチケットを削除できます。これはマッチが終了した後にも行う必要があります。 Delete Backfill Ticket ブループリントを使用して、サーバーでのバックフィルを停止します。
バックフィルチケットの削除
応答ハンドラーにカスタムイベントを設定できます。イベントの 
Response
構造体のピンを右クリックして 
Split Struct Pin
を選択し、
DeleteBackfillTicketResponse
の個々の値すべてにアクセスします。

ブループリントのユーティリティ関数

ブループリントに制限があるため、JSON データ型 (
FJsonObject
や 
FJsonValue
など) はネイティブな互換性を備えておらず、直接の操作に対応していません。API の一部として JSON データを管理できる一連のユーティリティ関数が、SDK によって実装されます。 
  • MatchmakerServer
    の一部としての 
    MatchmakerServerBlueprintUtil
  • MatchmakerClient
    の一部としての 
    MatchmakerClientBlueprintUtil
MatchmakerClient
または 
MatchmakerServer
を追加すると、依存関係として 
MatchmakerCore
が含まれます。

MatchmakerClient

プレイヤーのカスタムデータ
MatchmakerClient
モジュールには、
MatchmakerClientBlueprintUtil
があり、以下が含まれています。 
PlayerCustomDataAddStringData(FMatchmakerPlayer& Player, FString Key, FString Value)
このブループリントを使用して、プレイヤーの CustomData オブジェクトに文字列データフィールドを追加できます。 これは、データが正常に設定されている場合に true を返し、そうでない場合に false を返します。 
PlayerCustomDataAddNumberData(FMatchmakerPlayer& Player, FString Key, float Value)
このブループリントを使用して、プレイヤーの CustomData オブジェクトに数値データフィールドを追加できます。 これは、データが正常に設定されている場合に true を返し、そうでない場合に false を返します。 
PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)
このブループリントを使用して、プレイヤーの CustomData オブジェクトからデータフィールドを削除できます。 これは、プレイヤーの CustomData に 
Key
が含まれていて、それが削除された場合に true を返します。
Key
が見つからなかった場合は false を返します。
Attributes
MatchmakerClient
モジュールには、
MatchmakerClientBlueprintUtil
があり、以下が含まれています。 
CreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
このブループリントを使用して、文字列ベースの属性を 
CreateTicketOptions
オブジェクトに追加します。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。 
CreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
このブループリントを使用して、数値ベースの属性を 
CreateTicketOptions
オブジェクトに追加します。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。 
CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
このブループリントを使用して、
CreateTicketOptions
オブジェクトから属性を削除します。 これは、
CreateTicketOptions
に属性が含まれていて、それが削除された場合に true を返します。属性が見つからなかった場合は false を返します。

MatchmakerServer

MatchmakerServer
モジュールには、
MatchmakerServerBlueprintUtil
があり、以下が含まれています。 
CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
このブループリントを使用して、文字列ベースの属性を 
CreateBackfillTicketOptions
オブジェクトに追加できます。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。 
CreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
このブループリントは、数値ベースの属性を 
CreateBackfillTicketOptions
オブジェクトに追加するために使用されます。 これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。 
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
このブループリントを使用して、
CreateBackfillTicketOptions
オブジェクトから属性を削除します。これは、
CreateBackfillTicketOptions
に属性が含まれていて、それが削除された場合に true を返します。また、属性が見つからなかった場合に false を返します。