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

> Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.

以下のセクションでは、[Unreal Engine のブループリント](https://docs.unrealengine.com/5.3/en-US/ProgrammingAndScripting/Blueprints/GettingStarted/) を使用して Matchmaker SDK を統合する方法を示します。

Unity Gaming Services SDK 内では、次の 2 つの Matchmaker インターフェースを操作できます。

* [Matchmaker Client Blueprint API](#matchmaker-client-blueprint-api)
* [Matchmaker Server Blueprint API](#matchmaker-server-blueprint-api)

### Matchmaker SDK プラグインのインストール##install-the-matchmaker-sdk-plugin

先に進む前に、`MatchmakerSDK` をモジュールのパブリック依存関係として追加し、以下に示すようにプラグインのヘッダーファイルをクラスに加えます。

`MatchmakerServer` と `MatchmakerClient` をモジュールの依存関係として Unreal プロジェクトのビルドファイル (`YourProjectName.Build.cs`) に追加します。

```cpp
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-client-blueprint-api

Matchmaker クライアントサブシステムが、マッチメイキングとマッチ検出のクライアント部分を制御します。これには、マッチメイキングチケットの作成、削除、ポーリングが含まれています。

`UMatchmakerClientBlueprintApi` の静的関数を使用し、以下のブループリントを通じて Matchmaker クライアントサブシステムを操作します。

* [CreateTicket](#createticket)
* [DeleteTicket](#deleteticket)
* [GetTicketStatus](#getticketstatus)

#### CreateTicket##createticket

`CreateTicket` を使用するには、ブループリントに Create Ticket ノードを配置します。チケットを作成するための入力として、**Players** と **Options** の各フィールドに入力します。

以下の例では、1 人のプレイヤーとキューを渡してチケットを作成する方法を示しています。また、応答を処理して `TicketId` の `FString` 出力を取得するイベントも示しています。


**Frame:**
![プレイヤーの設定](/api/media?file=/matchmaker/media/images/unreal-sdk-set-up-player.png)


**Frame:**
![CreateTicketOptions の設定](/api/media?file=/matchmaker/media/images/unreal-sdk-createticketoptions.png)


**Frame:**
![Create Ticket の呼び出し](/api/media?file=/matchmaker/media/images/unreal-sdk-create-ticket.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`CreateTicketResponse` の個々の値すべてにアクセスします。

#### DeleteTicket##deleteticket

`DeleteTicket` ブループリントを使用して、Delete Ticket 呼び出しを発行し、削除する TicketId を渡します。

以下は、Delete Ticket の使用方法と応答の処理方法を示す簡単な例です。


**Frame:**
![マッチメイキングチケットの削除](/api/media?file=/matchmaker/media/images/unreal-sdk-deleteticket.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`DeleteTicketResponse` の個々の値すべてにアクセスします。

#### GetTicketStatus##getticketstatus

`GetTicketStatus` を使用し、CreateTicket ブループリントから取得した `TicketId` を使ってマッチメーカーに対してマッチをポーリングします。

ポーリングが成功または失敗して完了した後、またはユーザーがマッチメイキングを手動でキャンセルした場合には、`DeleteTicket` ブループリントを使用して、プレイヤーをマッチメイキングの対象と認識することを停止します。


**Frame:**
![マッチメイキングチケットのポーリング](/api/media?file=/matchmaker/media/images/unreal-sdk-poll-matchmaking.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`GetTicketStatusResponse]` の個々の値すべてにアクセスします。

上の画像は、`Set Timer by Event` ノードを使用したマッチメイキングチケットのポーリングの例を示しています。このノードは、ループ条件が true の場合に、Time 変数で設定された頻度でイベントを継続的にトリガーします。この例では Time が 5 に設定されているため、このイベントは、タイマーハンドラーがキャンセルされるまで 5 秒ごとに発生します。戻り値は、`Clear and Invalidate Timer by Handle` によるタイマーのキャンセルに使用できるタイマーハンドラーです。


**Frame:**
![Set Timer by Event](/api/media?file=/matchmaker/media/images/unreal-sdk-set-timer.png)

タイマーハンドルは、Set Timer by Event ノードから Clear and Invalidate Timer by Handle ノードに渡されます。Clear and Invalidate Timer by Handle をトリガーするには、何らかの条件付きロジックが必要です。マッチが返される前に、`GetTicketStatus` への最多連続呼び出しを実行する必要があります。InProgress のステータスが返されなくなったら、ポーリングを停止してチケットを削除しても問題ありません。

以下の画像は、ポーリング応答を処理して Clear and Invalidate Timer をトリガーする方法の基本的な例を示しています。


**Frame:**
![Clear and Invalidate Timer](/api/media?file=/matchmaker/media/images/unreal-sdk-invalidate-timer.png)

### Matchmaker Server Blueprint API##matchmaker-server-blueprint-api

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

`UMatchmakerServerBlueprintApi` を使用すると、以下のことができます。

* サーバーでのバックフィルを開始するために、[バックフィルチケットを作成する](#createbackfillticket)。
* 新しいプレイヤーがサーバーに参加できるように、[バックフィルチケットを承認する](#approvebackfillticket)。
* プレイヤーがサーバーから退出した場合とマッチメイキングプロセスの外部からサーバーに参加した場合にマッチメーカーに通知するために、[バックフィルチケットを更新する](#updatebackfillticket)。
* サーバーが新しいプレイヤーの受け入れを停止した後に、[バックフィルチケットを削除する](#deletebackfillticket)。

#### CreateBackfillTicket##createbackfillticket

あるプレイヤー (または複数のプレイヤー) が満員のマッチから退出した後には、新しいバックフィルチケットを作成する必要があります。また、サーバーは空のスロットを埋める必要があります。Create Backfill Ticket ブループリントを使用して、サーバーに新しいバックフィルチケットを作成します。


**Frame:**
![MatchProperties の設定](/api/media?file=/matchmaker/media/images/unreal-sdk-matchproperties.png)


**Frame:**
![CreatebackfillTicketOptions の設定](/api/media?file=/matchmaker/media/images/unreal-sdk-createbackfillticketoptions.png)


**Frame:**
![CreateBackfillTicket の呼び出し](/api/media?file=/matchmaker/media/images/unreal-sdk-createbackfillticket.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`CreateBackfillTicketResponse` の個々の値すべてにアクセスします。

#### ApproveBackfillTicket##approvebackfillticket

Approve Backfill Ticket ブループリントを使用し、バックフィルチケットを定期的に承認して新しいプレイヤーがサーバーに参加できるようにします。

バックフィルチケットの承認は、最速でも 1 秒に 1 回までにすることをお勧めします。チケットが承認されない状態が 20 秒続くと、そのチケットは Matchmaker サービスによって削除されます。


**Frame:**
![バックフィルチケットの承認](/api/media?file=/matchmaker/media/images/unreal-sdk-approve-backfill.png)

上の例では、承認がループで毎秒実行されます。バックフィルチケットを削除した後に Clear and Invalidate Timer by Handle ノードを使用してください。

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`ApproveBackfillTicketResponse` の個々の値すべてにアクセスします。

Unity では、応答から値をキャッシュし、それらの値を `UpdateBackfillTicket` での `BackfillTicket` のビルドに使用することをお勧めしています。

#### UpdateBackfillTicket##updatebackfillticket

バックフィルチケットは次の場合に更新します。

* プレイヤーがサーバーを退出した場合
* プレイヤーが対戦相手探しのロジックの外からサーバーに参加した場合

これには、パーティの招待、直接接続、友人の招待などが含まれますが、これらに限りません。

Update Backfill Ticket ブループリントを使用して、サーバーの現在のバックフィルチケットを更新します。


**Frame:**
![バックフィルチケットの更新](/api/media?file=/matchmaker/media/images/unreal-sdk-updatebackfillticket.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`UpdateBackfillTicketResponse` の個々の値すべてにアクセスします。

これは、3 秒に 1 回よりも少ない頻度で呼び出す必要があります。または、`ApproveBackfillTicket` がバックフィルチケットの変更を認識した後に呼び出す必要があります。そうすることで、マッチメイキングサイクルの経過を保証します。

> **Warning:**
>
> **重要**: バックフィルチケットの更新頻度が高すぎると、バックフィルによるマッチへのプレイヤー参加がまったくできなくなる可能性があります。詳細は、[対戦相手探しのロジックのサンプル](/matchmaker/rules-sample.md) を参照してください。

Unity では、最初に `ApproveBackfillTicket` を呼び出し、`ApproveBackfillTicket` から返された `BackfillTicket` を使用して必要に応じて修正し、`UpdateBackfillTicket` に渡すことをお勧めします。

#### DeleteBackfillTicket##deletebackfillticket

マッチが満員になり、サーバーが新しいプレイヤーを受け付ける必要がなくなった後は、バックフィルチケットを削除できます。これはマッチが終了した後にも行う必要があります。

Delete Backfill Ticket ブループリントを使用して、サーバーでのバックフィルを停止します。


**Frame:**
![バックフィルチケットの削除](/api/media?file=/matchmaker/media/images/unreal-sdk-deletebackfillticket.png)

応答ハンドラーにカスタムイベントを設定できます。イベントの `Response` 構造体のピンを右クリックして `Split Struct Pin` を選択し、`DeleteBackfillTicketResponse` の個々の値すべてにアクセスします。

### ブループリントのユーティリティ関数##blueprint-utility-functions

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

* `MatchmakerServer` の一部としての `MatchmakerServerBlueprintUtil`
* `MatchmakerClient` の一部としての `MatchmakerClientBlueprintUtil`

`MatchmakerClient` または `MatchmakerServer` を追加すると、依存関係として `MatchmakerCore` が含まれます。

#### MatchmakerClient##matchmakerclient

##### プレイヤーのカスタムデータ##player-custom-data

`MatchmakerClient` モジュールには、`MatchmakerClientBlueprintUtil` があり、以下が含まれています。

```cpp
PlayerCustomDataAddStringData(FMatchmakerPlayer& Player, FString Key, FString Value)
```

このブループリントを使用して、プレイヤーの CustomData オブジェクトに文字列データフィールドを追加できます。

これは、データが正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
PlayerCustomDataAddNumberData(FMatchmakerPlayer& Player, FString Key, float Value)
```

このブループリントを使用して、プレイヤーの CustomData オブジェクトに数値データフィールドを追加できます。

これは、データが正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)
```

このブループリントを使用して、プレイヤーの CustomData オブジェクトからデータフィールドを削除できます。

これは、プレイヤーの CustomData に `Key` が含まれていて、それが削除された場合に true を返します。`Key` が見つからなかった場合は false を返します。

##### Attributes##attributes

`MatchmakerClient` モジュールには、`MatchmakerClientBlueprintUtil` があり、以下が含まれています。

```cpp
CreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
```

このブループリントを使用して、文字列ベースの属性を `CreateTicketOptions` オブジェクトに追加します。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
CreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
```

このブループリントを使用して、数値ベースの属性を `CreateTicketOptions` オブジェクトに追加します。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
```

このブループリントを使用して、`CreateTicketOptions` オブジェクトから属性を削除します。

これは、`CreateTicketOptions` に属性が含まれていて、それが削除された場合に true を返します。属性が見つからなかった場合は false を返します。

#### MatchmakerServer##matchmakerserver

`MatchmakerServer` モジュールには、`MatchmakerServerBlueprintUtil` があり、以下が含まれています。

```cpp
CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
```

このブループリントを使用して、文字列ベースの属性を `CreateBackfillTicketOptions` オブジェクトに追加できます。これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
CreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
```

このブループリントは、数値ベースの属性を `CreateBackfillTicketOptions` オブジェクトに追加するために使用されます。

これは、属性が正常に設定されている場合に true を返し、そうでない場合に false を返します。

```cpp
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
```

このブループリントを使用して、`CreateBackfillTicketOptions` オブジェクトから属性を削除します。これは、`CreateBackfillTicketOptions` に属性が含まれていて、それが削除された場合に true を返します。また、属性が見つからなかった場合に false を返します。