Amazon GameLift 服務器開發套件（C ++）5.x 參考：操作

您可以使用此 Amazon GameLift C++ 伺服器開發套件參考來協助您準備好與 Amazon 搭配使用的多人遊戲 GameLift。如需有關整合程序的詳細資訊，請參閱添加亞馬遜GameLift到您的遊戲服務器。

注意

本主題說明使用 GameLift C++ 標準程式庫 (std) 建置時可以使用的 Amazon C++ API。具體而言，本文件適用於您使用-DDGAMELIFT_USE_STD=1選項編譯的程式碼。

GetSdkVersion()

傳回內建至伺服器程序的目前開發套件版本編號。

語法

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

傳回值

如果成功，將目前開發套件版本以 AwsStringOutcome 物件傳回。傳回的物件包含版本號碼 (範例5.0.0)。如果不成功，則會傳回錯誤訊息。

範例

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

InitSDK()

為受管 EC2 叢集初始化 Amazon GameLift 開發套件。在與 Amazon 相關的任何其他初始化發生之前，請在啟動 GameLift 時呼叫此方法。此方法會從主機環境讀取伺服器參數，以設定伺服器與 Amazon GameLift 服務之間的通訊。

語法

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

傳回值

返回一個首頁成果對象，指示服務器進程是否準備好調用ProcessReady()。

範例

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

InitSDK()

初始化Anywhere叢集的 Amazon GameLift 開發套件。在與 Amazon 相關的任何其他初始化發生之前，請在啟動 GameLift 時呼叫此方法。此方法需要明確的伺服器參數來設定伺服器與 Amazon GameLift 服務之間的通訊。

語法

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

參數

ServerParameters

若要初始化 Amazon GameLift Anywhere 叢集上的遊戲伺服器，請使用下列資訊建構ServerParameters物件：

• WebSocket 用來連線到遊戲伺服器的 URL。

• 用來託管遊戲伺服器的程序 ID。

• 主控遊戲伺服器處理程序的運算 ID。

• 包含您的 Amazon GameLift Anywhere 運算的 Amazon GameLift 車隊的 ID。

• Amazon GameLift 操作生成的授權令牌。

傳回值

返回一個首頁成果對象，指示服務器進程是否準備好調用ProcessReady()。

注意

如果部署到 InitSDK() Anywhere 叢集的遊戲組建時呼叫失敗，請檢查建立組建資源時使用的ServerSdkVersion參數。您必須將此值明確設定為使用中的伺服器 SDK 版本。此參數的預設值為 4.x，不相容。若要解決此問題，請建立新組建並將其部署到新的叢集。

範例

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

ProcessReady()

通 GameLift 知 Amazon 伺服器程序已準備好主持遊戲工作階段。調用後調用InitSDK()此方法。每個進程應該只調用一次此方法。

語法

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

參數

processParameters

ProcessParameters 物件會傳達以下有關伺服器程序的資訊：

• Amazon GameLift 服務呼叫以與伺服器處理序通訊之遊戲伺服器程式碼中實作的回呼方法名稱。

• 伺服器程序正在接聽的埠號。

• 您希望 Amazon 擷取和存放的任何遊戲工作階段特定檔案 GameLift 的路徑。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例會說明 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 服務伺服器處理序已準備好主持遊戲工作階段。在伺服器進程準備好主持遊戲工作階段之後，應該呼叫此方法。這些參數指定 Amazon GameLift 在某些情況下調用的回調函數名稱。遊戲伺服器代碼必須實作上述函數。

此為非同步呼叫。若要進行同步呼叫，請使用 ProcessReady()。如需詳細資訊，請參閱初始化伺服器處理序。

語法

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

參數

processParameters

ProcessParameters 物件會傳達以下有關伺服器程序的資訊：

• Amazon GameLift 服務呼叫以與伺服器處理序通訊之遊戲伺服器程式碼中實作的回呼方法名稱。

• 伺服器程序正在接聽的埠號。

• 您希望 Amazon 擷取和存放的任何遊戲工作階段特定檔案 GameLift 的路徑。

必要：是

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

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

通 GameLift 知 Amazon 服務器進程正在終止。在所有其他清理任務（包括關閉活動的遊戲會話）之後以及終止進程之前調用此方法。根據的結果ProcessEnding()，程序會以成功 (0) 或錯誤 (-1) 結束，並產生叢集事件。如果程序因錯誤而終止，則產生的叢集事件為SERVER_PROCESS_TERMINATED_UNHEALTHY。

語法

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

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例會Destroy()在使用成功或錯誤結束代碼來終止伺服器處理序之前呼叫ProcessEnding()和。

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

通 GameLift 知 Amazon 伺服器程序已啟動遊戲工作階段，現在已準備好接收玩家連線。在所有遊戲會話初始化之後，應將此操作作為onStartGameSession()回調函數的一部分調用。

語法

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

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

這個例子顯示了作ActivateGameSession()為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()

更新目前遊戲工作階段的能力，以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。

語法

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

參數

playerCreationSession政策

類型：PlayerSessionCreationPolicy枚舉值。

必要：是

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。

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 的onProcessTerminate()回調後採取行動 GameLift。Amazon GameLift 呼叫onProcessTerminate()的原因如下：

• 當服務器進程報告健康狀況不佳或沒有響應 Amazon 時 GameLift。

• 在縮小事件期間終止執行個體時。

• 執行個體因為現場執行個體中斷而終止時。

語法

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

通知 Amazon 具 GameLift 有指定玩家工作階段 ID 的玩家已連線到伺服器程序並需要驗證。Amazon 會 GameLift 驗證玩家工作階段 ID 是否有效。玩家會話驗證後，Amazon 將播放器插槽的狀態從保留 GameLift 更改為活動狀態。

語法

GenericOutcome AcceptPlayerSession(String playerSessionId)

參數

playerSessionId

創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例會處理包含驗證和拒絕非有效玩家工作階段 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()

通 GameLift 知 Amazon 播放器已與服務器進程斷開連接。作為回應，Amazon 將播放器插槽 GameLift 更改為可用。

語法

GenericOutcome RemovePlayerSession(String playerSessionId)

參數

playerSessionId

創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

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

DescribePlayerSessions()

檢索播放器會話數據，其中包括設置，會話元數據和播放器數據。使用此方法取得下列項目的相關資訊：

• 單一玩家工作階段

• 遊戲階段中的所有玩家工作階段

• 與單一玩家 ID 關聯的所有玩家工作階段

語法

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

參數

DescribePlayerSessionsRequest

描述要擷取哪些玩家工作階段的DescribePlayerSessionsRequest物件。

傳回值

如果成功，會傳回 DescribePlayerSessionsOutcome 物件，內含一組與請求參數相符的玩家工作階段物件。

範例

此範例要求所有主動連線至指定遊戲工作階段的玩家工作階段。透過省略限制值NextToken並將限制值設定為 10，Amazon 會 GameLift 傳回符合請求的前 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 會使用回調函OnUpdateGameSession()數 GameLift 提供更新的分房系統資料。

一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 StopMatchBackfill() 取消原始請求。

語法

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

參數

StartMatchBackfillRequest

傳達下列資訊的 StartMatchBackfillRequest 物件：

• 指派給回填請求的票證 ID。此信息是可選的; 如果沒有提供 ID，Amazon GameLift 將生成一個。

• 傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值會顯示在遊戲工作階段的分房系統資料中。

• 要回填的遊戲工作階段 ID。

• 遊戲工作階段目前玩家的可用配對資料。

傳回值

傳回具有相符回填工單 ID 的StartMatchBackfillOutcome物件，或失敗並顯示錯誤訊息。

範例

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

參數

StopMatchBackfillRequest

識別要取消配對票證的 StopMatchBackfillRequest 物件：

• 指派給回填請求的工單 ID。

• 回填要求傳送至的分房系統。

• 與回填要求相關聯的遊戲工作階段。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

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

擷取 TLS 憑證的路徑，用於加密 Amazon GameLift Anywhere 運算資源和 Amazon 之間的網路連線 GameLift。將運算裝置註冊到 Amazon GameLift Anywhere 叢集時，可以使用憑證路徑。若要取得更多資訊，請參閱RegisterCompute。

語法

GetComputeCertificateOutcome Server::GetComputeCertificate()

傳回值

傳回 GetComputeCertificateOutcome。

範例

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

GetFleetRoleCredentials()

擷取 IAM 角色登入資料， GameLift 以授權 Amazon 與其他人互動AWS 服務。如需詳細資訊，請參閱 與您車隊的其他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]-[主機 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);

摧毀（）

從記憶體中釋放 Amazon GameLift 遊戲伺服器 SDK。最佳做法是在終止程序之後ProcessEnding()和之前呼叫此方法。如果您使用的是 Anywhere 叢集，且未在每個遊戲工作階段後終止伺服器程序，請先呼叫Destroy()然InitSDK()後重新初始化，再通知 Amazon GameLift 程序已準備好主持遊戲工作階段。ProcessReady()

語法

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