Menu
Amazon GameLift
Developer Guide (Version )

Amazon GameLift Server API (C++) Reference: Actions

This Amazon GameLift C++ Server API reference can help you prepare your multiplayer game for use with Amazon GameLift. For details on the integration process, see Add Amazon GameLift to Your Game Server.

This API is defined in GameLiftServerAPI.h, LogParameters.h, ProcessParameters.h .

AcceptPlayerSession()

Notifies the Amazon GameLift service that a player with the specified player session ID has connected to the server process and needs validation. Amazon GameLift verifies that the player session ID is valid—that is, that the player ID has reserved a player slot in the game session. Once validated, Amazon GameLift changes the status of the player slot from RESERVED to ACTIVE.

Syntax

GenericOutcome AcceptPlayerSession(const std::string& playerSessionId);

Parameters

playerSessionId

Unique ID issued by the Amazon GameLift service in response to a call to the AWS SDK Amazon GameLift API action CreatePlayerSession. The game client references this ID when connecting to the server process.

Type: std::string

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example illustrates a function for handling a connection request, including validating and rejecting invalid player session IDs.

void ReceiveConnectingPlayerSessionID (Connection& connection, const std::string& playerSessionId){ Aws::GameLift::GenericOutcome connectOutcome = Aws::GameLift::Server::AcceptPlayerSession(playerSessionId); if(connectOutcome.IsSuccess()) { connectionToSessionMap.emplace(connection, playerSessionId); connection.Accept(); } else { connection.Reject(connectOutcome.GetError().GetMessage(); } }

ActivateGameSession()

Notifies the Amazon GameLift service that the server process has started a game session and is now ready to receive player connections. This action should be called as part of the onStartGameSession() callback function, after all game session initialization has been completed.

Syntax

GenericOutcome ActivateGameSession();

Parameters

This action has no parameters.

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example shows ActivateGameSession() being called as part of the onStartGameSession() callback function.

void onStartGameSession(Aws::GameLift::Model::GameSession myGameSession) { // game-specific tasks when starting a new game session, such as loading map GenericOutcome outcome = Aws::GameLift::Server::ActivateGameSession(); }

DescribePlayerSessions()

Retrieves player session data, including settings, session metadata, and player data. Use this action to get information for a single player session, for all player sessions in a game session, or for all player sessions associated with a single player ID.

Syntax

DescribePlayerSessionsOutcome DescribePlayerSessions ( const Aws::GameLift::Server::Model::DescribePlayerSessionsRequest &describePlayerSessionsRequest);

Parameters

describePlayerSessionsRequest

A DescribePlayerSessionsRequest object describing which player sessions to retrieve.

Required: Yes

Return Value

If successful, returns a DescribePlayerSessionsOutcome object containing a set of player session objects that fit the request parameters. Player session objects have a structure identical to the AWS SDK Amazon GameLift API PlayerSession data type.

Example

This example illustrates a request for all player sessions actively connected to a specified game session. By omitting NextToken and setting the Limit value to 10, Amazon GameLift returns the first 10 player sessions records matching the request.

// Set request parameters Aws::GameLift::Server::Model::DescribePlayerSessionsRequest request; request.SetPlayerSessionStatusFilter(Aws::GameLift::Server::Model::PlayerSessionStatusMapper::GetNameForPlayerSessionStatus(Aws::GameLift::Server::Model::PlayerSessionStatus::Active)); request.SetLimit(10); request.SetGameSessionId("the game session ID"); // can use GetGameSessionId() // Call DescribePlayerSessions Aws::GameLift::DescribePlayerSessionsOutcome playerSessionsOutcome = Aws::GameLift::Server::DescribePlayerSessions(request);

GetGameSessionId()

Retrieves a unique identifier for the game session currently being hosted by the server process, if the server process is active. The identifier is returned in ARN format: arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>.

Syntax

AwsStringOutcome GetGameSessionId();

Parameters

This action has no parameters.

Return Value

If successful, returns the game session ID as an AwsStringOutcome object. If not successful, returns an error message.

Example

Aws::GameLift::AwsStringOutcome sessionIdOutcome = Aws::GameLift::Server::GetGameSessionId();

GetSdkVersion()

Returns the current version number of the SDK in use.

Syntax

AwsStringOutcome GetSdkVersion();

Parameters

This action has no parameters.

Return Value

If successful, returns the current SDK version as an AwsStringOutcome object. The returned string includes the version number only (ex. "3.1.5"). If not successful, returns an error message.

Example

Aws::GameLift::AwsStringOutcome SdkVersionOutcome = Aws::GameLift::Server::GetSdkVersion();

GetTerminationTime()

Returns the time that a server process is scheduled to be shut down, if a termination time is available. A server process takes this action after receiving an onProcessTerminate() callback from the Amazon GameLift service. A server process may be shut down for several reasons: (1) process poor health, (2) when an instance is being terminated during a scale-down event, or (3) when an instance is being terminated due to a spot-instance interruption.

If the process has received an onProcessTerminate() callback, the value returned is the estimated termination time in epoch seconds. If no termination time is available, the value returned is -1, which indicates that the server process may be terminated at any time. If the process has not received an onProcessTerminate() callback, the returned value will always be -1. Learn more about shutting down a server process.

Syntax

AwsLongOutcome GetTerminationTime();

Parameters

This action has no parameters.

Return Value

If successful, returns the current SDK version as an AwsLongOutcome object. The value is either the termination time in epoch seconds, or the value -1. If not successful, returns an error message.

Example

Aws::GameLift::AwsLongOutcome TermTimeOutcome = Aws::GameLift::Server::GetTerminationTime();

InitSDK()

Initializes the Amazon GameLift SDK. This method should be called on launch, before any other Amazon GameLift-related initialization occurs.

Syntax

InitSDKOutcome InitSDK();

Parameters

This action has no parameters.

Return Value

If successful, returns an InitSdkOutcome object indicating that the server process is ready to call ProcessReady().

Example

Aws::GameLift::Server::InitSDKOutcome initOutcome = Aws::GameLift::Server::InitSDK();

ProcessEnding()

Notifies the Amazon GameLift service that the server process is shutting down. This method should exit with an exit code of 0; a non-zero exit code results in an event message that the process did not exit cleanly.

Syntax

GenericOutcome ProcessEnding();

Parameters

This action has no parameters.

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::ProcessEnding();

ProcessReady()

Notifies the Amazon GameLift service that the server process is ready to host game sessions. This method should be called after successfully invoking InitSDK() and completing any setup tasks required before the server process can host a game session.

This call is synchronous. To make an asynchronous call, use ProcessReadyAsync(). See Prepare a Server Process for more details.

Syntax

GenericOutcome ProcessReady( const Aws::GameLift::Server::ProcessParameters &processParameters);

Parameters

processParameters

A ProcessParameters object communicating the following information about the server process:

  • Names of callback methods, implemented in the game server code, that the Amazon GameLift service invokes to communicate with the server process.

  • Port number that the server process is listening on.

  • Path to any game session-specific files that you want Amazon GameLift to capture and store.

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example illustrates both the ProcessReady() call and callback function implementations.

// Set parameters and call ProcessReady std::string serverLog("serverOut.log"); // Example of a log file written by the game server std::vector<std::string> logPaths; logPaths.push_back(serverLog); int listenPort = 9339; Aws::GameLift::Server::ProcessParameters processReadyParameter = Aws::GameLift::Server::ProcessParameters( std::bind(&Server::onStartGameSession, this, std::placeholders::_1), std::bind(&Server::onProcessTerminate, this), std::bind(&Server::OnHealthCheck, this), std::bind(&Server::OnUpdateGameSession, this), listenPort, Aws::GameLift::Server::LogParameters(logPaths)); Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::ProcessReady(processReadyParameter); // Implement callback functions void Server::onStartGameSession(Aws::GameLift::Model::GameSession myGameSession) { // game-specific tasks when starting a new game session, such as loading map GenericOutcome outcome = Aws::GameLift::Server::ActivateGameSession (maxPlayers); } void Server::onProcessTerminate() { // game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup GenericOutcome outcome = Aws::GameLift::Server::ProcessEnding(); } bool Server::onHealthCheck() { bool health; // complete health evaluation within 60 seconds and set health return health; }

ProcessReadyAsync()

Notifies the Amazon GameLift service that the server process is ready to host game sessions. This method should be called once the server process is ready to host a game session. The parameters specify the names of callback functions for Amazon GameLift to call in certain circumstances. Game server code must implement these functions.

This call is asynchronous. To make a synchronous call, use ProcessReady(). See Prepare a Server Process for more details.

Syntax

GenericOutcomeCallable ProcessReadyAsync( const Aws::GameLift::Server::ProcessParameters &processParameters);

Parameters

processParameters

A ProcessParameters object communicating the following information about the server process:

  • Names of callback methods, implemented in the game server code, that the Amazon GameLift service invokes to communicate with the server process.

  • Port number that the server process is listening on.

  • Path to any game session-specific files that you want Amazon GameLift to capture and store.

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

// Set parameters and call ProcessReady std::string serverLog("serverOut.log"); // This is an example of a log file written by the game server std::vector<std::string> logPaths; logPaths.push_back(serverLog); int listenPort = 9339; Aws::GameLift::Server::ProcessParameters processReadyParameter = Aws::GameLift::Server::ProcessParameters( std::bind(&Server::onStartGameSession, this, std::placeholders::_1), std::bind(&Server::onProcessTerminate, this), std::bind(&Server::OnHealthCheck, this), std::bind(&Server::OnUpdateGameSession, this), listenPort, Aws::GameLift::Server::LogParameters(logPaths)); Aws::GameLift::GenericOutcomeCallable outcome = Aws::GameLift::Server::ProcessReadyAsync(processReadyParameter); // Implement callback functions void onStartGameSession(Aws::GameLift::Model::GameSession myGameSession) { // game-specific tasks when starting a new game session, such as loading map GenericOutcome outcome = Aws::GameLift::Server::ActivateGameSession (maxPlayers); } void onProcessTerminate() { // game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup GenericOutcome outcome = Aws::GameLift::Server::ProcessEnding(); } bool onHealthCheck() { // perform health evaluation and complete within 60 seconds return health; }

RemovePlayerSession()

Notifies the Amazon GameLift service that a player with the specified player session ID has disconnected from the server process. In response, Amazon GameLift changes the player slot to available, which allows it to be assigned to a new player.

Syntax

GenericOutcome RemovePlayerSession( const std::string& playerSessionId);

Parameters

playerSessionId

Unique ID issued by the Amazon GameLift service in response to a call to the AWS SDK Amazon GameLift API action CreatePlayerSession. The game client references this ID when connecting to the server process.

Type: std::string

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

Aws::GameLift::GenericOutcome disconnectOutcome = Aws::GameLift::Server::RemovePlayerSession(playerSessionId);

StartMatchBackfill()

Sends a request to find new players for open slots in a game session created with FlexMatch. See also the AWS SDK action StartMatchBackfill(). With this action, match backfill requests can be initiated by a game server process that is hosting the game session. Learn more about the FlexMatch backfill feature in Backfill Existing Games with FlexMatch.

This action is asynchronous. If new players are successfully matched, the Amazon GameLift service delivers updated matchmaker data using the callback function OnUpdateGameSession().

A server process can have only one active match backfill request at a time. To send a new request, first call StopMatchBackfill() to cancel the original request.

Syntax

StartMatchBackfillOutcome StartMatchBackfill ( const Aws::GameLift::Server::Model::StartMatchBackfillRequest &startBackfillRequest);

Parameters

StartMatchBackfillRequest

A StartMatchBackfillRequest object that communicates the following information:

  • A ticket ID to assign to the backfill request. This information is optional; if no ID is provided, Amazon GameLift will autogenerate one.

  • The matchmaker to send the request to. The full configuration ARN is required. This value can be acquired from the game session's matchmaker data.

  • The ID of the game session that is being backfilled.

  • Available matchmaking data for the game session's current players.

Required: Yes

Return Value

Returns a StartMatchBackfillOutcome object with the match backfill ticket or failure with an error message. Ticket status can be tracked using the AWS SDK action DescribeMatchmaking().

Example

// Build a backfill request std::vector<Player> players; Aws::GameLift::Server::Model::StartMatchBackfillRequest startBackfillRequest; startBackfillRequest.SetTicketId("a ticket ID"); //optional, autogenerated if not provided startBackfillRequest.SetMatchmakingConfigurationArn("the matchmaker configuration ARN"); //from the game session matchmaker data startBackfillRequest.SetGameSessionArn("the game session ARN"); // can use GetGameSessionId() startBackfillRequest.SetPlayers(players); //from the game session matchmaker data // Send backfill request Aws::GameLift::StartMatchBackfillOutcome backfillOutcome = Aws::GameLift::Server::StartMatchBackfill(startBackfillRequest); // Implement callback function for backfill void Server::OnUpdateGameSession(Aws::GameLift::Server::Model::GameSession gameSession, Aws::GameLift::Server::Model::UpdateReason updateReason, std::string backfillTicketId) { // handle status messages // perform game-specific tasks to prep for newly matched players }

StopMatchBackfill()

Cancels an active match backfill request that was created with StartMatchBackfill(). See also the AWS SDK action StopMatchmaking(). Learn more about the FlexMatch backfill feature in Backfill Existing Games with FlexMatch.

Syntax

GenericOutcome StopMatchBackfill ( const Aws::GameLift::Server::Model::StopMatchBackfillRequest &stopBackfillRequest);

Parameters

StopMatchBackfillRequest

A StopMatchBackfillRequest object identifying the matchmaking ticket to cancel:

  • ticket ID assigned to the backfill request being cancelled

  • matchmaker the backfill request was sent to

  • game session associated with the backfill request

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

// Set backfill stop request parameters Aws::GameLift::Server::Model::StopMatchBackfillRequest stopBackfillRequest; stopBackfillRequest.SetTicketId("the ticket ID"); stopBackfillRequest.SetGameSessionArn("the game session ARN"); // can use GetGameSessionId() stopBackfillRequest.SetMatchmakingConfigurationArn("the matchmaker configuration ARN"); // from the game session matchmaker data Aws::GameLift::GenericOutcome stopBackfillOutcome = Aws::GameLift::Server::StopMatchBackfillRequest(stopBackfillRequest);

TerminateGameSession()

Notifies the Amazon GameLift service that the server process has shut down the game session. Since each server process hosts only one game session at a time, there's no need to specify which session. This action should be called at the end of the game session shutdown process. After calling this action, the server process can call ProcessReady() to signal its availability to host a new game session. Alternatively it can call ProcessEnding() to shut down the server process and terminate the instance.

Syntax

GenericOutcome TerminateGameSession();

Parameters

This action has no parameters.

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example illustrates a server process at the end of a game session.

// game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::TerminateGameSession(); Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::ProcessReady(onStartGameSession, onProcessTerminate);

UpdatePlayerSessionCreationPolicy()

Updates the current game session's ability to accept new player sessions. A game session can be set to either accept or deny all new player sessions. See also the AWS SDK action UpdateGameSession().

Syntax

GenericOutcome UpdatePlayerSessionCreationPolicy( Aws::GameLift::Model::PlayerSessionCreationPolicy newPlayerSessionPolicy);

Parameters

newPlayerSessionPolicy

String value indicating whether the game session accepts new players.

Type: Aws::GameLift::Model::PlayerSessionCreationPolicy enum. Valid values include:

  • ACCEPT_ALL – Accept all new player sessions.

  • DENY_ALL – Deny all new player sessions.

Required: Yes

Return Value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example sets the current game session's join policy to accept all players.

Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::PlayerSessionCreationPolicy::ACCEPT_ALL);