Référence GameLift du SDK Amazon Server (C++) : Actions

Vous pouvez utiliser cette référence du SDK pour serveurs Amazon GameLift C++ pour vous aider à préparer votre jeu multijoueur en vue de son utilisation avec AmazonGameLift. Pour plus de détails sur le processus d'intégration, consultezAjoutez Amazon GameLift à votre serveur de jeu.

AcceptPlayerSession()

Informe le GameLift service Amazon qu'un joueur avec l'identifiant de session de joueur spécifié s'est connecté au processus du serveur et doit être validé. Amazon GameLift vérifie que l'identifiant de session du joueur est valide, c'est-à-dire que l'identifiant du joueur a réservé un emplacement de joueur dans la session de jeu. Une fois la validation effectuée, GameLift Amazon fait passer le statut de la machine à sous RÉSERVÉ à ACTIVE.

Syntaxe

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

Paramètres

playerSessionId

Identifiant unique émis par le GameLift service Amazon en réponse à un appel à l'action CreatePlayerSessionde l'GameLiftAPI Amazon du AWS SDK. Le client du jeu fait référence à cet identifiant lors de la connexion au processus du serveur.

Type : std : :string

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

Cet exemple illustre une fonction pour le traitement d'une demande de connexion, y compris la validation et le rejet des ID de session joueur non valides.

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

Indique au GameLift service Amazon que le processus du serveur a démarré une session de jeu et qu'il est désormais prêt à recevoir les connexions des joueurs. Cette action doit être appelée dans le cadre de la fonction de rappel onStartGameSession(), une fois que l'initialisation de toutes les sessions de jeu est terminée.

Syntaxe

GenericOutcome ActivateGameSession();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

Cet exemple illustre l'appel de ActivateGameSession() dans le cadre de la fonction de rappel 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()

Récupère les données de session de joueur, y compris les paramètres, les métadonnées de session et les données de joueur. Utilisez cette action pour obtenir des informations pour une seule session de joueur, pour toutes les sessions de joueur d'une session de jeu ou pour toutes les sessions de joueur associées à un seul ID de joueur.

Syntaxe

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

Paramètres

describePlayerSessionsRequête

Objet DescribePlayerSessionsRequest décrivant les sessions de joueur à récupérer.

Obligatoire : oui

Valeur renvoyée

En cas de réussite, renvoie un objet DescribePlayerSessionsOutcome qui contient un ensemble d'objets de session de joueur correspondant aux paramètres de la demande. Les objets de session du joueur ont une structure identique au type de PlayerSessiondonnées de l'GameLiftAPI Amazon du AWS SDK.

Exemple

Cet exemple illustre une demande de toutes les sessions de joueur activement connectées à une session de jeu spécifiée. En omettant la Limit valeur NextToken et en la définissant sur 10, Amazon GameLift renvoie les 10 premiers enregistrements des sessions des joueurs correspondant à la demande.

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

Extrait un identifiant unique pour la session de jeu actuellement hébergée par le processus serveur, si ce dernier est actif. L'identifiant est retourné dans un format ARN : arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>.

Pour les processus inactifs qui ne sont pas encore activés lors d'une session de jeu, l'appel renvoie Success GameSessionId = True et = "" (une chaîne vide).

Syntaxe

AwsStringOutcome GetGameSessionId();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

En cas de réussite, renvoie l'ID de session de jeu en tant qu'objet AwsStringOutcome. En cas d'échec, renvoie un message d'erreur.

Exemple

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

GetInstanceCertificate()

Récupère l'emplacement du fichier d'un certificat TLS codé PEM associé au parc et à ses instances. AWS Certificate Managergénère ce certificat lorsque vous créez une nouvelle flotte avec la configuration du certificat définie sur GENERATED. Utilisez ce certificat pour établir une connexion sécurisée avec un client de jeu et pour chiffrer la communication client/serveur.

Syntaxe

GetInstanceCertificateOutcome GetInstanceCertificate();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

En cas de succès, renvoie un GetInstanceCertificateOutcome objet contenant l'emplacement du fichier de certificat TLS et de la chaîne de certificats du parc, qui sont stockés sur l'instance. Un fichier de certificat racine, extrait de la chaîne de certificats, est également stocké sur l'instance. En cas d'échec, renvoie un message d'erreur.

Pour plus d'informations sur le certificat et les données de la chaîne de certificats, consultez la section Éléments de GetCertificate réponse dans la référence de l'AWS Certificate ManagerAPI.

Exemple

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

GetSdkVersion()

Renvoie numéro de version actuel du kit SDK en cours d'utilisation.

Syntaxe

AwsStringOutcome GetSdkVersion();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

En cas de réussite, renvoie la version actuelle du kit SDK en tant qu'objet AwsStringOutcome. La chaîne renvoyée inclut uniquement le numéro de version (par exemple « 3.1.5 »). En cas d'échec, renvoie un message d'erreur.

Exemple

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

GetTerminationTime()

Renvoie l'heure d'arrêt planifiée pour un processus serveur, si une heure de résiliation est disponible. Un processus serveur effectue cette action après avoir reçu un onProcessTerminate() rappel du GameLift service Amazon. Amazon GameLift peut appeler onProcessTerminate() pour les raisons suivantes : (1) lorsque le processus du serveur a signalé un mauvais fonctionnement ou n'a pas répondu à AmazonGameLift, (2) lors de la résiliation de l'instance lors d'un événement de réduction de la taille ou (3) lorsqu'une instance est résiliée en raison d'une interruption Spot.

Si le processus a reçu un onProcessTerminate() rappel, la valeur renvoyée est l'heure de fin estimée. Si le processus n'a pas reçu de onProcessTerminate() rappel, un message d'erreur est renvoyé. En savoir plus sur l'arrêt d'un processus serveur.

Syntaxe

AwsLongOutcome GetTerminationTime();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

En cas de succès, renvoie l'heure de fin sous forme d'AwsLongOutcomeobjet. La valeur est l'heure de fin, exprimée en ticks écoulés depuis 0001 00:00:00. Par exemple, la valeur date/heure 2020-09-13 12:26:40 -000Z est égale à 637355968000000000 ticks. Si aucune heure de fin n'est disponible, renvoie un message d'erreur.

Exemple

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

InitSDK()

Initialise le GameLift SDK Amazon. Cette méthode doit être appelée au lancement, avant toute autre initialisation GameLift liée à Amazon.

Syntaxe

InitSDKOutcome InitSDK();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

En cas de succès, renvoie un InitSdkOutcome objet indiquant que le processus serveur est prêt à être appeléProcessReady().

Exemple

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

ProcessEnding()

Informe le GameLift service Amazon que le processus du serveur est en train de s'arrêter. Cette méthode doit être appelée après toutes les autres tâches de nettoyage, y compris l'arrêt de toutes les sessions de jeu actives. Cette méthode doit quitter avec un code de sortie 0 ; un code de sortie différent de 0 génère un message d'événement indiquant que le processus ne s'est pas fermé correctement.

Une fois que la méthode se termine avec un code de 0, vous pouvez terminer le processus avec un code de sortie réussi. Vous pouvez également quitter le processus avec un code d'erreur. Si vous quittez le site avec un code d'erreur, l'événement du parc indiquera que le processus s'est terminé de manière anormale (SERVER_PROCESS_TERMINATED_UNHEALTHY).

Syntaxe

GenericOutcome ProcessEnding();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

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

ProcessReady()

Indique au GameLift service Amazon que le processus du serveur est prêt à héberger des sessions de jeu. Appelez cette méthode après avoir invoqué InitSDK() et terminé avec succès les tâches de configuration requises pour que le processus serveur puisse héberger une session de jeu. Cette méthode ne doit être appelée qu'une seule fois par processus.

Cet appel est synchrone. Pour effectuer un appel asynchrone, utilisez ProcessReadyAsync(). Pour plus d'informations, consultez Initialiser le processus du serveur.

Syntaxe

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

Paramètres

processParameters

Objet ProcessParameters communiquant les informations suivantes relatives au processus serveur :

• Noms des méthodes de rappel, implémentées dans le code du serveur de jeu, que le GameLift service Amazon invoque pour communiquer avec le processus du serveur.

• Numéro de port sur lequel le processus serveur écoute.

• Chemin d'accès à tous les fichiers spécifiques à une session de jeu que vous souhaitez qu'Amazon capture GameLift et stocke.

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

Cet exemple illustre les implémentations de la fonction d'appel et de rappel 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()

Indique au GameLift service Amazon que le processus du serveur est prêt à héberger des sessions de jeu. Cette méthode doit être appelée une fois que le processus serveur est prêt à héberger une session de jeu. Les paramètres spécifient les noms des fonctions de rappel qu'Amazon GameLift peut appeler dans certaines circonstances. Le code du serveur de jeux doit implémenter ces fonctions.

Cet appel est asynchrone. Pour effectuer un appel synchrone, utilisez ProcessReady(). Pour plus d'informations, consultez Initialiser le processus du serveur.

Syntaxe

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

Paramètres

processParameters

Objet ProcessParameters communiquant les informations suivantes relatives au processus serveur :

• Noms des méthodes de rappel, implémentées dans le code du serveur de jeu, que le GameLift service Amazon invoque pour communiquer avec le processus du serveur.

• Numéro de port sur lequel le processus serveur écoute.

• Chemin d'accès à tous les fichiers spécifiques à une session de jeu que vous souhaitez qu'Amazon capture GameLift et stocke.

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

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

Informe le GameLift service Amazon qu'un joueur avec l'identifiant de session de joueur spécifié s'est déconnecté du processus serveur. En réponse, Amazon GameLift change le créneau de joueur pour qu'il soit disponible, ce qui permet de l'attribuer à un nouveau joueur.

Syntaxe

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

Paramètres

playerSessionId

Identifiant unique émis par le GameLift service Amazon en réponse à un appel à l'action CreatePlayerSessionde l'GameLiftAPI Amazon du AWS SDK. Le client du jeu fait référence à cet identifiant lors de la connexion au processus du serveur.

Type : std : :string

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

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

StartMatchBackfill()

Envoie une demande de recherche de nouveaux joueurs pour des emplacements ouverts dans une session de jeu créée avec FlexMatch. Voir également l'action du AWS SDK StartMatchBackfill(). Avec cette action, les requêtes de renvoi de correspondance peuvent être initiées par processus de serveur de jeu qui héberge la session de jeu. En savoir plus sur la fonction de FlexMatch remblayage.

Cette action est asynchrone. Si de nouveaux joueurs sont jumelés avec succès, le GameLift service Amazon fournit des données de matchmaking mises à jour en invoquant la fonction de rappel. OnUpdateGameSession()

Un processus de serveur ne peut comporter qu'une seule requête de renvoi de correspondance à la fois. Pour envoyer une nouvelle requête, appelez d'abord StopMatchBackfill() pour annuler la requête d'origine.

Syntaxe

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

Paramètres

StartMatchBackfillRequest

Objet StartMatchBackfillRequest qui communique les informations suivantes :

• ID de ticket à attribuer à la requête de renvoi. Ces informations sont facultatives ; si aucun identifiant n'est fourni, Amazon en GameLift générera un automatiquement.

• Matchmaker auquel envoyer la requête. L'ARN de configuration complet est obligatoire. Cette valeur peut être acquise à partir des données matchmaker de la session de jeu.

• ID de la session de jeu en cours de renvoi.

• Données de correspondance disponibles pour les joueurs actuels de la session de jeu.

Obligatoire : oui

Valeur renvoyée

Renvoie un StartMatchBackfillOutcome objet contenant le ticket de remplissage correspondant ou un échec avec un message d'erreur. L'état du ticket peut être suivi à l'aide de l'action du AWS SDK DescribeMatchmaking().

Exemple

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

Annule une requête de renvoi de correspondance active qui a été créée avec StartMatchBackfill(). Voir également l'action du AWS SDK StopMatchmaking(). En savoir plus sur la fonction de FlexMatch remblayage.

Syntaxe

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

Paramètres

StopMatchBackfillRequest

Objet StopMatchBackfillRequest qui identifie le ticket de correspondance à annuler :

• Identifiant de ticket attribué à la requête de renvoi en cours d'annulation

• matchmaker auquel a été envoyée la requête

• session de jeu associée à la requête de renvoi

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

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

Cette méthode est obsolète depuis la version 4.0.1. Au lieu de cela, le processus du serveur doit appeler ProcessEnding() après la fin d'une session de jeu.

Informe le GameLift service Amazon que le processus du serveur a mis fin à la session de jeu en cours. Cette action est appelée lorsque le processus du serveur reste actif et prêt à héberger une nouvelle session de jeu. Il ne doit être appelé qu'une fois la procédure de fin de session de jeu terminée, car il indique à Amazon GameLift que le processus du serveur est immédiatement disponible pour héberger une nouvelle session de jeu.

Cette action n'est pas appelée si le processus du serveur doit être arrêté après la fin de la session de jeu. Appelez plutôt ProcessEnding() pour signaler que la session de jeu et le processus du serveur se terminent.

Syntaxe

GenericOutcome TerminateGameSession();

Paramètres

Cette action n'a aucun paramètre.

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

UpdatePlayerSessionCreationPolicy()

Met à jour la capacité de la session de jeu à accepter de nouvelles sessions de joueur. Une session de jeu peut être définie pour accepter ou refuser toutes les nouvelles sessions joueur. Voir également l'action du AWS SDK UpdateGameSession().

Syntaxe

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

Paramètres

newPlayerSessionPolitique

Valeur de chaîne indiquant si la session de jeu accepte ou non de nouveaux joueurs.

Type : Aws : GameLift : :Model : : PlayerSessionCreationPolicy enum. Les valeurs valides sont les suivantes :

• ACCEPT_ALL — Accepte toutes les sessions des nouveaux joueurs.

• DENY_ALL — Refuser toutes les sessions des nouveaux joueurs.

Obligatoire : oui

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

Cet exemple définit la stratégie de participation de la session de jeu actuelle de manière à ce que tous les joueurs soient acceptés.

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

Détruire ()

Nettoie la mémoire allouée par initSDK () lors de l'initialisation du serveur de jeu. Utilisez cette méthode après avoir terminé un processus sur un serveur de jeu pour éviter de gaspiller la mémoire du serveur.

Syntaxe

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

Paramètres

Il n'y a aucun paramètre.

Valeur renvoyée

Renvoie un résultat générique composé d'un succès ou d'un échec avec un message d'erreur.

Exemple

Cet exemple nettoie la mémoire allouée par InitSDK après la fin d'un processus sur un serveur de jeu.

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