Unreal: Matchmaking #

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

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.

Implement the enter matchmaking service call #

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. A player’s isReady value is automatically set to true when they make a character selection. See Make character selections.

Test

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.

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

  4. As test01, call EnterMatchmaking()

  5. As test02, call EnterMatchmaking()

To apply this functionality using Unreal Blueprints:

  1. Create a “Enter matchmaking” button that calls your EnterMatchmaking() function.

  2. As test01 in a party with a Casual game mode, click “Enter matchmaking”.

  3. As test02 in a different party with a Casual game mode, click “Enter matchmaking”.

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.

Add matchmaking event handlers to the client #

Goal:

Create an Unreal function that logs to the console whenever a player has entered matchmaking or has been added to a game instance.

The Pragma SDK provides an OnEnteredMatchmaking event that fires every time a party enters matchmaking, as well as a 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 HandleEnteredMatchmaking() and HandleOnAddedToGame() functions simply print an Unreal log entry.

Steps:

  1. Declare the HandleEnteredMatchmaking() and HandleOnAddedToGame() functions in your PC_TutorialPlayerController.h file under private:

    void HandleEnteredMatchmaking();
void HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext);

  2. Define HandleEnteredMatchmaking() and HandleOnAddedToGame() in your PC_TutorialPlayerController.cpp file:

    void APC_TutorialPlayerController::HandleEnteredMatchmaking()
{
    UE_LOG(LogTemp, Display, TEXT("You are in matchmaking."));
}

void ATutorialPlayerController::HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext)
{
    UE_LOG(LogTemp, Display, TEXT("Game instance ID: %p"), *FString(GameInstanceId) );
}

HandleEnteredMatchmaking() is called when the party enters matchmaking. Similarly, HandleOnAddedToGame() is called when matchmaking successfully creates a game instance by grouping together the appropriate number of players to play a game.

  1. Lastly, we need to register the HandleEnteredMatchmaking() and HandleOnAddedToGame() functions with the appropriate event handlers. In PC_TutorialPlayerController.cpp, add the following lines to the BeginPlay() function:

    Player->GameLoopApi().OnEnteredMatchmaking.AddUObject(
    this, &APC_TutorialPlayerController::HandleEnteredMatchmaking);

Player->GameLoopApi().OnAddedToGame.AddUObject(
    this, &APC_TutorialPlayerController::HandleOnAddedToGame);

Test

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

  1. As test01 in a ready party, call your EnterMatchmaking() function. When successfully executed, you’ll see “You are in matchmaking.” in your Unreal output log.

  2. As test02 in a ready party, call your EnterMatchmaking() function.

To apply this functionality using Unreal Blueprints, click the “Enter matchmaking” button.

When successfully executed, you’ll see “You are in matchmaking.” in your Unreal output log for each player, and a “Game instance ID [game instance ID]” message for each player, along with any on-screen functionality you defined in the Blueprints.

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/PragmaGameInstanceExtDto.h"
#include "Dto/PragmaPartyRpcExtDto.h"
#include "Pragma/Api/Player/PragmaFriendOverview.h"
#include "Services/Party/PragmaParty.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;
    
	UFUNCTION(Exec, BlueprintCallable, Category="Pragma")
	void LogIn(const FString& Username);

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

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

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

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	TArray<FString> GetPartyInvites();
	
	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	FString GetInviteCode();
	
	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void JoinByInviteCode(const FString& InviteCode);
	
	UFUNCTION(Exec, BlueprintCallable, meta=(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"))
	FString GetDisplayName();

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	FString GetPlayerId();

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	TArray<FString> GetPartyPlayerDisplayNames();

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

	UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma"))
	void EnterMatchmaking();
	
private:
	void HandleLoggedIn(const TPragmaResult<>& Result);
	void HandleLoggedOut();
	void HandlePartyUpdate(const UPragmaParty* Party);

	void HandleEnteredMatchmaking();
	void HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext);
	
	// Weak pointer to our Pragma Player owned by the PragmaLocalPlayerSubsystem.
	Pragma::FRuntimePtr Runtime;
	Pragma::FPlayerPtr Player;
	
};
Sample MyPlayerController.cpp source file
#include "MyPlayerController.h"
#include "PragmaPlayer.h"
#include "Services/Party/PragmaParty.h"
#include "Dto/PragmaAccountRpcDto.h"
#include "Dto/PragmaAccountServiceRaw.h"
#include "Dto/PragmaPartyRpcExtDto.h"
#include "Pragma/Api/Player/PragmaFriendOverview.h"
#include "PragmaLocalPlayerSubsystem.h"

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

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

	// The Pragma Runtime is automatically initialized in the PragmaGameInstanceSubsystem.
	auto RuntimeA = Subsystem->Runtime();

	// Set configuration for the SDK before logging in.
	RuntimeA->Config().BackendAddress = "http://127.0.0.1:10000";
	RuntimeA->Config().ProtocolType = EPragmaProtocolType::WebSocket;
	RuntimeA->Config().GameClientVersion = "GameServerVersion1";

	// The UPragmaLocalPlayerSubsystem is automatically initialized
	// with a Pragma Player object for every LocalPlayer.
	Player = Subsystem->Player();

	Player->GameLoopApi().OnPartyChanged.AddUObject(this, &AMyPlayerController::HandlePartyUpdate);

	Player->GameLoopApi().OnEnteredMatchmaking.AddUObject(
		this, &AMyPlayerController::HandleEnteredMatchmaking);

	Player->GameLoopApi().OnAddedToGame.AddUObject(
		this, &AMyPlayerController::HandleOnAddedToGame);

}

//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));
}

//Party functions

void AMyPlayerController::CreateParty()
{
	UPragmaGameLoopApi::FOnCompleteDelegate OnPartyCreatedDelegate;
	OnPartyCreatedDelegate.BindWeakLambda(this, [this](TPragmaResult<> Result)
	{
		if (Result.IsSuccessful())
		{
			UE_LOG(LogTemp, Display, TEXT("Pragma party created."));
		}
		else
		{
			UE_LOG(LogTemp, Warning, TEXT("Pragma unable to create party: %s"), *Result.Error().ToString());
		}
	});

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

FString AMyPlayerController::GetInviteCode()
{
	if (!Player->GameLoopApi().GetParty())
	{
		return FString{};
	}
	UE_LOG(LogTemp, Display, TEXT("Invite code: %s"), *Player->GameLoopApi().GetParty()->GetInviteCode());
	return Player->GameLoopApi().GetParty()->GetInviteCode();
}

void AMyPlayerController::JoinByInviteCode(const FString& InviteCode)
{
	UPragmaGameLoopApi::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->GameLoopApi().JoinPartyWithInviteCode(
		FPragma_Party_ExtPlayerJoinRequest{},
		InviteCode,
		JoinWithInviteCodeDelegate
	);
}

void AMyPlayerController::SendPartyInviteByUserId(const FString& InviteeId)
{
	Player->GameLoopApi().SendPartyInvite(
		InviteeId,
		UPragmaGameLoopApi::FOnInviteSentDelegate::CreateWeakLambda(
	this, [this, InviteeId](const TPragmaResult<FString>& SendPartyInviteResult)
	{
		if (SendPartyInviteResult.IsSuccessful())
		{
			const FString InviteId = SendPartyInviteResult.Payload();
			UE_LOG(LogTemp, Display, TEXT("Send party invite by player id succeeded. Party invite ID: %s"), *InviteId);
		}
		else
		{
			UE_LOG(LogTemp, Warning, TEXT("Pragma unable to accept invite: %s"), *SendPartyInviteResult.Error().ToString());
		}
	})
	);
}

TArray<FString> AMyPlayerController::GetPartyInvites()
{
	const TArray<FPragmaPartyInvite> PartyInvites = Player->GameLoopApi().GetPendingPartyInvites();

	TArray<FString> PartyInviteIds;

	for(const FPragmaPartyInvite PartyInvite : PartyInvites)
	{
		FString PartyInviteId = PartyInvite.GetInviteId();
		UE_LOG(LogTemp, Display, TEXT("Invitation id: %s"), *PartyInviteId);
		PartyInviteIds.Add(PartyInviteId);
	}
	
	return PartyInviteIds;
}

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

	Player->GameLoopApi().RespondToPartyInvite(
		FPragma_Party_ExtPlayerJoinRequest{},
		PartyInviteId,
		response,
		RespondInviteDelegate
	);
}

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

		UPragmaGameLoopApi::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->GameLoopApi().UpdateParty(Request, UpdatePartyDelegate);
	}
	else
	{
		UE_LOG(LogTemp, Display,TEXT("Only party leaders can select game mode"));
	}
}

void AMyPlayerController::SetCharacter(const EPragma_Party_Character& CharacterSelection)
{
	UPragmaGameLoopApi::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->GameLoopApi().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->GameLoopApi().LeaveParty(LeavePartyDelegate);
}


//Matchmaking functions

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);
}

// Player data functions

FString AMyPlayerController::GetDisplayName()
{
	UE_LOG(LogTemp, Display, TEXT("Your username: %s"), *Player->DisplayName());
	return Player->DisplayName();
}

TArray<FString> AMyPlayerController::GetPartyPlayerDisplayNames()
{
	const TArray<UPragmaPartyPlayer*> PartyPlayers =
		Player->GameLoopApi().GetParty()->GetPlayers();

	TArray<FString> DisplayNames;

	const FString& YourPlayerId = Player->Id();

	for (const UPragmaPartyPlayer* PartyPlayer : PartyPlayers)
	{
		FString DisplayName = PartyPlayer->GetDisplayName().DisplayName;
		FString PlayerId = PartyPlayer->GetPlayerId();

		if (PlayerId == YourPlayerId)
		{
			DisplayName += " (You)";
		}

		if (PartyPlayer->IsLeader())
		{
			DisplayName += " (Leader)";
		}

		if (PartyPlayer->IsReady())
		{
			DisplayName += " (Ready)";
		}

		UE_LOG(LogTemp, Display, TEXT("Party player: %s"), *DisplayName);
		
		DisplayNames.Add(DisplayName);
	}
		
	return DisplayNames;
}

FString AMyPlayerController::GetPlayerId()
{
	UE_LOG(LogTemp, Display, TEXT("Your id: %s"), *Player->Id());
	return Player->Id();
}

//Handler functions

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

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

void AMyPlayerController::HandlePartyUpdate(const UPragmaParty* Party)
{
	UE_LOG(LogTemp, Display, TEXT("Party state updated."));
}

void AMyPlayerController::HandleEnteredMatchmaking()
{
	UE_LOG(LogTemp, Display, TEXT("You are in matchmaking"));
}

void AMyPlayerController::HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext)
{
	UE_LOG(LogTemp, Display, TEXT("Game instance ID: %s"), *GameInstanceId );
}

Set Up Matchmaking with Pragma Engine
Unreal: Parties