Matchmaking

In order to access online features, the player must be logged in with the Online Subsystem. Please visit the Logging In page for more information.

The Matchmaking Process

During matchmaking, we will be creating, finding, and joining sessions through the Online Subsystem. So what are sessions exactly?

A session is the representation of an online room that exists on the online service's backend (e.g. the Steam servers). There are two types of sessions: Game Sessions representing online lobbies or matches, and Party Sessions representing online parties.

In C++ these session types are referred to as SessionName.

When matchmaking is started sessions will be queried first. If at least one session was found, the joining process starts. If no sessions were found, the matchmaking will decide whether to start a new search, or whether it should switch over to hosting role - creating a new session.

The joining process consists of three steps. First we'll request a reservation for the session by establishing a lightweight connection with the session host, and asking him to reserve a spot for us in the session. This ensures that all party members will be able to join the session. Next we will attempt to join the session on the backend service (e.g. Steam servers) using the Online Subsystem. Once we've joined the session, we can connect to the session host. This is where the actual multiplayer stuff happens such as establishing the connection with the host, receiving the map to load, and spawning into the game.

Session creation is also part of the matchmaking process. It is pretty straight forward, first we'll create the session on the backend and then open a listen server for it.

Starting Matchmaking

Matchmaking can be started from any class, and the latest matchmaking request can always be accessed through the KronosMatchmakingManager.

As an example, lets say we want to play a game of Team Deathmatch on a random map. I'll be reacting to the OnClicked event of a button inside a UMG widget, but feel free to use whatever class makes sense for you like the GameInstance for example.

Once matchmaking is complete, the player will join the game automatically.

Blueprint

C++

#include "KronosMatchmakingManager.h"
#include "KronosPartyManager.h"
#include "KronosMatchmakingPolicy.h"

// Get the matchmaking manager.
UKronosMatchmakingManager* MatchmakingManager = UKronosMatchmakingManager::Get(this);

// Request a new matchmaking policy. This operation is async!
// If matchmaking is in-progress, it will be canceled first.
MatchmakingManager->CreateMatchmakingPolicy(FOnCreateMatchmakingPolicyComplete::CreateLambda([this](UKronosMatchmakingPolicy* MatchmakingPolicy)
{
    // Parameters to be used when matchmaking results in creating a session.
    FKronosHostParams HostParams;
    HostParams.StartingLevel = TEXT("MyMap");
    HostParams.Playlist = TEXT("TeamDeathmatch");
    HostParams.MaxNumPlayers = 4;
    HostParams.bShouldAdvertise = true;
    HostParams.bIsLanMatch = false;
    HostParams.bUsesPresence = true;
    
    // Parameters to be used for matchmaking.
    FKronosMatchmakingParams MatchmakingParams;
    MatchmakingParams.HostParams = HostParams;
    MatchmakingParams.Playlist = TEXT("TeamDeathmatch");
    MatchmakingParams.MaxSearchAttempts = 3;
    MatchmakingParams.MaxSearchResults = 20;
    MatchmakingParams.MinSlotsRequired = UKronosPartyManager::Get(this)->GetPartySize();
    MatchmakingParams.bIsLanQuery = false;
    MatchmakingParams.bSearchPresence = true;
    
    // Flags for matchmaking (e.g. use EKronosMatchmakingFlags::NoHost if you don't want matchmaking to result in hosting).
    uint8 MatchmakingFlags = static_cast<uint8>(EKronosMatchmakingFlags::None);
    
    // Start matchmaking.
    // Notice that we are using NAME_GameSession!
    MatchmakingPolicy->StartMatchmaking(NAME_GameSession, MatchmakingParams, MatchmakingFlags, EKronosMatchmakingMode::Default);
}));

Canceling Matchmaking

You can cancel the latest matchmaking request at any time using a simple function call. All cleanup processes are handled automatically, such as canceling pending reservations and destroying pending sessions.

Blueprint

C++

#include "KronosMatchmakingManager.h"
#include "KronosMatchmakingPolicy.h"

// Get the matchmaking manager.
UKronosMatchmakingManager* MatchmakingManager = UKronosMatchmakingManager::Get(this);

// Check if we are matchmaking.
if (MatchmakingManager->IsMatchmaking())
{
    // Get the current matchmaking policy.
    // This is accessible even after matchmaking is canceled.
    UKronosMatchmakingPolicy* MatchmakingPolicy = MatchmakingManager->GetMatchmakingPolicy();

    // Begin canceling matchmaking.
    MatchmakingPolicy->CancelMatchmaking();
}

Creating Matches

You can also create matches directly using a simple function call. In this case you only have to fill out the "HostParams". Other matchmaking params are irrelevant.

The "StartingLevel" is the map that will be opened in listen server mode by the host after the session has been created. Whether the match is public or private is dictated by the "ShouldAdvertise" param.

You can also create hidden matches by enabling both the "ShouldAdvertise" and "Hidden" params. Hidden sessions are especially useful when you want to create a private match but your Online Subsystem requires sessions to be advertised in order to be joinable by other players. Hidden sessions can only be found during specific session queries (e.g. following party to a specific session).

Blueprints

C++

#include "KronosMatchmakingManager.h"
#include "KronosMatchmakingPolicy.h"

// Get the matchmaking manager.
UKronosMatchmakingManager* MatchmakingManager = UKronosMatchmakingManager::Get(this);

// Request a new matchmaking policy. This operation is async!
// If matchmaking is in-progress, it will be canceled first.
MatchmakingManager->CreateMatchmakingPolicy(FOnCreateMatchmakingPolicyComplete::CreateLambda([this](UKronosMatchmakingPolicy* MatchmakingPolicy)
{
    // Parameters to be used when matchmaking results in creating a session.
    FKronosHostParams HostParams;
    HostParams.StartingLevel = TEXT("MyMap");
    HostParams.Playlist = TEXT("TeamDeathmatch");
    HostParams.MaxNumPlayers = 4;
    HostParams.bShouldAdvertise = true;
    HostParams.bHidden = false;
    HostParams.bIsLanMatch = false;
    HostParams.bUsesPresence = true;
    
    // Initialize matchmaking params from the host params.
    // Only the host params matter when starting matchmaking in CreateOnly mode.
    FKronosMatchmakingParams MatchmakingParams = FKronosMatchmakingParams(HostParams);
    
    // No matchmaking flags needed.
    uint8 MatchmakingFlags = static_cast<uint8>(EKronosMatchmakingFlags::None);
    
    // Tell the matchmaking that we only want to create a session.
    EKronosMatchmakingMode MatchmakingMode = EKronosMatchmakingMode::CreateOnly;
    
    // Start matchmaking.
    // Notice that we are using NAME_GameSession!
    MatchmakingPolicy->StartMatchmaking(NAME_GameSession, MatchmakingParams, MatchmakingFlags, MatchmakingMode);
}));

Using Skill Ratings

Matchmaking has skill rating checks built into it by default.

So how does it work? The basic idea is that the each session advertises the average skill rating of players in the given session. When searching for sessions, matchmaking will compare against those advertised skill ratings.

You are responsible for feeding up-to-date skill rating values about players and sessions alike for matchmaking to work properly.

When creating a session, a default skill rating value can be given to the session via the "Elo" param. After that point, the session's host is responsible for updating the advertised skill rating when players join/leave the session. You can do this via the UpdateSession function.

When matchmaking, you can set the base skill rating to search for and a range around it. These are the "Elo" and "EloRange" params respectively. Matchmaking can make multiple attempts to find a session in the given skill range. This is dictated by the "EloSearchAttempts" param. If no sessions are found then the base skill rating will be increased by "EloSearchStep" amount.

There are two possible situations when creating a session or starting matchmaking: The player is either solo or in a party. If the player is solo, the "Elo" should be the player's skill rating. If the player is in a party, the "Elo" should be the average skill rating of party members.

You can use the GetPartyEloAverage helper function, however this only works if the player is in a party, and player skill ratings were set beforehand for each party member. For more information please refer to the Party Player Skill Rating section of the documentation.

Session Settings

When creating a session, the "ExtraSessionSettings" param allows you to add custom session settings to the session.

Session settings are simple key-value pairs. They can be advertised through the Online Subsystem, in which case players can read them once they have access to the session (e.g. player is in the session, or it was found after a search). Session settings can be used to filter out sessions by using Query Settings to compare against them.

Session settings can be updated on existing sessions. For more information please refer to the Updating Lobby Data section of the documentation.

Query Settings

When matchmaking, the "ExtraQuerySettings" param allows you to set custom query settings that will be used during session searches. These are filters that you can use to find sessions that suite your needs.

IMPORTANT: Different Online Subsystems may not support all types of query settings. The Steam Online Subsystem for example doesn't support bool settings.

It is important to note that Kronos has a two layer session filtering process. First, sessions will be queried by the Online Subsystem using the given settings. Once sessions are found, they will be filtered again by the plugin itself.

Query settings registered with the "ExtraQuerySettings" param are used for filtering at both layers automatically. However, if you are not registering query settings through the "ExtraQuerySettings" param for some reason then you have to override the FilterSearchResult function of the KronosMatchmakingSearchPass in C++ and handle your query settings manually.