Unreal: Matchmaking #

This tutorial uses Unreal Engine 5.3 with Pragma Engine 0.1.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

Required:

Get started #

To get started, re-run the update scrips command:

update-pragma-sdk.sh

Ensure you have a locally running Pragma Engine to test examples as you build each function.

How to use this tutorial #

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.

We’ve built this barebones matchmaking screen to help you visualize the functionality presented in this tutorial:

Screenshot of an example matchmaking screen in the Unreal game client

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.

For convenience, we’ve included sample C++ files that contain all the code from this tutorial, as well as the login/logout functionality and the party functionality.

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

Implement the Initialize Game Instance function #

Goal #

While the GameInstanceApi is not required to enter matchmaking, it is required for game instance creation. In this tutorial, we will test our matchmaking plugin by having the matchmaking service create a game instance after successfully matching two parties.

Implement a InitializeGameInstance() function that initializes the GameInstanceApi. You can also choose to implement the following functionality into a general Initialize() function that also initializes the Party, Game Instance, Friend, and Presence services (see the relevant tutorials for examples).

Steps #

  1. Declare the InitializeGameInstance() function in the public section of your MyPlayerController.h file:

    UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
void InitializeGameInstance();

  2. Define InitializeGameInstance() in your MyPlayerController.cpp file:

    void AMyPlayerController::InitializeGameInstance()
{
	UPragmaGameLoopApi::FOnCompleteDelegate GameInstanceInitializeDelegate;
	GameInstanceInitializeDelegate.BindWeakLambda(this, [this](const TPragmaResult<>& Result)
		{
			if (Result.IsSuccessful())
			{
				UE_LOG(LogTemp, Display, TEXT("Game Instance service initialized."));
			}
			else
			{
				UE_LOG(LogTemp, Warning, TEXT("Game Instance service failed to initialize: %s"), *Result.Error().ToString());
			}
		});
	Player->GameInstanceApi().Initialize(GameInstanceInitializeDelegate);
}

Enter matchmaking #

Goal #

Implement a EnterMatchmaking function that allows players in a party to enter matchmaking.

Steps #

  1. Declare the EnterMatchmaking() function in the public section of your MyPlayerController.h file:

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

  2. Define EnterMatchmaking() in your MyPlayerController.cpp file to enter the party into a matchmaking queue:

    void AMyPlayerController::EnterMatchmaking()
{
	UPragmaGameLoopApi::FOnCompleteDelegate OnEnterMatchmakingDelegate;
	OnEnterMatchmakingDelegate.BindWeakLambda(this, [this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Enter matchmaking success."));
		}
		else
		{
			UE_LOG(LogTemp, Warning, TEXT("Pragma unable to enter matchmaking: %s"), *Result.Error().ToString());
		}
	});

	Player->GameLoopApi().EnterMatchmaking(OnEnterMatchmakingDelegate);
}

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. For our tutorial, 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 #

Create an Unreal function that logs to the console whenever a player has been added to a game instance. This will verify the matchmaking process has successfully created a game instance.

The Pragma SDK provides an OnAddedToGame 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. Declare the HandleOnAddedToGameInstance() function in your MyPlayerController.h file under private:

    void HandleOnAddedToGameInstance(const FPragmaGameInstance& MyGameInstance);

  2. Define HandleOnAddedToGameInstance() in your MyPlayerController.cpp file:

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

  3. Register our HandleOnAddedToGameInstance() function with the appropriate event handler in the MyPlayerController.cpp file in the BeginPlay() function:

    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.

Sample header and source files #

The following sample files combine the code blocks from this tutorial, along with the functions from the Handle Login and Logout tutorial and Unreal: Parties tutorial.

Sample MyPlayerController.h header file
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "PragmaPtr.h"
#include "PragmaGameInstanceSubsystem.h"
#include "PragmaResult.h"
#include "Dto/PragmaPartyRpcExtDto.h"
#include "Services/Party/PragmaPartyInvite.h"
#include "MyPlayerController.generated.h"


// Forward declares Pragma pointer types for Pragma::FPlayer.
PRAGMA_FWD(FPlayer);

UCLASS()
class UNREALTUTORIAL_API AMyPlayerController : public APlayerController
{
	GENERATED_BODY()

public:
    
	virtual void BeginPlay() override;

	// Weak pointer to our Pragma Player owned by the PragmaLocalPlayerSubsystem.
	Pragma::FRuntimePtr Runtime;
	Pragma::FPlayerPtr Player;

	//Login and Logout functions
	
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void LogIn(const FString& Username);

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void LogOut();

	//Initialization functions

	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void InitializeParty();

	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void InitializeGameInstance();

	//Party functions
	
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void CreateParty();
	
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void JoinPartyWithInviteCode(const FString& InviteCode);

	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void JoinPartyWithPartyId(const FString& PartyId);
	
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void SendPartyInviteByPlayerId(const FString& InviteeId);

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void RespondToPartyInvite(const FString& PartyInviteId, const bool response);

	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void SetGameMode(const EPragma_Party_GameMode& GameModeSelection);

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void SetCharacter(const EPragma_Party_Character& CharacterSelection);

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void LeaveParty();
	
	
	//Matchmaking functions

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void EnterMatchmaking();
	
	
private:
	void HandleLoggedIn(const TPragmaResult<>& Result);
	void HandleLoggedOut();
	void HandleOnPartyInviteReceived(const FPragmaPartyInvite& MyPartyInvite);
	void HandleOnAddedToGameInstance(const FPragmaGameInstance& MyGameInstance);
};
Sample MyPlayerController.cpp source file
#include "MyPlayerController.h"
#include "PragmaPlayer.h"
#include "Dto/PragmaAccountRpcDto.h"
#include "Dto/PragmaPartyRpcExtDto.h"
#include "Pragma/Api/Player/PragmaFriendApi.h"
#include "Services/Party/PragmaPartyInvite.h"
#include "PragmaLocalPlayerSubsystem.h"

void AMyPlayerController::BeginPlay()
{
	Super::BeginPlay();

	UE_LOG(LogTemp, Display, TEXT("Initializing") );
	
	const auto* Subsystem = GetLocalPlayer()->GetSubsystem<UPragmaLocalPlayerSubsystem>();

	// The UPragmaLocalPlayerSubsystem is automatically initialized
	// with a Pragma Player object for every LocalPlayer.
	Player = Subsystem->Player();
	
	Player->PartyApi().OnPartyInviteReceived.AddUObject(
	this, &AMyPlayerController::HandleOnPartyInviteReceived);

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

//Login and Logout functions

void AMyPlayerController::LogIn(const FString& Username)
{
    Player->LogIn(
        EPragma_Account_IdProvider::UNSAFE,
        Username,
        Pragma::FPlayer::FLoggedInDelegate::CreateUObject(
            this, &AMyPlayerController::HandleLoggedIn));
}

void AMyPlayerController::LogOut()
{
    Player->LogOut(Pragma::FPlayer::FLoggedOutDelegate::CreateUObject(
        this, &AMyPlayerController::HandleLoggedOut));
}

//Initialization functions

void AMyPlayerController::InitializeParty()
{
	UPragmaPartyApi::FOnCompleteDelegate PartyInitializeDelegate;
	PartyInitializeDelegate.BindWeakLambda(this, [this](const TPragmaResult<>& Result)
		{
			if (Result.IsSuccessful())
			{
				UE_LOG(LogTemp, Display, TEXT("Party service initialized."));
			}
			else
			{
				UE_LOG(LogTemp, Warning, TEXT("Party service failed to initialize: %s"), *Result.Error().ToString());
			}
		});
	Player->PartyApi().Initialize(PartyInitializeDelegate);
}

void AMyPlayerController::InitializeGameInstance()
{
	UPragmaGameLoopApi::FOnCompleteDelegate GameInstanceInitializeDelegate;
	GameInstanceInitializeDelegate.BindWeakLambda(this, [this](const TPragmaResult<>& Result)
		{
			if (Result.IsSuccessful())
			{
				UE_LOG(LogTemp, Display, TEXT("Game Instance service initialized."));
			}
			else
			{
				UE_LOG(LogTemp, Warning, TEXT("Game Instance service failed to initialize: %s"), *Result.Error().ToString());
			}
		});
	Player->GameInstanceApi().Initialize(GameInstanceInitializeDelegate);
}


//Party functions

void AMyPlayerController::CreateParty()
{
	UPragmaPartyApi::FOnCompleteDelegate OnPartyCreatedDelegate;
	OnPartyCreatedDelegate.BindWeakLambda(this, [this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Pragma party created.  \n Party ID: %s \n Invite code: %s"),
				*Player->PartyApi().GetPartyCache()->Party()->GetId(),
				*Player->PartyApi().GetPartyCache()->Party()->GetInviteCode());
		}
		else
		{
			UE_LOG(LogTemp, Warning, TEXT("Pragma unable to create party: %s"), *Result.Error().ToString());
		}
	});

	Player->PartyApi().CreateParty(
		FPragma_Party_ExtCreateRequest{},
		FPragma_Party_ExtPlayerJoinRequest{},
		TArray<FString>(),
		TMap<FString, int32>(),
		OnPartyCreatedDelegate);
}

void AMyPlayerController::JoinPartyWithInviteCode(const FString& InviteCode)
{
	UPragmaPartyApi::FOnCompleteDelegate JoinWithInviteCodeDelegate;
	JoinWithInviteCodeDelegate.BindWeakLambda(this, [=, this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Joined party using invite code %s"), *InviteCode);
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to join party: %s"), *Result.Error().ToString());
		}
	});

	Player->PartyApi().JoinPartyWithInviteCode(
		FPragma_Party_ExtPlayerJoinRequest{},
		InviteCode,
		JoinWithInviteCodeDelegate
	);
}

void AMyPlayerController::JoinPartyWithPartyId(const FString& PartyId)
{
	UPragmaPartyApi::FOnCompleteDelegate JoinWithPartyIdDelegate;
	JoinWithPartyIdDelegate.BindWeakLambda(this, [=, this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Joined party using party ID %s"), *PartyId);
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to join party: %s"), *Result.Error().ToString());
		}
	});

	Player->PartyApi().JoinPartyWithId(
		FPragma_Party_ExtPlayerJoinRequest{},
		PartyId,
		JoinWithPartyIdDelegate
	);
}

void AMyPlayerController::SendPartyInviteByPlayerId(const FString& InviteeId)
{

	UPragmaPartyApi::FOnInviteSentDelegate SendPartyInviteDelegate;
	SendPartyInviteDelegate.BindWeakLambda(
		this, [this, InviteeId](const TPragmaResult<FString>& SendPartyInviteResult)
	{
		if (SendPartyInviteResult.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Party invite sent to player ID: %s"), *InviteeId);
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to send invite to player ID: %s Reason: %s"), *InviteeId, *SendPartyInviteResult.Error().ToString());
		}
	});
	
	Player->PartyApi().SendPartyInvite(
		InviteeId,
		SendPartyInviteDelegate
	);
}

void AMyPlayerController::RespondToPartyInvite(const FString& PartyInviteId, const bool Response)
{
	UPragmaPartyApi::FOnCompleteDelegate RespondInviteDelegate;
	RespondInviteDelegate.BindWeakLambda(this, [=, this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			if (Response==true)
			{
				UE_LOG(LogTemp, Display, TEXT("Accepted party invite. Party successfully joined."));
			}
			else
			{
				UE_LOG(LogTemp, Display, TEXT("Declined party invite"));
			}
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to respond: %s"), *Result.Error().ToString());
		}
	});

	Player->PartyApi().RespondToPartyInvite(
		FPragma_Party_ExtPlayerJoinRequest{},
		PartyInviteId,
		Response,
		RespondInviteDelegate
	);
}

void AMyPlayerController::SetGameMode(const EPragma_Party_GameMode& GameModeSelection)
{
	if(Player->PartyApi().GetPartyCache()->Party()->IsLeader(Player->Id())==true)
	{
		FPragma_Party_ExtUpdatePartyRequest Request;
		Request.Update.SetNewGameMode(GameModeSelection);

		UPragmaPartyApi::FOnCompleteDelegate UpdatePartyDelegate;
	
		UpdatePartyDelegate.BindWeakLambda(this, [=, this](TPragmaResult<> Result)
		{
			if (Result.IsSuccessful())
			{
				UE_LOG(LogTemp, Display,
					TEXT("Changed game mode selection to %s"), *UEnum::GetValueAsString<EPragma_Party_GameMode>(GameModeSelection));
			}
			else
			{
				UE_LOG(LogTemp, Warning,
					TEXT("Unable to change game mode: %s"), *Result.Error().ToString());
			}
		});

		Player->PartyApi().UpdateParty(Request, UpdatePartyDelegate);
	}
	else
	{
		UE_LOG(LogTemp, Display,TEXT("Only party leaders can select game mode"));
	}
}

void AMyPlayerController::SetCharacter(const EPragma_Party_Character& CharacterSelection)
{
	UPragmaPartyApi::FOnCompleteDelegate UpdatePartyPlayerDelegate;
	UpdatePartyPlayerDelegate.BindWeakLambda(this, [=, this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display,
				TEXT("Changed character selection to %s"), *UEnum::GetValueAsString<EPragma_Party_Character>(CharacterSelection));
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to change character: %s"), *Result.Error().ToString());
		}
	});

	FPragma_Party_ExtUpdatePartyPlayerRequest Request;
	Request.Update.SetNewCharacter(CharacterSelection);

	Player->PartyApi().UpdatePartyPlayer(Request, UpdatePartyPlayerDelegate);
}

void AMyPlayerController::LeaveParty()
{
	UPragmaGameLoopApi::FOnCompleteDelegate LeavePartyDelegate;
	LeavePartyDelegate.BindWeakLambda(this, [this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Successfully left party."));
		}
		else
		{
			UE_LOG(LogTemp, Warning,
				TEXT("Unable to leave party: %s"), *Result.Error().ToString());
		}
	});
	Player->PartyApi().LeaveParty(LeavePartyDelegate);
}

//Matchmaking functions

void AMyPlayerController::EnterMatchmaking()
{
	UPragmaPartyApi::FOnCompleteDelegate OnEnterMatchmakingDelegate;
	OnEnterMatchmakingDelegate.BindWeakLambda(this, [this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Enter matchmaking success."));
		}
		else
		{
			UE_LOG(LogTemp, Warning, TEXT("Pragma unable to enter matchmaking: %s"), *Result.Error().ToString());
		}
	});

	Player->PartyApi().EnterMatchmaking(OnEnterMatchmakingDelegate);
}


//Handler functions

void AMyPlayerController::HandleLoggedIn(const TPragmaResult<>& Result)
{
    if (Result.IsFailure())
    {
        UE_LOG(LogTemp, Display, TEXT("Pragma -- Login failed: %s"), *Result.ErrorCode());
    }
    UE_LOG(LogTemp, Display, TEXT("Pragma -- Logged in."));
}

void AMyPlayerController::HandleLoggedOut()
{
    UE_LOG(LogTemp, Display, TEXT("Pragma -- Logged out."));
}

void AMyPlayerController::HandleOnPartyInviteReceived(const FPragmaPartyInvite& MyPartyInvite)
{
	UE_LOG(LogTemp, Display, TEXT("Party invite received. Respond using invite ID: %s"), *MyPartyInvite.GetInviteId());
}

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

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