# 使用 Blueprint 集成

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

以下部分展示如何使用 [Unreal Engine 中的 Blueprint](https://docs.unrealengine.com/5.3/en-US/ProgrammingAndScripting/Blueprints/GettingStarted/) 与 Matchmaker SDK 集成。

您可以在 Unity Gaming Services SDK 中进行交互的两个 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 Client Subsystem 控制关于匹配和寻找匹配玩家的客户端部分。此部分包括创建、删除和轮询匹配工单。

使用 `UMatchmakerClientBlueprintApi` 中的静态函数通过以下 Blueprint 与 Matchmaker Client Subsystem 交互：

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

#### CreateTicket##createticket

要使用 `CreateTicket`，请在 Blueprint 中放置一个 Create Ticket 节点。填充输入的 \*\*Players（玩家）\*\*和 \*\*Options（选项）\*\*字段以创建工单。

以下示例展示了如何传入单个玩家和队列名称来创建工单。此外，还展示了一个事件，这个事件处理响应以获取 `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` Blueprint 发出删除工单调用，传入要删除的 TicketId。

下面是一个简单的示例，演示了如何使用 Delete Ticket 以及如何处理响应。


**Frame:**
![删除匹配工单](/api/media?file=/matchmaker/media/images/unreal-sdk-deleteticket.png)

您可以为响应处理程序设置一个自定义事件，然后右键单击该事件的 `Response` 结构引脚，并选择 `Split Struct Pin` 以访问 `DeleteTicketResponse` 中所有单独的值。

#### GetTicketStatus##getticketstatus

使用 `GetTicketStatus` 可以轮询 Matchmaker，以便使用从 CreateTicket Blueprint 中检索到的 `TicketId` 获取匹配。

轮询完成后无论成功还是失败，或者用户希望手动取消匹配，请使用 `DeleteTicket` Blueprint 停止在匹配中考虑相应玩家。


**Frame:**
![轮询匹配工单](/api/media?file=/matchmaker/media/images/unreal-sdk-poll-matchmaking.png)

您可以为响应处理程序设置一个自定义事件，然后右键单击该事件的 `Response` 结构引脚，并选择 `Split Struct Pin` 以访问 `GetTicketStatusResponse]` 中所有单独的值。

上图显示了使用 `Set Timer by Event` 节点来轮询匹配工单的示例。当循环条件成立时，该节点将按照 Time 变量中设置的频率来持续触发其事件。在本例中，Time 设置为 5；因此该事件每五秒发生一次，直到计时器处理程序被取消。返回值是计时器处理程序，您可以在其中使用 `Clear and Invalidate Timer by Handle` 来取消计时器。


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

Timer 句柄从 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 Server Subsystem 控制关于匹配的服务器部分。此部分包括创建、审批、删除和更新回填工单。

您可以使用 `UMatchmakerServerBlueprintApi` 执行以下操作：

* [创建回填工单](#createbackfillticket)以开始在服务器上回填。
* [审批回填工单](#approvebackfillticket)以让新玩家进入服务器。
* [更新回填工单](#updatebackfillticket)以便玩家在匹配过程之外离开或加入时通知 Matchmaker。
* 在服务器停止接受新玩家后[删除回填工单](#deletebackfillticket)。

#### CreateBackfillTicket##createbackfillticket

当一名（或多名）玩家离开完整匹配，因此服务器需要填补空缺时，您需要创建新的回填工单。可以使用 Create Backfill Ticket Blueprint 为服务器创建新的回填工单。


**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 Blueprint 定期审批您的回填工单，让新玩家进入服务器。

建议审批回填工单的速度不要超过每秒一次。如果 20 秒内未审批工单，Matchmaker Service 就会将工单删除。


**Frame:**
![Approve Backfill Ticket](/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 Blueprint 来更新服务器当前的回填工单。


**Frame:**
![Update Backfill Ticket](/api/media?file=/matchmaker/media/images/unreal-sdk-updatebackfillticket.png)

您可以为响应处理程序设置一个自定义事件，然后右键单击该事件的 `Response` 结构引脚，并选择 `Split Struct Pin` 以访问 `UpdateBackfillTicketResponse` 中所有单独的值。

此调用的频率应该不超过每三秒一次，或者在 `ApproveBackfillTicket` 看到回填工单发生变化后进行调用，以保证至少经过一个匹配周期。

> **Warning:**
>
> **重要**：过于频繁地更新回填工单可能会导致玩家无法回填到匹配中。请参阅[匹配逻辑样本](/matchmaker/rules-sample.md)以了解更多信息。

Unity 建议先调用 `ApproveBackfillTicket`，然后根据需要使用从 `ApproveBackfillTicket` 返回的 `BackfillTicket` 进行修改并传递到 `UpdateBackfillTicket` 中。

#### DeleteBackfillTicket##deletebackfillticket

当匹配人数已满之后，服务器不再需要接受新玩家时，您可以删除回填工单。匹配结束后，也应该执行此操作。

可以使用 Delete Backfill Ticket Blueprint 停止服务器上的回填。


**Frame:**
![Delete Backfill Ticket](/api/media?file=/matchmaker/media/images/unreal-sdk-deletebackfillticket.png)

您可以为响应处理程序设置一个自定义事件，然后右键单击该事件的 `Response` 结构引脚，并选择 `Split Struct Pin` 以访问 `DeleteBackfillTicketResponse` 中所有单独的值。

### Blueprint 实用函数##blueprint-utility-functions

由于 Blueprint 的限制，JSON 数据类型（例如 `FJsonObject` 和 `FJsonValue`）本身不兼容，也不支持直接操作。SDK 实现了一组实用函数，允许您在 API 中管理 JSON 数据：

* `MatchmakerServerBlueprintUtil` 作为 `MatchmakerServer` 的一部分
* `MatchmakerClientBlueprintUtil` 作为 `MatchmakerClient` 的一部分

添加 `MatchmakerClient` 或 `MatchmakerServer` 时，`MatchmakerCore` 作为依赖项包含在其中。

#### MatchmakerClient##matchmakerclient

##### 玩家自定义数据##player-custom-data

在 `MatchmakerClient` 模块中具有 `MatchmakerClientBlueprintUtil`，其中包含

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

您可以使用此 Blueprint 向玩家的 CustomData 对象添加字符串数据字段。

如果成功设置数据，返回 true；否则，返回 false。

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

您可以使用此 Blueprint 向玩家的 CustomData 对象添加数字数据字段。

如果成功设置数据，返回 true；否则，返回 false。

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

您可以使用此 Blueprint 从玩家的 CustomData 对象移除数据字段。

如果玩家的 CustomData 包含 `Key` 并且已被移除，返回 true。如果未找到 `Key`，返回 false。

##### 属性##attributes

在 `MatchmakerClient` 模块中具有 `MatchmakerClientBlueprintUtil`，其中包含

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

可以使用此 Blueprint 向 `CreateTicketOptions` 对象添加基于字符串的属性。如果成功设置该属性，返回 true；否则，返回 false。

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

可以使用此 Blueprint 向 `CreateTicketOptions` 对象添加基于数字的属性。如果成功设置该属性，返回 true；否则，返回 false。

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

可以使用此 Blueprint 从 `CreateTicketOptions` 对象中移除属性。

如果 `CreateTicketOptions` 包含该属性并且该属性已被移除，返回 true。如果未找到该属性，返回 false。

#### MatchmakerServer##matchmakerserver

在 `MatchmakerServer` 模块中具有 `MatchmakerServerBlueprintUtil`，其中包含

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

您可以使用此 Blueprint 向 `CreateBackfillTicketOptions` 对象添加基于字符串的属性。如果成功设置该属性，返回 true；否则，返回 false。

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

此 Blueprint 用于向 `CreateBackfillTicketOptions` 对象添加基于数字的属性。

如果成功设置该属性，返回 true；否则，返回 false。

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

可以使用此 Blueprint 从 `CreateBackfillTicketOptions` 对象中移除属性。如果 `CreateBackfillTicketOptions` 包含该属性并且该属性已被移除，返回 true；如果未找到该属性，返回 false。