SDK 5.x del servidor de Amazon GameLift para Unreal Engine: acciones

Utilice esta referencia del SDK 5.x del servidor de Unreal de Amazon GameLift como ayuda para preparar un juego multijugador para el uso con Amazon GameLift. Para obtener más información sobre el proceso de integración, consulte Adición de Amazon GameLift al servidor de juegos. Si utiliza el complemento de Amazon GameLift para Unreal, consulte también Complemento de Amazon GameLift para Unreal Engine.

SDK 5.x del servidor de Amazon GameLift para Unreal Engine: tipos de datos

GetSdkVersion()

Devuelve el número de versión actual del SDK integrado en el proceso del servidor.

Sintaxis

FGameLiftStringOutcome GetSdkVersion();

Valor devuelto

Si funciona correctamente, devuelve la versión del SDK actual como objeto FGameLiftStringOutcome. El objeto devuelto incluye el número de versión (por ejemplo, 5.0.0). Si no funciona, devuelve un mensaje de error.

Ejemplo

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

InitSDK()

Inicializa el SDK de Amazon GameLift para una flota de EC2 administrada. Llama a este método al lanzarlo antes de que se produzca cualquier otra inicialización relacionada con Amazon GameLift. Este método lee los parámetros del servidor del entorno de alojamiento para configurar la comunicación entre el servidor y el servicio de Amazon GameLift.

Sintaxis

FGameLiftGenericOutcome InitSDK()

Valor devuelto

Si funciona correctamente, devuelve un objeto InitSdkOutcome e indica que el proceso del servidor está listo para llamar a ProcessReady().

Ejemplo

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

InitSDK()

Inicializa el SDK de Amazon GameLift para una flota de Anywhere. Llama a este método al lanzarlo antes de que se produzca cualquier otra inicialización relacionada con Amazon GameLift. Este método requiere que los parámetros del servidor explícito configure la comunicación entre el servidor y el servicio de Amazon GameLift.

Sintaxis

FGameLiftGenericOutcome InitSDK(serverParameters)

Parámetros

Valor devuelto

Si funciona correctamente, devuelve un objeto InitSdkOutcome e indica que el proceso del servidor está listo para llamar a ProcessReady().

Ejemplo

//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()

Notifica a Amazon GameLift que el proceso del servidor de juegos está listo para alojar sesiones de juego. Llame a este método después de invocar InitSDK(). Se debe llamar a este método solo una vez por proceso.

Sintaxis

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

Parámetros

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

Este ejemplo ilustra las implementaciones tanto de la función de llamada ProcessReady() como de la función de delegación.

//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()

Informa a Amazon GameLift de que el proceso del servidor está finalizando. Llame a este método después de realizar todas las demás tareas de limpieza (lo que incluye el cierre de la sesión de juegos activa) y antes de finalizar el proceso. Según el resultado de ProcessEnding(), el proceso finaliza con éxito (0) o error (-1) y genera un evento de flota. Si el proceso termina con un error, el evento de flota generado es SERVER_PROCESS_TERMINATED_UNHEALTHY.

Sintaxis

FGameLiftGenericOutcome ProcessEnding()

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

//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()

Informa al servicio de Amazon GameLift de que el proceso del servidor ha activado una sesión de juego y que está listo para recibir las conexiones de los jugadores. Esta acción debe llamarse como parte de la función de devolución de llamada onStartGameSession(), después de la inicialización de todas las sesiones de juego.

Sintaxis

FGameLiftGenericOutcome ActivateGameSession()

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

Este ejemplo muestra cómo se llama a ActivateGameSession() como parte de la función de delegación onStartGameSession().

//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()

Actualiza la capacidad de la sesión de juego actual para aceptar sesiones de jugador nuevas. Una sesión de juego se puede configurar para que acepte o deniegue todas las sesiones nuevas de los jugadores.

Sintaxis

FGameLiftGenericOutcome UpdatePlayerSessionCreationPolicy(EPlayerSessionCreationPolicy policy)

Parámetros

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

Este ejemplo establece la política de participación en la sesión de juego actual para aceptar todos los jugadores.

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

GetGameSessionId()

Recupera el ID de la sesión de juego alojada por el proceso del servidor.

En el caso de los procesos inactivos que no se activan con una sesión de juego, la llamada devuelve FGameLiftError.

Sintaxis

FGameLiftStringOutcome GetGameSessionId()

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si funciona correctamente, devuelve el ID de sesión del juego como objeto FGameLiftStringOutcome. Si no funciona, devuelve un mensaje de error.

En el caso de los procesos inactivos que no se activan con una sesión de juego, la llamada devuelve Success=True y GameSessionId="".

Ejemplo

//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()

Devuelve la hora a la que está programada el cierre de un proceso de servidor, si hay una hora de terminación disponible. Un proceso de servidor realiza esta acción después de recibir una devolución de llamada onProcessTerminate() desde el servicio de Amazon GameLift. Amazon GameLift llama a onProcessTerminate() por las siguientes razones:

Sintaxis

AwsDateTimeOutcome GetTerminationTime()

Valor devuelto

Si el proceso se realiza correctamente, devuelve la hora de terminación como un objeto AwsDateTimeOutcome. El valor es la hora de terminación expresado en ciclos transcurridos desde 0001 00:00:00. Por ejemplo, el valor de la fecha y hora 2020-09-13 12:26:40 -000Z es igual a 637355968000000000 ciclos. Si no hay una hora de terminación disponible, devuelve un mensaje de error.

Si el proceso no ha recibido ninguna devolución de llamada ProcessParameters.OnProcessTerminate(), se devuelve un mensaje de error. Para obtener más información sobre cómo cerrar un proceso de servidor, consulte Respuesta a una notificación de cierre del proceso del servidor.

Ejemplo

AwsDateTimeOutcome TermTimeOutcome = gameLiftSdkModule->GetTerminationTime();

AcceptPlayerSession()

Informa al servicio de Amazon GameLift de que un jugador con el ID de sesión de jugador especificado se ha conectado al proceso del servidor y requiere validación. Amazon GameLift verifica que el ID de sesión del jugador sea válido. Una vez validada la sesión del jugador, Amazon GameLift cambia el estado de la ranura del jugador de RESERVADO a ACTIVO.

Sintaxis

FGameLiftGenericOutcome AcceptPlayerSession(const FString& playerSessionId)

Parámetros

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

En este ejemplo, se administra una solicitud de conexión que incluye la validación y el rechazo de los ID de sesión de los jugadores no válidos.

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()

Informa a Amazon GameLift de que un jugador se ha desconectado del proceso del servidor. Como respuesta, Amazon GameLift cambia el espacio del jugador para que esté disponible.

Sintaxis

FGameLiftGenericOutcome RemovePlayerSession(const FString& playerSessionId)

Parámetros

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

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()

Recupera datos de sesión de jugador, incluida la configuración, los metadatos de la sesión y los datos de jugador. Utilice este método para obtener información sobre los siguientes elementos:

Sintaxis

FGameLiftDescribePlayerSessionsOutcome DescribePlayerSessions(const FGameLiftDescribePlayerSessionsRequest &describePlayerSessionsRequest)

Parámetros

Valor devuelto

Si funciona correctamente, devuelve un objeto FGameLiftDescribePlayerSessionsOutcome que contiene un conjunto de objetos de sesión de jugador que se ajusta a los parámetros de la solicitud.

Ejemplo

En este ejemplo se solicitan todas las sesiones de jugador conectadas activamente a una sesión de juego específica. Al omitir NextToken y definir el valor Límite en 10, Amazon GameLift devolverá los primeros 10 registros de sesiones de jugador que coincidan con la solicitud.

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()

Envía una solicitud para encontrar nuevos jugadores para ranuras abiertas en una sesión de juego creada con FlexMatch. Para obtener más información, consulte Característica de reposición de FlexMatch.

Esta acción es asíncrona. Si se emparejan nuevos jugadores, Amazon GameLift ofrece datos actualizados del emparejador mediante la función de devolución de llamada OnUpdateGameSession().

Un proceso del servidor solo puede tener una solicitud de reposición de emparejamiento activa a la vez. Para enviar una nueva solicitud, en primer lugar llame a StopMatchBackfill() para cancelar la solicitud original.

Sintaxis

FGameLiftStringOutcome StartMatchBackfill (FStartMatchBackfillRequest &startBackfillRequest);

Parámetros

Valor devuelto

Devuelve un objeto StartMatchBackfillOutcome con el ID del ticket de reposición de emparejamiento o un error con un mensaje de error.

Ejemplo

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()

Cancela una solicitud de reposición de emparejamiento activa. Para obtener más información, consulte Característica de reposición de FlexMatch.

Sintaxis

FGameLiftGenericOutcome StopMatchBackfill (FStopMatchBackfillRequest &stopBackfillRequest);

Parámetros

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

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()

Recupera la ruta al certificado TLS utilizado para cifrar la conexión de red entre el recurso informático de Amazon GameLift Anywhere y Amazon GameLift. Puede utilizar la ruta del certificado al registrar el dispositivo informático en una flota de Amazon GameLift Anywhere. Para obtener más información, consulte RegisterCompute.

Sintaxis

FGameLiftGetComputeCertificateOutcome FGameLiftServerSDKModule::GetComputeCertificate()

Valor devuelto

Devuelve un objeto GetComputeCertificateResponse que contiene los siguientes elementos:

Ejemplo

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()

Recupera las credenciales del rol de IAM que autorizan a Amazon GameLift a interactuar con otros Servicios de AWS. Para obtener más información, consulte Comunicación con otros recursos de AWS de sus flotas.

Sintaxis

FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request)

Parámetros

FGameLiftGetFleetRoleCredentialsRequest

Valor devuelto

Devuelve un objeto FGameLiftGetFleetRoleCredentialsOutcome.

Ejemplo

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
}