Add GameLift to your game server

Your custom game server needs to communicate with the GameLift service once it is deployed and running on GameLift instances. Each game server process must be able to respond to events when they are triggered by the GameLift service. It must also keep GameLift informed about the server process status and (optionally) player connections. For more detail on how your game server, your game client, and the GameLift service work together to manage game hosting, see GameLift and game client/server interactions.

To prepare your game server to interact with GameLift, add the GameLift Server SDK to your game server project and build in basic functionality described in this topic. The Server SDK is available in several languages. See GameLift SDKs to learn more about the GameLift Server SDK. Download the latest version of Server SDK.

Server SDK API references:

• C++ Server API Reference

• C# Server API Reference

• Unreal Engine Plugin API Reference

Initialize the server process

This task is required.

Add code to establish communication with the GameLift service and report that the server process is ready to host a game session. This code must run before any GameLift-dependent code, such as on launch.

Note

The names of Server API operations are the same in all available languages.

1. Initialize GameLift API client by calling InitSdk().

2. Notify GameLift that a server process is ready to host a game session. Call ProcessReady() (C#) (C++) (Unreal) with the following information. ProcessReady() should be called only once per server process.

   • Port number being used by the server process. The port number and an IP address are provided to game clients to that they can connect to the server process to join a game session.

   • Location of files, such as game session logs, that you want GameLift to retain. These are files that are generated by the server process during a game session. They are stored temporarily on the instance where the server process is running, and are lost when the instance shuts down. Any files that are listed here are uploaded to the GameLift service. You can access them through the GameLift console or by calling the GameLift Service API GetGameSessionLogUrl(). Tip: If your fleet is configured to run multiple concurrent server processes per instance, consider using a file naming scheme that uniquely identifies game sessions.

   • Names of callback functions that can be invoked by the GameLift service on the server process. Your game server needs to implement these functions. Instructions for implementing these functions is covered in the remainder of this topic. See also ProcessParameters.

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

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

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

     • onUpdateGameSession (optional) is called when the 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 if you're using the FlexMatch backfill feature.

   You can set up a game server to securely access AWS resources that you own or control. Learn more about how to Communicate with other AWS resources from your fleets.

Report server process health

This task is optional.

Add code to implement the callback function onHealthCheck(). This function is invoked by the GameLift service to periodically collect health metrics from the server process. The server process's response to a health check is a binary: either healthy or unhealthy. To implement 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 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 choose to not implement a health check callback, the GameLift service considers the server process to be healthy unless the process does not respond, in which case it is considered unhealthy.

Server process health is used by 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 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 GameLift console.

Retrieve a TLS certificate

This task is optional.

If the server process 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() (C#) (C++) (Unreal).

Start a game session

This task is required.

Add code to implement the callback function onStartGameSession. The GameLift service invokes this method in order to trigger a new game session on the server process, as part of game session placement or matchmaking placement activities.

The onStartGameSession function takes a GameSession object as an input parameter. This object includes key game session information, such as maximum players, and may include game data and player data. The function implementation should accomplish the following tasks:

• Initiate actions to create a new game session based on the GameSession properties. At a minimum, the game server needs to associate the game session ID, which game clients will reference when connecting to the server process.

• Process game data and player data as needed. This data is in the GameSession object,

• Notify GameLift when the new game session is ready to accept players. Call the server API action ActivateGameSession() (C#) (C++) (Unreal). In response to a successful call, the GameLift service changes the game session status to ACTIVE.

Validate a new player

This task is optional.

If you're tracking the status of player sessions, add code to validate new players when they connect to a game server. The purpose of validation is to enable GameLift to keep track of current players and available game session slots. In essence, your game server is verifying that the player who is trying to connect is the same person who reserved an open slot.

For validation, a game client that is requesting access to the game session must include a player session ID. This ID is automatically generated by the GameLift service when a player asks to join a game (such as with StartGameSessionPlacement() or StartMatchmaking()). The player session reserves an open slot in a game session.

When game server process receives a game client connection request, it calls AcceptPlayerSession() (C#) (C++) (Unreal) with the player session ID. In response, the GameLift service verifies that player session ID corresponds to an open slot reserved in the game session. After the player session ID is validated, 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 GameLift service, the server process should deny the connection.

Report a player session ending

This task is optional.

If you're tracking the status of player sessions, add code to notify the GameLift service when a player leaves the game session. This code should run whenever the server process detects a dropped connection. This notification enables the GameLift service to accurately track current players and available slots in the game session.

In your code to handle dropped connections, add a call to the server API action RemovePlayerSession() (C#) (C++) (Unreal) with the corresponding player session ID.

End a game session

This task is required.

Add code to notify the GameLift service when a game session is ending. As a best practice, server processes are shut down once a game session is completed in order to recycle and refresh hosting resources. This code should be added to the server process shutdown sequence.

At the start of the process server shutdown code, call the server API action ProcessEnding() (C#) (C++) (Unreal). This call notifies the GameLift service that the server process is shutting down. On receipt of this notification, the GameLift service changes the game session status and server process status to TERMINATED. After calling ProcessEnding(), it is safe for the process to shut down.

Respond to a server process shutdown notification

This task is required.

Add code to shut down the server process in response to notification from the GameLift service. GameLift sends this notification when the server process has been reported consistently unhealthy, or if the instance where the server process is running is being terminated. An instance might be terminated as part of a capacity scale-down event, or in response to Spot Instance interruption.

Make the following changes to your game server code to handle a shutdown notification:

• Implement the callback function onProcessTerminate(). This function should call the code that shuts down the server process. When GameLift invokes this method, the server process usually has a few minutes to gracefully disconnect players, preserve game state data, and perform other cleanup tasks. Spot Instance interruptions provide a two-minute notice.

• Call the server API action GetTerminationTime() (C#) (C++) from your game server shut-down code. If GameLift has issued a call to terminate the server process, GetTerminationTime() returns the estimated termination time.

• At the start of your game server shut-down code, call the server API action ProcessEnding() (C#) (C++) (Unreal). This call notifies the GameLift service that the server process is shutting down. On receipt of this notification, the GameLift service changes the server process status to TERMINATED. After calling ProcessEnding(), it is safe for the process to shut down.