Skip to main content

Backfilling

The backfilling feature allows game servers to request a new player from the Matchmaker to replace a player that has left an active match. This can be used to ensure matches remain populated even as one or more players quit or disconnect.

note

Backfilling is only supported for game servers hosted on IMS Zeuz.

caution

Backfilling is a beta feature that is still undergoing development and improvement.

Client Integration

Backfilling is entirely server-driven - no change is required on the client to support this feature. Clients that are backfilled are notified of a connection in the same way as for normal matches.

Server Integration

Prerequisites

Servers hosted on IMS Zeuz are provided with two metadata values that are required to issue a backfill request:

  1. matchmaker_lobby_url - the URL the game server should use to communicate with the Matchmaker.
  2. matchmaker_lobby_token - the auth token the game server should use to authenticate with the Matchmaker.

Additionally, when issuing a backfill request, the game server must provide these pieces of information:

  1. A match token provided by the last player to connect to the game server.
  2. A list of ticket IDs of the players that need to be backfilled.

Process

To backfill a missing player, the game server must:

1. Connect to the matchmaker

Open a WebSocket connection to the URL specified by the matchmaker_lobby_url annotation, passing the authentication token provided by matchmaker_lobby_token as an HTTP header, e.g. Authorization: Bearer <matchmaker_lobby_token>.

2. Issue a backfill request

For this request you need an assignment token and a list of IDs of the players that need to be replaced.

note

It's important to always use the most recent assignment token you have for this request, to ensure that it will describe the match including players that have already been backfilled. We recommend checking the iat timestamp field of the assignment token of each new connecting player, and keeping a reference to the most recent one.

If using JSON, the request will look like this:

{
"msg_type": "BackfillRequest",
"msg": {
"token": "<raw-assignment-token>",
"missingTickets": ["t123456000b", "t123456000c"]
}
}

3. Remain connected

If the request was valid, the game server will immediately receive a backfill status update:

{
"msg_type": "BackfillStatusResponse",
"msg": {
"id": "<backfill-id>",
"status": "Created"
}
}

4. Wait for a backfill

As long as the game server remains connected to the matchmaker, the backfill request will persist.

If a player is found, a new status message will be received with the PartiallyFulfilled (if only some of the players have been replaced) or Fulfilled (if all the players have been replaced.)

{
"msg_type": "BackfillStatusResponse",
"msg": {
"id": "<backfill-id>",
"status": "PartiallyFulfilled"
}
}

Players will connect to the server like normal, and will present an Assignment Token containing an updated team formation that the server can use to determine which team the player should be added to.

5. Disconnect when finished

When the server no longer wishes to backfill, or if the match has ended, it can simply disconnect from the Matchmaker and the backfill request will be deleted.

6. Reconnect to issue another backfill

If the server wishes to issue another backfill request, it should repeat steps 1-5, using the match token provided by the last player to connect.