Riferimento Amazon GameLift Server SDK (C++): azioni

Puoi usare questo riferimento all'SDK per server Amazon GameLift C++ per aiutarti a preparare il tuo gioco multiplayer da utilizzare con Amazon. GameLift Per informazioni dettagliate sul processo di integrazione, consultaAggiungi Amazon GameLift al tuo server di gioco.

AcceptPlayerSession()

Notifica al GameLift servizio Amazon che un giocatore con l'ID di sessione specificato si è connesso al processo del server e deve essere convalidato. Amazon GameLift verifica che l'ID della sessione del giocatore sia valido, ovvero che l'ID giocatore abbia riservato uno slot per il giocatore nella sessione di gioco. Una volta convalidato, Amazon GameLift modifica lo stato dello slot del giocatore da RISERVATO a ATTIVO.

Sintassi

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

Parametri

playerSessionId

ID univoco emesso dal GameLift servizio Amazon in risposta a una chiamata all'azione CreatePlayerSessiondell'GameLiftAPI Amazon AWS SDK. Il client di gioco fa riferimento a questo ID durante la connessione al processo del server.

Tipo: std: :string

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

Questo esempio illustra una funzione per gestire una richiesta di connessione, inclusi la convalida e il rifiuto di ID di sessioni giocatore non validi.

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 servizio Amazon che il processo del server ha avviato una sessione di gioco ed è ora pronto per ricevere le connessioni dei giocatori. Questa operazione deve essere chiamata come parte della funzione di callback onStartGameSession(), dopo il completamento dell'inizializzazione di tutte le sessioni di gioco.

Sintassi

GenericOutcome ActivateGameSession();

Parametri

Questa operazione non prevede parametri.

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

Questo esempio illustra la chiamata a ActivateGameSession() nell'ambito della funzione di callback 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 i dati della sessione giocatore, tra cui le impostazioni, i metadati della sessione e i dati dei giocatori. Utilizza questa operazione per ottenere le informazioni per una singola sessione giocatore, per tutte le sessioni giocatore in una sessione di gioco o per tutte le sessioni giocatore associate a un singolo ID giocatore.

Sintassi

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

Parametri

describePlayerSessionsRichiesta

Un oggetto DescribePlayerSessionsRequest che descrive le sessioni giocatore da recuperare.

Campo obbligatorio: sì

Valore restituito

Se l'esito è positivo, restituisce un oggetto DescribePlayerSessionsOutcome contenente un set di oggetti di sessione giocatore corrispondente ai parametri della richiesta. Gli oggetti della sessione Player hanno una struttura identica al tipo di PlayerSessiondati dell'GameLiftAPI Amazon AWS SDK.

Esempio

Questo esempio illustra una richiesta per tutte le sessioni giocatore attivamente connesse a una sessione di gioco specificata. Omettendo NextToken e impostando il Limit valore su 10, Amazon GameLift restituisce i record delle sessioni dei primi 10 giocatori corrispondenti alla richiesta.

// 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 identificatore univoco della sessione di gioco attualmente ospitata dal processo del server, se il processo del server è attivo. L'identificatore viene restituito nel formato ARN: arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>.

Per i processi inattivi che non sono ancora stati attivati con una sessione di gioco, la chiamata restituisce Success = True e GameSessionId = "" (una stringa vuota).

Sintassi

AwsStringOutcome GetGameSessionId();

Parametri

Questa operazione non prevede parametri.

Valore restituito

Se l'esito è positivo, l'ID della sessione di gioco verrà restituito come oggetto AwsStringOutcome. Se l'esito è negativo, verrà restituito un messaggio di errore.

Esempio

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

GetInstanceCertificate()

Recupera la posizione del file di un certificato TLS con codifica PEM associato al parco veicoli e alle relative istanze. AWS Certificate Managergenera questo certificato quando si crea una nuova flotta con la configurazione del certificato impostata su GENERATED. Utilizza questo certificato per stabilire una connessione sicura con un client di gioco e per crittografare la comunicazione client/server.

Sintassi

GetInstanceCertificateOutcome GetInstanceCertificate();

Parametri

Questa operazione non prevede parametri.

Valore restituito

In caso di successo, restituisce un GetInstanceCertificateOutcome oggetto contenente la posizione del file di certificati TLS e della catena di certificati della flotta, che sono archiviati nell'istanza. Nell'istanza viene inoltre archiviato un file di certificato principale, estratto dalla catena di certificati. Se l'esito è negativo, verrà restituito un messaggio di errore.

Per ulteriori informazioni sul certificato e sui dati della catena di certificati, consulta GetCertificateResponse Elements in the AWS Certificate Manager API Reference.

Esempio

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

GetSdkVersion()

Restituisce il numero di versione corrente dell'SDK in uso.

Sintassi

AwsStringOutcome GetSdkVersion();

Parametri

Questa operazione non prevede parametri.

Valore restituito

Se l'esito è positivo, restituisce la versione corrente dell'SDK come oggetto AwsStringOutcome. La stringa restituita include solo il numero di versione (ad esempio «3.1.5"). Se l'esito è negativo, verrà restituito un messaggio di errore.

Esempio

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

GetTerminationTime()

Restituisce il tempo di arresto pianificato di un processo del server, se è disponibile un tempo di chiusura. Un processo del server esegue questa azione dopo aver ricevuto una onProcessTerminate() richiamata dal GameLift servizio Amazon. Amazon GameLift può chiamare onProcessTerminate() per i seguenti motivi: (1) quando il processo del server ha segnalato problemi di salute o non ha risposto ad AmazonGameLift, (2) quando si interrompe l'istanza durante un evento di ridimensionamento o (3) quando un'istanza viene interrotta a causa di un'interruzione Spot.

Se il processo ha ricevuto una onProcessTerminate() richiamata, il valore restituito è il tempo di terminazione stimato. Se il processo non ha ricevuto una onProcessTerminate() richiamata, viene restituito un messaggio di errore. Ulteriori informazioni sull'arresto di un processo del server.

Sintassi

AwsLongOutcome GetTerminationTime();

Parametri

Questa operazione non prevede parametri.

Valore restituito

In caso di successo, restituisce l'ora di terminazione come AwsLongOutcome oggetto. Il valore è il tempo di terminazione, espresso in zecche trascorse da 0001 00:00:00. Ad esempio, il valore data/ora 2020-09-13 12:26:40 -000Z è uguale a 637355968000000000 zecche. Se non è disponibile alcun orario di terminazione, restituisce un messaggio di errore.

Esempio

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

InitSDK()

Inizializza l'Amazon GameLift SDK. Questo metodo deve essere richiamato all'avvio, prima che si verifichi qualsiasi altra inizializzazione GameLift relativa ad Amazon.

Sintassi

InitSDKOutcome InitSDK();

Parametri

Questa operazione non prevede parametri.

Valore restituito

In caso di successo, restituisce un InitSdkOutcome oggetto che indica che il processo del server è pronto per la chiamataProcessReady().

Esempio

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

ProcessEnding()

Notifica al GameLift servizio Amazon che il processo del server si sta spegnendo. Questo metodo deve essere richiamato dopo tutte le altre attività di pulizia, tra cui l'arresto di tutte le sessioni di gioco attive. Questo metodo deve uscire con il codice 0; un codice di uscita diverso da zero genera un messaggio di evento che indica che il processo non è terminato correttamente.

Una volta che il metodo esce con un codice 0, puoi terminare il processo con un codice di uscita riuscito. Puoi anche uscire dal processo con un codice di errore. Se esci con un codice di errore, l'evento della flotta indicherà che il processo è terminato in modo anomalo ()SERVER_PROCESS_TERMINATED_UNHEALTHY.

Sintassi

GenericOutcome ProcessEnding();

Parametri

Questa operazione non prevede parametri.

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

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 servizio Amazon che il processo del server è pronto per ospitare sessioni di gioco. Richiama questo metodo dopo aver richiamato InitSDK() e completato con successo le attività di configurazione necessarie prima che il processo del server possa ospitare una sessione di gioco. Questo metodo deve essere chiamato solo una volta per processo.

Questa chiamata è sincrona. Per effettuare una chiamata asincrona, utilizza ProcessReadyAsync(). Per ulteriori dettagli, consulta Inizializza il processo del server.

Sintassi

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

Parametri

processParameters

Un oggetto ProcessParameters che comunica le informazioni seguenti sul processo del server:

• Nomi dei metodi di callback, implementati nel codice del server di gioco, che il GameLift servizio Amazon richiama per comunicare con il processo del server.

• Numero di porta sulla quale è in ascolto il processo del server.

• Percorso a qualsiasi file specifico della sessione di gioco che desideri che Amazon GameLift acquisisca e memorizzi.

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

Questo esempio illustra le implementazioni della funzione di chiamata e callback 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 servizio Amazon che il processo del server è pronto per ospitare sessioni di gioco. Questo metodo deve essere chiamato quando il processo del server è pronto per l'hosting di una sessione di gioco. I parametri specificano i nomi delle funzioni di callback che Amazon GameLift può chiamare in determinate circostanze. Il codice del server di gioco deve implementare queste funzioni.

Questa chiamata è asincrona. Per effettuare una chiamata sincrona, utilizza ProcessReady(). Per ulteriori dettagli, consulta Inizializza il processo del server.

Sintassi

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

Parametri

processParameters

Un oggetto ProcessParameters che comunica le informazioni seguenti sul processo del server:

• Nomi dei metodi di callback, implementati nel codice del server di gioco, che il GameLift servizio Amazon richiama per comunicare con il processo del server.

• Numero di porta sulla quale è in ascolto il processo del server.

• Percorso a qualsiasi file specifico della sessione di gioco che desideri che Amazon GameLift acquisisca e memorizzi.

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

// 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 servizio Amazon che un giocatore con l'ID di sessione specificato si è disconnesso dal processo del server. In risposta, Amazon GameLift modifica lo slot del giocatore rendendolo disponibile, il che consente di assegnarlo a un nuovo giocatore.

Sintassi

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

Parametri

playerSessionId

ID univoco emesso dal GameLift servizio Amazon in risposta a una chiamata all'azione CreatePlayerSessiondell'GameLiftAPI Amazon AWS SDK. Il client di gioco fa riferimento a questo ID durante la connessione al processo del server.

Tipo: std: :string

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

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

StartMatchBackfill()

Invia una richiesta per trovare nuovi giocatori per gli slot aperti in una sessione di gioco creata con FlexMatch. Vedi anche l'azione AWS SDK StartMatchBackfill(). Con questa operazione, è possibile avviare le richieste di backfill degli abbinamenti da un processo del server di gioco che ospita la sessione di gioco. Scopri di più sulla funzione di FlexMatch riempimento.

Questa operazione è asincrona. Se i nuovi giocatori vengono abbinati con successo, il GameLift servizio Amazon fornisce dati aggiornati sul matchmaker richiamando la funzione di callback. OnUpdateGameSession()

Un processo del server può avere un solo backfill degli abbinamenti attivo alla volta. Per inviare una nuova richiesta, chiama prima StopMatchBackfill() per annullare la richiesta originale.

Sintassi

StartMatchBackfillOutcome StartMatchBackfill ( 
    const Aws::GameLift::Server::Model::StartMatchBackfillRequest &startBackfillRequest);

Parametri

StartMatchBackfillRequest

Un oggetto StartMatchBackfillRequest che comunica le informazioni seguenti:

• ID del ticket da assegnare alla richiesta di backfill. Queste informazioni sono facoltative; se non viene fornito alcun ID, Amazon GameLift ne genererà uno automaticamente.

• Matchmaker a cui inviare la richiesta. L'ARN di configurazione completo è obbligatorio. Questo valore può essere acquisito dai dati del matchmaker della sessione di gioco.

• ID della sessione di gioco che è in fase di backfilling.

• Dati di abbinamento disponibili per i giocatori correnti della sessione di gioco.

Campo obbligatorio: sì

Valore restituito

Restituisce un StartMatchBackfillOutcome oggetto con il ticket di backfill corrispondente o un errore con un messaggio di errore. Lo stato del ticket può essere monitorato utilizzando l'azione AWS SDK DescribeMatchmaking().

Esempio

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

Annulla una richiesta di backfill degli abbinamenti attiva creata con StartMatchBackfill(). Vedi anche l'azione AWS SDK StopMatchmaking(). Scopri di più sulla funzione di FlexMatch riempimento.

Sintassi

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

Parametri

StopMatchBackfillRequest

Un oggetto StopMatchBackfillRequest che identifica il ticket di abbinamento da annullare:

• ID del ticket assegnato alla richiesta di backfill in fase di annullamento

• matchmaker a cui è stata inviata la richiesta di backfill

• sessione di gioco associata alla richiesta di backfill

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

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

Questo metodo è obsoleto con la versione 4.0.1. Invece, il processo del server dovrebbe richiamare ProcessEnding() dopo la fine di una sessione di gioco.

Notifica al GameLift servizio Amazon che il processo del server ha terminato la sessione di gioco corrente. Questa azione viene richiamata quando il processo del server rimarrà attivo e pronto per ospitare una nuova sessione di gioco. Dovrebbe essere richiamato solo dopo il completamento della procedura di chiusura della sessione di gioco, poiché segnala ad Amazon GameLift che il processo del server è immediatamente disponibile per ospitare una nuova sessione di gioco.

Questa azione non viene chiamata se il processo del server verrà chiuso dopo l'interruzione della sessione di gioco. Chiama invece ProcessEnding() per segnalare che sia la sessione di gioco che il processo del server stanno terminando.

Sintassi

GenericOutcome TerminateGameSession();

Parametri

Questa operazione non prevede parametri.

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

UpdatePlayerSessionCreationPolicy()

Aggiorna la capacità della sessione di gioco corrente di accettare nuove sessioni giocatore. Una sessione di gioco può essere configurata per accettare o rifiutare tutte le nuove sessioni giocatore. Vedi anche l'azione AWS SDK UpdateGameSession().

Sintassi

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

Parametri

newPlayerSessionPolitica

Valore della stringa che indica se la sessione di gioco accetta nuovi giocatori.

Tipo: Aws:GameLift: :Model:: PlayerSessionCreationPolicy enum. I valori validi includono:

• ACCEPT_ALL: accetta tutte le nuove sessioni giocatore.

• DENY_ALL: rifiuta tutte le nuove sessioni giocatore.

Campo obbligatorio: sì

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

Questo esempio definisce la policy di partecipazione alla sessione di gioco corrente per accettare tutti i giocatori.

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

Distruggi ()

Pulisce la memoria allocata da initSDK () durante l'inizializzazione del server di gioco. Usa questo metodo dopo aver terminato un processo del server di gioco per evitare di sprecare la memoria del server.

Sintassi

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

Parametri

Non ci sono parametri.

Valore restituito

Restituisce un risultato generico composto da successo o fallimento con un messaggio di errore.

Esempio

Questo esempio pulisce la memoria allocata da initSDK al termine di un processo del server di gioco.

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