C++ サーバー SDK 5.x for Amazon GameLift Servers -- アクション

サーバー SDK 5.x リファレンスを使用して、Amazon GameLift Servers でホスティングするマルチプレイヤーゲームを統合します。統合プロセスのガイダンスについては、「サーバー SDK を使用して、Amazon GameLift Servers をゲームサーバーに追加します。」を参照してください。

C++ サーバー SDK 5.x for Amazon GameLift Servers -- データ型

GetSdkVersion()

サーバープロセスに組み込まれた SDK の現在のバージョン番号を返します。

構文

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

戻り値

成功した場合、AwsStringOutcome オブジェクトとして現在の SDK バージョンを返します。返されるオブジェクトには、バージョン番号が含まれます (例: 5.0.0)。成功しなかった場合、エラーメッセージを返します。

例

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

InitMetrics()

サーバーパフォーマンスデータを収集およびレポートするためのメトリクスシステムを初期化します。最良の結果を得るには、InitSDK() の前にこのメソッドを呼び出して、SDK の初期化中にメトリクス収集を有効にします。

構文

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

パラメータ

戻り値

成功すると、成功を示す GenericOutcome オブジェクトが返されます。成功しなかった場合、エラーメッセージを返します。

例

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

Amazon GameLift Servers SDK を初期化します。他のAmazon GameLift Servers 関連の初期化が実行される前に、起動時にこのメソッドを呼び出します。このアクションは、ホスト環境からサーバーパラメータを読み取り、ゲームサーバープロセスと Amazon GameLift Servers サービス間の通信を設定します。べき等性トークンを使用するため、失敗したときにこの呼び出しを安全に再試行できます。

ゲームサーバービルドを Amazon GameLift Servers エージェントなしで Amazon GameLift Servers Anywhere フリートまたはコンテナフリートにデプロイする場合は、InitSDK() を呼び出し、サーバーパラメータのセットを指定します。

構文

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

戻り値

サーバープロセスが ProcessReady() を呼び出す準備ができているかどうかを示す InitSDKOutcome オブジェクトを返します。

例

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

Amazon GameLift Servers SDK を初期化します。他のAmazon GameLift Servers 関連の初期化が実行される前に、起動時にこのメソッドを呼び出します。このアクションには、ゲームサーバープロセスと Amazon GameLift Servers サービス間の通信を設定するサーバーパラメータのセットが必要です。べき等性トークンを使用するため、失敗したときにこの呼び出しを安全に再試行できます。

ゲームサーバービルドを Amazon GameLift Servers マネージド EC2 フリート、または Amazon GameLift Servers エージェントを使用する Amazon GameLift Servers Anywhere フリート、またはコンテナフリートにデプロイする場合は、サーバーパラメータなしで InitSDK() を呼び出します。

構文

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

パラメータ

戻り値

サーバープロセスが ProcessReady() を呼び出す準備ができているかどうかを示す InitSDKOutcome オブジェクトを返します。

例

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

サーバープロセスがゲームセッションをホストする準備ができたことを Amazon GameLift Servers に通知します。InitSDK() を呼び出した後にこのメソッドを呼び出します。このメソッドは、プロセスごとに 1 回だけ呼び出す必要があります。

構文

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

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例では、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()

サーバープロセスがゲームセッションをホストする準備ができたことを Amazon GameLift Servers サービスに通知します。サーバープロセスがゲームセッションをホストする準備ができたら、このメソッドを呼び出します。パラメータで、Amazon GameLift Servers が特定の状況で呼び出すコールバック関数の名前を指定します。ゲームサーバーコードは、これらの関数を実装する必要があります。

この呼び出しは非同期です。同期呼び出しを実行するには、ProcessReady() を使用します。詳細については、「サーバープロセスを初期化する」を参照してください。

構文

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

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

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

サーバープロセスが終了していることを Amazon GameLift Servers に通知します。アクティブなゲームセッションのシャットダウンを含むその他すべてのクリーンアップタスクの後そして、プロセスを終了する前にこのメソッドを呼び出します。ProcessEnding() の結果に応じて、プロセスは成功 (0) またはエラー (-1) で終了し、フリートイベントが生成されます。プロセスがエラーで終了した場合、生成されるフリートイベントは SERVER_PROCESS_TERMINATED_UNHEALTHY です。

構文

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

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例では、サーバープロセスを終了する前に、成功またはエラーの終了コードで ProcessEnding() と Destroy() を呼び出します。

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

サーバープロセスがゲームセッションをアクティブにし、プレイヤーの接続を受ける準備ができていることを Amazon GameLift Servers に通知します。このアクションは、すべてのゲームセッションの初期化の後、onStartGameSession() コールバック関数の一部として呼び出されます。

構文

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

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例では、onStartGameSession() 委任関数の一部として呼び出された ActivateGameSession() を示しています。

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

現在のゲームセッションの機能を更新し、新しいプレイヤーセッションを承諾します。ゲームセッションは、新しいプレイヤーセッションをすべて受け入れるか拒否するかを設定できます。

構文

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

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例は、現在のゲームセッションの参加ポリシーを、すべてのプレイヤーを受け入れるように設定します。

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

GetGameSessionId()

アクティブなサーバープロセスにホストされたゲームセッションの ID を取得します。

ゲームセッションでアクティブ化されていないアイドル状態のプロセスの場合、呼び出しは GameLiftError を返します。

構文

AwsStringOutcome GetGameSessionId()

パラメータ

このアクションにはパラメータがありません。

戻り値

成功した場合、ゲームセッション ID を AwsStringOutcome オブジェクトとして返します。成功しなかった場合、エラーメッセージを返します。

ゲームセッションでまだアクティブ化されていないアイドルプロセスの場合、呼び出しは Success=True および GameSessionId="" を返します。

例

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

GetTerminationTime()

終了時刻が判る場合に、サーバープロセスがシャットダウンを予定している時刻を返します。サーバープロセスは、Amazon GameLift Servers から onProcessTerminate() コールバックを受信した後、アクションを実行します。Amazon GameLift Servers は、次の理由で onProcessTerminate() を呼び出します。

構文

AwsDateTimeOutcome GetTerminationTime()

戻り値

成功した場合、終了時刻を AwsDateTimeOutcome オブジェクトとして返します。値は終了時間で、0001 00:00:00 以降の経過ティックで表現されます。例えば、日付時刻の値 2020-09-13 12:26:40 -000Z は、637355968000000000 ティックに等しくなります。終了時間がない場合は、エラーメッセージを返します。

プロセスが ProcessParameters.OnProcessTerminate() コールバックを受信していない場合、エラーメッセージが返されます。サーバープロセスのシャットダウンの詳細については、「サーバープロセスのシャットダウン通知に応答する」を参照してください。

例

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

AcceptPlayerSession()

指定されたプレイヤーセッション ID を持つプレイヤーがサーバープロセスに接続し、検証が必要であることを、Amazon GameLift Servers に通知します。Amazon GameLift Servers は、プレイヤーセッション ID が有効であることを検証します。検証できたら、Amazon GameLift Servers はプレーヤースロットの状態を RESERVED から ACTIVE に変更します。

構文

GenericOutcome AcceptPlayerSession(String playerSessionId)

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例では、無効なプレイヤーセッション ID の検証と拒否を含む接続リクエストを処理します。

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

プレイヤーがサーバープロセスから切断されたことを Amazon GameLift Servers に通知します。それに応じて、Amazon GameLift Servers はプレイヤースロットを利用可能に変更します。

構文

GenericOutcome RemovePlayerSession(String playerSessionId)

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

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

DescribePlayerSessions()

設定、セッションメタデータ、プレイヤーデータを含む、プレイヤーセッションデータを取得します。このメソッドを使用して、以下に関する情報を取得します。

構文

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

パラメータ

戻り値

成功した場合は、リクエストのパラメータに適合したプレイヤーセッションオブジェクトのセットを含む DescribePlayerSessionsOutcome オブジェクトを返します。

例

この例は、指定したゲームセッションにアクティブに接続されているすべてのプレイヤーセッションのリクエストします。NextToken を省略し、Limit 値を 10 に設定すると、Amazon GameLift Servers は、リクエストに一致するプレイヤーセッションレコードの最初の 10 個を返します。

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

FlexMatch で作成されたゲームセッションの空きスロット用に新規プレイヤーを検索するリクエストを送信します。詳細については、「FlexMatch バックフィル機能」を参照してください。

このアクションは非同期です。新規プレイヤーが正常にマッチングされると、Amazon GameLift Servers はコールバック関数 OnUpdateGameSession() を使用して更新済みマッチメーカーデータを送信します。

サーバープロセスではアクティブなマッチバックフィルリクエストは一度に 1 つだけです。新しいリクエストを送信するには、まず StopMatchBackfill() を呼び出して元のリクエストをキャンセルする必要があります。

構文

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

パラメータ

戻り値

StartMatchBackfillOutcome オブジェクトを、マッチバックフィルチケット ID またはエラーメッセージを伴うエラーとともに返します。

例

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

アクティブなマッチバックフィルリクエストをキャンセルします。詳細については、「FlexMatch バックフィル機能」を参照してください。

構文

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

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

Amazon GameLift Servers Anywhere コンピューティングリソースと Amazon GameLift Servers 間のネットワーク接続を暗号化するために使用される TLS 証明書へのパスを取得します。この証明書パスは、コンピューティングデバイスを Amazon GameLift Servers Anywhere フリートに登録するときに使用できます。詳細については、「RegisterCompute」を参照してください。

構文

GetComputeCertificateOutcome Server::GetComputeCertificate()

戻り値

戻り値は GetComputeCertificateOutcome。

例

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

GetFleetRoleCredentials()

Amazon GameLift Servers が他の AWS のサービス とやり取りすることを許可する IAM ロール認証情報を取得します。詳細については、「Amazon GameLift Servers ホストされたゲームサーバーを他の AWS リソースに接続する」を参照してください。

構文

GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

パラメータ

GetFleetRoleCredentialsRequest

戻り値

GetFleetRoleCredentialsOutcome オブジェクトを返します。

例

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

この例は、監査目的でオプションの RoleSessionName 値を使用して認証情報セッションに名前を割り当てる方法を示しています。ロールセッション名を指定しない場合、デフォルト値「[fleet-id]-[host-id]」が使用されます。

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

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

Destroy()

Amazon GameLift Servers ゲームサーバー SDK をメモリから解放します。ベストプラクティスとして、ProcessEnding() の後、かつプロセスの終了前にこのメソッドを呼び出します。Anywhere フリートを使用していて、ゲームセッションのたびにサーバープロセスを終了しない場合は、Destroy()、InitSDK() の順に呼び出して再初期化してから、ProcessReady() でゲームセッションをホストする準備ができたことを Amazon GameLift Servers に通知します。

構文

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

パラメータ

パラメータはありません。

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

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