Integrate using Blueprints

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

Read time 6 minutes

Last updated 6 months ago

Important

Unity Matchmaker will support Multiplay Hosting until the deprecation date of March 31st, 2026. To aid your migration away from Multiplay Hosting, migration examples for alternative hosting providers are available. Matchmaker will continue to work with Relay and Distributed Authority after the Multiplay Hosting deprecation.

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:

Matchmaker Client Blueprint API
Matchmaker Server Blueprint API

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
DeleteTicket
GetTicketStatus

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

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.

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.

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

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.

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:

Create a backfill ticket to begin backfill on the server.
Approve a backfill ticket to let new players into the server.
Update a backfill ticket to notify the matchmaker as players leave and join outside of the matchmaking process.
Delete a backfill ticket after the server stops accepting new players.

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.

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.

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

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.

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.

Warning

Updating a backfill ticket too often can cause players to never backfill into the match. See Matchmaking Logic Sample to learn more.

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.

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

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.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Matchmaker for the Unreal Engine

Matchmaker overview

Matchmaker for the Unreal Engine

Integrate using Blueprints

Install the Matchmaker SDK plugin

Matchmaker Client Blueprint API

CreateTicket

DeleteTicket

GetTicketStatus

Matchmaker Server Blueprint API

CreateBackfillTicket

ApproveBackfillTicket

UpdateBackfillTicket

DeleteBackfillTicket

Blueprint utility functions

MatchmakerClient

Player custom data

Attributes

MatchmakerServer