Messages

This page outlines the principle set of messages that clients can send to and receive from the Matchmaker.

ClientStatusRequest

Requests a status report for the connection. Returns a ClientStatusResponse.

{
  "msg_type": "ClientStatusRequest",
  "msg": {}
}

ClientStatusResponse

Describes the current state of the connection, including the connection ID (required for joining as a party), and the measured client latency (in milliseconds.)

{
  "msg_type": "ClientStatusResponse",
  "msg": {
    "id": "<connection-id>",
    "status": "Idle",
    "latencyMS": 123
  }
}

Status	Description
Idle	Client is not in a queue.
Queued	Client is in a queue.
Matched	Client has been matched and must accept or reject it (see Accept State)
Accepted	Match has been accepted by the client and is waiting for others to do the same.
Playing	Match has been formed and a server returned.

QueueListRequest

Requests a list of Queues available to the client to join. Returns a QueueListResponse.

{
  "msg_type": "QueueListRequest",
  "msg": {}
}

QueueListResponse

This describes all queues that are available to the client. The id value may be used in a QueueJoinRequest to join that specific queue.

{
  "msg_type": "QueueListResponse",
  "msg": {
    "queues": [
      {
        "id": "<queue-id>",
        "name": "<queue-name>",
        "attributes": {}
      }
    ]
  }
}

QueueJoinRequest

This requests that the client joins a queue.

{
  "msg_type": "QueueJoinRequest",
  "msg": {
    "id": "<queue-id>",
    "attributes": [
      {
        "entry_type": "StringMapEntry",
        "entry": {
          "key": "map",
          "value": "shoreditch"
        }
      }
    ],
    "clientLatency": []
  }
}

Queue ID

The msg.id field should reference a Queue ID returned by the QueueListResponse object.

Join Attributes

The msg.attributes section of this message can be used to describe additional matching parameters, such as a desired map.

Attributes are expressed as a list of objects containing the key/value pairs. For instance, if the client wanted to play the map shoreditch, it would add a map key to the list of attributes, taking care to define it as a StringMapEntry:

"attributes": [
  {
    "entry_type": "StringMapEntry",
    "entry": {
      "key": "map",
      "value": "shoreditch"
    }
  }
]

The client can specify as many attributes as required by extending the attributes array with additional entries.

Other value types are available, namely IntegerMapEntry for integers, and DoubleMapEntry for floating point values.

Client Latency data

Optionally, the client can provide ping data that the matchmaking rules can use to match players to servers that will give them lower-latency games.

The join request can be augmented with clientLatency data array:

"clientLatency": [
  {"location": "london", "pingMillis": 44},
  {"location": "newyork", "pingMillis": 120},
  {"location": "sydney", "pingMillis": 398}
]

In this array, the location values should match the metadata provided by servers for the queue’s chosen platform.

This data may then be referenced by queues that have enabled the client_latency extension.

ServerAssignmentResponse

This message will be received by the client when a match has been found for it.

{
  "msg_type": "ServerAssignmentResponse",
  "msg": {
    "queue": "<queue-id>",
    "assignment": "203.4.113.4:29000",
    "token": "<assignment-token>"
  }
}

The game client may now disconnect from the Matchmaker and connect to the game server defined by the assignment value, providing the token Assignment Token value to the game server when it connects.

For more information on what the game server should do when it receives a connection, see Assignment Token.

ClientResetRequest

This message puts the client back into the default ‘idle’ state, as if they had reconnected, but retains their existing connection ID. Typically, this should be used to leave the queuing state.

{
  "msg_type": "ClientResetRequest",
  "msg": {}
}