# 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**](../examples/example-content) shipped with the plugin, or the [**Sample Project**](../examples/sample-project) that is available for download.

## Project Configuration

Before we can dive into the plugin, we need to configure an [**Online Subsystem**](https://dev.epicgames.com/documentation/en-us/unreal-engine/online-subsystem-in-unreal-engine) 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**](../configuration) section of the documentation and configure the project to use the **Null Online Subsystem**.

## Setting Up The Main Menu

### 1. Creating The Menu Widget

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FR5EMuMoFS0OC26FHHNuv%2FGettingStarted_MainMenuWidget.jpg?alt=media&#x26;token=e98f63be-c3a6-46b2-877d-08ec49c58e0d" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FYH1RDosXtuOtVRPYZob6%2FGettingStarted_GameDefaultMap.jpg?alt=media&#x26;token=838f990e-2e10-4a65-9363-e3c25eb7b47b" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FURW33qiAv3AGJRoHHwns%2FCreateKronosOnlineSession.jpg?alt=media&#x26;token=9ad83d05-9a4b-4446-91b5-a5437b002008" alt=""><figcaption></figcaption></figure>

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".

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FHAeHXtC1p84N6AOO2Lfo%2FGettingStarted_OnEnterGame.jpg?alt=media&#x26;token=732b807b-d72d-42b9-9cd4-fef9af0c8834" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FaK1frhFHtJu6zmc1f4HW%2FGettingStarted_OverrideOnlineSession.jpg?alt=media&#x26;token=de36ccab-c32b-4372-9aa2-5a46fefa221e" alt=""><figcaption></figcaption></figure>

## 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".

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FXKm4LBHC1Dn2X4bTuEyh%2FGettingStarted_CreateMatch.jpg?alt=media&#x26;token=4c805ae1-567f-4dcb-8a4b-519af889c1cc" alt=""><figcaption></figcaption></figure>

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**](../examples/example-content) 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)

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FSg3d8xHe5WacDMzodwFM%2FGettingStarted_FindMapPath.jpg?alt=media&#x26;token=86d4964c-50ba-450f-bf82-f1e95028580c" alt=""><figcaption></figcaption></figure>

### 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.

{% hint style="success" %}
After the match is created the player will join the game automatically. We do not need to do anything else.
{% endhint %}

## 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".

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FOfyIft7AcumQzplGdT1L%2FGettingStarted_StartMatchmaking.jpg?alt=media&#x26;token=828d9284-6570-4edb-b73e-e078b4b77150" alt=""><figcaption></figcaption></figure>

### 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.

{% hint style="success" %}
After matchmaking is complete the player will join the game automatically. We do not need to do anything else.
{% endhint %}

## 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.

### 1. Creating the Matchmaking State Widget

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**](widgets) section of the documentation.

{% hint style="info" %}
You can skip this part by simply using the example matchmaking state widget found in the [**Example Content**](../examples/example-content) of the plugin.
{% endhint %}

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FKx8BwAiUe7iZKizysomx%2FGettingStarted_CreateMatchmakingStateWidget.jpg?alt=media&#x26;token=90eb79b2-b252-4de8-881b-7d27c793f46b" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2Fj0bWpUosbxo87E9rvW8B%2FGettingStarted_MatchmakingStateWidget.jpg?alt=media&#x26;token=a35a7cbf-f55e-47e6-938c-39a829d72697" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FvMz120smHUAW9Y08S3pz%2FGettingStarted_UpdateMatchmakingStateText.jpg?alt=media&#x26;token=e8aab25b-00d4-4931-ba3a-23ee9e48ed76" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FGLrfZMh9VmVFQJIxxIBe%2FGettingStarted_CancelMatchmaking.jpg?alt=media&#x26;token=fd1c3331-5a00-49f0-a30c-f799435a33f8" alt=""><figcaption></figcaption></figure>

### 4. Adding the Widget To The Screen

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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2F3KqcSAL06xcovyzkBNr7%2FGettingStarted_AddMatchmakingStateToMenu.jpg?alt=media&#x26;token=bc0ba665-080e-4520-87fe-1cbb52363775" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Now if you start matchmaking the widget should pop up automatically, displaying the current state of matchmaking.
{% endhint %}

## 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**](../../testing-and-debugging#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.

<figure><img src="https://3833329260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfIkwZ5xO6YLccFyQBEgv%2Fuploads%2FCZuSAqHnPswv8xWNaZg1%2FLogsWindow.jpg?alt=media&#x26;token=4ba7f712-71a0-411f-a09d-9e504d9f9a7f" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For more information about logging please refer to the [**Debugging**](../../testing-and-debugging#debugging) section of the documentation.
{% endhint %}

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.

## Where To Go From Here?

Since we have just covered matchmaking and also touched on user authentication briefly, I recommend one of the following topics:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:orange;"><strong>Lobby</strong></mark></td><td>Learn more about how to setup your own lobby map!</td><td></td><td><a href="lobby/lobby-setup">lobby-setup</a></td></tr><tr><td><mark style="color:orange;"><strong>Party</strong></mark></td><td>Learn more about how to create parties so that players can join games together!</td><td></td><td><a href="party">party</a></td></tr></tbody></table>
