Integrate using Blueprints#

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 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 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 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 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 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.

You can set up a custom event for the response handler and right-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.

You can set up a custom event for the response handler and right-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.