Generate manual backfill requests from a game server - Amazon GameLift Servers
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).

Generate manual backfill requests from a game server

You can manually initiate match backfill requests from the game server process that is hosting the game session. The server process has the most up-to-date information on 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 Roadmap: Add matchmaking to a Amazon GameLift Servers hosting solution.

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

As with other server functionality, a game server uses the Amazon GameLift Servers 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 Servers 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 About 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 Servers 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.