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.
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:
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 enter matchmaking service call #
Goal #
Implement a EnterMatchmaking
function that allows players in a party to enter matchmaking.
Steps #
Declare the
EnterMatchmaking()
function in thepublic
section of yourMyPlayerController.h
file:UFUNCTION(Exec, BlueprintCallable, meta=(Category="Pragma")) void EnterMatchmaking();
Define
EnterMatchmaking()
in yourMyPlayerController.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’sisReady
value is automatically set totrue
when they make a character selection. See Make character selections.
Test #
To test this functionality using the Unreal in-game console:
Open two clients and log in as
test01
andtest02
.As
test01
, create a party and set the game mode toCasual
.As
test02
, create a party and set the game mode toCasual
.As
test01
, callEnterMatchmaking()
As
test02
, callEnterMatchmaking()
To apply this functionality using Unreal Blueprints:
Create a “Enter matchmaking” button that calls your
EnterMatchmaking()
function.As
test01
in a party with aCasual
game mode, click “Enter matchmaking”.As
test02
in a different party with aCasual
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 game instance handler #
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 succeeded.
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 HandleOnAddedToGame()
function simply print an Unreal log entry.
Steps #
Declare the
HandleOnAddedToGame()
function in yourMyPlayerController.h
file underprivate
:void HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext);
Define
HandleOnAddedToGame()
in yourMyPlayerController.cpp
file:void AMyPlayerController::HandleOnAddedToGame(const FString GameInstanceId, const FPragma_GameInstance_ExtAddedToGame Ext) { UE_LOG(LogTemp, Display, TEXT("Game instance ID: %s"), *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.Register the
HandleOnAddedToGame()
functions with the appropriate event handler. InMyPlayerController.cpp
, add the following lines to theBeginPlay()
function:Player->GameLoopApi().OnAddedToGame.AddUObject( this, &AMyPlayerController::HandleOnAddedToGame);
Test #
To test this functionality using the Unreal in-game console:
As
test01
in a ready party, call yourEnterMatchmaking()
function.As
test02
in a ready party, call yourEnterMatchmaking()
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.
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.