Amazon GameLift
Developer Guide (Version )

Add FlexMatch to a Game Client

This topic describes how to initiate the FlexMatch matchmaking process for your players. To learn more about FlexMatch and how to set it up for your games, see the these topics:


When requesting matchmaking for your players, we highly recommend making these requests through a client-side game service, and not directly from your game client. By using a trusted source, you can more easily protect against hacking attempts and also avoid the use of fake player data that can ruin the game experience for your players. If your game uses a session directory service, this is a good option for handling matchmaking requests.

As with other client functionality, your game service enables matchmaking by using the AWS SDK with the 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.

The information in this topic assumes that you've (1) created a matchmaking configuration (see Design a FlexMatch Matchmaker); and (2) successfully integrated Amazon GameLift into the game service (see Add Amazon GameLift to Your Game Client). To test FlexMatch in your game, you also need to set up your game server to properly start game sessions for matches (see Add FlexMatch to a Game Server.

To enable FlexMatch for your game clients, you'll need to add the following functionality:

  • Request matchmaking for one or more players.

  • Track the status of matchmaking requests.

  • Request player acceptance for a proposed match.

  • Once a game session is created for the new match, get player connection information and join the game.

When using FlexMatch, you may want to set up backfilling for your games. Match backfill helps keep game sessions filled as players leave the game, and is particularly useful in games with longer life spans. It ensures that new players who enter a game meet the same match criteria as existing players. Learn more about match backfill in How Amazon GameLift FlexMatch Works. For help setting it up, see Backfill Existing Games with FlexMatch.

Request Matchmaking for Players

Add code to create and send a matchmaking request to a FlexMatch matchmaker. To manage matchmaking requests, use these APIs:

To create a matchmaking request, call StartMatchmaking with the following information.


Specify the name of the matchmaking configuration to use for the request. FlexMatch places each request into the request pool for the specified matchmaker, and the request will be processed according to the matchmaker's configuration and rule set.

Ticket ID

Specify a ticket ID. All matchmaking requests must be given a unique ticket ID. You are responsible for generating, assigning, and managing ticket IDs. You can use any string format, up to a maximum of 128 characters. Ticket IDs are attached to all requests, events and notifications related to matchmaking.

Player data

Specify one or more players you want to create a match for. If you include multiple players in a single request, FlexMatch tries to create a match for all the players and place them into the same team. All players in a request must pass matchmaking rules for the request to be matched.


A player (identified by their player ID) can only be included in one active matchmaking request at a time. If you create a new request for a player, any active matchmaking tickets with the same player ID are automatically canceled.

  • Player ID – Each player must have a unique player ID, generated by you. For more information, see Generate Player IDs.

  • Player attributes – For each player in a request, there should be a set of player attribute values as required by the matchmaker; these are defined in the matchmaker's rule set and support rules that evaluate potential matches based on player attributes like individual skill level. The attribute name and data type in the matchmaking request must match that defined in the matchmaker's rule set. Attributes in a rule set can be configured with a default value to be used when a matchmaking request does not provide one. However, if an attribute has no default value, and the matchmaking request does not provide one, the player cannot be matched (and the matchmaking request will never succeed). For more information on matchmaker rule sets and player attributes, see Build a FlexMatch Rule Set.

  • Player latencies – Player latency data contains reported latency values for one or more regions. Player latency data may be used to find matches between players who report similar latencies; when provided, it is also used to place a match's game session in a region that offers the lowest possible latency for all players in the match.

    If a matchmaker has a rule that evaluates player latency, players must report latency to be matched. In this case, players can only be matched in regions that a latency value is provided for.

Additional factors that affect a matchmaking request are set in the matchmaking configuration, including a time limit for requests, and optional player acceptance of matches. All matchmaking requests sent to a matchmaker are processed as configured. For more information on configuring a matchmaker and setting match rules, see Design a FlexMatch Matchmaker.

A matchmaking request can be canceled at any time using StopMatchmaking.

Track Matchmaking Request Status

Add code to game service to track the status of all matchmaking requests and respond as needed. There are a couple of options available for tracking status.

Event notifications

Set up notifications to track events that Amazon GameLift emits for matchmaking processes. This is the recommended method; it is simple to set up and an efficient use of resources. You can set up notifications either directly, by creating an SNS topic, or by using CloudWatch Events. For more information on setting up notifications, see Set up FlexMatch Event Notification. Once you've set up notifications, you need to add a listener on your game service to detect the events and respond as needed. It's also a good idea to poll for status updates if you haven't received a notification after 30 seconds.

Continuous polling

Retrieve a matchmaking request ticket, including current status, by calling DescribeMatchmaking. This call returns complete information about the matchmaking request. Once a request has been successfully completed, the ticket also contains the information needed to connect a player to the match. We recommend polling no more than once every 10 seconds.

Request Player Acceptance

For requests that use a matchmaker with player acceptance turned on, your game service must be able to do the following:

  1. Detect when player acceptance is required. Your game service must be able to detect when a matchmaking ticket's status is REQUIRES_ACCEPTANCE. If you're monitoring notifications, a change to this status triggers the FlexMatch event MatchmakingRequiresAcceptance.

  2. Get acceptances from all players. Your game service must have a mechanism to present the match details to each player in the matchmaking ticket and solicit an acceptance or rejection. You can retrieve match details by calling DescribeMatchmaking.

  3. Report player responses to FlexMatch. Report each player acceptance by calling AcceptMatch with either accept or reject. All players in a matchmaking request must accept the match for it to go forward.

  4. Handle tickets with failed acceptances. Your game service should have a way to handle matchmaking requests that fail player acceptance. This includes requests where any player in the request either rejects the match or fails to respond by the acceptance time limit.

Connect to a Match

Add code to your game service to handle a successfully completed match (status COMPLETED or event MatchmakingSucceeded) as needed. This includes handing off the match's connection information to game clients. When a matchmaking request is completed, connection information is added to the matchmaking ticket. Connection information (see GameSessionConnectionInfo) includes the game session IP address and port, as well as a set of player IDs and player session IDs for all players in the match. Retrieve a completed matchmaking ticket by calling DescribeMatchmaking.

Your game client uses this information to connect directly to the server process that is hosting the match. A connection request for a matched game session must include a player session ID and a player ID. As with all game session connections, the player session ID is used to validate the player's connection request and claim a reserved slot in the game session. For matched game sessions, the player ID associates the connected player to a set of matchmaker data, including team assignments, that describe the game session (see GameSession).

Sample StartMatchmaking Requests

The following code example builds matchmaking requests for a variety of matchmakers. As discussed, each matchmaker has its own requirements for player attributes, and matchmaking requests must match those requirements.

# Uses matchmaker for two-team game mode based on player skill level def start_matchmaking_for_cowboys_vs_aliens(config_name, ticket_id, player_id, skill, team): response = gamelift.start_matchmaking( ConfigurationName=config_name, Players=[{ "PlayerAttributes": { "skill": {"N": skill} }, "PlayerId": player_id, "Team": team }], TicketId=ticket_id) # Uses matchmaker for monster hunter game mode based on player skill level def start_matchmaking_for_players_vs_monster(config_name, ticket_id, player_id, skill, is_monster): response = gamelift.start_matchmaking( ConfigurationName=config_name, Players=[{ "PlayerAttributes": { "skill": {"N": skill}, "desiredSkillOfMonster": {"N": skill}, "wantsToBeMonster": {"N": int(is_monster)} }, "PlayerId": player_id }], TicketId=ticket_id) # Uses matchmaker for brawler game mode with latency def start_matchmaking_for_three_team_brawler(config_name, ticket_id, player_id, skill, role): response = gamelift.start_matchmaking( ConfigurationName=config_name, Players=[{ "PlayerAttributes": { "skill": {"N": skill}, "character": {"S": [role]}, }, "PlayerId": player_id, "LatencyInMs": { "us-west-2": 20} }], TicketId=ticket_id) # Uses matchmaker for multiple game modes and maps based on player experience def start_matchmaking_for_multi_map(config_name, ticket_id, player_id, skill, maps, modes): response = gamelift.start_matchmaking( ConfigurationName=config_name, Players=[{ "PlayerAttributes": { "experience": {"N": skill}, "gameMode": {"SL": modes}, "mapPreference": {"SL": maps} }, "PlayerId": player_id }], TicketId=ticket_id)