Understanding backfill ticket lifecycle
Overview
This article provides an overview of the backfill ticket lifecycle, which outlines the default end-to-end flow of a session after a match has been formed by Matchmaking. However, it is possible to customize several stages of this flow to better suit your game's needs. You can learn more about this in the Extend section.
Matchmaking uses workers to run matching logic in parallel for each match pool, helping to prevent interruptions in queue processing. The backfilling process takes precedence over new match creation to ensure existing matches are optimally filled before forming new ones, if available sessions do not meet player requests.
Backfill tickets represent a request to AGS Matchmaking to find players to fill empty seat(s). These tickets can be created manually by a dedicated server (DS) or P2P host, or automatically by Matchmaking.
Backfill will not initiate under the following circumstances:
- The session is at full capacity. Full capacity is the variable player_max_number set in the ruleset (authoritative), not the one set in the session (e.g. updating mid game with patch operation).
- Session has joinability CLOSED, which doesn’t allow session members composition to change.
There are several things during backfilling that you should be aware of:
Auto Backfill: Determines whether Matchmaking should automatically create a backfill ticket immediately after a match is formed. For manual creation, it is up to the dedicated server (DS) or P2P host to decide whether to submit a backfill request.
Backfill Ticket: Represents a request for backfilling. Backfill tickets are removed from the queue either when the session is full or when the ticket expires. When a session becomes full, the corresponding backfill ticket is removed from the queue—so make sure to configure the Max Players value in the Session Template appropriately. Your server can create a new backfill ticket when an empty slot becomes available. Even when the auto backfill is on, a player leaving a full session does not trigger automatic backfill ticket creation.
Backfill Proposal: Contains an updated team composition as a proposal, which the server can either accept or reject. A backfill proposal can contain multiple added matchmaking tickets, in which the DS can accept them partially. Backfill proposals have an expiration time, configurable via the Admin Portal. Until the proposal is accepted, rejected, or expired, Matchmaking will not match the proposed players' tickets to anyone else.
Auto Accept Backfill Proposal: If you want the server to have control over whether to accept join-in-progress players, you need to enable the Auto-Accept Backfill Proposal setting in the matchpool.
- Partial Backfill Acceptance: A backfill proposal can contain multiple added matchmaking tickets, in which the DS can accept them partially. When a proposal contains multiple added matchmaking tickets, the DS can choose to accept only some of them while rejecting the others. This gives the DS flexibility to control who is allowed to join the server. Please note that this will only be available if Auto Accept Backfill Proposal is enabled
Backfill ticket lifecycle
The diagram below shows the lifecycle of when a backfill ticket is created (manually and automatically), processed by Matchmaking and removed from the backfill queue. There are 2 ways for a backfill ticket to be removed from the queue, it is either:
- through backfill ticket expiration, or
- request to stop backfill, which can be triggered from delete backfill ticket or during accept/reject backfill proposal.
When a new match is formed, Matchmaking will create a session and backfill a ticket if needed and configured. Matchmaking will pass players’ information such as regions, client version, and other attributes upon creating a session. By default, the matchmaking process ends at this point. However, if auto_backfill is enabled in the match ruleset, Matchmaking will create a backfill ticket, add it to the backfill queue, and update the session with the backfill ticket ID.
The DS or P2P leader submits a backfill ticket to Matchmaking The DS or P2P host/leader determines if there are free seats in their session, and wants to add more players. They can submit a backfill ticket to Matchmaking, containing their sessionID to fill up.
The backfill ticket is hydrated with player attributes defined in the associated match ruleset. Each match pool has an associated match ruleset that defines the player attributes and criteria that should be used by the match function to find appropriate matches from within the pool. When a request to backfill is received, Matchmaking will hydrate the ticket with session attributes, region, active players, cross platform attributes.
The backfill ticket is evaluated with the player tickets in the match pool to find valid matches. After the backfill ticket has been hydrated with the session attributes, the Matchmaking service will then call the associated match function to evaluate the tickets in the match pool in order to find a valid match. If a match isn't found during processing, the backfill ticket will be returned to the queue to be evaluated again. By default, AGS Matchmaking will use the specified criteria in the associated ruleset as the logic to find a match. However, this can be extended with more complex logic if needed. Refer to Extend for more information.
The matchmaking finds a new team composition and proposes to the server if needed.
After matchmaking finds a new team composition that meets both the session and player criteria, the service forms a proposal.
- If the session doesn’t have a server, or if Auto Accept Backfill Proposal is enabled, the service immediately updates the session to invite join-in-progress players.
- If Auto Accept Backfill Proposal is disabled, the service sends a proposal to the server through DSHub. In this case, the server could be either a P2P host or a dedicated server (DS).
{
"Payload": {
"BackfillTicketID": "{backfill ticket ID}",
"CreatedAt": "{backfill ticket creation time}",
"AddedTickets": [
{
"Namespace": "{namespace}",
"PartySessionID": "{party ID-1}",
"TicketID": "{ticket ID-1}",
"MatchPool": "{match pool}",
"CreatedAt": "{proposal creation time}",
"Players": [
{
"PlayerID": "{user ID A}",
"PartyID": "",
"PlatformID": "",
"Attributes": {}
}
],
"TicketAttributes": {
"client_version": "0.8.1",
"{User ID A}": {
// attributes
},
"TicketInformation": "",
"Latencies": {
"ap-northeast-2": 228,
"ap-southeast-1": 160,
"ap-southeast-2": 283,
"eu-central-1": 26,
"sa-east-1": 203,
"us-east-2": 100,
"us-west-2": 152
},
"ExcludedSessions": ""
}
}
],
"ProposedTeams": [
{
"TeamID": "{proposed team ID}",
"UserIDs": [
// existing list of users
],
"Parties": [{
"partyID": "party-ID",
"userIDs": []
},
{
"partyID": "party-ID",
"userIDs": []
},
{
"partyID": "party-ID",
"userIDs": []
}
]
}
],
"ProposalID": "{proposal ID}",
"MatchPool": "{match pool}",
"MatchSessionID": "{game session ID}",
"Attribute": ""
}
}
It is important for the server to respond promptly, as Matchmaking holds the proposal, which includes the join-in-progress players and the session, until the backfill proposal expires. If the server rejects the proposal, the backfill ticket and player tickets are returned to the queue for re-evaluation.
The join in-progress player(s) receive the match results and an invitation to join the game session. If a proposal containing the new team composition is accepted, Matchmaking will update the session to let the Session service notify the current active players in that session about the members' change and invite the join in-progress players.
When a backfill ticket expires or a session reaches maximum capacity, the ticket will be removed from the backfill queue. An open session can have players dropping in and out, and it becomes the server's responsibility to know when to queue a backfill ticket to Matchmaking.