First-match matchmaking

How did we do?

You can use HiveMP Lobbies to implement basic "first-match" matchmaking, where players are paired up on a first-come, first-serve basis.

This type of matchmaking is suitable for basic multiplayer games with low player counts.

Check for existing lobbies

To initiate matchmaking, your game should first check to see if there are any game lobbies currently open:

curl -s \
  -H "X-API-Key: $apiKey" \
  -H "Accept: application/json" \
  -H "Content-Length: 0" \
  -X GET \
  "https://lobby-api.hivemp.com/v1/lobbies/paginated"\
"?limit=2"

After executing this method, you'll receive the first page of game lobbies:

{
  "moreResults": true,
  "next": "abcdef0123456789...",
  "results": [
    {
      "currentSessions": 0,
      "id": "lb-5682741632827392",
      "maxSessions": 4,
      "name": "Test Lobby",
      "ownerSessionId": "us-5722461490380800"
    },
    {
      "currentSessions": 0,
      "id": "lb-5682741632827393",
      "maxSessions": 4,
      "name": "Test Lobby 2",
      "ownerSessionId": "us-5722461490380800"
    }
  ]
}

If there's one or more available game lobbies, you should iterate through the list, and check:

  • If there is at least one current session (the owner of the lobby has joined), and
  • If the current sessions is less than the maximum sessions

For each game lobby that meets these requirements, try to join them one at a time until the first successful lobby join. If joining fails, move onto the next game lobby that's available.

Creating a game lobby if necessary

If there are no game lobbies available, or you've iterated through the entire list of available lobbies and were unable to join any of them, then create a new game lobby:

curl -s \
  -H "X-API-Key: $apiKey" \
  -H "Accept: application/json" \
  -H "Content-Length: 0" \
  -X PUT \
  "https://lobby-api.hivemp.com/v1/lobby"\
"?name=My+Game+Lobby"\
"&maxSessions=4"

After executing this method, you'll get a new game lobby that looks like this:

{
  "currentSessions": 0,
  "id": "lb-5752141660553216",
  "maxSessions": 4,
  "name": "My Game Lobby",
  "ownerSessionId": "us-5722461490380800"
}

Once you've created your own game lobby, you'll then need to join it:

curl -s \
  -H "X-API-Key: $apiKey" \
  -H "Accept: application/json" \
  -H "Content-Length: 0" \
  -X PUT \
  "https://lobby-api.hivemp.com/v1/session"

After executing this method, you'll receive a connected session object that looks like this:

{
  "lobbyId": "lb-5682741632827392",
  "sessionId": "us-5658312181809152"
}

Wait for players to fill the game lobby

Once you've joined a game lobby (whether someone else's or your own), you should wait until the lobby has been filled with players by polling the current game lobby status or session list.

In addition, you might want to coordinate the status of "is the game starting" and the host's address and port using HiveMP Attributes. Refer to Coordinating game settings on how to synchronise match-level settings.

Clean up game lobbies and connected sessions when done

Once the game has started and players have a direct connection to the host server, the owner should delete the game lobby. This prevents the game lobby from cluttering up the list of game lobbies when new clients are attempting to find a game lobby to join.

curl -s \
  -H "X-API-Key: $apiKey" \
  -H "Accept: application/json" \
  -H "Content-Length: 0" \
  -X DELETE \
  "https://lobby-api.hivemp.com/v1/lobby"

After executing this method, you'll receive the value of true:

true

Further reading