Amazon GameLift
Developer Guide (Version )

Add FlexMatch to a Game Server

This topic describes how to integrate Amazon GameLift FlexMatch into your game server. This is one of several tasks required to add FlexMatch features to your game; see FlexMatch Integration Roadmap for the full process. For a detailed description of FlexMatch's customized matchmaking, see How Amazon GameLift FlexMatch Works.

The information in this topic assumes that you've successfully integrated the Amazon GameLift Server SDK into your game server project, as described in Add Amazon GameLift to Your Game Server. With this work completed, you have most of the mechanisms you need. The sections in this topic cover the remaining work needed to handle games that are set up with FlexMatch.

Set Up Your Game Server for Matchmaking

To set up your game server to handle matched games, complete the following tasks.

  1. Start game sessions created with matchmaking. To request a new game session, Amazon GameLift sends an onStartGameSession() request to your game server with a game session object (see GameSession). Your game server uses the game session information, including customized game data, to start the requested game session. For more details, see Start a Game Session.

    For matched games, the game session object contains a set of matchmaker data, described later in this topic. Matchmaker data includes information that your game server needs to set up a new game session for the match. This includes the match's team structure, team assignments, and certain player attributes. For example, you might use the average skill level of the players to unlock certain features or levels. As another example, you might allow players to choose multiple map preferences and then build matches with just one common map choice. In this scenario, you would use the player attribute data to determine the right map for the game session. See Work with Matchmaker Data for more details.

  2. Handle player connections. When connecting to a matched game, a game client references a player ID as well as the player session ID used for validation (see Validate a New Player) Your code must use the player ID to associate an incoming player with player information in the matchmaker data. Matchmaker data identifies each player's team assignment, and may provide other information required to correctly represent the player in the game. For example, player attributes might determine the player's game character, location or status in the game, etc.

  3. Report when players leave a game. Ensure that your game server is calling the Server API RemovePlayerSession() to report dropped players (see Report a Player Session Ending). This step is particularly important if you're using FlexMatch backfill to fill empty slots in existing games, and critical when initiating backfill requests in a client-side game service. For more on implementing FlexMatch backfill, see Backfill Existing Games with FlexMatch.

  4. Request new players for existing matched game sessions (optional). If you intend to use the match backfill feature to add new players to existing games, you may want to send backfill requests directly from the game server. For more details, including request options, see Backfill Existing Games with FlexMatch. Learn more about the match backfill feature in Matchmaking Process.

Work with Matchmaker Data

Your game server must be able to recognize and use the game information in a GameSession object. The Amazon GameLift service passes these objects to your game server whenever a game session is started or updated. Core game session information includes game session ID and name, maximum player count, connection information, and custom game data (if provided).

For game sessions that are created using FlexMatch, the GameSession object also contains a set of matchmaker data that was generated as part of the matchmaking process. In addition to a unique match ID, it identifies the matchmaker that was used to create the match and describes the teams, team assignments, and players. It includes the player attributes from the original matchmaking request (see the Player object). It doesn't include the player latency; if you need latency data on current players, such as for match backfill, we recommend getting fresh data.


Matchmaker data specifies the full matchmaking configuration ARN, which identifies the configuration name, AWS account, and region. When requesting match backfill, you need either the full configuration ARN (when requesting from a game server) or just the configuration name (when requesting from a game client or client service). You can extract the configuration name from an ARN value by parsing out the string that follows ":matchmakingconfiguration/". In the example shown, the matchmaking configuration name is "MyMatchmakerConfig".

The following JSON shows a typical set of matchmaker data. This example describes a two-player game, with players matched based on skill ratings and highest level attained. The matchmaker also matched based on character, and ensured that matched players have at least one map preference in common. In this example scenario, the game server should be able to detect the common map--or select from multiple common preferences--to determine which map to assign for the game session.

{ "matchId":"1111aaaa-22bb-33cc-44dd-5555eeee66ff", "matchmakingConfigurationArn":"arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig", "teams":[ {"name":"attacker", "players":[ {"playerId":"4444dddd-55ee-66ff-77aa-8888bbbb99cc", "attributes":{ "skills":{ "attributeType":"STRING_DOUBLE_MAP", "valueAttribute":{"Body":10.0,"Mind":12.0,"Heart":15.0,"Soul":33.0}} } }] },{ "name":"defender", "players":[{ "playerId":"3333cccc-44dd-55ee-66ff-7777aaaa88bb", "attributes":{ "skills":{ "attributeType":"STRING_DOUBLE_MAP", "valueAttribute":{"Body":11.0,"Mind":12.0,"Heart":11.0,"Soul":40.0}} } }] }] }