Amazon GameLift server SDK 5.x for Unreal Engine: Actions

Use the Amazon GameLift Unreal server SDK 5.x reference to help you prepare your multiplayer game for use with Amazon GameLift. For details about the integration process, see Add Amazon GameLift to your game server. If you're using the Amazon GameLift plugin for Unreal, see also Amazon GameLift plugin for Unreal Engine.

Amazon GameLift server SDK 5.x for Unreal Engine: Data types

GetSdkVersion()

Returns the current version number of the SDK built into the server process.

Syntax

FGameLiftStringOutcome GetSdkVersion();

Return value

If successful, returns the current SDK version as an FGameLiftStringOutcome object. The returned object includes the version number (example 5.0.0). If not successful, returns an error message.

Example

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

InitSDK()

Initializes the Amazon GameLift SDK for a managed EC2 fleet. Call this method on launch, before any other initialization related to Amazon GameLift occurs. This method reads server parameters from the host environment to set up communication between the server and the Amazon GameLift service.

Syntax

FGameLiftGenericOutcome InitSDK()

Return value

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

Example

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
FGameLiftGenericOutcome initSdkOutcome = gameLiftSdkModule->InitSDK();

InitSDK()

Initializes the Amazon GameLift SDK for an Anywhere fleet. Call this method on launch, before any other initialization related to Amazon GameLift occurs. This method requires explicit server parameters to set up communication between the server and the Amazon GameLift service.

Syntax

FGameLiftGenericOutcome InitSDK(serverParameters)

Parameters

Return value

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

Example

//Define the server parameters
FServerParameters serverParameters;
parameters.m_authToken = "1111aaaa-22bb-33cc-44dd-5555eeee66ff"; 
parameters.m_fleetId = "arn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa";
parameters.m_hostId = "HardwareAnywhere"; 
parameters.m_processId = "PID1234";
parameters.m_webSocketUrl = "wss://us-west-1.api.amazongamelift.com"; 

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
FGameLiftGenericOutcome initSdkOutcome = gameLiftSdkModule->InitSDK(serverParameters);

ProcessReady()

Notifies Amazon GameLift that the server process is ready to host game sessions. Call this method after invoking InitSDK(). This method should be called only once per process.

Syntax

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

Parameters

Return value

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

Example

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

//Calling ProcessReady tells GameLift this game server is ready to receive incoming game sessions!
UE_LOG(GameServerLog, Log, TEXT("Calling Process Ready"));
FGameLiftGenericOutcome processReadyOutcome = gameLiftSdkModule->ProcessReady(*params); 

ProcessEnding()

Notifies Amazon GameLift that the server process is terminating. Call this method after all other cleanup tasks (including shutting down the active game session) and before terminating the process. Depending on the result of ProcessEnding(), the process exits with success (0) or error (-1) and generates a fleet event. If the process terminates with an error, the fleet event generated is SERVER_PROCESS_TERMINATED_UNHEALTHY).

Syntax

FGameLiftGenericOutcome ProcessEnding()

Return value

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

Example

//OnProcessTerminate callback. GameLift will invoke this callback before shutting down an instance hosting this game server.
//It gives this game server a chance to save its state, communicate with services, etc., before being shut down.
//In this case, we simply tell GameLift we are indeed going to shutdown.
params->OnTerminate.BindLambda([=]() {
  UE_LOG(GameServerLog, Log, TEXT("Game Server Process is terminating"));
  gameLiftSdkModule->ProcessEnding();
});

ActivateGameSession()

Notifies Amazon GameLift that the server process has activated 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.

Syntax

FGameLiftGenericOutcome ActivateGameSession()

Return value

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

Example

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

//When a game session is created, GameLift sends an activation request to the game server and passes along the game session object containing game properties and other settings.
//Here is where a game server should take action based on the game session object.
//Once the game server is ready to receive incoming player connections, it should invoke GameLiftServerAPI.ActivateGameSession()
auto onGameSession = [=](Aws::GameLift::Server::Model::GameSession gameSession)
{
  FString gameSessionId = FString(gameSession.GetGameSessionId());
  UE_LOG(GameServerLog, Log, TEXT("GameSession Initializing: %s"), *gameSessionId);
  gameLiftSdkModule->ActivateGameSession();
};

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.

Syntax

FGameLiftGenericOutcome UpdatePlayerSessionCreationPolicy(EPlayerSessionCreationPolicy policy)

Parameters

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.

FGameLiftGenericOutcome outcome = gameLiftSdkModule->UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::EPlayerSessionCreationPolicy::ACCEPT_ALL);

GetGameSessionId()

Retrieves the ID of the game session hosted by the active server process.

For idle processes that aren't activated with a game session, the call returns a FGameLiftError.

Syntax

FGameLiftStringOutcome GetGameSessionId()

Parameters

This action has no parameters.

Return value

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

For idle processes that aren't activated with a game session, the call returns Success=True and GameSessionId="".

Example

//When a game session is created, GameLift sends an activation request to the game server and passes along the game session object containing game properties and other settings.
//Here is where a game server should take action based on the game session object.
//Once the game server is ready to receive incoming player connections, it should invoke GameLiftServerAPI.ActivateGameSession()
auto onGameSession = [=](Aws::GameLift::Server::Model::GameSession gameSession)
{
  FString gameSessionId = FString(gameSession.GetGameSessionId());
  UE_LOG(GameServerLog, Log, TEXT("GameSession Initializing: %s"), *gameSessionId);
  gameLiftSdkModule->ActivateGameSession();
};

GetTerminationTime()

Returns the time that a server process is scheduled to be shut down, if a termination time is available. A server process takes action after receiving an onProcessTerminate() callback from Amazon GameLift. Amazon GameLift calls onProcessTerminate() for the following reasons:

Syntax

AwsDateTimeOutcome GetTerminationTime()

Return value

If successful, returns the termination time as an AwsDateTimeOutcome object. The value is the termination time, expressed in elapsed ticks since 0001 00:00:00. For example, the date time value 2020-09-13 12:26:40 -000Z is equal to 637355968000000000 ticks. If no termination time is available, returns an error message.

If the process hasn't received a ProcessParameters.OnProcessTerminate() callback, an error message is returned. For more information about shutting down a server process, see Respond to a server process shutdown notification.

Example

AwsDateTimeOutcome TermTimeOutcome = gameLiftSdkModule->GetTerminationTime();

AcceptPlayerSession()

Notifies Amazon GameLift 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. After the player session is validated, Amazon GameLift changes the status of the player slot from RESERVED to ACTIVE.

Syntax

FGameLiftGenericOutcome AcceptPlayerSession(const FString& playerSessionId)

Parameters

Return value

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

Example

This example handles a connection request that includes validating and rejecting non-valid player session IDs.

bool GameLiftManager::AcceptPlayerSession(const FString& playerSessionId, const FString& playerId)
{
  #if WITH_GAMELIFT
  UE_LOG(GameServerLog, Log, TEXT("Accepting GameLift PlayerSession: %s . PlayerId: %s"), *playerSessionId, *playerId);
  FString gsId = GetCurrentGameSessionId();
  if (gsId.IsEmpty()) {
    UE_LOG(GameServerLog, Log, TEXT("No GameLift GameSessionId. Returning early!"));
    return false;
  }
  
  if (!gameLiftSdkModule->AcceptPlayerSession(playerSessionId).IsSuccess()) {
    UE_LOG(GameServerLog, Log, TEXT("PlayerSession not Accepted."));
    return false;
  }

  // Add PlayerSession from internal data structures keeping track of connected players
  connectedPlayerSessionIds.Add(playerSessionId);
  idToPlayerSessionMap.Add(playerSessionId, PlayerSession{ playerId, playerSessionId });
  return true;
  #else
  return false;
  #endif
}

RemovePlayerSession()

Notifies Amazon GameLift that a player has disconnected from the server process. In response, Amazon GameLift changes the player slot to available.

Syntax

FGameLiftGenericOutcome RemovePlayerSession(const FString& playerSessionId)

Parameters

Return value

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

Example

bool GameLiftManager::RemovePlayerSession(const FString& playerSessionId)
{
  #if WITH_GAMELIFT
  UE_LOG(GameServerLog, Log, TEXT("Removing GameLift PlayerSession: %s"), *playerSessionId);

  if (!gameLiftSdkModule->RemovePlayerSession(playerSessionId).IsSuccess()) {
    UE_LOG(GameServerLog, Log, TEXT("PlayerSession Removal Failed"));
    return false;
  }

  // Remove PlayerSession from internal data structures that are keeping track of connected players
  connectedPlayerSessionIds.Remove(playerSessionId);
  idToPlayerSessionMap.Remove(playerSessionId);

  // end the session if there are no more players connected
  if (connectedPlayerSessionIds.Num() == 0) {
    EndSession();
  }

  return true;
  #else
  return false;
  #endif
}

DescribePlayerSessions()

Retrieves player session data which includes settings, session metadata, and player data. Use this method to get information about the following:

Syntax

FGameLiftDescribePlayerSessionsOutcome DescribePlayerSessions(const FGameLiftDescribePlayerSessionsRequest &describePlayerSessionsRequest)

Parameters

Return value

If successful, returns a FGameLiftDescribePlayerSessionsOutcome object containing a set of player session objects that fit the request parameters.

Example

This example requests 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 session records matching the request.

void GameLiftManager::DescribePlayerSessions()
{
  #if WITH_GAMELIFT
  FString localPlayerSessions;
  for (auto& psId : connectedPlayerSessionIds)
  {
    PlayerSession ps = idToPlayerSessionMap[psId];
    localPlayerSessions += FString::Printf(TEXT("%s : %s  ; "), *(ps.playerSessionId), *(ps.playerId));
  }
  UE_LOG(GameServerLog, Log, TEXT("LocalPlayerSessions: %s"), *localPlayerSessions);

  UE_LOG(GameServerLog, Log, TEXT("Describing PlayerSessions in this GameSession"));
  FGameLiftDescribePlayerSessionsRequest request;
  request.m_gameSessionId = GetCurrentGameSessionId();

  FGameLiftDescribePlayerSessionsOutcome outcome = gameLiftSdkModule->DescribePlayerSessions(request);
  LogDescribePlayerSessionsOutcome(outcome);
  #endif
}

StartMatchBackfill()

Sends a request to find new players for open slots in a game session created with FlexMatch. For more information, see FlexMatch backfill feature.

This action is asynchronous. If new players are matched, Amazon GameLift 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

FGameLiftStringOutcome StartMatchBackfill (FStartMatchBackfillRequest &startBackfillRequest);

Parameters

Return value

Returns a StartMatchBackfillOutcome object with the match backfill ticket ID, or failure with an error message.

Example

FGameLiftStringOutcome FGameLiftServerSDKModule::StartMatchBackfill(const FStartMatchBackfillRequest& request) 
{
  #if WITH_GAMELIFT
  Aws::GameLift::Server::Model::StartMatchBackfillRequest sdkRequest;
  sdkRequest.SetTicketId(TCHAR_TO_UTF8(*request.m_ticketId));
  sdkRequest.SetGameSessionArn(TCHAR_TO_UTF8(*request.m_gameSessionArn));
  sdkRequest.SetMatchmakingConfigurationArn(TCHAR_TO_UTF8(*request.m_matchmakingConfigurationArn));
  for (auto player : request.m_players) {
    Aws::GameLift::Server::Model::Player sdkPlayer;
    sdkPlayer.SetPlayerId(TCHAR_TO_UTF8(*player.m_playerId));
    sdkPlayer.SetTeam(TCHAR_TO_UTF8(*player.m_team));
    for (auto entry : player.m_latencyInMs) {
      sdkPlayer.WithLatencyMs(TCHAR_TO_UTF8(*entry.Key), entry.Value);
    }

    std::map<std::string, Aws::GameLift::Server::Model::AttributeValue> sdkAttributeMap;
    for (auto attributeEntry : player.m_playerAttributes) {
      FAttributeValue value = attributeEntry.Value;
      Aws::GameLift::Server::Model::AttributeValue attribute;
      switch (value.m_type) {
        case FAttributeType::STRING:
          attribute = Aws::GameLift::Server::Model::AttributeValue(TCHAR_TO_UTF8(*value.m_S));
        break;
        case FAttributeType::DOUBLE:
          attribute = Aws::GameLift::Server::Model::AttributeValue(value.m_N);
        break;
        case FAttributeType::STRING_LIST:
          attribute = Aws::GameLift::Server::Model::AttributeValue::ConstructStringList();
          for (auto sl : value.m_SL) {
            attribute.AddString(TCHAR_TO_UTF8(*sl));
          };
        break;
        case FAttributeType::STRING_DOUBLE_MAP:
          attribute = Aws::GameLift::Server::Model::AttributeValue::ConstructStringDoubleMap();
          for (auto sdm : value.m_SDM) {
            attribute.AddStringAndDouble(TCHAR_TO_UTF8(*sdm.Key), sdm.Value);
          };
        break;
      }
      sdkPlayer.WithPlayerAttribute((TCHAR_TO_UTF8(*attributeEntry.Key)), attribute);
    }
    sdkRequest.AddPlayer(sdkPlayer);
  }
  auto outcome = Aws::GameLift::Server::StartMatchBackfill(sdkRequest);
  if (outcome.IsSuccess()) {
    return FGameLiftStringOutcome(outcome.GetResult().GetTicketId());
  }
  else {
    return FGameLiftStringOutcome(FGameLiftError(outcome.GetError()));
  }
  #else
  return FGameLiftStringOutcome("");
  #endif
}

StopMatchBackfill()

Cancels an active match backfill request. For more information, see FlexMatch backfill feature.

Syntax

FGameLiftGenericOutcome StopMatchBackfill (FStopMatchBackfillRequest &stopBackfillRequest);

Parameters

Return value

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

Example

FGameLiftGenericOutcome FGameLiftServerSDKModule::StopMatchBackfill(const FStopMatchBackfillRequest& request)
{
  #if WITH_GAMELIFT
  Aws::GameLift::Server::Model::StopMatchBackfillRequest sdkRequest;
  sdkRequest.SetTicketId(TCHAR_TO_UTF8(*request.m_ticketId));
  sdkRequest.SetGameSessionArn(TCHAR_TO_UTF8(*request.m_gameSessionArn));
  sdkRequest.SetMatchmakingConfigurationArn(TCHAR_TO_UTF8(*request.m_matchmakingConfigurationArn));
  auto outcome = Aws::GameLift::Server::StopMatchBackfill(sdkRequest);
  if (outcome.IsSuccess()) {
    return FGameLiftGenericOutcome(nullptr);
  }
  else {
    return FGameLiftGenericOutcome(FGameLiftError(outcome.GetError()));
  }
  #else
  return FGameLiftGenericOutcome(nullptr);
  #endif
}

GetComputeCertificate()

Retrieves the path to the TLS certificate used to encrypt the network connection between your Amazon GameLift Anywhere compute resource and Amazon GameLift. You can use the certificate path when you register your compute device to a Amazon GameLift Anywhere fleet. For more information see, RegisterCompute.

Syntax

FGameLiftGetComputeCertificateOutcome FGameLiftServerSDKModule::GetComputeCertificate()

Return value

Returns a GetComputeCertificateResponse object containing the following:

Example

FGameLiftGetComputeCertificateOutcome FGameLiftServerSDKModule::GetComputeCertificate()
{
  #if WITH_GAMELIFT
  auto outcome = Aws::GameLift::Server::GetComputeCertificate();
  if (outcome.IsSuccess()) {
    auto& outres = outcome.GetResult();
    FGameLiftGetComputeCertificateResult result;
    result.m_certificate_path = UTF8_TO_TCHAR(outres.GetCertificatePath());
    result.m_computeName = UTF8_TO_TCHAR(outres.GetComputeName());
    return FGameLiftGetComputeCertificateOutcome(result);
  }
  else {
    return FGameLiftGetComputeCertificateOutcome(FGameLiftError(outcome.GetError()));
  }
  #else
  return FGameLiftGetComputeCertificateOutcome(FGameLiftGetComputeCertificateResult());
  #endif
}

GetFleetRoleCredentials()

Retrieves IAM role credentials that authorize Amazon GameLift to interact with other AWS services. For more information, see Communicate with other AWS resources from your fleets.

Syntax

FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request)

Parameters

FGameLiftGetFleetRoleCredentialsRequest

Return value

Returns a FGameLiftGetFleetRoleCredentialsOutcome object.

Example

FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request)
{
  #if WITH_GAMELIFT
  Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest sdkRequest;
  sdkRequest.SetRoleArn(TCHAR_TO_UTF8(*request.m_roleArn));
  sdkRequest.SetRoleSessionName(TCHAR_TO_UTF8(*request.m_roleSessionName));

  auto outcome = Aws::GameLift::Server::GetFleetRoleCredentials(sdkRequest);

  if (outcome.IsSuccess()) {
    auto& outres = outcome.GetResult();
    FGameLiftGetFleetRoleCredentialsResult result;
    result.m_assumedUserRoleArn = UTF8_TO_TCHAR(outres.GetAssumedUserRoleArn());
    result.m_assumedRoleId = UTF8_TO_TCHAR(outres.GetAssumedRoleId());
    result.m_accessKeyId = UTF8_TO_TCHAR(outres.GetAccessKeyId());
    result.m_secretAccessKey = UTF8_TO_TCHAR(outres.GetSecretAccessKey());
    result.m_sessionToken = UTF8_TO_TCHAR(outres.GetSessionToken());
    result.m_expiration = FDateTime::FromUnixTimestamp(outres.GetExpiration());
    return FGameLiftGetFleetRoleCredentialsOutcome(result);
  }
  else {
    return FGameLiftGetFleetRoleCredentialsOutcome(FGameLiftError(outcome.GetError()));
  }
  #else
  return FGameLiftGetFleetRoleCredentialsOutcome(FGameLiftGetFleetRoleCredentialsResult());
  #endif
}