Add Amazon GameLift to your game client - Amazon GameLift
Set up Amazon GameLift on a backend serviceGet game sessionsCreate game sessionsJoin a player to a game session
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).

Add Amazon GameLift to your game client

Integrate Amazon GameLift into game components that need game session information, create new game sessions, and add players to games. Depending on your game architecture, this functionality is in backend services that handle tasks such as player authentication, matchmaking, or game session placement.

Note

For detailed information about how to set up matchmaking for your Amazon GameLift hosted game, see the Amazon GameLift FlexMatch Developer Guide.

Set up Amazon GameLift on a backend service

Add code to initialize a game client and store key settings for use with Amazon GameLift. This code must run before any code dependent on Amazon GameLift.

  1. Use the default client configuration or create a custom client configuration object. For more information, see AWS::Client::ClientConfiguration (C++) or AmazonGameLiftConfig (C#).

    A client configuration specifies a target location and endpoint. The location determines which resources (such as fleets, queues, and matchmakers) Amazon GameLift interacts with when responding to requests. The default client configuration specifies the US East (N. Virginia) Region. To use any other location, create a custom configuration.

  2. Initialize a Amazon GameLift client. Use Aws::GameLift::GameLiftClient() (C++) or AmazonGameLiftClient() (C#) with a default client configuration or a custom client configuration.

  3. Add a mechanism to generate a unique identifier for each player. For more information, see Generate player IDs.

  4. Collect and store the following information to use when contacting Amazon GameLift:

    • Target fleet – Most Amazon GameLift API requests must specify a target fleet. To do so, use either a fleet ID or an alias ID that points to the target fleet. With fleet aliases, you can switch players from one fleet to another without issuing a game client update.

    • Target queue – If your game uses multi-fleet queues to place new game sessions, then you can specify which queue to use. To specify a target queue, use the queue name.

    • Amazon credentials – All calls to Amazon GameLift must provide credentials for the Amazon Web Services account that hosts the game. This is the same account that you used to set up your Amazon GameLift fleets. To provide access to your backend servers, create an Amazon Identity and Access Management (IAM) user or user group for players. Also create an Aws::Auth::AWSCredentials (C++) object containing an IAM access key and secret key for the player user group. For help with finding the keys, see Managing access keys for IAM users in the IAM User Guide.

Get game sessions

Add code to discover available game sessions and manage game session settings and metadata.

Search for active game sessions

Use SearchGameSessions to get information about a specific game session, all active sessions, or sessions that meet a set of search criteria. This call returns a GameSession object for each active game session that matches your search request.

Use search criteria to get a filtered list of active game sessions for players to join. For example, you can filter sessions as follows:

  • Exclude game sessions that are full: CurrentPlayerSessionCount = MaximumPlayerSessionCount.

  • Choose game sessions based on length of time that the session has been running: Evaluate CreationTime.

  • Find game sessions based on a custom game property: gameSessionProperties.gameMode = "brawl".

Manage game sessions

Use any of the following operations to retrieve or update game session information.

Create game sessions

Add code to start new game sessions on your deployed fleets and make them available to players. There are two options for creating game sessions, depending on whether you're deploying your game in multiple Amazon Web Services Regions or in a single Region.

Create a game session in a multi-location queue

Use StartGameSessionPlacement to place a request for a new game session in a queue. To use this operation, create a queue. This determines where Amazon GameLift places the new game session. For more information about queues and how to use them, see Setting up Amazon GameLift queues for game session placement.

When creating a game session placement, specify the name of the queue to use, a game session name, a maximum number of concurrent players, and an optional set of game properties. You can also optionally provide a list of players to automatically join the game session. If you include player latency data for relevant Regions, then Amazon GameLift uses this information to place the new game session on a fleet that provides the ideal gameplay experience for the players.

Game session placement is an asynchronous process. After you've placed a request, you can let it succeed or time out. You can also cancel the request at any time using StopGameSessionPlacement. To check the status of your placement request, call DescribeGameSessionPlacement.

Create a game session on a specific fleet

Use CreateGameSession to create a new session on a specified fleet. This synchronous operation succeeds or fails depending on whether the fleet has resources available to host a new game session. After Amazon GameLift creates the new game session and returns a GameSession object, you can join players to it.

When you use this operation, provide a fleet ID or alias ID, a session name, and the maximum number of concurrent players for the game. Optionally, you can include a set of game properties. Game properties are defined in an array of key-value pairs.

If you use the Amazon GameLift resource protection feature to limit the number of game sessions that one player can create, then provide the game session creator's player ID.

Join a player to a game session

Add code to reserve a player slot in an active game session and connect game clients to game sessions.

  1. Reserve a player slot in a game session

    To reserve a player slot, create a new player session for the game session. For more information about player sessions, see How players connect to games.

    There are two ways to create new player sessions:

    Amazon GameLift first verifies that the game session is accepting new players and has available player slots. If successful, Amazon GameLift reserves a slot for the player, creates the new player session, and returns a PlayerSession object. This object contains the DNS name, IP address, and port that a game client needs to connect to the game session.

    A player session request must include a unique ID for each player. For more information, see Generate player IDs.

    A player session can include a set of custom player data. This data is stored in the newly created player session object, which you can retrieve by calling DescribePlayerSessions(). Amazon GameLift also passes this object to the game server when the player connects directly to the game session. When requesting multiple player sessions, provide a string of player data for each player that's mapped to the player ID in the request.

  2. Connect to a game session

    Add code to the game client to retrieve the PlayerSession object, which contains the game session's connection information. Use this information to establish a direct connection to the server.

    • You can connect using the specified port and the DNS name or IP address assigned to the server process.

    • If your game server validates incoming player connections, then reference the player session ID.

    After making the connection, the game client and server process communicate directly without involving Amazon GameLift. The server maintains communication with Amazon GameLift to report player connection status, health status, and more. If the game server validates incoming players, then it verifies that the player session ID matches a reserved slot in the game session, and accepts or denies the player connection. When the player disconnects, the server process reports the dropped connection.