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

以下のセクションでは、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 を返します。

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.