Add Amazon GameLift to your game server - Amazon GameLift
Initialize the server process(Optional) Report server process health(Optional) Get a TLS certificateStart a game session(Optional) Validate a new player(Optional) Report a player session endingEnd a game sessionRespond to a server process shutdown notification

Add Amazon GameLift to your game server

This topic describes how to modify your game server code to add code for use with Amazon GameLift. Use these instructions for game servers that you plan to deploy onto Amazon GameLift managed EC2 fleets, managed container fleets, or Anywhere fleets.

Your custom game server must communicate with Amazon GameLift, because each game server process must be able to respond to events that Amazon GameLift starts. Your game server must also keep Amazon GameLift informed about the server process status and player connections. For more information about how your game server, backend service, game client, and Amazon GameLift work together to manage game hosting, see Game client/server interactions with Amazon GameLift.

To prepare your game server to interact with Amazon GameLift, add the Amazon GameLift Server SDK to your game server project and build in the functionality described in this topic. The Server SDK is available in several languages. For more information about the Amazon GameLift Server SDK, see Get Amazon GameLift development tools.

Server SDK API references:

Initialize the server process

Add code to establish communication with Amazon GameLift and to report that the server process is ready to host a game session. This code must run before any Amazon GameLift code.

  1. Initialize Amazon GameLift API client by calling InitSdk(). To initialize a game server process that is running on an Amazon GameLift managed EC2 instance, use the default InitSDK() (C++) (C#) (Unreal) (Go) without parameters. Amazon GameLift automatically connects to Amazon GameLift for you.

    Note

    To initialize a game server process that is running on an Amazon GameLift Anywhere compute resource, call InitSdk() with ServerParameters:

    • The URL of the websocket used to connect to your game server.

    • The ID of the process used to host your game server.

    • The ID of the compute hosting your game server processes.

    • The ID of the GameLift fleet containing your Amazon GameLift Anywhere compute.

    • The authorization token generated by the Amazon GameLift operation GetComputeAuthToken.

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

    • The port number that the server process uses. The backend service provides the port number and an IP address to game clients to connect to the server process and join a game session.

    • The location of files, such as game session logs, that you want Amazon GameLift to retain. The server process generates these files during a game session. They're temporarily stored on the instance where the server process is running, and they're lost when the instance shuts down. Any files that you list are uploaded to Amazon GameLift. You can access these files through the Amazon GameLift console or by calling the Amazon GameLift API operation GetGameSessionLogUrl().

      Note

      If plan to deploy the game server to a managed container fleet, you don't need to specify log parameters. Instead, send game session and other log data to standard output. Container fleets automatically capture all container standard output as a log stream.

    • The names of callback functions that Amazon GameLift can call to your server process. Your game server must implement these functions. For more information, see (C++) (C#) (Unreal) (Go) .

      • (Optional) onHealthCheck – Amazon GameLift calls this function regularly to request a health status report from the server.

      • onStartGameSession – Amazon GameLift calls this function in response to the client request CreateGameSession().

      • onProcessTerminate – Amazon GameLift forces the server process to stop, letting it shut down gracefully.

      • (Optional) onUpdateGameSession – Amazon GameLift delivers an updated game session object to the game server or provides a status update on a match backfill request. The FlexMatch backfill feature requires this callback.

    You can also set up a game server to securely access AWS resources that you own or control. For more information, see Communicate with other AWS resources from your fleets.

(Optional) Report server process health

Add code to your game server to implement the callback function onHealthCheck(). Amazon GameLift invokes this callback method periodically to collect health metrics. To implement this callback function, do the following:

  • Evaluate the health status of the server process. For example, you might report the server process as unhealthy if any external dependencies have failed.

  • Complete the health evaluation and respond to the callback within 60 seconds. If Amazon GameLift doesn't receive a response in that time, it automatically considers the server process to be unhealthy.

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

If you don't implement a health check callback, then Amazon GameLift considers the server process to be healthy unless the server doesn't respond.

Amazon GameLift uses server process health to end unhealthy processes and clear up resources. If a server process continues to report as unhealthy or doesn't respond for three consecutive health checks, then Amazon GameLift might shut down the process and start a new one. Amazon GameLift collects metrics on a fleet's server process health.

(Optional) Get a TLS certificate

If the server process is running on a fleet that has TLS certificate generation activated, then you can retrieve the TLS certificate to establish a secure connection with a game client and to encrypt client server communication. A copy of the certificate is stored on the instance. To get the file location, call GetComputeCertificate() (C++) (C#) (Unreal) (Go) .

Start a game session

Add code to implement the callback function onStartGameSession. Amazon GameLift invokes this callback to start a game session on the server.

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

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

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

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

(Optional) Validate a new player

If you're tracking the status of player sessions, then add code to validate a new player when they connect to a game server. Amazon GameLift tracks current players and available game session slots.

For validation, a game client requesting access to the game session must include a player session ID. Amazon GameLift automatically generates this ID when a player asks to join a game using StartGameSessionPlacement() or StartMatchmaking(). The player session then reserves an open slot in a game session.

When the game server process receives a game client connection request, it calls AcceptPlayerSession() (C++) (C#) (Unreal) (Go) with the player session ID. In response, Amazon GameLift verifies that the player session ID corresponds to an open slot reserved in the game session. After Amazon GameLift validates the player session ID, the server process accepts the connection. The player can then join the game session. If Amazon GameLift doesn't validate the player session ID, then the server process denies the connection.

(Optional) Report a player session ending

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

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

End a game session

Add code to the server process shutdown sequence to notify Amazon GameLift when a game session is ending. To recycle and refresh hosting resources, Amazon GameLift shuts down server processes after the game session is complete.

At the start of the server process shutdown code, call the server API operation ProcessEnding() (C++) (C#) (Unreal) (Go) g . This call notifies Amazon GameLift that the server process is shutting down. Amazon GameLift changes the game session status and server process status to TERMINATED. After calling ProcessEnding(), it's safe for the process to shut down.

Respond to a server process shutdown notification

Add code to shut down the server process in response to a notification from Amazon GameLift. Amazon GameLift sends this notification when the server process consistently reports unhealthy, or if the instance where the server process is running is being terminated. Amazon GameLift can stop an instance as part of a capacity scale-down event, or in response to Spot Instance interruption.

To handle a shutdown notification, make the following changes to your game server code:

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

  • Call the server API operation GetTerminationTime() (C++) (C#) (Unreal) (Go) from your game server shutdown code. If Amazon GameLift has issued a call to stop the server process, then GetTerminationTime() returns the estimated termination time.

  • At the start of your game server shutdown code, call the server API operation ProcessEnding() (C++) (C#) (Unreal) (Go) . This call notifies Amazon GameLift that the server process is shutting down, and Amazon GameLift then changes the server process status to TERMINATED. After calling ProcessEnding(), it's safe for the process to shut down.