Generate manual backfill requests from a backend service - 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 backend 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 Roadmap: Add matchmaking to a Amazon GameLift Servers hosting solution.

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 Servers API. This SDK is available in C++, C#, and several other languages. For a general description of client APIs, see the Amazon GameLift Servers API Reference, which describes the service API for Amazon GameLift Servers actions and 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 Servers 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 About 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.