Referencia al SDK (C++) del GameLift servidor de Amazon: Acciones

Puedes usar esta referencia del SDK del servidor GameLift C++ de Amazon como ayuda para preparar tu juego multijugador para usarlo con Amazon GameLift. Para obtener información detallada acerca del proceso de integración, consulteAñade Amazon GameLift a tu servidor de juegos.

AcceptPlayerSession()

Notifica al GameLift servicio de Amazon que un jugador con el ID de sesión de jugador especificado se ha conectado al proceso del servidor y necesita ser validado. Amazon GameLift comprueba que el ID de sesión del jugador es válido, es decir, que el ID del jugador ha reservado un espacio de jugador en la sesión de juego. Una vez validado, Amazon GameLift cambia el estado del espacio de jugador de RESERVADO a ACTIVO.

Sintaxis

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

Parámetros

playerSessionId

ID único emitido por el GameLift servicio de Amazon en respuesta a una llamada a la acción de la GameLift API de Amazon delAWS SDK CreatePlayerSession. El cliente del juego hace referencia a este ID cuando se conecta al proceso del servidor.

Tipo: std: :string

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

Este ejemplo muestra una función para gestionar una solicitud de conexión, incluida la validación y el rechazo de ID de sesión de jugador 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();
    }       
}

ActivateGameSession()

Notifica al GameLift servicio de Amazon que el proceso del servidor ha iniciado una sesión de juego y ahora 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 completar la inicialización de todas las sesiones de juego.

Sintaxis

GenericOutcome ActivateGameSession();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

Este ejemplo muestra cómo se llama a ActivateGameSession() como parte de la función de devolución de llamada 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();
}

DescribePlayerSessions()

Recupera datos de sesión de jugador, incluida la configuración, los metadatos de la sesión y los datos de jugador. Utilice esta acción para obtener información para una única sesión de jugador, para todas las sesiones de jugador de una sesión de juego o para todas las sesiones de jugador asociadas a un solo ID de jugador.

Sintaxis

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

Parámetros

describePlayerSessionsSolicitud

Es un objeto DescribePlayerSessionsRequest que describe las sesiones de jugador a recuperar.

Obligatorio: sí

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. Los objetos de sesión del jugador tienen una estructura idéntica al tipo de PlayerSessiondatos de la GameLift API de Amazon delAWS SDK.

Ejemplo

Este ejemplo muestra una solicitud de todas las sesiones de jugador conectadas activamente a una sesión de juego específica. Al omitirNextToken y establecer elLimit valor en 10, Amazon GameLift devuelve los primeros 10 registros de sesiones del jugador que coinciden 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);

GetGameSessionId()

Recupera un identificador único de la sesión de juego alojada actualmente por el proceso del servidor, siempre que esté activo. El identificador se devuelve en el formato de ARN: arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>.

Para los procesos inactivos que aún no estén activados con una sesión de juego, la llamada devuelveSuccess =True yGameSessionId ="" (una cadena vacía).

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.

Ejemplo

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

GetInstanceCertificate()

Recupera la ubicación del archivo de un certificado TLS codificado en PEM que está asociado a la flota y sus instancias. AWS Certificate Managergenera este certificado al crear una flota nueva con la configuración del certificado establecida en GENERATED. Utilice este certificado para establecer una conexión segura con un cliente de juego y para cifrar la comunicación cliente/servidor.

Sintaxis

GetInstanceCertificateOutcome GetInstanceCertificate();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si tiene éxito, devuelve unGetInstanceCertificateOutcome objeto que contiene la ubicación del archivo de certificado TLS y la cadena de certificados de la flota, que están almacenados en la instancia. En la instancia también se almacena un archivo de certificado raíz, extraído de la cadena de certificados. Si no funciona, devuelve un mensaje de error.

Para obtener más información sobre el certificado y los datos de la cadena de certificados, consulte Elementos deGetCertificate respuesta en la referenciaAWS Certificate Manager de la API.

Ejemplo

Aws::GameLift::GetInstanceCertificateOutcome certificateOutcome = 
    Aws::GameLift::Server::GetInstanceCertificate();

GetSdkVersion()

Devuelve el número de versión actual del SDK en uso.

Sintaxis

AwsStringOutcome GetSdkVersion();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si funciona correctamente, devuelve la versión del SDK actual como objeto AwsStringOutcome. La cadena devuelta incluye solo el número de versión (por ejemplo, «3.1.5"). Si no funciona, devuelve un mensaje de error.

Ejemplo

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

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 del servidor realiza esta acción después de recibir unaonProcessTerminate() llamada del GameLift servicio de Amazon. Amazon GameLift puede llamaronProcessTerminate() por los siguientes motivos: (1) cuando el proceso del servidor informa de problemas o no responde a Amazon GameLift, (2) cuando finaliza la instancia durante un evento de reducción de escala o (3) cuando se cancela una instancia debido a una interrupción puntual.

Si el proceso ha recibido unaonProcessTerminate() devolución de llamada, el valor devuelto es el tiempo de finalización estimado. Si el proceso no ha recibido ningunaonProcessTerminate() devolución de llamada, se devuelve un mensaje de error. Más información acerca del apagado de un proceso de servidor.

Sintaxis

AwsLongOutcome GetTerminationTime();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si tiene éxito, devuelve la hora de terminación como unAwsLongOutcome objeto. El valor es el tiempo de finalización, expresado en marcas transcurridas desde las 0001 00:00:00. Por ejemplo, el valor de fecha y hora 2020-09-13 12:26:40 -000Z es igual a 637355968000000000 ticks. Si no hay una hora de finalización disponible, devuelve un mensaje de error.

Ejemplo

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

InitSDK()

Inicializa el GameLift SDK de Amazon. Este método debe invocarse en el momento del lanzamiento, antes de que se produzca cualquier otra inicialización GameLift relacionada con Amazon.

Sintaxis

InitSDKOutcome InitSDK();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si tiene éxito, devuelve un InitSdkOutcome objeto que indica que el proceso del servidor está listo para la llamadaProcessReady().

Ejemplo

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

ProcessEnding()

Notifica al GameLift servicio de Amazon que el proceso del servidor se está cerrando. Este método debe llamarse después de realizar las demás tareas de limpieza, incluido el cierre de todas las sesiones de juego activas. Se debe salir de este método con un código de salida de 0; un código de salida que no sea 0 provoca un mensaje de evento que afirma que no se ha salido del proceso correctamente.

Una vez que el método salga con un código de 0, puede finalizar el proceso con un código de salida correcto. También puede salir del proceso con un código de error. Si sales con un código de error, el evento de la flota indicará que el proceso ha terminado de forma anormal (SERVER_PROCESS_TERMINATED_UNHEALTHY).

Sintaxis

GenericOutcome ProcessEnding();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::ProcessEnding();
if (outcome.Success)
    exit(0);  // exit with success
// otherwise, exit with error code
exit(errorCode);
            

ProcessReady()

Notifica al GameLift servicio de Amazon que el proceso del servidor está listo para albergar sesiones de juego. Ejecute este método después de invocarInitSDK() y completar correctamente las tareas de configuración necesarias antes de que el proceso del servidor pueda albergar una sesión de juego. Este método debe invocarse solo una vez por proceso.

La llamada es síncrona. Para realizar una llamada asíncrona, utilice ProcessReadyAsync(). Consulte Inicializar el proceso del servidor para obtener más detalles.

Sintaxis

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

Parámetros

processParameters

Es un objeto ProcessParameters que comunica la siguiente información acerca del proceso del servidor:

• Nombres de los métodos de devolución de llamada, implementados en el código del servidor del juego, que el GameLift servicio de Amazon invoca para comunicarse con el proceso del servidor.

• Número de puerto de escucha del servidor de proceso.

• Ruta a cualquier archivo específico de la sesión de juego que quieras GameLift que Amazon capture y almacene.

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

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

// 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 GameLift servicio de Amazon que el proceso del servidor está listo para albergar sesiones de juego. Este método debe llamarse cuando 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 GameLift a las que Amazon puede 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 Inicializar el proceso del servidor para obtener más detalles.

Sintaxis

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

Parámetros

processParameters

Es un objeto ProcessParameters que comunica la siguiente información acerca del proceso del servidor:

• Nombres de los métodos de devolución de llamada, implementados en el código del servidor del juego, que el GameLift servicio de Amazon invoca para comunicarse con el proceso del servidor.

• Número de puerto de escucha del servidor de proceso.

• Ruta a cualquier archivo específico de la sesión de juego que quieras GameLift que Amazon capture y almacene.

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso 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;
}        

RemovePlayerSession()

Notifica al GameLift servicio de Amazon que un jugador con el ID de sesión de jugador especificado se ha desconectado del proceso del servidor. En respuesta, Amazon GameLift cambia el espacio del jugador a disponible, lo que permite asignarlo a un nuevo jugador.

Sintaxis

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

Parámetros

playerSessionId

ID único emitido por el GameLift servicio de Amazon en respuesta a una llamada a la acción de la GameLift API de Amazon delAWS SDK CreatePlayerSession. El cliente del juego hace referencia a este ID cuando se conecta al proceso del servidor.

Tipo: std: :string

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

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

StartMatchBackfill()

Envía una solicitud para encontrar nuevos jugadores para ranuras abiertas en una sesión de juego creada con FlexMatch. Consulte también la acción delAWS SDK StartMatchBackfill(). Con esta acción, un proceso del servidor de juegos que aloja la sesión de juego puede iniciar solicitudes de reposición de emparejamiento. Más información sobre la función de FlexMatch relleno.

Esta acción es asíncrona. Si los nuevos jugadores se emparejan correctamente, el GameLift servicio de Amazon proporciona datos de emparejamiento actualizados mediante la función de devolución de llamadasOnUpdateGameSession().

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 ( 
    const Aws::GameLift::Server::Model::StartMatchBackfillRequest &startBackfillRequest);

Parámetros

StartMatchBackfillRequest

Un objeto StartMatchBackfillRequest que comunica la siguiente información:

• Un ID de ticket que se asignará a la solicitud de reposición. Esta información es opcional; si no se proporciona ningún identificador, Amazon GameLift generará uno automáticamente.

• El creador de emparejamientos al que se enviará la solicitud. El ARN de configuración completo es obligatorio. Este valor se puede obtener de los datos del creador de emparejamientos de la sesión de juego.

• El ID de la sesión de juego que está en fase de reposición.

• Datos de emparejamiento disponibles para los jugadores actuales de la sesión de juego.

Obligatorio: sí

Valor devuelto

Devuelve un StartMatchBackfillOutcome objeto con el ticket de relleno correspondiente o un error con un mensaje de error. El estado del ticket se puede rastrear mediante la acción delAWS SDK DescribeMatchmaking().

Ejemplo

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

Cancela una solicitud de reposición de emparejamiento activa que se creó con StartMatchBackfill(). Consulte también la acción delAWS SDK StopMatchmaking(). Más información sobre la función de FlexMatch relleno.

Sintaxis

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

Parámetros

StopMatchBackfillRequest

Un objeto StopMatchBackfillRequest que identifica el ticket de emparejamiento que se va a cancelar:

• ID del ticket asignado a la solicitud de reposición que se va a cancelar

• el creador de emparejamientos al que se envió la solicitud de reposición

• sesión de juego asociada a la solicitud de reposición

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

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

Este método está en desuso en la versión 4.0.1. En su lugar, el proceso del servidor deberíaProcessEnding() ejecutarse una vez finalizada la sesión de juego.

Notifica al GameLift servicio de Amazon que el proceso del servidor ha finalizado la sesión de juego actual. Esta acción se activa cuando el proceso del servidor permanece activo y listo para alojar una nueva sesión de juego. Solo debe invocarse después de completar el procedimiento de finalización de la sesión de juego, ya que indica a Amazon GameLift que el proceso del servidor está disponible inmediatamente para albergar una nueva sesión de juego.

Esta acción no se ejecuta si el proceso del servidor se interrumpe una vez finalizada la sesión del juego. En su lugar, llamaProcessEnding() para indicar que tanto la sesión del juego como el proceso del servidor están finalizando.

Sintaxis

GenericOutcome TerminateGameSession();

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

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. Consulte también la acción delAWS SDK UpdateGameSession().

Sintaxis

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

Parámetros

newPlayerSessionPolítica

Valor de cadena que indica si la sesión de juego acepta jugadores nuevos.

Tipo: Aws:GameLift:: :Model::PlayerSessionCreationPolicy enum. Los valores válidos son:

• ACCEPT_ALL: se aceptan todas las sesiones de jugador nuevas.

• DENY_ALL: se rechazan todas las sesiones de jugador nuevas.

Obligatorio: sí

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso 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);

Destruir ()

Limpia la memoria asignada por initSDK () durante la inicialización del servidor del juego. Usa este método después de finalizar un proceso del servidor de juegos para evitar desperdiciar la memoria del servidor.

Sintaxis

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

Parámetros

No hay parámetros.

Valor devuelto

Devuelve un resultado genérico que consiste en el éxito o el fracaso con un mensaje de error.

Ejemplo

En este ejemplo, se limpia la memoria asignada por initSDK una vez finalizado un proceso del servidor de juegos.

if (Aws::GameLift::Server::ProcessEnding().IsSuccess()) {
  Aws::GameLift::Server::Destroy();
  exit(0);
}