本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 Amazon GameLift Servers 4.x 的 C\$1\$1 伺服器 SDK -- 動作使用伺服器 SDK 參考來整合多玩家遊戲，以便與進行託管Amazon GameLift Servers。如需整合程序的指引，請參閱 [使用伺服器 SDK 將 Amazon GameLift Servers新增至您的遊戲伺服器](gamelift-sdk-server-api.md)。 **注意** 此參考適用於的舊版伺服器 SDKAmazon GameLift Servers。如需最新版本，請參閱[適用於 -- 動作的 C\$1\$1 伺服器 SDK Amazon GameLift Servers 5.x](integration-server-sdk5-cpp-actions.md)。 # 適用於 Amazon GameLift Servers 4.x 的 C\$1\$1 伺服器 SDK -- 資料類型使用伺服器 SDK 參考來整合多玩家遊戲，以便與進行託管Amazon GameLift Servers。如需整合程序的指引，請參閱 [使用伺服器 SDK 將 Amazon GameLift Servers新增至您的遊戲伺服器](gamelift-sdk-server-api.md)。 **注意** 此參考適用於的舊版伺服器 SDKAmazon GameLift Servers。如需最新版本，請參閱[適用於 -- 資料類型的 C\$1\$1 伺服器 SDK Amazon GameLift Servers 5.x](integration-server-sdk5-cpp-datatypes.md)。此 API 定義於 `GameLiftServerAPI.h`、`LogParameters.h`、`ProcessParameters.h`。 [適用於 Amazon GameLift Servers 4.x 的 C\$1\$1 伺服器 SDK -- 動作](integration-server-sdk-cpp-ref-actions.md) ## DescribePlayerSessionsRequest 此資料類型用於指定要擷取的玩家工作階段，您可利用下列方式使用： + 提供 PlayerSessionId 以要求特定玩家工作階段。 + 提供 GameSessionId 以要求特定遊戲工作階段之中的所有玩家工作階段。 + 提供 PlayerId 以要求特定玩家的所有玩家工作階段。對於大量的玩家工作階段，可使用分頁參數於循序區塊擷取結果。 ### 目錄 **GameSessionId** 獨一無二的遊戲工作階段識別項。請使用此參數要求特定遊戲工作階段的所有玩家工作階段。遊戲工作階段 ID 格式如下：`arn:aws:gamelift:::gamesession/fleet-/`。的值可能是自訂 ID 字串 (若在建立遊戲工作階段時有指定 ID)，或是產生的字串。類型：字串必要：否 **限制** 回傳結果的數量上限。使用此參數搭配 *NextToken* 取得結果做為一組循序頁面。若指定玩家工作階段 ID，此參數將遭到忽略。類型：整數必要：否 **NextToken** 字符顯示下一個結果循序頁面的開始處。使用前一個呼叫此動作傳回的字符。指定結果集的開始處時，請勿指定值。若指定玩家工作階段 ID，此參數將遭到忽略。類型：字串必要：否 **PlayerId** 玩家的唯一識別項。玩家 ID 是由開發人員定義。請參閱 [產生玩家 IDs](player-sessions-player-identifiers.md)。類型：字串必要：否 **PlayerSessionId** 玩家工作階段的唯一識別項。類型：字串必要：否 **PlayerSessionStatusFilter** 用於篩選結果的玩家工作階段狀態。可能的玩家工作階段狀態包括下列項目： + RESERVED – 玩家工作階段要求已收到，但玩家尚未連線至伺服器程序及/或通過驗證。 + ACTIVE – 玩家已由伺服器程序驗證，目前已連線。 + COMPLETED – 玩家連線已中斷。 + TIMEDOUT – 玩家工作階段要求已收到，但玩家並未在逾時限制 (60 秒) 內連線及/或通過驗證。類型：字串必要：否 ## LogParameters 此資料類型用於識別遊戲工作階段期間產生的哪些檔案要由 Amazon GameLift Servers 上傳，並在遊戲工作階段結束時存放。系統會在進行 [ProcessReady()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-processready) 呼叫時，將此資訊傳送至 Amazon GameLift Servers 服務。 ### 目錄 **logPaths** 您要 Amazon GameLift Servers 存放遊戲伺服器日誌檔案的目錄路徑，以供日後存取使用。這些檔案是在每個遊戲工作階段期間產生。檔案路徑及名稱於您的遊戲伺服器定義，並儲存於遊戲組建根目錄。日誌路徑必須是絕對的。例如若您的遊戲建構將遊戲工作階段記錄儲存於 `MyGame\sessionlogs\` 這樣的目錄，則記錄路徑就可能是 `c:\game\MyGame\sessionLogs` (在 Windows 執行個體) 或 `/local/game/MyGame/sessionLogs` (在 Linux 執行個體)。類型：std:vector 必要：否 ## ProcessParameters 此資料類型包含一組參數，系統會在進行 [ProcessReady()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-processready) 呼叫時將該組參數傳送至 Amazon GameLift Servers 服務。 ### 目錄 **port** 伺服器程序接聽新玩家連線所在的連接埠編號。值必須屬於為部署此遊戲伺服器組建之機群所設定的連接埠範圍。此連接埠號碼包含在遊戲工作階段和遊戲工作階段物件中，遊戲工作階段會使用該物件來連接到伺服器程序。類型：整數必要：是 **logParameters** 含對遊戲工作階段日誌檔之目錄路徑清單的物件。類型：Aws::GameLift::Server::[LogParameters](#integration-server-sdk-cpp-ref-dataypes-log) 必要：否 **onStartGameSession** Amazon GameLift Servers 服務叫用以啟用新遊戲工作階段的回呼函數名稱。會Amazon GameLift Servers呼叫此函數以回應用戶端請求 [CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)。該回呼函數會傳遞 [GameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_GameSession.html) 物件 (即 *Amazon GameLift Servers 服務 API 參考*中所定義的物件)。類型：`const std::function onStartGameSession` 必要：是 **onProcessTerminate** Amazon GameLift Servers 服務叫用以強制伺服器程序關閉的回呼函數名稱。呼叫此函數後，Amazon GameLift Servers 會等待五分鐘讓系統關閉伺服器程序，然後透過 [ProcessEnding()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-processending) 呼叫進行回應。如果沒有收到回應，就會關閉伺服器程序。類型：`std::function onProcessTerminate` 必要：否 **onHealthCheck** Amazon GameLift Servers 服務叫用以從伺服器程序請求運作狀態報告的回呼函數名稱。每 60 秒Amazon GameLift Servers呼叫此函數。呼叫此函數後，Amazon GameLift Servers 會等待 60 秒確認是否有回應，若未收到任何回應，系統即會將該伺服器程序記錄為運作狀態不佳。類型：`std::function onHealthCheck` 必要：否 **onUpdateGameSession** Amazon GameLift Servers 服務叫用以將更新的遊戲工作階段物件傳遞至伺服器程序的回呼函數名稱。會在處理[相符回填](https://docs.aws.amazon.com/gamelift/latest/flexmatchguide/match-backfill.html)請求時Amazon GameLift Servers呼叫此函數，以提供更新的配對建構器資料。然後傳送 [GameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_GameSession.html) 物件、狀態更新 (`updateReason`) 及配對回填票證 ID。類型：`std::function onUpdateGameSession` 必要：否 ## StartMatchBackfillRequest 此項資料類型用於傳送配對回填要求。系統會在進行 [StartMatchBackfill()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-startmatchbackfill) 呼叫時，將此資訊傳送至 Amazon GameLift Servers 服務。 ### 目錄 **GameSessionArn** 獨一無二的遊戲工作階段識別項。API 動作 [GetGameSessionId()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-getgamesessionid) 以 ARN 格式傳回識別項。類型：字串必要：是 **MatchmakingConfigurationArn** 以 ARN 為格式的唯一識別項，讓配對建構器使用此項要求。尋找用於建立原始遊戲工作階段的配對建構器時，請查看配對建構器資料屬性之中的遊戲工作階段物件。進一步了解 [Word 中的配對建構器資料與配對建構器資料](https://docs.aws.amazon.com/gamelift/latest/flexmatchguide/match-server.html#match-server-data)。類型：字串必要：是 **Players** 表示目前遊戲工作階段之中所有玩家的一組資料。配對建構器使用此項資訊搜尋適合配對現有玩家的新玩家。如需播放器物件格式的說明，請參閱 *Amazon GameLift Servers API 參考指南*。尋找玩家屬性、ID 及團隊指派時，請查看配對建構器資料屬性之中的遊戲工作階段物件。若配對建構器使用延遲，您可收集現有區域更新後的延遲，並將其納入各個玩家資料之中。類型：std：vector[](https://docs.aws.amazon.com/gamelift/latest/apireference/API_Player.html) 必要：是 **TicketId** 配對或配對回填要求票證的唯一識別項。如果此處未提供任何值， Amazon GameLift Servers會以 UUID 的形式產生一個值。您可使用此識別項依據需求追蹤配對回填票證狀態或取消要求。類型：字串必要：否 ## StopMatchBackfillRequest 此項資料類型用於取消配對回填要求。系統會在進行 [StopMatchBackfill()](integration-server-sdk-cpp-ref-actions.md#integration-server-sdk-cpp-ref-stopmatchbackfill) 呼叫時，將此資訊傳送至 Amazon GameLift Servers 服務。 ### 目錄 **GameSessionArn** 與遭取消要求有關的唯一遊戲工作階段識別碼。類型：字串必要：是 **MatchmakingConfigurationArn** 做為此要求傳送目標的配對建構器唯一識別項。類型：字串必要：是 **TicketId** 遭取消回填要求票證的唯一識別碼。類型：字串必要：是 [適用於 Amazon GameLift Servers 4.x 的 C\$1\$1 伺服器 SDK -- 資料類型](integration-server-sdk-cpp-ref-datatypes.md) **Topics** + [適用於 Amazon GameLift Servers 4.x 的 C\$1\$1 伺服器 SDK -- 資料類型](integration-server-sdk-cpp-ref-datatypes.md) + [AcceptPlayerSession()](#integration-server-sdk-cpp-ref-acceptplayersession) + [ActivateGameSession()](#integration-server-sdk-cpp-ref-activategamesession) + [DescribePlayerSessions()](#integration-server-sdk-cpp-ref-describeplayersessions) + [GetGameSessionId()](#integration-server-sdk-cpp-ref-getgamesessionid) + [GetInstanceCertificate()](#integration-server-sdk-cpp-ref-getinstancecertificate) + [GetSdkVersion()](#integration-server-sdk-cpp-ref-getsdk) + [GetTerminationTime()](#integration-server-sdk-cpp-ref-getterm) + [InitSDK()](#integration-server-sdk-cpp-ref-initsdk) + [ProcessEnding()](#integration-server-sdk-cpp-ref-processending) + [ProcessReady()](#integration-server-sdk-cpp-ref-processready) + [ProcessReadyAsync()](#integration-server-sdk-cpp-ref-processreadyasync) + [RemovePlayerSession()](#integration-server-sdk-cpp-ref-removeplayersession) + [StartMatchBackfill()](#integration-server-sdk-cpp-ref-startmatchbackfill) + [StopMatchBackfill()](#integration-server-sdk-cpp-ref-stopmatchbackfill) + [TerminateGameSession()](#integration-server-sdk-cpp-ref-terminategamesession) + [UpdatePlayerSessionCreationPolicy()](#integration-server-sdk-cpp-ref-updateplayersessioncreationpolicy) + [Destroy()](#integration-server-sdk-cpp-ref-destroy) ## AcceptPlayerSession() 通知Amazon GameLift Servers服務，具有指定玩家工作階段 ID 的玩家已連線到伺服器程序，且需要驗證。 Amazon GameLift Servers 會驗證玩家工作階段 ID 是否有效，也就是玩家 ID 在遊戲工作階段中已預留玩家位置。經過驗證後，Amazon GameLift Servers 會將玩家位置的狀態從 RESERVED (已預留) 變更為 ACTIVE (使用中)。 ### 語法 ``` GenericOutcome AcceptPlayerSession(const std::string& playerSessionId); ``` ### Parameters **playerSessionId** 由 Amazon GameLift Servers服務發出的唯一 ID，以回應對 AWS SDK Amazon GameLift Servers API 動作 [CreatePlayerSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreatePlayerSession.html) 的呼叫。遊戲用戶端在連線至伺服器程序時參考此 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 Servers 服務。此動作應當做 `onStartGameSession()` 回呼函數的一部分，在所有遊戲工作階段初始化完成後進行。 ### 語法 ``` GenericOutcome ActivateGameSession(); ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例顯示的是做為 `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); ``` ### Parameters **describePlayerSessionsRequest** [DescribePlayerSessionsRequest](integration-server-sdk-cpp-ref-datatypes.md#integration-server-sdk-cpp-ref-dataypes-playersessions) 物件描述的是要擷取哪個玩家工作階段。必要：是 ### 傳回值如果成功，會傳回 `DescribePlayerSessionsOutcome` 物件，內含一組與請求參數相符的玩家工作階段物件。玩家工作階段物件的結構與 AWS SDK Amazon GameLift Servers API [PlayerSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_PlayerSession.html) 資料類型相同。 ### 範例此範例展示了讓所有玩家工作階段均主動連線至指定之遊戲工作階段的請求。透過省略 `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); ``` ## GetGameSessionId() 若伺服器流程正在運作，擷取目前正在由伺服器程序託管的遊戲工作階段專屬識別符。此識別符會以 ARN 格式傳回：`arn:aws:gamelift:::gamesession/fleet-/`。對於尚未透過遊戲工作階段啟用的閒置程序，呼叫會傳回 `Success`= `True`和 `GameSessionId`=`""` （空字串）。 ### 語法 ``` AwsStringOutcome GetGameSessionId(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，則會把遊戲工作階段 ID 當成 `AwsStringOutcome` 物件傳回。如果不成功，則會傳回錯誤訊息。 ### 範例 ``` Aws::GameLift::AwsStringOutcome sessionIdOutcome = Aws::GameLift::Server::GetGameSessionId(); ``` ## GetInstanceCertificate() 擷取與機群及其執行個體相關聯的 pem 編碼 TLS 憑證的檔案位置。當您建立憑證組態設為 GENERATED 的新機群時， AWS Certificate Manager 會產生此憑證。使用此憑證可與遊戲用戶端建立安全連線，以及加密用戶端/伺服器通訊。 ### 語法 ``` GetInstanceCertificateOutcome GetInstanceCertificate(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會傳回`GetInstanceCertificateOutcome`物件，其中包含存放在執行個體上的機群 TLS 憑證檔案和憑證鏈的位置。從憑證鏈擷取的根憑證檔案也會存放在執行個體上。如果不成功，則會傳回錯誤訊息。如需憑證和憑證鏈資料的詳細資訊，請參閱 AWS Certificate Manager API 參考中的 [GetCertificate 回應元素](https://docs.aws.amazon.com/acm/latest/APIReference/API_GetCertificate.html#API_GetCertificate_ResponseElements)。 ### 範例 ``` Aws::GameLift::GetInstanceCertificateOutcome certificateOutcome = Aws::GameLift::Server::GetInstanceCertificate(); ``` ## GetSdkVersion() 傳回所用的 SDK 目前的版本編號。 ### 語法 ``` AwsStringOutcome GetSdkVersion(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，將目前開發套件版本以 `AwsStringOutcome` 物件傳回。傳回的字串僅包含版本編號（例如 "3.1.5")。如果不成功，則會傳回錯誤訊息。 ### 範例 ``` Aws::GameLift::AwsStringOutcome SdkVersionOutcome = Aws::GameLift::Server::GetSdkVersion(); ``` ## GetTerminationTime() 若設有終止時間，即傳回伺服器程序排定關閉的時間。伺服器程序在收到 Amazon GameLift Servers服務的回`onProcessTerminate()`呼後會採取此動作。 Amazon GameLift Servers可能會`onProcessTerminate()`呼叫，原因如下：(1) 伺服器程序回報運作狀態不佳或未回應 Amazon GameLift Servers、(2) 在縮減事件期間終止執行個體時，或 (3) 執行個體因 [Spot 中斷](spot-tasks.md)而終止時。如果程序已收到回`onProcessTerminate()`呼，則傳回的值為預估的終止時間。如果程序尚未收到回`onProcessTerminate()`呼，則會傳回錯誤訊息。進一步了解[關閉伺服器處理程序](gamelift-sdk-server-api.md#gamelift-sdk-server-terminate)的相關資訊。 ### 語法 ``` AwsLongOutcome GetTerminationTime(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會將終止時間傳回為 `AwsLongOutcome` 物件。該值是終止時間，以自 0001 00：00：00 起已經過的刻度表示。例如，日期時間值 2020-09-13 12：26：40 -000Z 等於 637355968000000000 個刻度。如果沒有可用的終止時間，會傳回錯誤訊息。 ### 範例 ``` Aws::GameLift::AwsLongOutcome TermTimeOutcome = Aws::GameLift::Server::GetTerminationTime(); ``` ## InitSDK() 初始化 Amazon GameLift Servers 開發套件。您應在啟動時隨即呼叫此方法，以避免系統先進行任何其他與 Amazon GameLift Servers 相關的初始化程序。 ### 語法 ``` InitSDKOutcome InitSDK(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會傳回 InitSdkOutcome 物件，代表伺服器程序已準備好呼叫 [ProcessReady()](#integration-server-sdk-cpp-ref-processready)。 ### 範例 ``` Aws::GameLift::Server::InitSDKOutcome initOutcome = Aws::GameLift::Server::InitSDK(); ``` ## ProcessEnding() 若伺服器程序正在關閉中，則此動作會通知 Amazon GameLift Servers 服務。此方法應於所有其他清除作業 (包括關閉所有作用中遊戲工作階段) 之後呼叫。此方法應以結束代碼 0 結束，非零的結束代碼會導致該程序未徹底結束的事件訊息出現。一旦方法以代碼 0 結束，您就可以以成功的結束代碼終止程序。您也可以使用錯誤碼結束程序。如果您使用錯誤代碼結束，機群事件將指出程序異常終止 (`SERVER_PROCESS_TERMINATED_UNHEALTHY`)。 ### 語法 ``` GenericOutcome ProcessEnding(); ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` 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 Servers 服務。在成功叫用[InitSDK()](#integration-server-sdk-cpp-ref-initsdk)並完成伺服器程序可託管遊戲工作階段之前所需的設定任務之後，呼叫此方法。每個程序只能呼叫此方法一次。此為同步呼叫。若要進行非同步呼叫，請使用 [ProcessReadyAsync()](#integration-server-sdk-cpp-ref-processreadyasync)。如需詳細資訊，請參閱[初始化伺服器程序](gamelift-sdk-server-api.md#gamelift-sdk-server-initialize)。 ### 語法 ``` GenericOutcome ProcessReady( const Aws::GameLift::Server::ProcessParameters &processParameters); ``` ### Parameters **processParameters** [ProcessParameters](integration-server-sdk-cpp-ref-datatypes.md#integration-server-sdk-cpp-ref-dataypes-process) 物件會傳達以下有關伺服器程序的資訊： + 在遊戲伺服器程式碼中實作的回呼方法名稱，可供 Amazon GameLift Servers 服務呼叫以與伺服器程序通訊。 + 伺服器程序正在接聽的埠號。 + 任何要 Amazon GameLift Servers 擷取並存放的遊戲工作階段特定檔案路徑。必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例會說明 [ProcessReady()](#integration-server-sdk-cpp-ref-processready) 呼叫和回呼函數的實作。 ``` // Set parameters and call ProcessReady std::string serverLog("serverOut.log"); // Example of a log file written by the game server std::vector 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()](#integration-server-sdk-cpp-ref-processready)。如需詳細資訊，請參閱[初始化伺服器程序](gamelift-sdk-server-api.md#gamelift-sdk-server-initialize)。 ### 語法 ``` GenericOutcomeCallable ProcessReadyAsync( const Aws::GameLift::Server::ProcessParameters &processParameters); ``` ### Parameters **processParameters** [ProcessParameters](integration-server-sdk-cpp-ref-datatypes.md#integration-server-sdk-cpp-ref-dataypes-process) 物件會傳達以下有關伺服器程序的資訊： + 在遊戲伺服器程式碼中實作的回呼方法名稱，可供 Amazon GameLift Servers 服務呼叫以與伺服器程序通訊。 + 伺服器程序正在接聽的埠號。 + 任何要 Amazon GameLift Servers 擷取並存放的遊戲工作階段特定檔案路徑。必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` // 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 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() 若具有指定玩家工作階段 ID 的玩家已與伺服器程序中斷連線，則此動作會通知 Amazon GameLift Servers 服務。Amazon GameLift Servers 會對此做出回應，將玩家位置變更為可用，使該位置可指派給新玩家。 ### 語法 ``` GenericOutcome RemovePlayerSession( const std::string& playerSessionId); ``` ### Parameters **playerSessionId** 由 Amazon GameLift Servers服務發出的唯一 ID，以回應對 AWS SDK Amazon GameLift Servers API 動作 [CreatePlayerSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreatePlayerSession.html) 的呼叫。遊戲用戶端在連線至伺服器程序時參考此 ID。類型：std：：string 必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` Aws::GameLift::GenericOutcome disconnectOutcome = Aws::GameLift::Server::RemovePlayerSession(playerSessionId); ``` ## StartMatchBackfill() 此動作會傳送請求，以便替 FlexMatch 所建立的遊戲工作階段開放空位找到新玩家。另請參閱 AWS SDK 動作 [StartMatchBackfill()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartMatchBackfill.html)。使用此動作，目前代管遊戲工作階段的遊戲伺服器程序即可初始化配對回填請求。進一步了解[FlexMatch回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。此為非同步動作。如果新玩家成功配對，Amazon GameLift Servers此服務會透過叫用回呼函數來提供更新的配對建構器資料`OnUpdateGameSession()`。一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 [StopMatchBackfill()](#integration-server-sdk-cpp-ref-stopmatchbackfill) 取消原始請求。 ### 語法 ``` StartMatchBackfillOutcome StartMatchBackfill ( const Aws::GameLift::Server::Model::StartMatchBackfillRequest &startBackfillRequest); ``` ### Parameters **StartMatchBackfillRequest** [StartMatchBackfillRequest](integration-server-sdk-cpp-ref-datatypes.md#integration-server-sdk-cpp-ref-dataypes-startmatchbackfillrequest) 物件會傳達以下資訊： + 指派給回填請求的票證 ID。此為選填的資訊，若未提供任何 ID，則 Amazon GameLift Servers 會自動產生一個。 + 傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值可從遊戲工作階段的配對建構器資料中取得。 + 經回填之遊戲工作階段的 ID。 + 遊戲工作階段目前玩家可用的配對資料。必要：是 ### 傳回值傳回 StartMatchBackfillOutcome 物件，附帶配對回填票證或含有錯誤訊息的故障狀況。您可以使用 AWS SDK 動作 [DescribeMatchmaking()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html) 追蹤票證狀態。 ### 範例 ``` // Build a backfill request std::vector 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()](#integration-server-sdk-cpp-ref-startmatchbackfill) 建立的使用中配對回填請求。另請參閱 AWS SDK 動作 [StopMatchmaking()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StopMatchmaking.html)。進一步了解[FlexMatch回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。 ### 語法 ``` GenericOutcome StopMatchBackfill ( const Aws::GameLift::Server::Model::StopMatchBackfillRequest &stopBackfillRequest); ``` ### Parameters **StopMatchBackfillRequest** 識別配對票證的 [StopMatchBackfillRequest](integration-server-sdk-cpp-ref-datatypes.md#integration-server-sdk-cpp-ref-dataypes-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()](#integration-server-sdk-cpp-ref-processending)在遊戲工作階段結束後呼叫。** 通知Amazon GameLift Servers服務伺服器程序已結束目前的遊戲工作階段。當伺服器程序保持作用中狀態並準備好託管新的遊戲工作階段時，就會呼叫此動作。只有在遊戲工作階段終止程序完成後，才應該呼叫它，因為它會向發出訊號Amazon GameLift Servers，表示伺服器程序可立即用於託管新的遊戲工作階段。如果伺服器程序會在遊戲工作階段停止後關閉，則不會呼叫此動作。反之，呼叫 [ProcessEnding()](#integration-server-sdk-cpp-ref-processending)以發出遊戲工作階段和伺服器程序都即將結束的訊號。 ### 語法 ``` GenericOutcome TerminateGameSession(); ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ## UpdatePlayerSessionCreationPolicy() 更新目前遊戲工作階段的能力，以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。另請參閱 SDK AWS 動作 [UpdateGameSession()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_UpdateGameSession.html)。 ### 語法 ``` GenericOutcome UpdatePlayerSessionCreationPolicy( Aws::GameLift::Model::PlayerSessionCreationPolicy newPlayerSessionPolicy); ``` ### Parameters **newPlayerSessionPolicy** 字串值代表遊戲工作階段是否可接受新玩家。類型： Aws::GameLift::Model::PlayerSessionCreationPolicy 列舉。有效值包含： + **ACCEPT\$1ALL** – 接受所有新玩家工作階段。 + **DENY\$1ALL** – 拒絕所有新玩家工作階段。必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。 ``` Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::PlayerSessionCreationPolicy::ACCEPT_ALL); ``` ## Destroy() 清除遊戲伺服器初始化期間 initSDK() 配置的記憶體。在您結束遊戲伺服器程序後使用此方法，以避免浪費伺服器記憶體。 ### 語法 ``` GenericOutcome Aws::GameLift::Server::Destroy(); ``` ### Parameters 沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例會在遊戲伺服器程序結束後清除 initSDK 配置的記憶體。 ``` if (Aws::GameLift::Server::ProcessEnding().IsSuccess()) { Aws::GameLift::Server::Destroy(); exit(0); } ```