SDK 5.x del servidor de Amazon GameLift para C++: acciones

Utilice la referencia del SDK 5.x del servidor de Amazon GameLift para C++ como ayuda para integrar un juego multijugador para el alojamiento con Amazon GameLift. Para obtener ayuda con el proceso de integración, consulte Adición de Amazon GameLift al servidor de juegos.

SDK 5.x del servidor de Amazon GameLift para C++: tipos de datos

GetSdkVersion()

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

Sintaxis

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

Valor devuelto

Si funciona correctamente, devuelve la versión del SDK actual como objeto AwsStringOutcome. 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. Llame a este método en el lanzamiento, antes de cualquier otro paso de inicialización relacionado con Amazon GameLift. Esta acción lee los parámetros del servidor desde el entorno de alojamiento para configurar la comunicación entre el proceso del servidor de juegos y el servicio de Amazon GameLift.

Si la compilación del servidor de juegos se va a implementar sin el agente de Amazon GameLift en una flota, o flota de contenedores, de Amazon GameLift Anywhere, llame a InitSDK() y especifique un conjunto de parámetros de servidor.

Sintaxis

Server::InitSDKOutcome Server::initSdkOutcome = InitSDK();

Valor devuelto

Devuelve un objeto InitSDKOutcome que indica si 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.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = 
  Aws::GameLift::Server::InitSDK();

InitSDK()

Inicializa el SDK de Amazon GameLift. Llame a este método en el lanzamiento, antes de cualquier otro paso de inicialización relacionado con Amazon GameLift. Para esta acción, es necesario que un conjunto de parámetros del servidor establezca la comunicación entre el proceso del servidor de juegos y el servicio de Amazon GameLift.

Si la compilación del servidor de juegos se va a implementar en una flota de EC2 administrada por Amazon GameLift o una flota, o flota de contenedores, de Amazon GameLift Anywhere con el agente de Amazon GameLift, llame a InitSDK() sin los parámetros del servidor.

Sintaxis

Server::InitSDKOutcome Server::initSdkOutcome = InitSDK(serverParameters);

Parámetros

Valor devuelto

Devuelve un objeto InitSDKOutcome que indica si el proceso del servidor está listo para llamar a ProcessReady().

Ejemplo

Ejemplo de Amazon GameLift Anywhere

//Define the server parameters
std::string websocketUrl = "wss://us-west-1.api.amazongamelift.com";
std::string processId = "PID1234";
std::string fleetId = "arn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa";
std::string hostId = "HardwareAnywhere";
std::string authToken = "1111aaaa-22bb-33cc-44dd-5555eeee66ff";
Aws::GameLift::Server::Model::ServerParameters serverParameters = 
  Aws::GameLift::Server::Model::ServerParameters(webSocketUrl, authToken, fleetId, hostId, processId);

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = Aws::GameLift::Server::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.

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

Notifica al servicio de Amazon GameLift que el proceso del servidor está listo para alojar sesiones de juego. Este método debe llamarse después de que el proceso del servidor esté listo para alojar una sesión de juego. Los parámetros especifican los nombres de las funciones de devolución de llamada para Amazon GameLift que llamar en determinadas circunstancias. El código de servidor de juegos debe implementar estas funciones.

La llamada es asíncrona. Para realizar una llamada síncrona, utilice ProcessReady(). Consulte Inicialización del proceso del servidor para obtener más detalles.

Sintaxis

GenericOutcomeCallable ProcessReadyAsync(
    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

// 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;
}        

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 finaliza con un error, el evento de flota generado será SERVER_PROCESS_TERMINATED_UNHEALTHY.

Sintaxis

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

Valor devuelto

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

Ejemplo

En este ejemplo, se llama a ProcessEnding() y Destroy() antes de finalizar el proceso del servidor con un código de salida correcto o erróneo.

Aws::GameLift::GenericOutcome processEndingOutcome = Aws::GameLift::Server::ProcessEnding();
Aws::GameLift::Server::Destroy();

// Exit the process with success or failure
if (processEndingOutcome.IsSuccess()) {
  exit(0);
}
else {
  cout << "ProcessEnding() failed. Error: " << processEndingOutcome.GetError().GetErrorMessage();
  exit(-1);
}

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

Aws::GameLift::GenericOutcome activateGameSessionOutcome = Aws::GameLift::Server::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().

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

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

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

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.

Aws::GameLift::GenericOutcome outcome = 
  Aws::GameLift::Server::UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::PlayerSessionCreationPolicy::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 GameLiftError.

Sintaxis

AwsStringOutcome 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 AwsStringOutcome. 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

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

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 una 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

Aws::GameLift::AwsLongOutcome TermTimeOutcome = Aws::GameLift::Server::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

GenericOutcome AcceptPlayerSession(String 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.

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

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

GenericOutcome RemovePlayerSession(String playerSessionId)

Parámetros

Valor devuelto

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

Ejemplo

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

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

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

Parámetros

Valor devuelto

Si funciona correctamente, devuelve un objeto DescribePlayerSessionsOutcome 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.

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

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

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest 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

// Build a backfill request
std::vector<Player> players;
Aws::GameLift::Server::Model::StartMatchBackfillRequest startBackfillRequest;
startBackfillRequest.SetTicketId("1111aaaa-22bb-33cc-44dd-5555eeee66ff");  // optional, autogenerated if not provided
startBackfillRequest.SetMatchmakingConfigurationArn("arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig"); //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()

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

Sintaxis

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

Parámetros

Valor devuelto

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

Ejemplo

// Set backfill stop request parameters

Aws::GameLift::Server::Model::StopMatchBackfillRequest stopBackfillRequest;
stopBackfillRequest.SetTicketId("1111aaaa-22bb-33cc-44dd-5555eeee66ff");
stopBackfillRequest.SetGameSessionArn("the game session ARN"); // can use GetGameSessionId()
stopBackfillRequest.SetMatchmakingConfigurationArn("arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig");
// from the game session matchmaker data

Aws::GameLift::GenericOutcome stopBackfillOutcome = 
  Aws::GameLift::Server::StopMatchBackfill(stopBackfillRequest);

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

GetComputeCertificateOutcome Server::GetComputeCertificate()

Valor devuelto

Devuelve GetComputeCertificateOutcome.

Ejemplo

Aws::GameLift::GetComputeCertificateOutcome certificate = Aws::GameLift::Server::GetComputeCertificate();

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

GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

Parámetros

GetFleetRoleCredentialsRequest

Valor devuelto

Devuelve un objeto GetFleetRoleCredentialsOutcome.

Ejemplo

// form the fleet credentials request 
Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest getFleetRoleCredentialsRequest; 
getFleetRoleCredentialsRequest.SetRoleArn("arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction");

Aws::GameLift::GetFleetRoleCredentialsOutcome credentials = Aws::GameLift::Server::GetFleetRoleCredentials(getFleetRoleCredentialsRequest);

En este ejemplo, se muestra el uso del valor RoleSessionName opcional para asignar un nombre a la sesión de credenciales con fines de auditoría. Si no proporciona un nombre de sesión de rol, se utiliza el valor predeterminado «[fleet-id]-[host-id]».

// form the fleet credentials request 
Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest getFleetRoleCredentialsRequest; 
getFleetRoleCredentialsRequest.SetRoleArn("arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction");
getFleetRoleCredentialsRequest.SetRoleSessionName("MyFleetRoleSession"); 

Aws::GameLift::GetFleetRoleCredentialsOutcome credentials = Aws::GameLift::Server::GetFleetRoleCredentials(getFleetRoleCredentialsRequest);

Destroy()

Libera de la memoria el SDK del servidor de juegos de Amazon GameLift. Como práctica recomendada, llame a este método después de ProcessEnding() y antes de finalizar el proceso. Si utiliza una flota de Anywhere y no va a finalizar los procesos del servidor después de cada sesión de juego, llame a Destroy() y, a continuación, a InitSDK() para reinicializa antes de informar a Amazon GameLift de que el proceso está listo para organizar una sesión de juego con ProcessReady().

Sintaxis

GenericOutcome Aws::GameLift::Server::Destroy();

Parámetros

No hay parámetros.

Valor devuelto

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

Ejemplo

Aws::GameLift::GenericOutcome processEndingOutcome = Aws::GameLift::Server::ProcessEnding();
Aws::GameLift::Server::Destroy();

// Exit the process with success or failure
if (processEndingOutcome.IsSuccess()) {
  exit(0);
}
else {
  cout << "ProcessEnding() failed. Error: " << processEndingOutcome.GetError().GetErrorMessage();
  exit(-1);
}