使用 Blueprint 集成

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

阅读时间7 分钟

最后更新于 7 个月前

以下部分展示如何使用 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。

文档

Development

User Acquisition

Monetization

工业

文档

Development

User Acquisition

Monetization

工业

Matchmaker for the Unreal Engine

Matchmaker overview

Matchmaker for the Unreal Engine

使用 Blueprint 集成

安装 Matchmaker SDK 插件

Matchmaker Client Blueprint API

CreateTicket

DeleteTicket

GetTicketStatus

Matchmaker Server Blueprint API

CreateBackfillTicket

ApproveBackfillTicket

UpdateBackfillTicket

DeleteBackfillTicket

Blueprint 实用函数

MatchmakerClient

玩家自定义数据

属性

MatchmakerServer