Concepts
Project
A project is one game. Players, devices, matches, leaderboards, queues, builds and keys all belong to exactly one project and are never visible to another. The same phone is a different player in every project.
Keys and tokens
| Credential | Held by | Proves |
|---|---|---|
Client key md_pub_… |
Every game install | Which project a request is for. Not a secret. Header x-matchdock-key. |
Server key md_sec_… |
Your team and CI | That the caller may manage the project. |
| Access token | One player's device | Who the player is. Returned by device sign-in, sent as Authorization: Bearer …, valid for 30 days. |
| Join token | One player, for one match | That this player belongs to this server session. The game server verifies it with Matchdock. |
| Server secret | One server process | That a call comes from the server of this session. Handed over in the environment, never logged. |
Queue
A named line players wait in, such as casual_1v1 or ranked. Each queue has rating windows that widen with waiting time (for example ±100 at first, ±250 after 10 seconds, ±500 after 30). Players only meet opponents from the same project, queue and region. Matches are two players today.
Match and server session
A match is the pairing and its outcome. A server session is the running game server for that match: a node, a port, a build version, a lifecycle.
| Session status | Meaning |
|---|---|
ALLOCATED |
A node and port are reserved; the server is starting. |
READY / ACTIVE |
Players are connected; the match is being played. |
FINISHED |
A result was accepted. |
ABORTED |
Ended without a result and without rating changes (cancelled before kick-off, server exited early, everybody left). |
FAILED / TIMEOUT |
The server crashed, the node was lost, or nothing happened in time. |
Every session keeps a timeline of events - allocated, started, each player connecting and leaving, result received - which is what you see when you open a match in the console.
Node and region
A node is a machine in our fleet that runs game servers. Matches are placed on a healthy node in the players' region when one has room and fall back to another region instead of failing. A node can be dedicated to a single project.
Build
A version of your dedicated server. Exactly one build per project is live; new matches use it while running matches finish on the build they started with. See Server builds.