本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

亞馬遜GameLift服務器 SDK（C ++）參考：操作

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

AcceptPlayerSession()

通知 Amazon GameLift 服務具有指定玩家工作階段 ID 的玩家已連線到伺服器程序並需要驗證。Amazon 會GameLift驗證玩家工作階段 ID 是否有效 — 也就是說，玩家 ID 已在遊戲工作階段中保留一個玩家位置。一旦驗證，亞馬遜GameLift將播放器插槽的狀態從保留更改為活動狀態。

語法

GenericOutcome AcceptPlayerSession(const std::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();
    }       
}

ActivateGameSession()

通知 Amazon GameLift 服務伺服器處理序已啟動遊戲工作階段，現在已準備好接收玩家連線。此動作應當做 onStartGameSession() 回呼函數的一部分，在所有遊戲工作階段初始化完成後進行。

語法

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

DescribePlayerSessions()

擷取玩家工作階段資料，包括設定、工作階段中繼資料和玩家資料。使用此動作可取得單一玩家工作階段資訊、一個遊戲工作階段中所有玩家工作階段的資訊，或是與單一玩家 ID 關聯的所有玩家工作階段資訊。

語法

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

參數

傳回值

如果成功，會傳回 DescribePlayerSessionsOutcome 物件，內含一組與請求參數相符的玩家工作階段物件。播放器工作階段物件的結構與 AWS SDK Amazon GameLift API PlayerSession資料類型相同。

範例

此範例展示了讓所有玩家工作階段均主動連線至指定之遊戲工作階段的請求。藉由省略NextToken並將Limit值設定為 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);

GetGameSessionId()

若伺服器流程正在運作，擷取目前正在由伺服器程序託管的遊戲工作階段專屬識別符。此識別符會以 ARN 格式傳回：arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>。

對於尚未通過遊戲會話激活的空閒進程，調用返回 Success = True 和 GameSessionId =""（空字符串）。

語法

AwsStringOutcome GetGameSessionId();

參數

此動作沒有參數。

傳回值

如果成功，則會把遊戲工作階段 ID 當成 AwsStringOutcome 物件傳回。如果不成功，則會傳回錯誤訊息。

範例

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

GetInstanceCertificate()

擷取與叢集及其執行個體相關聯的 PEM 編碼 TLS 憑證的檔案位置。 AWS Certificate Manager當您建立新的叢集並將憑證組態設定為「已產生」時，會產生此憑證。使用此憑證可與遊戲用戶端建立安全連線，以及加密用戶端/伺服器通訊。

語法

GetInstanceCertificateOutcome GetInstanceCertificate();

參數

此動作沒有參數。

傳回值

如果成功，會傳回包含叢集 TLS 憑證檔案和憑證鏈結位置的GetInstanceCertificateOutcome物件，這些檔案儲存在執行個體上。從憑證鏈結擷取的根憑證檔案也會儲存在執行個體上。如果不成功，則會傳回錯誤訊息。

如需有關憑證和憑證鏈結資料的詳細資訊，請參閱 AWS Certificate Manager API 參考中的GetCertificate回應元素。

範例

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

GetSdkVersion()

傳回所用的 SDK 目前的版本編號。

語法

AwsStringOutcome GetSdkVersion();

參數

此動作沒有參數。

傳回值

如果成功，將目前開發套件版本以 AwsStringOutcome 物件傳回。返回的字符串僅包含版本號（例如「3.1.5」）。如果不成功，則會傳回錯誤訊息。

範例

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

GetTerminationTime()

若設有終止時間，即傳回伺服器程序排定關閉的時間。伺服器處理序會在收到來自 Amazon GameLift 服務的onProcessTerminate()回呼後採取此動作。Amazon GameLift 可能會因onProcessTerminate()為下列原因而致電：(1) 伺服器處理序報告運作狀態不佳或未回應 Amazon 時GameLift、(2) 在縮減事件期間終止執行個體時，或 (3) 執行個體因 Spot 中斷而終止時。

如果進程已收到onProcessTerminate()回調，則返回的值是估計的終止時間。如果處理序未收到onProcessTerminate()回呼，則會傳回錯誤訊息。進一步了解關閉伺服器處理程序的相關資訊。

語法

AwsLongOutcome GetTerminationTime();

參數

此動作沒有參數。

傳回值

如果成功，則返回終止時間作為AwsLongOutcome對象。該值是終止時間，以自 0001 00:00:00 以來經過的刻度表示。例如，日期時間值 2020-9 月 13 日 12:26：40 -000Z 等於刻度。如果沒有可用的終止時間，則返回錯誤消息。

範例

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

InitSDK()

初始化亞馬遜開GameLift發套件。在發生任何其他 Amazon GameLift 相關初始化之前，應在啟動時呼叫此方法。

語法

InitSDKOutcome InitSDK();

參數

此動作沒有參數。

傳回值

如果成功，則返回一個InitSdkOutcome對象，指示服務器進程已準備好調用ProcessReady()。

範例

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

ProcessEnding()

通知 Amazon GameLift 服務伺服器處理序正在關閉。此方法應於所有其他清除作業 (包括關閉所有作用中遊戲工作階段) 之後呼叫。此方法應以結束代碼 0 結束，非零的結束代碼會導致該程序未徹底結束的事件訊息出現。

一旦該方法退出代碼為 0，您可以使用成功的退出代碼終止該進程。您也可以使用錯誤碼結束程序。如果您以錯誤碼結束，叢集事件將指示處理序異常終止 (SERVER_PROCESS_TERMINATED_UNHEALTHY)。

語法

GenericOutcome ProcessEnding();

參數

此動作沒有參數。

傳回值

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

範例

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

ProcessReady()

通知 Amazon GameLift 服務伺服器處理序已準備好主持遊戲工作階段。在成功叫用InitSDK()並完成伺服器處理序主控遊戲工作階段之前所需的設定工作之後，呼叫此方法。每個進程應該只調用一次此方法。

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

語法

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 服務伺服器處理序已準備好主持遊戲工作階段。一旦伺服器程序準備好代管遊戲工作階段時，即應呼叫此方法。這些參數指定亞馬遜GameLift在某些情況下調用的回調函數的名稱。遊戲伺服器代碼必須實作上述函數。

此為非同步呼叫。若要進行同步呼叫，請使用 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;
}        

RemovePlayerSession()

通知 Amazon GameLift 服務具有指定玩家工作階段 ID 的玩家已中斷與伺服器處理序的連線。作為回應，亞馬遜將播放器插槽GameLift更改為可用，這允許將其分配給新玩家。

語法

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

參數

傳回值

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

範例

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

StartMatchBackfill()

此動作會傳送請求，以便替 FlexMatch 所建立的遊戲工作階段​開放空位找到新玩家。另請參閱 AWS SDK 動作 StartMatchBackfill()。使用此動作，目前代管遊戲工作階段的遊戲伺服器程序即可初始化配對回填請求。進一步瞭解FlexMatch回填功能。

此為非同步動作。如果成功配對新玩家，Amazon GameLift 服務會透過叫用回呼函數來提供更新的分房系統資料。OnUpdateGameSession()

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

語法

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

參數

傳回值

返回匹配回填票證或失敗的StartMatchBackfillOutcome對象，並顯示錯誤消息。您可以使用 AWS SDK 動作 DescribeMatchmaking() 來追蹤工單狀態。

範例

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

取消以 StartMatchBackfill() 建立的使用中配對回填請求。另請參閱 AWS SDK 動作 StopMatchmaking()。進一步瞭解FlexMatch回填功能。

語法

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

參數

傳回值

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

範例

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

此方法已被版本 4.0.1 棄用。相反，在遊戲會話結束ProcessEnding()後，服務器進程應該調用。

通知 Amazon GameLift 服務伺服器處理序已結束目前的遊戲工作階段。當伺服器處理程序保持作用中並準備好主持新遊戲工作階段時，就會呼叫此動作。只有在遊戲工作階段終止程序完成後，才應該呼叫它，因為它會向 Amazon 發出訊號GameLift，伺服器程序可立即用於託管新的遊戲工作階段。

如果在遊戲工作階段停止後關閉伺服器程序，則不會呼叫此動作。相反，調用ProcessEnding()以表示遊戲會話和服務器進程都結束。

語法

GenericOutcome TerminateGameSession();

參數

此動作沒有參數。

傳回值

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

UpdatePlayerSessionCreationPolicy()

更新目前遊戲工作階段的能力，以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。另請參閱 AWS SDK 動作 UpdateGameSession()。

語法

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

參數

傳回值

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

範例

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

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

摧毀（）

在遊戲伺服器初始化期間清除 InitSDK () 配置的記憶體。結束遊戲伺服器程序後，請使用此方法，以避免浪費伺服器記憶體。

語法

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

參數

沒有參數。

傳回值

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

範例

此範例會在遊戲伺服器處理序結束後清除 InitSDK 配置的記憶體。

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