Documentation

Support

Matchmaker

Matchmaker

Integrate using Blueprints

Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.
Read time 6 minutesLast updated 2 days ago
The following section shows how to integrate with the Matchmaker SDK using Blueprints in the Unreal Engine. The two Matchmaker interfaces you can interact with within the Unity Gaming Services SDK are the:

Install the Matchmaker SDK plugin

Before continuing, add the 
MatchmakerSDK
as a public dependency of your module, then include the plugin header files in your classes as shown below. Add 
MatchmakerServer
and 
MatchmakerClient
to your module's dependencies to your Unreal project build file (
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

The Matchmaker client subsystem controls the client portion of matchmaking and finding matches. This includes creating, deleting, and polling matchmaking tickets. Use the static functions from 
UMatchmakerClientBlueprintApi
to interact with the Matchmaker client subsystem through the following Blueprints:

CreateTicket

To use 
CreateTicket
, place a Create Ticket node in your blueprint. Populate the Players and Options fields for the inputs to create a ticket. The following example shows how to pass in a single player and a queue name to create a ticket. It also shows an event that handles the response to get an 
FString
output for the 
TicketId
.
Setup a player
Set up CreateTicketOptions
Call Create Ticket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the event's 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
CreateTicketResponse
.

DeleteTicket

Use the 
DeleteTicket
blueprint to issue a delete ticket call, passing in the TicketId to delete. Below is a simple example demonstrating how to use Delete Ticket and how to handle the response.
Delete Matchmaking Ticket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the event's 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
DeleteTicketResponse
.

GetTicketStatus

Use 
GetTicketStatus
to poll the matchmaker for a match using the 
TicketId
retrieved from the CreateTicket blueprint. After polling completes either successfully or not, or if the user wishes to manually cancel matchmaking, use the 
DeleteTicket
blueprint to stop considering the player(s) for matchmaking.
Poll Matchmaking Ticket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the event's 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
GetTicketStatusResponse]
. The image above shows an example of polling a matchmaking ticket with the 
Set Timer by Event
node. When the looping condition is true, this node triggers its event continuously in the frequency that is set in the Time variable. In this case, Time is set to 5; therefore this event occurs every five seconds until the timer handler is canceled. The return value is the timer handler which you can use to cancel the timer using a 
Clear and Invalidate Timer by Handle
.
Set Timer by Event
The Timer handle gets passed from the Set Timer by Event node to the Clear and Invalidate Timer by Handle node. You should have some conditional logic to trigger Clear and Invalidate Timer by Handle. You must make most consecutive calls to 
GetTicketStatus
before a match is returned. After the status no longer returns as InProgress, it's safe to stop polling and delete the ticket. The following image shows a basic example of how to handle a polling response and trigger a Clear and Invalidate Timer.
Clear and Invalidate Timer

Matchmaker Server Blueprint API

The Matchmaker Server Subsystem controls the server portion of matchmaking. This includes creating, approving, deleting, and updating backfill tickets. You can use the 
UMatchmakerServerBlueprintApi
to:

CreateBackfillTicket

You need to create a new backfill ticket after a player (or players) leaves a full match, and the server needs to fill the empty slots. Use the Create Backfill Ticket blueprint to create a new backfill ticket for the server.
Set Up MatchProperties
Set up CreatebackfillTicketOptions
Call CreateBackfillTicket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the events 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
CreateBackfillTicketResponse
.

ApproveBackfillTicket

Use the Approve Backfill Ticket blueprint to periodically approve your backfill ticket to let new players into the server. It's recommended to approve backfill tickets no faster than once a second. If a ticket goes for 20 seconds without approval, the Matchmaker service deletes it.
Approve Backfill Ticket
In the example above, approval runs in a loop every second. Be sure to use a Clear and Invalidate Timer by Handle node after deleting the backfill ticket. You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the events 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
ApproveBackfillTicketResponse
. Unity recommends caching the values from the response and using them to build the 
BackfillTicket
in 
UpdateBackfillTicket
.

UpdateBackfillTicket

Update the backfill ticket whenever:
  • A player leaves the server
  • A player joins the server from outside of matchmaking logic
This can include but isn't limited to party invites, direct connections, and friend invites. Use the Update Backfill Ticket blueprint to update a server's current backfill ticket.
Update Backfill Ticket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the events 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
UpdateBackfillTicketResponse
. You should call this no more than once every three seconds or after 
ApproveBackfillTicket
sees a change in the backfill ticket to guarantee a matchmaking cycle has passed. Unity recommends calling 
ApproveBackfillTicket
first and using the 
BackfillTicket
returned from 
ApproveBackfillTicket
to modify as needed and pass into the 
UpdateBackfillTicket
.

DeleteBackfillTicket

You can delete a backfill ticket after a match becomes full and the server no longer needs to accept new players. You should also do this after a match ends. Use the Delete Backfill Ticket blueprint to stop backfill on a server.
Delete Backfill Ticket
You can set up a custom event for the response handler and right-click (macOS: Ctrl+click) the events 
Response
struct pin and select 
Split Struct Pin
to access all the individual values in 
DeleteBackfillTicketResponse
.

Blueprint utility functions

Due to limitations in Blueprints, JSON data types (such as 
FJsonObject
and 
FJsonValue
) are not natively compatible and don’t support direct manipulation. The SDK implements a set of utility functions that allow you to manage JSON data as part of the API: 
  • MatchmakerServerBlueprintUtil
    as part of 
    MatchmakerServer
  • MatchmakerClientBlueprintUtil
    as part of 
    MatchmakerClient
MatchmakerCore
is included as a dependency when adding 
MatchmakerClient
or 
MatchmakerServer
.

MatchmakerClient

Player custom data
In the 
MatchmakerClient
module there is 
MatchmakerClientBlueprintUtil
with 
PlayerCustomDataAddStringData(FMatchmakerPlayer& Player, FString Key, FString Value)
You can use this blueprint to add a string data field to a player’s CustomData object. This returns true if the data is set successfully; otherwise, it returns false. 
PlayerCustomDataAddNumberData(FMatchmakerPlayer& Player, FString Key, float Value)
You can use this blueprint to add a number data field to a player's CustomData object. This returns true if the data is set successfully; otherwise, it returns false. 
PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)
You can use this blueprint to remove a data field from a player’s CustomData object. This returns true if the player’s CustomData contains a 
Key
and it was removed. It returns false if a 
Key
wasn't found.
Attributes
In the 
MatchmakerClient
module there is 
MatchmakerClientBlueprintUtil
with 
CreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
Use this blueprint to add a string-based attribute to a 
CreateTicketOptions
object. This returns true if the attribute is set successfully, and false otherwise. 
CreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
Use this blueprint to add a number-based attribute to a 
CreateTicketOptions
object. This returns true if the attribute is set successfully, and false otherwise. 
CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
Use this blueprint to remove an attribute from a 
CreateTicketOptions
object. This returns true if 
CreateTicketOptions
contains the attribute and it was removed. If the attribute wasn't found, it returns false.

MatchmakerServer

In the 
MatchmakerServer
module, there’s 
MatchmakerServerBlueprintUtil
with 
CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
You can use this blueprint to add a string-based attribute to a 
CreateBackfillTicketOptions
object. This returns true if the attribute is set successfully, and false otherwise. 
CreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
This blueprint is used to add a number-based attribute to a 
CreateBackfillTicketOptions
object. This returns true if the attribute is set successfully, and false otherwise. 
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
Use this blueprint to remove an attribute from a 
CreateBackfillTicketOptions
object. This returns true if 
CreateBackfillTicketOptions
contains the attribute and it was removed, and false if the attribute wasn't found.