Matchmaking

Joining and leaving

POST /matchmaking/join     { "queueName": "ranked", "region": "eu-central" }
GET  /matchmaking/status
POST /matchmaking/leave
POST /matchmaking/abandon

queueName defaults to casual_1v1. A player can hold one ticket and one active match at a time; joining again while searching returns the existing ticket.

Poll status every one to three seconds while searching:

`status`	Meaning
`IDLE`	Not queued, no active match. After a search that ended without a match, `ticketStatus` says why (`CANCELLED` or `EXPIRED`).
`SEARCHING`	Waiting for an opponent.
`MATCH_FOUND`, `READY`, `ACTIVE`	There is a server: `host`, `port`, `joinToken`, `slot`, `matchId`, `serverSessionId` and `opponent` are set.
`FINISHED`, `ABORTED`, `TIMEOUT`	The last match ended; details are in the payload. Reported only until the player queues again, so it always describes the current search.

leave removes a searching ticket. abandon also backs out of a match that has been made but has not kicked off, stopping its server; once a match is active, leaving it is a forfeit. Both players cancelling in the same instant is handled.

How players are paired

The matchmaker runs every second and drains the whole queue each time. For the longest-waiting player it looks for the longest-waiting opponent in the same project, queue and region whose rating is within the current window; a player nobody fits is skipped, not allowed to block the line.

Rating windows widen with waiting time and are set per queue:

curl -X PUT $API/admin/projects/$PROJECT/queues/ranked -H "x-matchdock-key: $KEY" \
  -H 'content-type: application/json' -d '{
    "ratingWindows": [
      { "afterSeconds": 0,  "window": 80 },
      { "afterSeconds": 15, "window": 200 },
      { "afterSeconds": 40, "window": 600 }
    ]
  }'

{"enabled": false} closes a queue to new players without touching those already waiting. The console has an editor for all of this under Matchmaking.

When the fleet is full

If no node has room, the two players go back into the queue - they are not thrown out - and are matched again as soon as capacity frees up.

Friend matches

POST /matchmaking/friend creates a match between two specific players, bypassing the queue. It is scoped to the project like everything else.