Skip to main content

Setting up Player-based

There are two different architecture types to integrate Idem into you game. For details see Architecture.

In the Player-based architecture, each player, or more correctly your game client running on the player's machine, connects to Idem to submit itself to matchmaking. Once a match is found, Idem will spin up a game server on your behalf for the players to play on. For this setup, Idem partners with multiple hosting providers. For a full list of currently supportd hosting providers see Hosting providers. (If you don't find the hosting provider of your choice on that list, reach out to support@idem.gg. We are continously growing our partner network and that specific provider might alreay be part of it soon.)

The default flow for a player-based setup looks like this:

Player-based architecture default flow

Player-based architecture default flow

note

The player-based architecture only works with WebSocket. It does not support REST calls

🄰 Setup your game-server​

Go to your hosting provider and set up the code for your game-server. Idem will be calling it through the respective API to launch an instance of your game-server, as soon as a match is found. Specific details on integrating each hosting-provider, including examples, can be found here.

🄱 Select Player-based configuration​

Got to the Idem Console. Under the tab Integration pick player-based and select the hosting provider of your choice and enter the respective data needed to launch the game-server.

You can find details about the parameters and responses for each integration provider on the related pages:

🄲 Retrieve Join-Code​

In the Idem Console, under the matchmaker tab, you will be shown a JOIN_CODE (only shows if step 2 is completed). You will need this code to open a WebSocket connection from your game-clients to Idem to submit them for matchmaking.

🄳 Integrate into your game client​

Each player's game-client will need to establish a websocket to Idem's API (using the JOIN_CODE obtained in 🄲) and then submit themselves to matchmaking via the WebSocket. Once a match suggestion is found for them, Idem will host a server on your behalf at the hosting provider you set up and then send the connection details to the player via the same WebSocket connection.

The following steps describe what the game-client needs to do step-by-step.

1. Open WebSocket connection​

First, the game-client needs to open a WebSocket connection to Idem using the following URI:

uri = WEBSOCKET_API_URL/?playerId=PLAYER_ID&code=JOINCODE&authorization=PLAYER_AUTH

WEBSOCKET_API_URL​

URL to connect to. Initially, simply take wss://ws.beta.idem.gg. Later you can change this environment, as you take the game from testing to production. See WebSocket for more.

PLAYER_ID​

Identifier for the player. If you are planning to use one of our player authorization integrations, refer to the Player authorization documentation to find out which identifier to use. If you don't want to use player authorization, this can be any value as long as it is unique for each player.

JOIN_CODE​

Code retrieved in step (c). This code allows Idem to associate your game-client's request with your game. It functions as a basic level of shared authorization. See PLAYER_AUTH below for more details.

PLAYER_AUTH​

Initially, use the value Demo. This skips any further authorization. Once you have made yourself familiar with the general setup, we recommend to integrate one of the third-party authorization providers (e.g. Steam or Firebase) to authenticate players using your game client.

2. Submit the player to the matchmaking queue​

Once the WebSocket connection is established, the game-client can enqueue the player via the addPlayerAction. Idem will respond to this with an addPlayerResponse, confirming that the player is now considered by the matchmaking. You can use this information to update the UI to inform the user that the system is now looking for a match for them.

3. Wait for matchFound and inform the player about it​

Once a match if found for the player, Idem sends a matchFound message to the game client via the WebSocket. This means a match was found and Idem is now requesting the game server to be hosted by the hosting provider you configured in 🄱.

Message example​

{
    "action": "matchFound",
    "payload": {
        "gameId": "1v1",
        "matchUuid": "9e6697cd-2271-41bf-9f10-ce7e083e0ed7"
    }
}
tip

We strongly recommend to update the UI to inform the user that they have been matched and a game server is now being hosted for them. This gives them a better feeling of progress and avoids them experiencing a longer wait without updates.

info

While waiting, Idem will send a keepAlive message every minute.

4. Wait for joinInfo and the join the server​

Once Idem receives the join info for the game server from the hosting provider, it will immediately forward that information to the game-client. This comes in form of a joinInfo action. The shape of the payload depends on the hosting provider. See the relevant hosting provider page for more information.

Once received, the information from the joinInfo should be used to have the game clients connect to the game server.

info

Depending on how you are setting up your game server, it might not be ready to accept connections when the hosting providers reports to Idem that it is running. It is recommended to add some retry logic to the game client in case the server is not ready to accept the game clients connection request immediately.

warning

The Idem matchmaker will launch a server (or the equivalent of the respective provider) on your behalf for each valid match that is created. We strongly recommend to make sure that your server code has logic to correctly shut down when the match is over or if the match does is not played for some reason, e.g. not all players joining ("no show"). Otherwise you might get charged for unnecessary server usage by the hosting provider.

A note on removing players from the queue​

Waiting players are automatically removed from the queue as soon as the websocket connection breaks. Hence, the removePlayer action is not used in player-based setup.

Code sample​

This Python code is an example of how to connect your game-client to Idem for a 1v1 game mode. The game-client connects to Idem, and submits a player to the queue. If then another player joins (e.g. by running the code in a separate terminal), Idem generates a match, launches the game-server on your provider, and returns the connection details to both game-clients. This is an easy way to see the end-to-end process fromt the game-client side.

We recommend using this code to get first experience with the WebSocket interactions.

Setup​

  • JOIN_CODE : Enter the join-code you can obtain from the console in the "matchmaker" tab.
  • SERVER : When joining the matchmaking, a list of viable server(-regions) is attached to each player (see Latency and region). The matchmaker will only match those players with each other that have at least on server in common. When a match is found, a server is launched in that region. For this sample, ensure you put servers into the list that your hosting provider allows.
player_based_sample.py
import json
import sys
import random

import websockets
import websockets.sync.client as client

WEBSOCKET_API_URL = "wss://ws.beta.idem.gg"
GAME_ID = "1v1"
JOIN_CODE = "9cf9dc78-49c0-4965b-ab2c-5b257d7eeab34"

SERVER = ['eu-west','somewhere'] # pick a server (-region) here that is supported by your game-hoster


def sync_websocket_client(code: str, player_id: str, player_auth: str):
    uri = f"{WEBSOCKET_API_URL}/?playerId={player_id}&code={code}&authorization={player_auth}"

    try:
        with client.connect(uri) as websocket:
            print(f"Connected to {WEBSOCKET_API_URL}")

            ## 1. Adding player to matchmaking queue
            print("\n-- 1. Adding player to matchmaking queue --")

            # Send player to matchmaking queue
            request = {
                "action": "addPlayer",
                "payload": {
                    "players": [
                        {"playerId": player_id, "servers": SERVER}
                    ],
                    "partyName": player_id,
                    "gameId": GAME_ID,
                },
            }
            websocket.send(json.dumps(request))
            print(f"Sent add_player request: {request}")


            ## 2. Waiting for Idem to confirm having received the message
            print("\n-- 2. Waiting for Idem to confirm the player being added to matchmaking queue --")

            # Listening
            response = json.loads(websocket.recv())

            # Check for error, e.g. if player with same id already in the queue
            assert 'error' not in response, f"Error: {response['error']['code']}, {response['error']['message']}"

            # Receive acknowledgement of player
            print(f"Received add_player acknowledgement: {response}")


            ## 3. Waiting for a second player to join, match to be created, server to be launched
            print("\n-- 3. Waiting for second player to join, be matched, server to be launched --")

            # Wait for other players
            while True:
                response = json.loads(websocket.recv())
                if response['action']=='keepAlive':
                    print('Received Keep-Alive ping')
                else:
                    print(f"Received game room info: {response}")
                    break

    except websockets.exceptions.ConnectionClosed as e:
        print(f"Connection closed: {e}")
    except Exception as e:
        if str(e)=="server rejected WebSocket connection: HTTP 500":
            print("Check the join-code. The server rejected the join-code")
        else:
            print(e)

if __name__ == "__main__":
    # read the player_id from the command line
    player_id = sys.argv[1] if len(sys.argv) > 1 and sys.argv[1]!='-f' else "player"+str(random.randint(1, 10000))
    sync_websocket_client(JOIN_CODE, player_id, "Demo")

🄴 Integrate into your game-server​

The last step is to integrate Idem into your game-server. To faciliate this, Idem is passing environment variables to the server as part of the hosting request to the server hosting provider independent of the specific provider. These are:

idemGameId​

The game mode the server was hosted for. Examples include:

  • 1v1
  • 2v2
  • 3-coop
Depending on your setup, you might want to use this to run the correct game mode on your server.

idemMatchUuid​

The unique identifier for the match. You will need to reference this when confirming the match at the beginning and reporting back the match result to Idem when the match is finished.

idemTeams​

An array including all teams in the match with their players. The shape of this is an "array of arrays of player objects". Each player object contains the playerId and the player's rating. Examples:

1v1 match
[
  [{ "playerId": "player1", "rating": 1350.5 }],
  [{ "playerId": "player2", "rating": 1420.3 }]
]
2v2 match
[
  [
    { "playerId": "player1", "rating": 1590.4 },
    { "playerId": "player2", "rating": 1510.2 }
  ],
  [
    { "playerId": "player3", "rating": 1625.9 },
    { "playerId": "player4", "rating": 1480.7 }
  ]
]
3-coop match
[
  [
    { "playerId": "player1", "rating": 1775.3 },
    { "playerId": "player2", "rating": 1840.6 },
    { "playerId": "player3", "rating": 1715.8 }
  ]
]

Required integration​

There are three required steps for integrating Idem into your game-server using the first two variables:

1. Confirming the match​

To allow Idem to correctly manage the matches lifecycle, the game server needs to send a confirmation to Idem once the match has started. This is step ⑤ in the graphic on top of the page.

For this, the server needs to open a WebSocket connection and authorize using username and password as described in the API documentation. After opening a WebSocket connection, the server needs to send the confirmMatchAction with the idemGameId as gameId and the idemMatchUuid as the matchId.

tip

Once the match is confirmed, this removes players from the matchmaking queue. So if you are creating test matches during development, confirming the match does "free up" the player IDs to be reused. Before this, players are blocked from entering the queue again as no player can be in the matchmaking process twice at the same time.

Alternatively, you can also use random player IDs during testing to avoid the requeueing limitation in case of unconfirmed matches.

tip

If you prefer using a REST call for this, you can also use the relevant REST API endpoint.

2. Reporting the match result​

After the game is completed, the game server can report the outcome of the game to Idem with the completeMatchAction. This is step ⑥ in the graphic on top of the page.

For this, the WebSocket connection created for confirming the match can be reused or a new one can be opened if the previous one was already closed. Similar to the confirmMatchAction the message should use the idemGameId as gameId and the idemMatchUuid as the matchId.

You also need to pass values for server (string) and gameLength (float). If this data is not relevant to you in the future, you can pass any non-null value.

Additionally, the outcome of the match needs to be provided as a teams object where each team is listed with the rank (starting from 0), and an array of players with their score. If your game does not have a scores, just pass 1 for each player.

For a 1v1 game the message for the completeMatchAction could for example look like this:

{
  "action": "updateMatchCompleted",
  "messageId": null,
  "payload": {
    "gameId": "1v1",
    "matchId": "ba60813a-f7ea-4a8f-84c6-c7faf4d415ae",
    "server": "test",
    "gameLength": 10.0,
    "teams": [
      {
        "rank": 0,
        "players": [
          {
            "playerId": "player1",
            "score": 1.0
          }
        ]
      },
      {
        "rank": 1,
        "players": [
          {
            "playerId": "player2",
            "score": 1.0
          }
        ]
      }
    ]
  }
}

For more options, refer to the API documentation or reach out to us at support@idem.gg.

tip

If you prefer using a REST call for this, you can also use the relevant REST API endpoint.

3. Reporting if the match is not completed for some reason​

If the match is not completed for some reason, you need to fail it in order to allow the players to requeue to the matchmaking. Some examples for why this might be necessary are:

  • Not all players are joining (see "Checking teams and players" below)
  • There is some error on the game server

For this, the server needs to open a WebSocket connection and authorize using username and password as described in the API documentation. After opening a WebSocket connection, the server needs to send the failMatchAction with the idemGameId as gameId and the idemMatchUuid as the matchId.

info

Requeueing players directly via the failMatchAction is not supported for player-based setups. Therefore all players in the match need to be passed in the remove parameter of the failMatchAction.

If for some reason the game server realizes a problem immediately, the match can also be failed before confirming it (see 1.). Based on the behavior of the failMatchAction, this will also remove the players from the matchmaking queue and allow them to requeue.

tip

If you prefer using a REST call for this, you can also use the relevant REST API endpoint.

Optional integration​

In addition to the required integration, the information provided by Idem in the form of enviornment variables enables two more scenarios that might not be relevant for all customers.

1. Starting the right game mode​

If your game supports different game modes, your game-server can use the idemGameId variable to start the right game mode for upcoming match. This removes the need to infer this in some way from the clients connecting.

2. Checking teams and players​

The idemTeams variable provides a list of teams in the match with the respetive players. You can leverage this to check if various things related to the players and teams. For example:

  • Is a specific player trying to join the server expected and should be admitted?
  • Are players in the right teams? (As this is important since the matchmaking considers each player's skill to decide in which team to put them.)
  • Have all players joined so that the game can start?