AWS Documentation » Amazon GameLift » Developer Guide » Preparing Games for Amazon GameLift » Integrating Games with Custom Game Servers » Integrating your Game Server for Amazon GameLift » Add Amazon GameLift to Your Game Server

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Add Amazon GameLift to Your Game Server

Your game server needs to communicate with the Amazon GameLift service once it is deployed and running on Amazon GameLift instances. Each game server process must be able to respond to events when they are triggered by the Amazon GameLift service, and it must keep Amazon GameLift informed about the server process status and (optionally) player connections. For more details, see Amazon GameLift and Game Client/Server Interactions.

Integrate the Amazon GameLift Server SDK to your game server. See Amazon GameLift SDKs to learn more about the Server SDK and download the latest version. The Server SDK is available in several languages, see these API references for complete information:

• C++ Server API Reference

• C# Server API Reference

• Unreal Engine Plugin API Reference

To integrate Amazon GameLift into your game server, add the Amazon GameLift Server SDK to your game server project and build the basic functionality described in this topic.

Prepare a Server Process

Add code to initialize an Amazon GameLift client and notify the Amazon GameLift service that the server is ready to host a game session. This code should run automatically before any Amazon GameLift-dependent code, such as on launch.

Note

Server API action names are the same in all available languages.

1. Initialize the Server SDK. Call InitSdk().

2. Notify Amazon GameLift that a game server process is ready to host a game session. Each server process started on an Amazon GameLift instance must call ProcessReady() with the following information:

   • Port number being used by the server process. This port number, along with an IP address, is stored in a game session object, which game clients use when connecting to an active game session.

   • Location of files generated during an active game session that you want Amazon GameLift to retain, such as game session logs. Files generated by a server process when hosting a game session are saved to the Amazon GameLift instance, but lost when an instance is shut down. Amazon GameLift will upload any of these files you request; once uploaded, they are accessible through the Amazon GameLift console or by calling the Amazon GameLift API GetGameSessionLogUrl(). Consider using a file naming scheme that uniquely identifies game sessions if your fleet is configured to run multiple concurrent server processes per instance.

   • Names of callback functions used by Amazon GameLift to trigger certain actions on the server process. More information on implementing these functions is provided in the following sections and in ProcessParameters.

     • onHealthCheck (required) is called regularly to request a health status report from the server process.

     • onStartGameSession (required) is called when the Amazon GameLift service receives request to start a new game session (CreateGameSession()).

     • onProcessTerminate (required) is called when the Amazon GameLift service needs to force the server process to terminate, allowing the server process to shut down gracefully.

     • onUpdateGameSession (optional) is called when the Amazon GameLift service delivers an updated game session object to the game server or provides a status update on a match backfill request. This callback is required only if you're using the FlexMatch backfill feature. Learn more about how to implement this callback function at Update Match Data on the Game Server.

   Depending on how you configure your fleets, there may be multiple server processes running concurrently on a fleet instance. Once one server process on an instance calls ProcessReady() successfully, the Amazon GameLift service sets the instance's status to ACTIVE.

   You can set up a game server to securely access your resources on other AWS services. Learn more about possible ways to do this in Access AWS Resources From Your Fleets.

Report Server Process Health

Add code to implement the callback function onHealthCheck(). This function is invoked by the Amazon GameLift service regularly to collect health metrics from the server process. The server process's response to a health check is a binary: healthy or unhealthy. When implementing this callback function, do the following:

• Evaluate the status of the server process using whatever measures make sense for your game. For example, you might report the server process as unhealthy if any external dependencies have failed or if metrics such as memory capacity fall outside a defined limit.

• Complete the health evaluation and respond to the callback within 60 seconds. If the Amazon GameLift service does not receive a response in that time, it will automatically consider the server process to be unhealthy.

• Return a boolean value: true for healthy, false for unhealthy.

If you do not implement a health check callback, the Amazon GameLift service considers the server process to be healthy unless the process is not responding, in which case it is considered unhealthy.

Server process health is used by Amazon GameLift to efficiently end unhealthy processes and free up resources. If a server process continues to report unhealthy or does not respond for three consecutive health checks, the Amazon GameLift service may shut down the process and start a new one. Metrics on a fleet's server process health is collected and viewable on the Amazon GameLift console.

Start a Game Session

Add code to implement the callback function onStartGameSession. This function is invoked by the Amazon GameLift service when creating a new game session, which may occur in response to a CreateGameSession() request or as part of game session placement or matchmaking activities.

The onStartGameSession function takes a GameSession object, provided by the Amazon GameLift service, as an input parameter. This object contains the game session ID and other information that defines the requested game session. The function should accomplish the following tasks:

• Perform whatever actions are needed to create a new game session. The new game session should reflect the GameSession object, including creating slots for the specified maximum number of players and referencing the game session name and ID. The Amazon GameLift service provides the same game session information to the game client.

• Process the game property values specified by the game client in its request. The game properties are contained in the GameSession object.

• At some point after the new game session is ready to accept players, the server process must call the server API action ActivateGameSession(). In response to a successful call, the Amazon GameLift service changes the game session status to ACTIVE.

Retrieve a TLS Certificate

If the game server is running on a fleet that has TLS certificate generation enabled, you can retrieve the TLS certificate and use it to establish a secure connection with a game client and encrypt client/server communication. A copy of the certificate is stored on the instance. To get the file location, call GetInstanceCertificate().

Validate a New Player

Add code to verify a player connection request with the Amazon GameLift service. This code should run whenever a new player attempts to connect to the server process and before accepting the connection.

Connection requests from a game client must reference a player session ID. This ID is issued by the Amazon GameLift service and used to reserve a player slot in the game session (in response to an AWS SDK call to CreatePlayerSession()). The game server must call AcceptPlayerSession() with the referenced player session ID to verify that the connection request is coming from the authorized player.

Once the player session ID is validated by the Amazon GameLift service, the server process can accept the connection and allow the player to join the game session. If the player session ID is not validated by the Amazon GameLift service, the server process should deny the connection.

To acquire player data associated with the game session, call DescribePlayerSessions().

Report a Player Session Ending

Add code to notify the Amazon GameLift service when a player disconnects from the game session. This code should run whenever the server process detects a dropped connection.

In the code handling the dropped connection, add a call to the server API action RemovePlayerSession() with the player session ID associated with the dropped connection. This notification enables the Amazon GameLift service to accurately track the number of current players and available slots in the game session.

Stop a Game Session

Add code to notify the Amazon GameLift service when a game session is ending. The notification enables the Amazon GameLift service to accurately track a server process's availability for new game sessions. This code should be added to the normal game session ending process.

At the end of the code to stop a game session, add a call to the server API action TerminateGameSession(). On successful receipt of this notification, the Amazon GameLift service changes the game session status to TERMINATED and may immediately start a new game session.

Note

If stopping a game session will be immediately followed by shutting down the server process, you can call the server API action ProcessEnding(), which terminates both the game session and the server process.

Shut Down a Server Process

Shut down may be initiated by a server process or by the Amazon GameLift service. Make the following changes to your game server code to handle either scenario.

• Implement the callback function onProcessTerminate(). This function should call your code that shuts down the game server. The Amazon GameLift service calls this function to initiate a server process shut down, usually prior to terminating the instance that is running the server process. Reasons to invoke this call is when Amazon GameLift is shutting down an unhealthy server process, when a spot instance is interrupted, or when instance capacity is scaling down. After receiving this call, the server process usually has a few minutes (two minutes in the case of a spot instance termination) to gracefully disconnect players, preserve game state data, and perform other cleanup tasks.

• Call the server API action GetTerminationTime() from your game server shut-down code. If Amazon GameLift has issued a call to terminate the server process, GetTerminationTime() returns the estimated termination time, if available. You can use this information to determine which shut-down activities can be done in the time remaining, such as saving game state data or migrating players to a new game session.

• At the start of your game server shut-down code, call the server API action ProcessEnding(). This call notifies the Amazon GameLift service that the server process is shutting down. On receipt of this notification, the Amazon GameLift service changes the server process status to TERMINATED and may immediately recycle the instance's resources as needed. This also ensures that no new game sessions are sent to the process. Once ProcessEnding() has been invoked, it is safe for the process to shut down.