Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account

Add Amazon GameLift Servers to your game server

PDF
RSS
Focus mode
Add Amazon GameLift Servers to your game server - Amazon GameLift Servers
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

This topic describes how to modify your game server code so that game server processes can communicate with the Amazon GameLift Servers service. Use these instructions for game servers that you plan to deploy onto Amazon GameLift Servers managed EC2 fleets, managed container fleets, or Anywhere fleets.

Game server processes communicate with the Amazon GameLift Servers service to receive instructions from the service and to report server process health and game session status. For detailed information on interactions between your game hosting solution components (game server, backend service, game client, and Amazon GameLift Servers), see Game client/server interactions with Amazon GameLift Servers.

To prepare your game for hosting, add the server SDK for Amazon GameLift Servers to your game server project. If you're using the Amazon GameLift Servers plugin for Unreal Engine or Unity, the server SDK is built in and ready to use. The Server SDK is available in several languages. For more information about tool support for game servers, including the server SDK, see Get Amazon GameLift Servers development tools.

Server SDK API references:

Initialize the server process

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

  1. Initialize an Amazon GameLift Servers API client by calling InitSdk(). If you're preparing your game server to run on Amazon GameLift Servers managed EC2 fleets, use the default InitSDK() (C++) (C#) (Unreal) (Go) with no parameters. The API client handles connection to the Amazon GameLift Servers service for you.

    If you're preparing your game server for use on an Amazon GameLift Servers Anywhere fleet:

    Initialize the Amazon GameLift Servers API client by calling InitSdk() with the following 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 fleet containing your Amazon GameLift Servers Anywhere compute.

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

  2. Notify the service that the game server process is ready to host a game session. Call ProcessReady() (C++) (C#) (Unreal) (Go) with the following ProcessParameters. Each game server process must call ProcessReady() only once.

    • The port number for the server process. When the server process starts a game session, it provides the port to the Amazon GameLift Serversservice, which updates the game session information. Your game can retrieve this information and provide it to game clients, which use it to connect to the server process and join the game session.

    • The locations of files that you want Amazon GameLift Servers to store for you. These might include game session logs and other files that the server process generates during a game session. Although Amazon GameLift Servers saves these files temporarily on the compute where the server process is running, these are only available until the instance shuts down. You can access stored files through the Amazon GameLift Servers console or by calling the Amazon GameLift Servers API operation GetGameSessionLogUrl().

      If you're preparing your game server for use on an Amazon GameLift Servers managed containers fleet:

      You don't need to specify log parameters for a container fleet. Instead, send game session and other log data to standard output. Container fleets automatically capture all container standard output as a log stream.

    • The following callback functions that allow Amazon GameLift Servers to send messages or prompts to a game server process. Your must implement each of these functions in your game server code. For more information, see ProcessParameters(C++) (C#) (Unreal) (Go) .

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

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

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

      • (Optional) onUpdateGameSession – Amazon GameLift Servers 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 so that it can securely access other 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 Servers 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 Servers 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 Servers considers the server process to be healthy unless the server doesn't respond.

The Amazon GameLift Servers service 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 the service might shut down the process and start a new one. The service 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 Servers invokes this callback to start a game session on the server process.

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 the Amazon GameLift Servers service 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, the service 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 Servers tracks current players and available game session slots.

For validation, a game client that tries to join a game session must include a player session ID. Amazon GameLift Servers generates this ID when your game starts new game sessions by calling StartGameSessionPlacement() or StartMatchmaking(). On these requests, an open slot in a game session is reserved for the player 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 Servers verifies that the player session ID corresponds to an open slot reserved in the game session. After Amazon GameLift Servers validates the player session ID, the server process accepts the connection. The player can then join the game session. If Amazon GameLift Servers 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, add code to notify Amazon GameLift Servers when a player leaves the game session. This code should run whenever the server process detects a dropped connection. Amazon GameLift Servers 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 Servers when a game session is ending. To recycle and refresh hosting resources, shut down each server process 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 Servers that the server process is shutting down. Amazon GameLift Servers 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 the Amazon GameLift Servers service. The service 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 Servers can stop an instance as part of a capacity scale-down event, or in response to Spot Instance interruption. A Spot Instance interruption provides a two-minute notice, which gives the server process time to disconnect players gracefully, preserve game state data, and perform other cleanup tasks.

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

  • Implement the callback function onProcessTerminate() (C++) (C#) (Unreal) (Go) . This function should call code that shuts down the server process.

  • Call the server API operation GetTerminationTime() (C++) (C#) (Unreal) (Go) from your game server shutdown code. If Amazon GameLift Servers 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 the Amazon GameLift Servers service that the server process is shutting down. The service then changes the server process status to TERMINATED. After calling ProcessEnding(), it's safe for the process to shut down.

On this page

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.