SDK do servidor C++ para Amazon GameLift Servers 5.x – Ações

Use a referência do SDK 5.x do servidor para integrar o jogo multijogador à hospedagem com o Amazon GameLift Servers. Para obter orientação sobre o processo de integração, consulte Integre o Amazon GameLift Servers ao seu servidor de jogos com o SDK do servidor..

SDK do servidor C++ 5.x para Amazon GameLift Servers -- Tipos de dados

GetSdkVersion()

Retorna o número da versão atual do SDK compilado no processo de servidor.

Sintaxe

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

Valor de retorno

Se bem-sucedido, retornará a versão do SDK atual como um objeto AwsStringOutcome. O objeto retornada inclui apenas o número da versão (exemplo, 5.0.0). Se não for bem-sucedido, retornará uma mensagem de erro.

Exemplo

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

InitMetrics()

Inicializa o sistema de métricas para coletar e reportar dados de desempenho do servidor. Para obter melhores resultados, chame esse método antes de InitSDK() para ativar a coleta de métricas durante a inicialização do SDK.

Sintaxe

Aws::GameLift::GenericOutcome InitMetrics();
Aws::GameLift::GenericOutcome InitMetrics(const Aws::GameLift::Server::MetricsParameters &metricsParameters);

Parameters

Valor de retorno

Se for bem-sucedido, retornará um objeto Resultado genérico indicando sucesso. Se não for bem-sucedido, retornará uma mensagem de erro.

Exemplo

// Initialize with default parameters (uses environment variables if available)
// Defaults: localhost:8125 for StatsD, localhost:8126 for crash reporter
// FlushInterval: 10000ms, MaxPacketSize: 512 bytes
Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::InitMetrics();
if (outcome.IsSuccess()) {
    // Metrics system initialized successfully
}

// Initialize with custom parameters
Aws::GameLift::Server::MetricsParameters metricsParams("localhost", 8125, "crash-host", 8126, 5000, 1024);
Aws::GameLift::GenericOutcome customOutcome = Aws::GameLift::Server::InitMetrics(metricsParams);
if (customOutcome.IsSuccess()) {
    // Metrics system initialized with custom parameters
}

InitSDK()

Inicializa o Amazon GameLift Servers SDK. Chame esse método na inicialização, antes de quaisquer outros passos de inicialização relacionados ao Amazon GameLift Servers. Esta ação lê os parâmetros do servidor do ambiente host para definir a comunicação entre o processo do servidor de jogos e o serviço do Amazon GameLift Servers. Ele usa um token de idempotência, então você repete essa chamada com segurança quando ela falhar.

Se a compilação do servidor de jogos for implantada sem o Amazon GameLift Servers Agent em uma frota do Amazon GameLift Servers Anywhere ou uma frota de contêineres, chame InitSDK() e especifique um conjunto de parâmetros do servidor.

Sintaxe

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

Valor de retorno

Retorna um objeto InitSDKOutcome que indica se o processo do servidor está pronto para ser chamado ProcessReady().

Exemplo

//Call InitSDK to establish a local connection with the Amazon GameLift Servers Agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = 
  Aws::GameLift::Server::InitSDK();

InitSDK()

Inicializa o Amazon GameLift Servers SDK. Chame esse método na inicialização, antes de quaisquer outros passos de inicialização relacionados ao Amazon GameLift Servers. Essa ação exige um conjunto de parâmetros do servidor para configurar a comunicação entre o processo do servidor de jogo e o serviço do Amazon GameLift Servers. Ele usa um token de idempotência, então você repete essa chamada com segurança quando ela falhar.

Se a compilação do servidor de jogo for implantada em uma frota do EC2 gerenciada pelo Amazon GameLift Servers, em uma frota do Amazon GameLift Servers Anywhere ou em uma frota de contêineres com o Amazon GameLift Servers Agent, chame InitSDK() sem os parâmetros do servidor.

Sintaxe

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

Parameters

Valor de retorno

Retorna um objeto InitSDKOutcome que indica se o processo do servidor está pronto para ser chamado ProcessReady().

Exemplo

Exemplo de Amazon GameLift Servers 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 Amazon GameLift Servers Agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = Aws::GameLift::Server::InitSDK(serverParameters);

ProcessReady()

Notifica o Amazon GameLift Servers de que o processo do servidor está pronto para hospedar sessões do jogo. Chame esse método após invocar InitSDK(). Esse método deve ser chamado somente uma vez por processo.

Sintaxe

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

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

Este exemplo ilustra as implementações das funções de chamada e delegação 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 o serviço Amazon GameLift Servers de que o processo do servidor está pronto para hospedar sessões do jogo. Este método deve ser chamado depois que o processo do servidor estiver pronto para hospedar uma sessão de jogo. Os parâmetros especificam os nomes das funções de retorno do Amazon GameLift Servers para chamar determinadas circunstâncias. O código do servidor de jogos deve implementar essas funções.

Essa chamada é assíncrona. Para fazer uma chamada síncrona, use ProcessReady(). Consulte Inicializar o processo do servidor para obter mais detalhes.

Sintaxe

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

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

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

Notifica o Amazon GameLift Servers de que o processo do servidor está sendo encerrado. Chame esse método depois de todas as outras tarefas de limpeza (incluindo o encerramento da sessão ativa do jogo) e antes de encerrar o processo. Dependendo do resultado ProcessEnding(), o processo sai com sucesso (0) ou erro (-1) e gera um evento de frota. Se o processo for encerrado com um erro, o evento de frota gerado será SERVER_PROCESS_TERMINATED_UNHEALTHY.

Sintaxe

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

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

Este exemplo chama ProcessEnding() e Destroy() antes de encerrar o processo do servidor com um código de saída bem-sucedido ou de erro.

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

Notifica o Amazon GameLift Servers de que o processo do servidor ativou uma sessão do jogo e já está pronto para receber as conexões do jogador. Essa ação deve ser chamada como parte da função de retorno de chamada onStartGameSession(), após toda inicialização da sessão do jogo.​

Sintaxe

Aws::GameLift::GenericOutcome activateGameSessionOutcome = Aws::GameLift::Server::ActivateGameSession();

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

Este exemplo mostra chamado ActivateGameSession() como parte da função de delegação 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()

Atualiza a capacidade da sessão do jogo atual para aceitar novas sessões de jogador. Atualiza a capacidade da sessão do jogo atual para aceitar novas sessões de jogador.

Sintaxe

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

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

Este exemplo define a política de ingresso da sessão do jogo atual para aceitar todos os jogadores.

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

GetGameSessionId()

Recupera o ID da sessão de jogo hospedada pelo processo do servidor ativo.

Para processos inativos que não são ativados com uma sessão de jogo, a chamada retorna um GameLiftError.

Sintaxe

AwsStringOutcome GetGameSessionId()

Parameters

Essa ação não tem um parâmetro.

Valor de retorno

Se bem-sucedido, retornará o ID da sessão de jogo como um objeto AwsStringOutcome. Se não for bem-sucedido, retornará uma mensagem de erro.

Para processos inativos que não são ativados com uma sessão de jogo, a chamada retorna Success=True e GameSessionId="".

Exemplo

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

GetTerminationTime()

Retorna a hora em que um processo do servidor está programado para ser desligado, se essa informação estiver disponível. Um processo do servidor realiza a ação depois de receber um retorno de chamada onProcessTerminate() do serviço Amazon GameLift Servers. O Amazon GameLift Servers chama o onProcessTerminate() pelos seguintes motivos:

Sintaxe

AwsDateTimeOutcome GetTerminationTime()

Valor de retorno

Se for bem-sucedido, retornará o horário de término como um objeto AwsDateTimeOutcome. O valor é o tempo de rescisão, expresso em tiques decorridos desde então 0001 00:00:00. Por exemplo, o valor da data e hora 2020-09-13 12:26:40 -000Z é igual aos tiques 637355968000000000. Se nenhum horário de rescisão estiver disponível, o retornará uma mensagem de erro.

Se o processo não tiver recebido um retorno de chamada ProcessParameters.OnProcessTerminate(), uma mensagem de erro será retornada. Para obter mais informações sobre como desligar um processo do servidor, consulte Responder a uma notificação de desligamento do processo do servidor.

Exemplo

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

AcceptPlayerSession()

Notifica o serviço Amazon GameLift Servers de que um jogador com o ID da sessão do jogador especificado se conectou ao processo do servidor e precisa de validação. O Amazon GameLift Servers confirma que o ID da sessão do jogador é válido. Depois que a sessão do jogador é validada, o Amazon GameLift Servers altera o status do slot do jogador de RESERVED para ACTIVE.

Sintaxe

GenericOutcome AcceptPlayerSession(String playerSessionId)

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

Este exemplo trata de uma solicitação de conexão que inclui a validação e a rejeição de IDs de sessão de jogadores inválidas.

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

Notifica o Amazon GameLift Servers de que um jogador se desconectou do processo do servidor. Em resposta, o Amazon GameLift Servers altera o espaço do jogador para disponível.

Sintaxe

GenericOutcome RemovePlayerSession(String playerSessionId)

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

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

DescribePlayerSessions()

Recupera dados da sessão do jogador, que incluem configurações, metadados da sessão e dados do jogador. Use esse método para obter informações sobre o seguinte:

Sintaxe

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

Parameters

Valor de retorno

Se bem-sucedido, retorna um objeto Descreva o resultado das sessões de jogadores que contém um conjunto de objetos de sessão do jogador que atendem aos parâmetros de solicitação.

Exemplo

Este exemplo solicita todas as sessões de jogador conectadas ativamente a uma sessão de jogo especificada. Omitindo NextToken e definindo o valor Limit como 10, o Amazon GameLift Servers retorna os 10 primeiros registros de sessões do jogador correspondentes à solicitação.

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

Envia uma solicitação para encontrar novos jogadores para os slots abertos em uma sessão de jogo criada com o FlexMatch. Para obter mais informações, consulte o recurso de alocação do FlexMatch.

Esta ação é assíncrona. Se novos jogadores forem combinados, o Amazon GameLift Servers entregará os dados atualizados do marcador de jogos usando a função de retorno de chamada OnUpdateGameSession().

Um processo de servidor pode ter apenas uma solicitação de alocação de correspondência ativa por vez. Para enviar uma nova solicitação, primeiro chame StopMatchBackfill() para cancelar a solicitação original.

Sintaxe

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

Parameters

Valor de retorno

Retorna um objeto StartMatchBackfillOutcome com o ID do tíquete de alocação de correspondência ou um falha com uma mensagem de erro.

Exemplo

// 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 uma solicitação de alocação de correspondência ativa. Para obter mais informações, consulte o recurso de alocação do FlexMatch.

Sintaxe

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

Parameters

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

// 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 o caminho para o certificado TLS usado para criptografar a conexão de rede entre seu recurso de computação do Amazon GameLift Servers Anywhere e o Amazon GameLift Servers. Você poderá usar o caminho do certificado ao registrar seu dispositivo computacional em uma frota do Amazon GameLift Servers Anywhere. Para obter mais informações, consulte RegisterCompute.

Sintaxe

GetComputeCertificateOutcome Server::GetComputeCertificate()

Valor de retorno

Retorna um GetComputeCertificateOutcome.

Exemplo

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

GetFleetRoleCredentials()

Recupera as credenciais do perfil do IAM que autorizam o Amazon GameLift Servers a interagir com outros Serviços da AWS. Para obter mais informações, consulte Conecte seu servidor de jogos hospedado pelo Amazon GameLift Servers a outros recursos da AWS.

Sintaxe

GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

Parameters

GetFleetRoleCredentialsRequest

Valor de retorno

Informa um objeto GetFleetRoleCredentialsOutcome.

Exemplo

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

Este exemplo mostra o uso do valor RoleSessionName opcional para atribuir um nome à sessão de credenciais para fins de auditoria. Se você não fornecer um nome de sessão de função, o valor padrão "[fleet-id]-[host-id]" será usado.

// 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 o SDK do servidor de jogos do Amazon GameLift Servers da memória. Como melhor prática, chame esse método antes ProcessEnding() e depois de encerrar o processo. Se você estiver usando uma frota Anywhere e não estiver encerrando os processos do servidor após cada sessão de jogo, chame Destroy() e reinicialize InitSDK() antes de notificar o Amazon GameLift Servers de que o processo está pronto para hospedar uma sessão de jogo com ProcessReady().

Sintaxe

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

Parameters

Não há parâmetros.

Valor de retorno

Retorna um resultado genérico que consiste em sucesso ou falha com uma mensagem de erro.

Exemplo

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