Setting Up Matchmaking

Matchmaking puts players together and starts a server for their match. You set the rules once, in a queue. Your game does the rest through lobbies.

Before you start

A build with status ready.
The Pro plan. Queues, lobbies and matchmaking are Pro only. See Plan Limits.

How it works

A player creates a lobby from your game. Friends join it.
The lobby’s host (the player who created it) enters the queue.
Simpl looks for other lobbies in the same queue that fit your rules.
When there are enough players, Simpl starts a server and tells every player where to connect.

1. Create a queue

In the dashboard: open the Queues tab, click Create queue, fill in the form, and click Create queue again to save it. With the API, using your server key:

curl -X POST https://api.simpl.gg/v1/queues \
  -H "api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "queue_id": "duel",
    "name": "Duel",
    "timeout": 120,
    "max_players": 2,
    "server_settings": {
      "version_tag": "0.1.0",
      "region": "iad",
      "tier": "1x-1g"
    },
    "matchmaking": {}
  }'

These fields are required:

Field	What it is
`queue_id`	Your own ID for the queue. 1 to 64 characters: lowercase letters, digits and underscores.
`name`	A name people can read.
`timeout`	A whole number of seconds, 1 or more. To limit how long matchmaking searches, use `matchmaking.timeout` (below).
`max_players`	Players in one match.
`server_settings`	The server to start: `version_tag` (your build’s name), `region` and `tier`.
`matchmaking`	Your rules. `{}` means no rules: the first lobbies to fill `max_players` play together.

Optional: host_leave_behavior says what happens when the host leaves a lobby. "promote" (the default) makes another player the host. "delete" closes the lobby.

2. Add rules (optional)

Rules go in matchmaking. They read the player state: a small set of values each player sends when they join a lobby, such as a skill rating.

{
  "matchmaking": {
    "timeout": 120,
    "rules": [
      { "type": "difference", "field": "mmr", "max_difference": 200 },
      { "type": "equals", "field": "mode" },
      { "type": "region", "min_overlap": 1 }
    ]
  }
}

Rule	What it does	Needs
`difference`	Players’ numbers must be close. Here, skill ratings (`mmr`) at most 200 apart.	`field`, `max_difference`
`equals`	Players must have the same value, such as the same game mode.	`field`
`region`	Players must share at least `min_overlap` regions from their `regions` list. A player with no list counts the lobby’s region.	`min_overlap`

matchmaking.timeout is how many seconds Simpl searches before giving up. The lobby then goes back to waiting.

Teams and roles

For a game like 1 hunter against 4 survivors, list how many of each role each team needs. The match size is then the total, 5 here.

{
  "matchmaking": {
    "team_composition": {
      "hunter": { "hunter": 1 },
      "survivors": { "survivor": 4 }
    }
  }
}

Each player says which role they want with role in their state. A player with no role can fill any spot.

3. Send player state

Players send their state when they create or join a lobby:

{
  "state": {
    "mmr": 1450,
    "mode": "ranked",
    "regions": ["iad", "ewr"],
    "role": "survivor"
  }
}

4. Find a match from your game

Your game calls these with the client key (ck_live_...) in the api-key header, and the player’s ID in the x-player-id header. The player ID is your own ID for that player.

Create a lobby: POST /v1/lobbies with name, region, your queue_id and the player’s state.
Other players join by the lobby’s ID or its invite code.
The host enters the queue: POST /v1/lobbies/{lobby_id}/queue.
Wait for the server. Simpl sends a server_ready event when the server is up, with its network_ports. Players connect to host:external_port of the port named game. You can also read the lobby (GET /v1/lobbies/{lobby_id}) every few seconds until its server has status running.

See the API reference for every lobby call.

Getting Started

Build Your Server

Run Your Server

Players

Unreal SDK

Platform

Setting Up Matchmaking

Before you start

How it works

1. Create a queue

2. Add rules (optional)

Teams and roles

3. Send player state

4. Find a match from your game

​Before you start

​How it works

​1. Create a queue

​2. Add rules (optional)

​Teams and roles

​3. Send player state

​4. Find a match from your game

Before you start

How it works

1. Create a queue

2. Add rules (optional)

Teams and roles

3. Send player state

4. Find a match from your game