AcceptPlayerSession()ActivateGameSession()DescribePlayerSessions()GetGameSessionId()GetInstanceCertificate()GetSdkVersion()GetTerminationTime()InitSDK()ProcessEnding()ProcessReady()ProcessReadyAsync()RemovePlayerSession()StartMatchBackfill()StopMatchBackfill()TerminateGameSession()UpdatePlayerSessionCreationPolicy()Destroy()

適用於 C++ 的 Amazon GameLift 伺服器 SDK 4.x -- 動作

使用 Amazon GameLift C++ 伺服器 SDK 參考，整合您的多玩家遊戲以與 Amazon GameLift 託管。如需整合程序的相關指引，請參閱將 Amazon GameLift 新增至您的遊戲伺服器。

注意

此參考適用於舊版的 Amazon GameLift 伺服器 SDK。如需最新版本，請參閱適用於 C++ 的 Amazon GameLift 伺服器 SDK 5.x -- 動作。

適用於 C++ 的 Amazon GameLift 伺服器 SDK 4.x -- 資料類型

主題

AcceptPlayerSession()
ActivateGameSession()
DescribePlayerSessions()
GetGameSessionId()
GetInstanceCertificate()
GetSdkVersion()
GetTerminationTime()
InitSDK()
ProcessEnding()
ProcessReady()
ProcessReadyAsync()
RemovePlayerSession()
StartMatchBackfill()
StopMatchBackfill()
TerminateGameSession()
UpdatePlayerSessionCreationPolicy()
Destroy()

AcceptPlayerSession()

通知 Amazon GameLift 服務，具有指定玩家工作階段 ID 的玩家已連線至伺服器程序，且需要驗證。Amazon GameLift 會驗證玩家工作階段 ID 是否有效，也就是玩家 ID 已在遊戲工作階段中預留玩家位置。驗證後，Amazon GameLift 會將玩家位置的狀態從 RESERVED 變更為 ACTIVE。

語法


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

參數

playerSessionId

Amazon GameLift 服務為回應呼叫 AWS SDK Amazon GameLift API 動作 CreatePlayerSession 而發出的唯一 ID。遊戲用戶端會在連線至伺服器程序時參考此 ID。

類型：std：：string

必要：是

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例展示了用來處理連線請求的函數，其處理過程包括驗證和拒絕無效的玩家工作階段 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);

參數

describePlayerSessionsRequest

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

必要：是

傳回值

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

範例

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

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 憑證的檔案位置。當您建立憑證組態設為 GENERATED 的新機群時， AWS Certificate Manager 會產生此憑證。使用此憑證可與遊戲用戶端建立安全連線，以及加密用戶端/伺服器通訊。

語法


GetInstanceCertificateOutcome GetInstanceCertificate();

參數

此動作沒有參數。

傳回值

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

如需憑證和憑證鏈資料的詳細資訊，請參閱 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-09-13 12：26：40 -000Z 等於 637355968000000000 個刻度。如果沒有可用的終止時間，會傳回錯誤訊息。

範例


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

InitSDK()

初始化 Amazon GameLift SDK。在任何其他 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);

參數

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

RemovePlayerSession()

通知 Amazon GameLift 服務，具有指定玩家工作階段 ID 的玩家已中斷與伺服器程序的連線。為了回應，Amazon GameLift 將玩家插槽變更為可用，以便將其指派給新的玩家。

語法


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

參數

playerSessionId

Amazon GameLift 服務發出的唯一 ID，以回應對 AWS SDK Amazon GameLift API 動作 CreatePlayerSession 的呼叫。遊戲用戶端會在連線至伺服器程序時參考此 ID。

類型：std：：string

必要：是

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例


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

參數

StartMatchBackfillRequest

StartMatchBackfillRequest 物件會傳達以下資訊：

指派給回填請求的票證 ID。此資訊是選用的；如果未提供 ID，Amazon GameLift 會自動產生。
傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值可從遊戲工作階段的配對建構器資料中取得。
經回填之遊戲工作階段的 ID。
遊戲工作階段目前玩家可用的配對資料。

必要：是

傳回值

傳回 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);

參數

StopMatchBackfillRequest

識別配對票證的 StopMatchBackfillRequest 物件，用以取消：

已取消指派給此回填請求的票證 ID
回填請求的傳送目標配對建構器
與回填請求相關的遊戲工作階段

必要：是

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例


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

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

語法


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

參數

newPlayerSessionPolicy

字串值代表遊戲工作階段是否可接受新玩家。

類型： Aws::GameLift::Model::PlayerSessionCreationPolicy 列舉。有效值包含：

ACCEPT_ALL – 接受所有新玩家工作階段。
DENY_ALL – 拒絕所有新玩家工作階段。

必要：是

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

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


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

Destroy()

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

語法


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

參數

沒有參數。

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例會在遊戲伺服器程序結束後清除由 initSDK 配置的記憶體。


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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

伺服器 SDK 4 和更早版本

資料類型