Skip to main content

Customization

There are two levers to customize the self-hosted matchmaker:

  1. gameMode parameters
  2. ticket parameters

Both of these don't have to be set in the container, but are passed with each request. This means you can use on container dynamically for any number of configurations.

gameMode parameters​

The gameMode object in the API request payload defines the general behavior of the matchmaker. The core parameters are shared between the community and advanced tier. Others are custom to the advanced tier matchmaker.

Core parameters​

numTeams and numPlayersPerTeam​

The most essential and only non-optional parameters for the gameMode are numTeams and numPlayersPerTeam. These define what kind of matchs the matchmaker will create.

Here are some examples how you can use them to create different types of game modes:

Game mode typeGame modenumTeamsnumPlayersPerTeam
PvP1v111
PvP3v333
Coop2-coop12
Coop8-coop18
free-for-all (FFA)16-ffa161
maxWaitingTime​

maxWaitingTime sets the longest duration a player waits before matchmaking. When a ticket’s waiting time exceeds this limit, the matchmaker creates the best possible match with available compatible tickets. This means that the average wait for players will be lower than the maxWaitingTime - unless there is simply not enough players to make matches. Set maxWaitingTime to reflect the longest acceptable wait for your players.

tip

If a request only includes tickets whose joinTimestamp is not older than the maxWaitingTime no matches will be created.

If the maxWaitingTime parameter is not provided or set to 0, the matchmaker will try to create matches for all available tickets independent of their joinTimestamp.

Parameters for advanced matchmaker​

targetWaitingTime​

targetWaitingTime avoids prolonged waits and poor match quality often caused by traditional methods (e.g., expanding radius search). Idem's advanced matchmaking uses a probabilistic model to dynamically balance wait times against match quality. For example, during peak hours, players quickly match with similarly rated opponents; during off-peak times, it intelligently matches players despite wider skill gaps to minimize wait times.

Choose lower targetWaitingTime values for fast-paced, short-session mobile games (where quick matchmaking is crucial), and higher values for PC/console games where players are ok to potentially wait longer for better match quality.

ticket parameters​

Each ticket object in the API described the matchmaking requirements for one player.

Similar to the gameMode, there are core parameters that apply to both tiers and additional parameters for the advanced tier.

Core parameters​

ticketId​

This the identifier for the ticket. It has to be unique within one API call. The maximum allowed length is 50 characters.

partyId​

The identifier for the party the ticket is part of. The maximum allowed length is 50 characters.

joinTimestamp​

This is the time the ticket was created, i.e. added to your matchmaking queue. This must be a unix timestamp.

rating​

This is a numeric value that allows comparing players to each others for assessing "soft" compatibility.

In most cases, rating is a representaiton of skill, like TrueSkill or ELO. But we have seen other values being used, like trophy count, games played, or even difficulty selected (for coop games). You can use anything as long as it is a numeric value.

The allowed range is 0 to 10,000 (ten thousand).

note

If your game does not require matching players by rating, you can simply pass the same value for all players.

servers​

This is a list of servers, provided as strings, that would be acceptable for a match. The matchmaker will only match tickets that have at least one overlapping server. If there is multiple options for the server in a match, the matchmaker will pick a random one.

Example:

{
  ...,
  "servers": ["eu-central-1", "us-west-1"],
  ...
}
note

If your game does not require considering servers, you can simply pass the same value for all players.

Parameters for advanced matchmaker​

servers with latency​

In addition to mere server compatibility, the advanced matchmaker can also optimize server latency. This means it will consider the latency of each ticket to the different servers in order to create matches with servers that have the optimal latency for each ticket. To be able to do this, a server-latency-map has to be provided for each ticket instead of just a server list.

{
  "servers": {
    "eu-central-1": 76,
    "eu-west": 31,
    "us-east": 176
  }
}
note

In one request, all tickets must have either a server list or a server-latency-map.