Architecture

Player-based

You can use Idem's matchmaker in combination with 3rd party hosting providers. There is two different architectures (for detail see Technical integration):

(1) Server-based: You have a server orchestrating your game deployment. This server connects to all players and spins up 3rd party game servers for them to then play on. Such orchestration server would call Idem's API to get match pairings.

If you are using this architecture, please implement following the instructions for the 5 minute matchmaker.

(2) Player-based: You do not operate a server orchestrating your game. Instead players should directly connect to Idem to submit themselves for matchmaking. Once a match is found, Idem will spin up your game server on your behalf for the players to play on. For this use-case, Idem partners with Hathora. Please follow below instructions to set it up.

Player-based with Hathora

Setting up Hathora

Before you get started, make sure you have an Idem account. You can also first have a look at our 5 minute matchmaker) to test connectivity and play around a little.

(1) Test game on Hathora: Make sure your game is added to Hathora and can be launched.
(2) Hathora Token: Obtain your API token and App ID from the Hathora Console.
(3) Key into Idem: Log into Idem, create a new 'token hosting provider' and paste in your Hathora token
(4) Adapt client code: Configure your game-client to connect to Idem directly. For this you use the game_id and join_code obtained from the Idem Console. The game_id is shown under tab "Matchmaker", being called "game mode". The join_code for your game will be shown under the tab "Matchmaker", if you have setup the integration with Hathora in the respective tab. For a reference implementation, please see the code below
(5) Run: Once your player's client is launched, it will connect to Idem. As soon as a match is created you will receive a link to the Hathora room with your launched game.

Authorization

The authorisation for players is currently under development.

Connection

note

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

Websocket actions

Game-clients (=players) are only allowed to add themselves to the queue via the "addPlayer" action. Players are removed from the queue, as soon as the websocket connection breaks. Hence, the "removePlayer" action is not allowed in player-based setup.

Python

player_based_hathora,py

import json
import sys

import websockets
import websockets.sync.client as client

WEBSOCKET_API_URL = "wss://ws.beta.idem.gg"
GAME_ID = "1v1"
JOIN_CODE = "0346d652b-5151-41gh-f859-ed8c318660345"

REGION = "Frankfurt"


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}")
        # Send your request
        request = {
            "action": "addPlayer",
            "payload": {
                "players": [
                    {"playerId": player_id, "servers": [REGION]}
                ],
                "partyName": player_id,
                "gameId": GAME_ID,
            },
        }
        websocket.send(json.dumps(request))
        print(f"Sent add_player request: {request}")

        # Wait for the response, this is the acknowledgement of the add_player request
        response = websocket.recv()
        print(f"Received add_player acknowledgement: {response}")

        # Wait for the Hathora room response
        response = websocket.recv()
        print(f"Received Hathora game room info: {response}")

except websockets.exceptions.ConnectionClosed as e:
    print(f"Connection closed: {e}")


if __name__ == "__main__":
# read the player_id from the command line
player_id = sys.argv[1] if len(sys.argv) > 1 else "player1"
sync_websocket_client(JOIN_CODE, player_id, "Demo")

warning

Idem will launch an instance for any valid request on its matchmaker. Make sure to keep tokens secure and instances on Hathora under observation.

Sample implementation: Bullet Mania

Bullet Mania is a multiplayer game built by Hathora to illustrate how to use their cloud to build scalable games. The following is a fork of Bullet Mania incorporating Idem's matchmaker and leveraging the player-based architecture, where no orchestration (middleware) is required.

Try it out!
The game can be played at bulletmania.idem.gg.

Get the code
The corresponding code is available on Github here.

Implementation details

This is a step-by-step guide of the implementation:

Step 1: Start page

Client hosted on bulletmania.idem.gg is loaded. Upon pressing 'Join', the player's name is send to Idem's matchmaker and added to the queue.

Step 2: Waiting for match

The matchmaker confirms to the client that the player has been added to the queue. The client's message changes accordingly to "[...] Waiting for suitable match"

Step 3: Firing up the game server

As soon as the matchmaker finds a match, it requests a room from Hathora. The URL for the room the matchmaker sends to both players' client. The clients then join the game server, where a game is being booted.

Step 4: Running the game

The game is played on the game server.

Step 5: End of game

When the game ends, the result of the game is reported by the game server to the matchmaker. The game server shuts down.

Step 6: Result screen

The matchmaker calculates the ratings based on the recent game. The players' ratings are returned to the client in order to be displayed.