Getting Started

This guide is a step by step process on how to get started with using Kronos in your project from initial project configuration to having basic matchmaking functionality working. For more in-depth examples take a look at the Example Content shipped with the plugin, or the Sample Project that is available for download.

Project Configuration

Before we can dive into the plugin, we need to configure an Online Subsystem for the project. Kronos relies on this for its matchmaking functionality, and to communicate with online platforms such as Steam or EOS.

If you haven't already, please follow the steps outlined in the Configuration section of the documentation and configure the project to use the Null Online Subsystem.

Let's start by creating the user interface for the main menu. Create a simple UserWidget blueprint and add two Buttons to it. One for creating a match, and one for starting matchmaking.

We will add the widget to the screen in just a minute.

2. Authenticating Users

Before we can do any sort of matchmaking, we need to login with the Online Subsystem first. Kronos features an automated user authentication process, so we do not need to do anything. Authentication will start automatically when the "Game Default Map" - set in your Project Settings - is opened.

When authentication is complete, the OnEnterGame event of the KronosOnlineSession will be called. Think about this as passing the "login screen" of the game. We are going to override this event to show our main menu widget.

3. Overriding the On Enter Game Event

First, create a new blueprint from the KronosOnlineSession class.

Open the blueprint, and add the OnEnterGame event to the graph. Here we are going to add our main menu widget to the screen. The reason we are doing it here (and not in BeginPlay for example) is because authentication has its own widget - like a "login screen".

Now that we have our custom online session class, we need to configure the plugin to use it. To do this, go to Edit -> Project Settings -> Kronos Matchmaking and set the online session class to the custom blueprint that we have created. Also, make sure that "Authenticate User Automatically" is enabled.

Creating Matches

1. Using the Create Match Node

To create a match simply use the CreateKronosMatch node. I'm going to hook this up with the OnClicked event of my create match button. To make the required host parameters simply drag off of the "Host Params" property and search for "make".

Let's go over some of the parameters that we need to setup.

2. Setting the Starting Level Param

The most important parameter for us right now is the "Starting Level". This will be the map that is opened in listen-server mode when the session is created. For now I'm just going to use the KronosExampleLobby map that is provided with the plugin, but you can use any map here. It doesn't have to be a lobby map either. The map name can be given in the following forms (without the quotes):

Short package name: "KronosExampleLobby"
Long package name: "/Kronos/Examples/Maps/KronosExampleLobby" (recommended)

3. Setting the Playlist Params

The "Playlist", "Map Name", and "Game Mode" params are purely cosmetic information used for session filtering. These are the parameters that the matchmaking system will match when searching for sessions to join. They can be left empty if not needed for the project. As an example I'm going to set my playlist params to the following (without the quotes):

Playlist: "PVP"
Map Name: "Hangar"
Game Mode: "Deathmatch"

Again, these are purely cosmetic information on the session. They do not alter gameplay, or the game mode class that is used by the "Starting Level" in any way.

After the match is created the player will join the game automatically. We do not need to do anything else.

Starting Matchmaking

1. Using the Start Matchmaking Node

Matchmaking can be started via the StartKronosMatchmaking node. I'm going to hook this up with the OnClicked event of my matchmaking button. To make the required matchmaking parameters simply drag off of the "Matchmaking Params" property and search for "make". I'm also going to do the same for the "Host Params".

2. Setting the Host Params

The "Host Params" is going to be used if the matchmaking results in creating a new session. It is the same set of parameters that you use to create matches with. I'm going to use the same parameters that I used at the create match section above.

3. Setting the Min Slots Required Param

The "Min Slots Required" param tells the matchmaking system to ignore sessions that do not have at least X amount of open slots. We can use the GetPartySize node to easily determine how many slots we need. This node returns the number of players in the party, or 1 if the player is not in a party. By using this we basically avoid sessions that we would not fit.

4. Setting the Playlist Params

The "Playlist", "Map Name", and "Game Mode" params are purely cosmetic information used for session filtering. When these parameters are given for the matchmaking, sessions have to match their corresponding params to be considered for joining. If left empty, all sessions will be considered as valid. As an example I'm going to set my playlist params to the following (without the quotes):

Playlist: "PVP"
Map Name: -
Game Mode: "Deathmatch"

I have intentionally left the "Map Name" empty so that it is not considered. I just want to find a "Deathmatch" game, I do not care which map it is currently being played on.

After matchmaking is complete the player will join the game automatically. We do not need to do anything else.

Displaying Matchmaking State

At this point we should be able to create matches, and other players should be able to find them via matchmaking! There is only one thing missing, which is displaying the matchmaking state to the user.

First, create a new blueprint from the KronosMatchmakingStateWidget class. This is a custom UserWidget class that has a few convenient events such as "OnMatchmakingStarted", "OnMatchmakingUpdated", etc. For more information about the different widgets available, please refer to the Widgets section of the documentation.

You can skip this part by simply using the example matchmaking state widget found in the Example Content of the plugin.

I'm going to add Vertical Box to the widget first. Then I'm going to add a Text that will display the current matchmaking state, and a Button for canceling matchmaking. You can play around with the alignment and padding of the different elements to make it look how you want.

Now that we have the widget setup, we can implement its functionality.

2. Updating the Matchmaking State Text

Add the OnMatchmakingUpdated event to the graph. When matchmaking is updated we are going to change our text based on the current matchmaking state.

I think it would also make sense if the widget itself was only visible while matchmaking, so we are going to have our widget hidden by default and then update its visibility each time the matchmaking state changes.

3. Canceling Matchmaking

To cancel matchmaking simply use the CancelKronosMatchmaking node. I'm going to hook this up with the OnClicked event of my cancel matchmaking button. This will cancel the currently active matchmaking process if there is any, and also handle any cleanups necessary such as canceling pending reservations or destroying pending sessions.

Now that we have the matchmaking state widget done, I'm simply going to add it to my main menu widget and enable "Size To Content". This way we do not need to manually add it to the screen. They will both get created at the same time.

Now if you start matchmaking the widget should pop up automatically, displaying the current state of matchmaking.

Testing Matchmaking In Editor

At this point we should be able to create matches, and other players should be able to find them via matchmaking! Lets test if everything is working correctly in the editor by starting two players.

There are some limitations and caveats to what can be tested in the editor and how. Please refer to the Testing In Editor section for more details, but in short we have to:

Configure the project to use the Null Online Subsystem.
Set play mode to Standalone Game.
Set number of players to 2.
Disable Run Under One Process in advanced play settings.

I'm also going to enable logging so that we can see what is going on behind the scenes. To enable logging go to Editor Preferences -> Play and add the -LOG to the "Additional Launch Parameters" field. This is also going to be very useful if something is not working correctly because we will see exactly what the error messages are.

For more information about logging please refer to the Debugging section of the documentation.

Now if you press play in the editor, you should see two player windows pop up. To confirm that everything is working correctly, try creating a match with one of the players and matchmaking with the other.