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 sessionUse game session properties

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 an Amazon GameLift client and store key settings. This code must run before any code dependent on Amazon GameLift.

  1. Set up a client configuration. 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 region and endpoint to use when contacting Amazon GameLift. Region identifies the set of deployed resources (fleets, queues, and matchmakers) to use. The default client configuration sets location to the US East (N. Virginia) Region. To use any other Region, create a custom configuration.

  2. Initialize an 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:

    • Target fleet – Many Amazon GameLift API requests must specify a fleet. To do so, use either a fleet ID or an alias ID that points to the target fleet. As a best practice, use fleet aliases so that you can switch players from one fleet to another without having to update your backend services.

    • Target queue – For games that use multi-fleet queues to place new game sessions, specify the name of the queue to use.

    • AWS credentials – All calls to Amazon GameLift must provide credentials for the AWS account that hosts the game. You acquire these credentials by creating a player user, as described in Set up programmatic access for your game. Depending on how you manage access for the player user, do the following:

      • If you use a role to manage player user permissions, add code to assume the role before calling an Amazon GameLift API. The request to assume the role returns a set of temporary security credentials. For more information, see Switching to an IAM role (AWS API) in the IAM User Guide.

      • If you have long-term security credentials, configure your code to locate and use stored credentials. See Authenticate using long-term credentials in in the AWS SDKs and Tools Reference Guide. For information on storing credentials, see theAWS API references for (C++) and (.NET).

      • If you have temporary security credentials, add code to regularly refresh the credentials using the AWS Security Token Service (AWS STS), as described in Using temporary security credentials with the AWS SDKs in the IAM User Guide. The code must request new credentials before the old ones expire.

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 AWS 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 Managing game session placement with Amazon GameLift queues.

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 fleets have TLS certificate generation enabled, then connect using the DNS name and port.

    • 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.

Use game session properties

Your game client can pass data into a game session by using a game property. Game properties are key-value pairs that your game server can add, read, list, and change. You can pass in a game property when you're creating a new game session, or later when the game session is active. A game session can contain up to 16 game properties. You cannot delete game properties.

For example, your game offers these difficulty levels: Novice, Easy, Intermediate, and Expert. A player chooses Easy, and then begins the game. Your game client requests new game session from Amazon GameLift by using either StartGameSessionPlacement or CreateGameSession as explained in the preceding sections. In the request, the client passes this : {"Key": "Difficulty", "Value":"Easy"}.

In response to the request, Amazon GameLift creates a GameSession object that contains the specified game property. Amazon GameLift then instructs an available game server to start the new game session and passes the GameSession object. The game server starts a game session with a Difficulty of Easy.

Learn more