Unreal: Matchmaking #

This tutorial uses Unreal Engine 5.3 with Pragma Engine 0.3.0 to demonstrate integrating Pragma Engine party functionality with a third-party game engine. This guide assumes you are proficient with Unreal Editor.

We’ve previously built the party flow up until the point players enter matchmaking: players can create a new party, join a party with an invite code, and select their game mode and characters. In this tutorial, we’ll expand the MyPlayerController.h header file and MyPlayerController.cpp source file to implement matchmaking functionality.

Prerequisites
About the Unreal Tutorials

The code presented in this tutorial is simplified to give you an introduction to the game flow. An actual game would have a more sophisticated design, and the player experience may differ significantly.

The functions in this tutorial are built as UFunctions with the Exec and BlueprintCallable specifiers, meaning they can be executed by the in-game console and in a Blueprint or Level Blueprint graph. The Exec specifier is useful for quickly testing your functions.

The example tests in each section are meant to ensure your C++ code is working properly and are unlikely to represent a completed game design. Adapt the organization and naming to suit your project’s needs.

Note that you may need to update your #include statements as you progress through the tutorial.

Update SDK #

Because there were changes to the ext protos, re-run the update script command from your Unreal Plugins folder:

update-pragma-sdk.sh

Enter matchmaking #

Goal Allow players in a party to enter matchmaking.

Steps #

  1. In MyPlayerController.h, declare EnterMatchmaking():

    public:
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void EnterMatchmaking();

  2. In MyPlayerController.cpp, define EnterMatchmaking() to enter the party into a matchmaking queue:

    void AMyPlayerController::EnterMatchmaking()
{
	Player->PartyApi().EnterMatchmaking(
		UPragmaPartyApi::FOnCompleteDelegate::CreateWeakLambda(
			this, [this](const TPragmaResult<> Result)
			{
				if (Result.IsSuccessful())
				{
					UE_LOG(LogTemp, Display,
						TEXT("MyGameClient -- Enter matchmaking success."));
				}
				else
				{
					UE_LOG(LogTemp, Error,
						TEXT("MyGameClient -- Unable to enter matchmaking: %s"),
						*Result.GetErrorAsString());
				}
			}));
}

As long as the two players are in different parties and both parties are set to the same game mode, the WarmbodyMatchmakingPlugin will match the two parties, create a game instance, and send the two parties to the game instance.

Players cannot enter matchmaking without being in the “ready” state. A player’s isReady value is automatically set to true when they make a character selection. See Make character selections.

Display game instance information #

Goal: Alert a player that they have been added to a game instance. This will verify the matchmaking process has succeeded.

The Pragma SDK for Unreal provides an OnAddedToGameInstance event that fires when a party is added to a game instance. We can use these events in Unreal to trigger handler functions for matchmaking and game instance updates. For now, our HandleOnAddedToGameInstance() function simply print an Unreal log entry.

Steps #

  1. In MyPlayerController.h, declare HandleOnAddedToGameInstance():

    private:
	void HandleOnAddedToGameInstance(const FPragmaGameInstance& GameInstance);

  2. In MyPlayerController.cpp, define HandleOnAddedToGame():

    void AMyPlayerController::HandleOnAddedToGameInstance(
	const FPragmaGameInstance& GameInstance)
{
	UE_LOG(LogTemp, Display, TEXT("MyGameClient -- Game instance ID: %s"),
		*GameInstance.GetId());
}

  3. In the MyPlayerController.cpp BeginPlay() function, register our HandleOnAddedToGame() function with the appropriate event handler:

    Player->GameInstanceApi().OnAddedToGameInstance.AddUObject(
	this, &AMyPlayerController::HandleOnAddedToGameInstance);

Test matchmaking functionality #

To test this functionality using the Unreal in-game console:

  1. Open two clients and log in as test01 and test02.

  2. As test01, create a party and set the game mode to Casual. Set a character.

  3. As test02 , create a party and set the game mode to Casual. Set a character.

  4. As test01, call EnterMatchmaking()

  5. As test02, call EnterMatchmaking()

To apply this functionality using Unreal Blueprints, create an “Enter matchmaking” button that calls the EnterMatchmaking function and populated a text box with the resulting game instance ID.

Upon successfully entering matchmaking, the Unreal output log should display a “Enter matchmaking success.” message for each player, as well as identical game instance IDs for each player.

Next steps #

At this point, players can enter matchmaking and enter game instances with appropriate matches. Continue to the Social tutorial to learn how to implement sample friend and presence functionality.


Set Up Matchmaking with Pragma Engine
Social