Skip to content

SDK Guide - Matchmaking

You can grab our SDK from our public GitHub:


In this article, we'll guide you through the step-by-step explanation of how to implement our Matchmaking feature to your game.


Before progressing into this guide, you will need to complete the guide below :

Matchmaking Game Mode Configuration

Create Matchmaking Game Mode

To create matchmaking game mode you need to go to the link below (please contact us for the credentials) :

The Figure 1 below is the admin portal dashboard showing the daily active users on a specific game over time.

Matchmaking & Lobby Statistics
Figure 1. Admin Portal Dashboard

To create the matchmaking game mode for a specific namespace of yours, select the game namespace in the Admin Portal and go to Matchmaking tab under Game Management section.

How to Configure Game Matchmaking Rules
Figure 2. Matchmaking menu

The Matchmaking menu shows the list of game modes of the specific game namespace. Click Add Configuration button to create a new game mode.

How to Set Game Lobby & Matchmaking
Figure 3a. Creating a new game mode

Fill out the game mode info by following the instructions. Form details:

  • Game Mode. The name of the game mode. The allowed characters are lowercase alphabet and number (max 64 characters).
    E.g.: solo, 2vs2, etc.
  • Namespace. The namespace of your game.
  • Find Match Time Out (sec). The allowed period of time for a matchmaking request to stay in the queue. Fill "0" (zero) in the textfield to add no time limit.
  • Description. The description of the game mode.

Rule Set. In this section, you can set the Alliance Number and Player Number for each match.

  • Alliance Number. Alliance number is the number of sides opposing each other in a game. E.g. in a typical battle royale game, there are 25-100 opposing sides in total, and in a typical MOBA game, there are 2 opposing sides in total. Configure the number of opposing sides in your game by adding the max and min alliance number rule.
  • Player Number. You can configure the number of players in each joining party (in an alliance) here. The rule needs at least one player to be in a party to start a match. E.g. in a player-vs-player match, we can assign one player for each party and match the parties consisting of 1 player each. In a party vs party scenario, we can also set multiple players in a party and match the parties to oppose each others.
Creating A Game Matchmaking System
Figure 3b. Game mode creation fields are filled out
Adding Rules to Game Matchmaking Configuration
Figure 3c. Matchmaking game mode details

After Add button is clicked, the matchmaking game mode details page is shown and you can edit the info. The basic section consists of information that's provided when you fill out the previous form. The two other sections are explained below.

Matching Rules. You can add a matching rule by clicking the Add Rule button. In the Add Matching Rule window, you can set up the variables for:

  • Attribute. Input player attribute for the matching rule. E.g. mmr (Matchmaking Rating).
  • Criteria. Criteria is how the specified attribute fits the rule. Currently, the only supported criteria is Distance. Matchmaking will match player attributes based on the specified value distance.
  • Reference. Reference is the value of the criteria. E.g, for a distance criteria of 1000, the matchmaking service will match players with attributes value within 1000 points distance.

When you finish with the variables, click the save button to save your configuration.

Set Rules for Your Game Matchmaking & Lobby
Figure 3d. Adding Matching Rule

One more rule you can set is the Flexing Rules.

Flexing Rules. Flexing rules option is used when the the specified matching rules cannot match players within the specified duration. You can add the flexing rule by clicking the Add Flexing Rule button. In the Add Flexing Rule window, you can set up these variables:

  • Attribute. You need to specify the same attribute you want to flex as the matching rule. E.g. mmr (Matchmaking Rating).
  • Criteria. Criteria is how the specified attribute fits the rule. Same as the matching rule, currently we only support distance criteria. Matchmaking will match player attributes based on the specified value distance.
  • Reference. Reference is the value of the criteria. The reference for flexing rule should be higher than the matching rule since it is to broaden the search range for matchmaking. E.g. if you set the distance value to 1000, the flexing rule value can be 2000, so that it can reach more players to match.
  • Duration (sec). The time specified for the flexing rule to take effect.

When you're finished, click the save button to save your configuration.

Flexing Rules for Game Matchmaking
Figure 3e. Add the Flexing Rule

Once you're done with the config, you can start implementing the matchmaking feature into the game.


Start Matchmaking

To enable the Matchmaking Service implementation, the configurations from the previous section of this guide need to be done, especially the Matchmaking Game Mode.

In this part of the guide, the example scenario of implementation is that after a player creates a party, either the player wants to go matchmaking by himself or have other players to join the party, the matchmaking can be started right away. The StartMatchmaking lobby is called and initiates the matchmaking process.

Enabling Your Own Machmaking & Lobby System
Figure 4a. StartMatchmaking action preview
Creating Game Matchmaking & Lobby
Figure 4b. FindMatchButtonClicked function
Enabling Game Matchmaking & Lobby
Figure 4c. Callback to create a party when the local player is not yet in a party
Enabling Your Own Game Matchmaking & Lobby
Figure 4d. Callback to FindMatch function

After the Find Match button is clicked and we receive a callback, the matchmaking board that contains matchmaking info will be shown.

Matchmaking Completed

Matchmaking Completed is an event where the match that the player's looking for is found. It carries MatchmakingNotif that has match status {“start”, “cancel”, “done”} and MatchId.

Enable Party & Invitation System to Your Game
Figure 5a. Registering a callback to MatchmakingCompleted in AccelByte Lobby Services
Matchmaking & Lobby - Add Party System to Your Game
Figure 5b. Unregistering a callback to MatchmakingCompleted in AccelByte Lobby Service
Adding Matchmaking & Lobby System to Your Game
Figure 5c. Matchmaking Complete callback on "done", "start", and "cancel"

When the party leader starts the matchmaking, all of the party members will be getting match "start" status. Match "cancel" indicates that the party leader cancels the matchmaking using the Cancel Search button on the example matchmaking board. Last, but not least, match "done" status is sent to the players when all the match requirements are filled.

Ready for Match Confirmation

Ready for Match Confirmation is a feature that lets the players choose whether they want to join the match. In this sample game, we enable the auto-accept right after a matchmaking completes with MatchmakingNotif callback status returns “done” as in figure 5c shown above.

Adding Matchmaking Consent to Your Game
Figure 6. Matchmaking Ready-for-Match Confirmation callback

Ready for Match Confirmed

Ready for Match Confirmed is an event you need to register to if you'd like to track the info on which players have confirmed Ready-for-Match function.

Adding Ready-to-Match to Your Game's Matchmaking & Lobby System
Figure 7a. Registering Ready-for-Match from AccelByte Lobby service
Adding Ready-to-Match Consent to Your Game's Matchmaking & Lobby System
Figure 7b. Unregistering Ready-for-Match from AccelByte Lobby service
Enabling Ready-to-Match Callback on Your Game's Matchmaking
Figure 7c. Callback for Ready-for-Match Confirmation

Cancel Matchmaking

A player can cancel matchmaking by clicking the Cancel Search button from the sample board. CancelMatchmaking command is stackable on the backend, therefore, make sure to only call it once when the matchmaking (StartMatchmaking) is started. If the cancel button (that calls CancelMatchmaking) is clicked twice, the second click negates the next StartMatchmaking command.

Add 'Cancel Matchmaking' to Your Game System
Figure 8a. CancelMatchmaking action preview
Cancel Game Matchmaking Function
Figure 8b. CancelMatchmaking function
Callback to Cancel Matchmaking on Your Game
Figure 8c. Matchmaking-Canceled callback

The matchmaking cancelation also sends Matchmaking Completed event to all the members of the party. The MatchmakingNotif status value will be “cancel” as shown in Figure 5c.

DS Updates

Once the matchmaking is done, all the matched players get updates from Distributed Server (DS). The first status is "CREATING" which marks that the DS is still on the creation process. When the DS is ready, the second callback is launched and the status changes from "CREATING" to "READY". Along with the status, DsNotif also comes with IP and Port that is needed by the game client to connect to the DS.

Game Matchmaking With Dedicated Servers Manager
Figure 9a. DSUpdated action preview

Register the callback to the DSUpdated event for your matchmaking board. On callback, you need to connect the player to the DS using the IP and Port that are received from the DsNotif.

Combining Game Matchmaking and Dedicated Servers
Figure 9b. Registering DSUpdated event
Dedicated Servers for Game Matchmaking & Lobby
Figure 9c. Unregistering DSUpdated event
Adding Callback to Dedicated Servers on Your Game's Matchmaking System
Figure 9d. Callback to DSUpdated "CREATING" and "READY" status

That just about covers it for our Matchmaking feature. While this guide highlights what's available in our feature set, it is important to note that we can help you customize it to match your exact needs, should you need small changes or a completely bespoke feature.

No two games are the same and we believe that each of our clients are unique, thus our tailored services might be a your solution to your needs.

Please reach out to us at should you have any questions or need a further guidance regarding this SDK guide.

Find a Backend Solution for Your Game!

Reach out to the AccelByte team to learn more.