Amazon GameLift Service
API Reference (API Version 2015-10-01)

StartMatchBackfill

Finds new players to fill open slots in an existing game session. This operation can be used to add players to matched games that start with fewer than the maximum number of players or to replace players when they drop out. By backfilling with the same matchmaker used to create the original match, you ensure that new players meet the match criteria and maintain a consistent experience throughout the game session. You can backfill a match anytime after a game session has been created.

To request a match backfill, specify a unique ticket ID, the existing game session's ARN, a matchmaking configuration, and a set of data that describes all current players in the game session. If successful, a match backfill ticket is created and returned with status set to QUEUED. The ticket is placed in the matchmaker's ticket pool and processed. Track the status of the ticket to respond as needed.

The process of finding backfill matches is essentially identical to the initial matchmaking process. The matchmaker searches the pool and groups tickets together to form potential matches, allowing only one backfill ticket per potential match. Once the a match is formed, the matchmaker creates player sessions for the new players. All tickets in the match are updated with the game session's connection information, and the GameSession object is updated to include matchmaker data on the new players. For more detail on how match backfill requests are processed, see How Amazon GameLift FlexMatch Works.

Learn more

Backfill Existing Games with FlexMatch

How GameLift FlexMatch Works

Related operations

Request Syntax

{ "ConfigurationName": "string", "GameSessionArn": "string", "Players": [ { "LatencyInMs": { "string" : number }, "PlayerAttributes": { "string" : { "N": number, "S": "string", "SDM": { "string" : number }, "SL": [ "string" ] } }, "PlayerId": "string", "Team": "string" } ], "TicketId": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

ConfigurationName

Name of the matchmaker to use for this request. The name of the matchmaker that was used with the original game session is listed in the GameSession object, MatchmakerData property. This property contains a matchmaking configuration ARN value, which includes the matchmaker name. (In the ARN value "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MM-4v4", the matchmaking configuration name is "MM-4v4".) Use only the name for this parameter.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9-\.]*

Required: Yes

GameSessionArn

Amazon Resource Name (ARN) that is assigned to a game session and uniquely identifies it.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [a-zA-Z0-9:/-]+

Required: Yes

Players

Match information on all players that are currently assigned to the game session. This information is used by the matchmaker to find new players and add them to the existing game.

  • PlayerID, PlayerAttributes, Team -\\- This information is maintained in the GameSession object, MatchmakerData property, for all players who are currently assigned to the game session. The matchmaker data is in JSON syntax, formatted as a string. For more details, see Match Data.

  • LatencyInMs -\\- If the matchmaker uses player latency, include a latency value, in milliseconds, for the region that the game session is currently in. Do not include latency values for any other region.

Type: Array of Player objects

Required: Yes

TicketId

Unique identifier for a matchmaking ticket. If no ticket ID is specified here, Amazon GameLift will generate one in the form of a UUID. Use this identifier to track the match backfill ticket status and retrieve match results.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9-\.]*

Required: No

Response Syntax

{ "MatchmakingTicket": { "ConfigurationName": "string", "EndTime": number, "EstimatedWaitTime": number, "GameSessionConnectionInfo": { "GameSessionArn": "string", "IpAddress": "string", "MatchedPlayerSessions": [ { "PlayerId": "string", "PlayerSessionId": "string" } ], "Port": number }, "Players": [ { "LatencyInMs": { "string" : number }, "PlayerAttributes": { "string" : { "N": number, "S": "string", "SDM": { "string" : number }, "SL": [ "string" ] } }, "PlayerId": "string", "Team": "string" } ], "StartTime": number, "Status": "string", "StatusMessage": "string", "StatusReason": "string", "TicketId": "string" } }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

MatchmakingTicket

Ticket representing the backfill matchmaking request. This object includes the information in the request, ticket status, and match results as generated during the matchmaking process.

Type: MatchmakingTicket object

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServiceException

The service encountered an unrecoverable internal failure while processing the request. Clients can retry such requests immediately or after a waiting period.

HTTP Status Code: 500

InvalidRequestException

One or more parameter values in the request are invalid. Correct the invalid parameter values before retrying.

HTTP Status Code: 400

NotFoundException

A service resource associated with the request could not be found. Clients should not retry such requests.

HTTP Status Code: 400

UnsupportedRegionException

The requested operation is not supported in the region specified.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: