使用 Blueprint 集成#

以下部分展示如何使用 Unreal Engine 中的 Blueprint 与 Matchmaker SDK 集成。

您可以在 Unity Gaming Services SDK 中进行交互的两个 Matchmaker 接口是：

• Matchmaker Client Blueprint API
• Matchmaker Server Blueprint API

安装 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 Client Subsystem 控制关于匹配和寻找匹配玩家的客户端部分。此部分包括创建、删除和轮询匹配工单。

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

• CreateTicket
• DeleteTicket
• GetTicketStatus

CreateTicket#

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

以下示例展示了如何传入单个玩家和队列名称来创建工单。此外，还展示了一个事件，这个事件处理响应以获取 TicketId 的 FString 输出。

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

DeleteTicket#

使用 DeleteTicket Blueprint 发出删除工单调用，传入要删除的 TicketId。

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

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

GetTicketStatus#

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

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

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

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

Timer 句柄从 Set Timer by Event 节点传递到 Clear and Invalidate Timer by Handle 节点。您应该设置一些条件逻辑来触发 Clear and Invalidate Timer by Handle。在返回匹配结果之前，必须对 GetTicketStatus 进行大多数连续调用。当状态不再返回为 InProgress 后，便可以安全地停止轮询并删除工单了。

下图显示了如何处理轮询响应并触发 Clear and Invalidate Timer 的基本示例。

Matchmaker Server Blueprint API#

Matchmaker Server Subsystem 控制关于匹配的服务器部分。此部分包括创建、审批、删除和更新回填工单。

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

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

CreateBackfillTicket#

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

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

ApproveBackfillTicket#

使用 Approve Backfill Ticket Blueprint 定期审批您的回填工单，让新玩家进入服务器。

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

在上面的示例中，每秒循环运行一次审批。删除回填工单后，请务必使用 Clear and Invalidate Timer by Handle 节点。

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

Unity 建议缓存响应中的值，并使用这些值在 UpdateBackfillTicket 中构建 BackfillTicket。

UpdateBackfillTicket#

每当发生以下情况时，请更新回填工单：

• 一名玩家离开服务器
• 一名玩家从匹配逻辑之外加入服务器

这些情况可能包括但不限于派对邀请、直接连接和好友邀请。

可以使用 Update Backfill Ticket Blueprint 来更新服务器当前的回填工单。

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

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

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

DeleteBackfillTicket#

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

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

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

Blueprint 实用函数#

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

• MatchmakerServerBlueprintUtil 作为 MatchmakerServer 的一部分
• MatchmakerClientBlueprintUtil 作为 MatchmakerClient 的一部分

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

MatchmakerClient#

玩家自定义数据

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

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

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

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

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

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

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

PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)

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

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

属性

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

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

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

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

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

CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)

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

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

MatchmakerServer#

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

CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)

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

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

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

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

CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)

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