Version: en

Configuring Standard Backfill

warning

This documentation is now deprecated. If you are using Matchmaker Self Serve though UDash, please use the documentation here.

Configuring Backfill#

Sample Backfill Ticket Data Property:

{
"MatchProperties": {
"Teams": [
{
"TeamName": "hunters0",
"TeamDefinitionName": "hunters",
"PlayerIds": [
"aabb",
"bbcc",
"ccdd"
]
},
{
"TeamName": "monsters0",
"TeamDefinitionName": "monsters",
"PlayerIds": [
"ddee",
"eeff",
"ffgg"
]
}
]
},
"TeamDefinitions": [
{
"Name": "hunters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0,
"Relax": null
},
"PlayerCount": {
"Min": 3.0,
"Max": 3.0,
"Relax": null
}
},
{
"Name": "monsters",
"TeamCount": {
"Min": 1.0,
"Max": 1.0,
"Relax": null
},
"PlayerCount": {
"Min": 3.0,
"Max": 3.0,
"Relax": null
}
}
],
"Players": [
{
"Id": "aabb",
"Data": null
},
{
"Id": "bbcc",
"Data": null
},
{
"Id": "ccdd",
"Data": null
},
{
"Id": "ddee",
"Data": null
},
{
"Id": "eeff",
"Data": null
},
{
"Id": "ffgg",
"Data": null
}
],
"Region": "US-WEST"
}

Flow Overview#

Prerequisites#

To enable backfill, set the "BackfillEnabled" property of the Matchmaking Config to true. Participating in server side backfill requires a DGS to understand the backfill contract and to activily update and approve backfill ticket ids. See Backfill section of 'How To' for in depth details

Backfill Matchmaking Logic#

On the matchmaking logic configuration side, there are currently no details required other than enabling backfill via the "BackfillEnabled" property. In the future more powerfull rules may be added.

How does backfill work#

Matchmaking Logic#

When backfill is enabled, any match that is not full but meets the minimum requirement for number of players and teams will create a backfill ticket. The backfill ticket represents the state of the ongoing matchmaking effort and contains all of information required to see what teams and players are part of the match. (see BackfillData Contract).

DGS Backfill Logic#

When backfill is enabled, the DGS is the authority for accepting matches and the tickets associated with them. The DGS has a few methods at its disposal that allow it to interact collabaritvly with matchmaking logic to track new and dropped players. When a DGS starts, it should read its session data record. If that session data record has a BackfillTicketId set, then this server was created with a backfill ticket! To find out how to read the session data, see Reading session service JWT and ID on the DGS

DGS Backfill Loop#

Since the DGS is the authority for accepting matches via backfill ticket, the first step should be to get the latest backfill ticket by approving it.

  1. DGS should accept any pending updates to the backfill ticket by calling the /api/v2/backfill/{id}/approvals API. See Backfill API for details
  2. After calling approve, the DGS will recieve the latest backfill ticket object. Inside of the properties map of the backfill ticket under "data" is a base64 encoded string containing the BackfillData Contract. This contract can be used to observer the current state of the teams, what players they have and any custom data associated with any players.
  3. The DGS may now choose to update this BackfillData contract by adding or removing players from the teams. Be sure to add/remove players to/from both the team list and the player array.
    1. If the DGS has recieved players outside of matchmaking or noticed players dropped, it must call the Update Backfill Ticket method. This method has serious side effects as it will overwrite the current state of the backfill ticket with whatever the server provides. Care must be taken to adhere strictly to the BackfillData contract. For much more depth these scenarios see DGS Updates Backfill Ticket Too Frequently
  4. Regardless of weather the DGS updated the backfill ticket in step 3:
    1. If the DGS still needs more players, go back to step 1
    2. If the DGS is full, delete the backfill ticket using the delete API call.
  5. If the DGS needs to begin backfilling again after deleting its ticket, this can be done by creating a new backfill ticket with a valid "data" property containing BackfillData contract that reflects the latest state of the DGS (what do teams look like now, who has joined, dropped?)
Further Reading#

The topic of backfill is complex. The links above all contain more details and context. For much more in depth discussion on how matchmaking logic and backfilling DGS's collaborate (and tips on avoiding pitfalls) please read the How To Backfill section.

What's Next?#