Backfill existing games with FlexMatch - Amazon GameLift
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Backfill existing games with FlexMatch

Match backfill uses your FlexMatch mechanisms to find new players for existing matched game sessions. Although you can always add players to any game (see Join a player to a game session), match backfill ensures that new players meet the same match criteria as current players. In addition, match backfill assigns the new players to teams, manages player acceptance, and sends updated match information to the game server. Learn more about match backfill in FlexMatch matchmaking process.

Note

FlexMatch backfill is not currently available for games using Realtime Servers.

There are two types of backfill mechanisms:

  • To fill game sessions that start with fewer than the maximum allowed players, enable automatic backfill.

  • To replace players who drop out of a game session in progress, add functionality to your game server to send backfill requests.

Turn on automatic backfill

With automatic match backfill, Amazon GameLift automatically triggers a backfill request whenever a game session starts with one or more unfilled player slots. This feature allows games to start as soon as the minimum number of matched players is found and fill remaining slots later as additional players are matched. You can opt to stop automatic backfill at any time.

As an example, consider a game that can hold six to ten players. FlexMatch initially locates six players, forms the match, and starts a new game session. With automatic backfill, the new game session can immediately request an additional four players. Depending on the game style, we might want to allow new players to join at any time during the game session. Alternatively, we might want to stop automatic backfill after initial setup phase and before gameplay starts.

To add automatic backfill to your game, make the following updates to your game.

  1. Enable automatic backfill. Automatic backfill is managed in a matchmaking configuration. When enabled, it is used with all matched game sessions that are created with that matchmaker. Amazon GameLift begins generating backfill requests for a non-full game session as soon as the game session starts up on a game server.

    To turn on automatic backfill, open a match configuration and set the backfill mode to "AUTOMATIC". For more details, see Create a matchmaking configuration

  2. Turn on backfill prioritization. Customize your matchmaking process to prioritize filling backfill requests before creating new matches. In your matchmaking rule set, add an algorithm component and set backfill priority to "high". For more details, see Customize the match algorithm.

  3. Update game session with new matchmaker data. Amazon GameLift updates your game server with match information using the Server SDK callback function onUpdateGameSession (see Initialize the server process). Add code to your game server to handle updated game session objects as a result of backfill activity. Learn more in Update match data on the game server.

  4. Turn off automatic backfill for a game session. You can opt to stop automatic backfill at any point during an individual game session. To stop automatic backfill, add code to your game client or game server to make the Amazon GameLift API call StopMatchmaking. This call requires a ticket ID. Use the backfill ticket ID from the latest backfill request. You can get this information from the game session matchmaking data, which is updated as described in the previous step.

Send backfill requests (from a game server)

You can initiate match backfill requests directly from the game server process that is hosting the game session. The server process has the most up-to-date information on current players connected to the game and the status of empty player slots.

This topic assumes that you've already built the necessary FlexMatch components and successfully added matchmaking processes to your game server and a client-side game service. For more details on setting up FlexMatch, see FlexMatch integration with Amazon GameLift hosting.

To enable match backfill for your game, add the following functionality:

As with other server functionality, a game server uses the Amazon GameLift Server SDK. This SDK is available in C++ and C#.

To make match backfill requests from your game server, complete the following tasks.

  1. Trigger a match backfill request. Generally, you want to initiate a backfill request whenever a matched game has one or more empty player slots. You may want to tie backfill requests to specific circumstances, such as to fill critical character roles or balance out teams. You'll likely also want to limit backfilling activity based on a game session's age.

  2. Create a backfill request. Add code to create and send match backfill requests to a FlexMatch matchmaker. Backfill requests are handled using these server APIs:

    To create a backfill request, call StartMatchBackfill with the following information. To cancel a backfill request, call StopMatchBackfill with the backfill request's ticket ID.

    • Ticket ID — Provide a matchmaking ticket ID (or opt to have them autogenerated). You can use the same mechanism to assign ticket IDs to both matchmaking and backfill requests. Tickets for matchmaking and backfilling are processed the same way.

    • Matchmaker — Identify which matchmaker to use for the backfill request. Generally, you'll want to use the same matchmaker that was used to create the original match. This request takes a matchmaking configuration ARN. This information is stored in the game session object (GameSession), which was provided to the server process by Amazon GameLift when activating the game session. The matchmaking configuration ARN is included in the MatchmakerData property.

    • Game session ARN — Identify the game session being backfilled. You can get the game session ARN by calling the server API GetGameSessionId(). During the matchmaking process, tickets for new requests do not have a game session ID, while tickets for backfill requests do. The presence of at game session ID is one way to tell the difference between tickets for new matches and tickets for backfills.

    • Player data — Include player information (Player) for all current players in the game session you are backfilling. This information allows the matchmaker to locate the best possible player matches for the players currently in the game session. You must include the team membership for every player. Do not specify a team if you are not using backfill. If your game server has been accurately reporting player connection status, you should be able to acquire this data as follows:

      1. The server process hosting the game session should have the most up-to-date information which players are currently connected to the game session.

      2. To get player IDs, attributes, and team assignments, pull player data from the game session object (GameSession), MatchmakerData property (see Work with matchmaker data). The matchmaker data includes all players who were matched to the game session, so you'll need to pull the player data for only the currently connected players.

      3. For player latency, if the matchmaker calls for latency data, collect new latency values from all current players and include it in each Player object. If latency data is omitted and the matchmaker has a latency rule, the request will not be successfully matched. Backfill requests require latency data only for the region that the game session is currently in. You can get a game session's region from the GameSessionId property of the GameSession object; this value is an ARN, which includes the region.

  3. Track the status of a backfill request. Amazon GameLift updates your game server about the status of backfill requests using the Server SDK callback function onUpdateGameSession (see Initialize the server process). Add code to handle the status messages—as well as updated game session objects as a result of successful backfill requests—at Update match data on the game server.

    A matchmaker can process only one match backfill request from a game session at a time. If you need to cancel a request, call StopMatchBackfill(). If you need to change a request, call StopMatchBackfill and then submit an updated request.

Send backfill requests (from a client service)

As an alternative to sending backfill requests from a game server, you may want to send them from a client-side game service. To use this option, the client-side service must have access to current data on game session activity and player connections; if your game uses a session directory service, this might be a good choice.

This topic assumes that you've already built the necessary FlexMatch components and successfully added matchmaking processes to your game server and a client-side game service. For more details on setting up FlexMatch, see FlexMatch integration with Amazon GameLift hosting.

To enable match backfill for your game, add the following functionality:

As with other client functionality, a client-side game service uses the Amazon SDK with Amazon GameLift API. This SDK is available in C++, C#, and several other languages. For a general description of client APIs, see the Amazon GameLift Service API Reference, which describes the low-level service API for Amazon GameLift-related actions and includes links to language-specific reference guides.

To set up a client-side game service to backfill matched games, complete the following tasks.

  1. Trigger a request for backfilling. Generally, a game initiates a backfill request whenever a matched game has one or more empty player slots. You may want to tie backfill requests to specific circumstances, such as to fill critical character roles or balance out teams. You'll likely also want to limit backfilling based on a game session's age. Whatever you use for a trigger, at a minimum you'll need to the following information. You can get this information from the game session object (GameSession) by calling DescribeGameSessions with a game session ID.

    • Number of currently empty player slots. This value can be calculated from a game session's maximum player limit and the current player count. Current player count is updated whenever your game server contacts the Amazon GameLift service to validate a new player connection or to report a dropped player.

    • Creation policy. This setting indicates whether the game session is currently accepting new players.

    The game session object contains other potentially useful information, including game session start time, custom game properties, and matchmaker data.

  2. Create a backfill request. Add code to create and send match backfill requests to a FlexMatch matchmaker. Backfill requests are handled using these client APIs:

    To create a backfill request, call StartMatchBackfill with the following information. A backfill request is similar to a matchmaking request (see Request matchmaking for players), but also identifies the existing game session. To cancel a backfill request, call StopMatchmaking with the backfill request's ticket ID.

    • Ticket ID — Provide a matchmaking ticket ID (or opt to have them autogenerated). You can use the same mechanism to assign ticket IDs to both matchmaking and backfill requests. Tickets for matchmaking and backfilling are processed the same way.

    • Matchmaker — Identify the name of a matchmaking configuration to use. Generally, you'll want to use the same matchmaker for backfilling that was used to create the original match. This information is in a game session object (GameSession), MatchmakerData property, under the matchmaking configuration ARN. The name value is the string following ""matchmakingconfiguration/". (For example, in the ARN value "arn:aws-cn:gamelift:us-west-2:111122223333:matchmakingconfiguration/MM-4v4", the matchmaking configuration name is "MM-4v4".)

    • Game session ARN — Specify the game session being backfilled. Use the GameSessionId property from the game session object; this ID uses the ARN value that you need. Matchmaking tickets (MatchmakingTicket) for backfill requests have the game session ID while being processed; tickets for new matchmaking requests do not get a game session ID until the match is placed; the presence of at game session ID is one way to tell the difference between tickets for new matches and tickets for backfills.

    • Player data — Include player information (Player) for all current players in the game session you are backfilling. This information allows to matchmaker to locate the best possible player matches for the players currently in the game session. You must include the team membership for every player. Do not specify a team if you are not using backfill. If your game server has been accurately reporting player connection status, you should be able to acquire this data as follows:

      1. Call DescribePlayerSessions() with the game session ID to discover all players who are currently connected to the game session. Each player session includes a player ID. You can add a status filter to retrieve active player sessions only.

      2. Pull player data from the game session object (GameSession), MatchmakerData property (see Work with matchmaker data. Use the player IDs acquired in the previous step to get data for currently connected players only. Since matchmaker data is not updated when players drop out, you will need extract the data for current players only.

      3. For player latency, if the matchmaker calls for latency data, collect new latency values from all current players and include it in the Player object. If latency data is omitted and the matchmaker has a latency rule, the request will not be successfully matched. Backfill requests require latency data only for the region that the game session is currently in. You can get a game session's region from the GameSessionId property of the GameSession object; this value is an ARN, which includes the region.

  3. Track status of backfill request. Add code to listen for matchmaking ticket status updates. You can use the mechanism set up to track tickets for new matchmaking requests (see Track matchmaking events) using event notification (preferred) or polling. Although you don't need to trigger player acceptance activity with backfill requests, and player information is updated on the game server, you still need to monitor ticket status to handle request failures and resubmissions.

    A matchmaker can process only one match backfill request from a game session at a time. If you need to cancel a request, call StopMatchmaking. If you need to change a request, call StopMatchmaking and then submit an updated request.

    Once a match backfill request is successful, your game server receives an updated GameSession object and handles the tasks needed to join new players to the game session. See more at Update match data on the game server.

Update match data on the game server

No matter how you initiate match backfill requests in your game, your game server must be able to handle the game session updates that Amazon GameLift delivers as a result of match backfill requests.

When Amazon GameLift completes a match backfill request—successfully or not—it calls your game server using the callback function onUpdateGameSession. This call has three input parameters: a match backfill ticket ID, a status message , and a GameSession object containing the most up-to-date matchmaking data including player information. You need to add the following code to your game server as part of your game server integration:

  1. Implement the onUpdateGameSession function. This function must be able to handle the following status messages (updateReason):

    • MATCHMAKING_DATA_UPDATED – New players were successfully matched to the game session. The GameSession object contains updated matchmaker data, including player data on existing players and newly matched players.

    • BACKFILL_FAILED – The match backfill attempt failed due to an internal error. The GameSession object is unchanged.

    • BACKFILL_TIMED_OUT – The matchmaker failed to find a backfill match within the time limit. The GameSession object is unchanged.

    • BACKFILL_CANCELLED – The match backfill request was canceled by a call to StopMatchmaking (client) or StopMatchBackfill (server). The GameSession object is unchanged.

  2. For successful backfill matches, use the updated matchmaker data to handle the new players when they connect to the game session. At a minimum, you'll need to use the team assignments for the new player(s), as well as other player attributes that are required to get the player started in the game.

  3. In your game server's call to the Server SDK action ProcessReady(), add the onUpdateGameSession callback method name as a process parameter.