本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
Amazon GameLift 服務器 SDK(虛幻)5.x 參考:操作
您可以使用這個 Amazon GameLift 虛幻伺服器開發套件參考來協助您準備好與 Amazon GameLift 搭配使用的多人遊戲。如需有關整合程序的詳細資訊,請參閱添加 Amazon GameLift 到您的遊戲服務器和如需使用 Unreal SDK 伺服器外掛程式的資訊,請參閱 GameLift 將 Amazon 集成到虛幻引擎項目中。
動作
- GetSdkVersion()
- InitSDK()
- InitSDK()
- ProcessReady()
- ProcessEnding()
- ActivateGameSession()
- UpdatePlayerSessionCreationPolicy()
- GetGameSessionId()
- GetTerminationTime()
- AcceptPlayerSession()
- RemovePlayerSession()
- DescribePlayerSessions()
- StartMatchBackfill()
- StopMatchBackfill()
- GetComputeCertificate()
- GetFleetRoleCredentials()
注意
本主題說明您在為虛幻引擎建置時可以使用的 Amazon GameLift C++ API。具體而言,本文件適用於您使用-DBUILD_FOR_UNREAL=1
選項編譯的程式碼。
GetSdkVersion()
傳回內建至伺服器程序的目前開發套件版本編號。
語法
FGameLiftStringOutcome GetSdkVersion();
傳回值
如果成功,將目前開發套件版本以 FGameLiftStringOutcome 物件傳回。傳回的物件包含版本號碼 (範例5.0.0
)。如果不成功,則會傳回錯誤訊息。
範例
Aws::GameLift::AwsStringOutcome SdkVersionOutcome = Aws::GameLift::Server::GetSdkVersion();
InitSDK()
為受管 EC2 叢集初始化 Amazon GameLift 開發套件。在與 Amazon 相關的任何其他初始化發生之前,請在啟動 GameLift 時呼叫此方法。此方法會從主機環境讀取伺服器參數,以設定伺服器與 Amazon GameLift 服務之間的通訊。
語法
FGameLiftGenericOutcome InitSDK()
傳回值
如果成功,則返回一個InitSdkOutcome
對象,指示服務器進程已準備好調用ProcessReady()。
範例
//Call InitSDK to establish a local connection with the GameLift agent to enable further communication. FGameLiftGenericOutcome initSdkOutcome = gameLiftSdkModule->InitSDK();
InitSDK()
初始化Anywhere叢集的 Amazon GameLift 開發套件。在與 Amazon 相關的任何其他初始化發生之前,請在啟動 GameLift 時呼叫此方法。此方法需要明確的伺服器參數來設定伺服器與 Amazon GameLift 服務之間的通訊。
語法
FGameLiftGenericOutcome InitSDK(serverParameters)
參數
- FServerParameters
-
若要初始化 Amazon GameLift Anywhere 叢集上的遊戲伺服器,請使用下列資訊建構
ServerParameters
物件:-
WebSocket 用來連線到遊戲伺服器的 URL。
-
用來託管遊戲伺服器的程序 ID。
-
主控遊戲伺服器處理程序的運算 ID。
-
包含您的 Amazon GameLift Anywhere 運算的 Amazon GameLift 車隊的 ID。
-
Amazon GameLift 操作生成的授權令牌。
-
傳回值
如果成功,則返回一個InitSdkOutcome
對象,指示服務器進程已準備好調用ProcessReady()。
注意
如果部署到 InitSDK()
Anywhere 叢集的遊戲組建時呼叫失敗,請檢查建立組建資源時使用的ServerSdkVersion
參數。您必須明確地將此值設定為使用中的伺服器 SDK 版本。此參數的預設值為 4.x,不相容。若要解決此問題,請建立新組建並將其部署到新的叢集。
範例
//Define the server parameters FServerParameters serverParameters; parameters.m_authToken = "
1111aaaa-22bb-33cc-44dd-5555eeee66ff
"; parameters.m_fleetId = "arn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa
"; parameters.m_hostId = "HardwareAnywhere
"; parameters.m_processId = "PID1234
"; parameters.m_webSocketUrl = "wss://us-west-1.api.amazongamelift.com
"; //Call InitSDK to establish a local connection with the GameLift agent to enable further communication. FGameLiftGenericOutcome initSdkOutcome = gameLiftSdkModule->InitSDK(serverParameters);
ProcessReady()
通 GameLift 知 Amazon 伺服器程序已準備好主持遊戲工作階段。調用後調用InitSDK()此方法。每個進程應該只調用一次此方法。
語法
GenericOutcome ProcessReady(const Aws::GameLift::Server::ProcessParameters
&processParameters);
參數
- processParameters
-
通訊有關伺服器處理序的下列資訊的FProcessParameters物件:
-
Amazon GameLift 服務呼叫以與伺服器處理序通訊之遊戲伺服器程式碼中實作的回呼方法名稱。
-
伺服器程序正在接聽的埠號。
-
您希望 Amazon 擷取和存放的任何遊戲工作階段特定檔案 GameLift 的路徑。
-
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
此範例會說明 ProcessReady() 呼叫和委派函數的實作。
//Calling ProcessReady tells GameLift this game server is ready to receive incoming game sessions! UE_LOG(GameServerLog, Log, TEXT("Calling Process Ready")); FGameLiftGenericOutcome processReadyOutcome = gameLiftSdkModule->ProcessReady(*params);
ProcessEnding()
通 GameLift 知 Amazon 服務器進程正在終止。在所有其他清理任務(包括關閉活動的遊戲會話)之後以及終止進程之前調用此方法。根據的結果ProcessEnding()
,程序會以成功 (0) 或錯誤 (-1) 結束,並產生叢集事件。如果處理序因錯誤而終止,則產生的叢集事件為SERVER_PROCESS_TERMINATED_UNHEALTHY
)。
語法
FGameLiftGenericOutcome ProcessEnding()
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
//OnProcessTerminate callback. GameLift will invoke this callback before shutting down an instance hosting this game server. //It gives this game server a chance to save its state, communicate with services, etc., before being shut down. //In this case, we simply tell GameLift we are indeed going to shutdown. params->OnTerminate.BindLambda([=]() { UE_LOG(GameServerLog, Log, TEXT("Game Server Process is terminating")); gameLiftSdkModule->ProcessEnding(); });
ActivateGameSession()
通 GameLift 知 Amazon 伺服器程序已啟動遊戲工作階段,現在已準備好接收玩家連線。在所有遊戲會話初始化之後,應將此操作作為onStartGameSession()
回調函數的一部分調用。
語法
FGameLiftGenericOutcome ActivateGameSession()
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
這個例子顯示了作ActivateGameSession()
為onStartGameSession()
委託函數的一部分調用。
//When a game session is created, GameLift sends an activation request to the game server and passes along the game session object containing game properties and other settings. //Here is where a game server should take action based on the game session object. //Once the game server is ready to receive incoming player connections, it should invoke GameLiftServerAPI.ActivateGameSession() auto onGameSession = [=](Aws::GameLift::Server::Model::GameSession gameSession) { FString gameSessionId = FString(gameSession.GetGameSessionId()); UE_LOG(GameServerLog, Log, TEXT("GameSession Initializing: %s"), *gameSessionId); gameLiftSdkModule->ActivateGameSession(); };
UpdatePlayerSessionCreationPolicy()
更新目前遊戲工作階段的能力,以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。
語法
FGameLiftGenericOutcome UpdatePlayerSessionCreationPolicy(EPlayerSessionCreationPolicy policy)
參數
- playerCreationSession政策
-
字串值代表遊戲工作階段是否可接受新玩家。
有效值包含:
-
ACCEPT_ALL – 接受所有新玩家工作階段。
-
DENY_ALL – 拒絕所有新玩家工作階段。
-
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。
FGameLiftGenericOutcome outcome = gameLiftSdkModule->UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::EPlayerSessionCreationPolicy::
ACCEPT_ALL
);
GetGameSessionId()
擷取使用中伺服器處理序主控的遊戲工作階段 ID。
對於未使用遊戲工作階段啟動的閒置進程,呼叫會傳回FGameLiftError.
語法
FGameLiftStringOutcome GetGameSessionId()
參數
此動作沒有參數。
傳回值
如果成功,則會把遊戲工作階段 ID 當成 FGameLiftStringOutcome 物件傳回。如果不成功,則返回錯誤消息。」
對於未使用遊戲會話激活的空閒進程,調用返回 Success
= True
和 GameSessionId
= ""
。
範例
//When a game session is created, GameLift sends an activation request to the game server and passes along the game session object containing game properties and other settings. //Here is where a game server should take action based on the game session object. //Once the game server is ready to receive incoming player connections, it should invoke GameLiftServerAPI.ActivateGameSession() auto onGameSession = [=](Aws::GameLift::Server::Model::GameSession gameSession) { FString gameSessionId = FString(gameSession.GetGameSessionId()); UE_LOG(GameServerLog, Log, TEXT("GameSession Initializing: %s"), *gameSessionId); gameLiftSdkModule->ActivateGameSession(); };
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()
調,則返回錯誤消息。如需關閉伺服器處理序的詳細資訊,請參閱回應伺服器處理序關閉通知。
範例
AwsDateTimeOutcome TermTimeOutcome = gameLiftSdkModule->GetTerminationTime();
AcceptPlayerSession()
通知 Amazon 具 GameLift 有指定玩家工作階段 ID 的玩家已連線到伺服器程序並需要驗證。Amazon 會 GameLift 驗證玩家工作階段 ID 是否有效。玩家會話驗證後,Amazon 將播放器插槽的狀態從保留 GameLift 更改為活動狀態。
語法
FGameLiftGenericOutcome AcceptPlayerSession(const FString& playerSessionId)
參數
- playerSessionId
-
創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
此範例會處理包含驗證和拒絕非有效玩家工作階段 ID 的連線要求。
bool GameLiftManager::AcceptPlayerSession(const FString& playerSessionId, const FString& playerId) { #if WITH_GAMELIFT UE_LOG(GameServerLog, Log, TEXT("Accepting GameLift PlayerSession: %s . PlayerId: %s"), *playerSessionId, *playerId); FString gsId = GetCurrentGameSessionId(); if (gsId.IsEmpty()) { UE_LOG(GameServerLog, Log, TEXT("No GameLift GameSessionId. Returning early!")); return false; } if (!gameLiftSdkModule->AcceptPlayerSession(playerSessionId).IsSuccess()) { UE_LOG(GameServerLog, Log, TEXT("PlayerSession not Accepted.")); return false; } // Add PlayerSession from internal data structures keeping track of connected players connectedPlayerSessionIds.Add(playerSessionId); idToPlayerSessionMap.Add(playerSessionId, PlayerSession{ playerId, playerSessionId }); return true; #else return false; #endif }
RemovePlayerSession()
通 GameLift 知 Amazon 播放器已與服務器進程斷開連接。作為回應,Amazon 將播放器插槽 GameLift 更改為可用。
語法
FGameLiftGenericOutcome RemovePlayerSession(const FString& playerSessionId)
參數
playerSessionId
-
創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
bool GameLiftManager::RemovePlayerSession(const FString& playerSessionId) { #if WITH_GAMELIFT UE_LOG(GameServerLog, Log, TEXT("Removing GameLift PlayerSession: %s"), *playerSessionId); if (!gameLiftSdkModule->RemovePlayerSession(playerSessionId).IsSuccess()) { UE_LOG(GameServerLog, Log, TEXT("PlayerSession Removal Failed")); return false; } // Remove PlayerSession from internal data structures that are keeping track of connected players connectedPlayerSessionIds.Remove(playerSessionId); idToPlayerSessionMap.Remove(playerSessionId); // end the session if there are no more players connected if (connectedPlayerSessionIds.Num() == 0) { EndSession(); } return true; #else return false; #endif }
DescribePlayerSessions()
檢索播放器會話數據,其中包括設置,會話元數據和播放器數據。使用此方法可取得下列項目的相關資訊:
-
單一玩家工作階段
-
遊戲工作階段中的所有玩家工作階
-
與單一玩家 ID 關聯的所有玩家工作階段
語法
FGameLiftDescribePlayerSessionsOutcome DescribePlayerSessions(const FGameLiftDescribePlayerSessionsRequest &describePlayerSessionsRequest)
參數
傳回值
如果成功,會傳回 FGameLiftDescribePlayerSessionsOutcome 物件,內含一組與請求參數相符的玩家工作階段物件。
範例
此範例要求所有主動連線至指定遊戲工作階段的玩家工作階段。透過省略限制值NextToken並將限制值設定為 10,Amazon 會 GameLift 傳回符合請求的前 10 個玩家工作階段記錄。
void GameLiftManager::DescribePlayerSessions() { #if WITH_GAMELIFT FString localPlayerSessions; for (auto& psId : connectedPlayerSessionIds) { PlayerSession ps = idToPlayerSessionMap[psId]; localPlayerSessions += FString::Printf(TEXT("%s : %s ; "), *(ps.playerSessionId), *(ps.playerId)); } UE_LOG(GameServerLog, Log, TEXT("LocalPlayerSessions: %s"), *localPlayerSessions); UE_LOG(GameServerLog, Log, TEXT("Describing PlayerSessions in this GameSession")); FGameLiftDescribePlayerSessionsRequest request; request.m_gameSessionId = GetCurrentGameSessionId(); FGameLiftDescribePlayerSessionsOutcome outcome = gameLiftSdkModule->DescribePlayerSessions(request); LogDescribePlayerSessionsOutcome(outcome); #endif }
StartMatchBackfill()
發送請求,在使用建立的遊戲工作階段中尋找新玩家的開放角子機 FlexMatch。如需詳細資訊,請參閱FlexMatch 回填功能。
此為非同步動作。如果配對新玩家,Amazon 會使用回調函OnUpdateGameSession()
數 GameLift 提供更新的分房系統資料。
一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求,請先呼叫 StopMatchBackfill() 取消原始請求。
語法
FGameLiftStringOutcome StartMatchBackfill (FStartMatchBackfillRequest &startBackfillRequest);
參數
- FStartMatchBackfillRequest
-
傳達下列資訊的 StartMatchBackfillRequest 物件:
-
指派給回填請求的票證 ID。此信息是可選的; 如果沒有提供 ID,Amazon GameLift 將生成一個。
-
傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值會顯示在遊戲工作階段的分房系統資料中。
-
要回填的遊戲工作階段 ID。
-
遊戲工作階段目前玩家的可用配對資料。
-
傳回值
傳回具有相符回填工單 ID 的StartMatchBackfillOutcome
物件,或失敗並顯示錯誤訊息。
範例
FGameLiftStringOutcome FGameLiftServerSDKModule::StartMatchBackfill(const FStartMatchBackfillRequest& request) { #if WITH_GAMELIFT Aws::GameLift::Server::Model::StartMatchBackfillRequest sdkRequest; sdkRequest.SetTicketId(TCHAR_TO_UTF8(*request.m_ticketId)); sdkRequest.SetGameSessionArn(TCHAR_TO_UTF8(*request.m_gameSessionArn)); sdkRequest.SetMatchmakingConfigurationArn(TCHAR_TO_UTF8(*request.m_matchmakingConfigurationArn)); for (auto player : request.m_players) { Aws::GameLift::Server::Model::Player sdkPlayer; sdkPlayer.SetPlayerId(TCHAR_TO_UTF8(*player.m_playerId)); sdkPlayer.SetTeam(TCHAR_TO_UTF8(*player.m_team)); for (auto entry : player.m_latencyInMs) { sdkPlayer.WithLatencyMs(TCHAR_TO_UTF8(*entry.Key), entry.Value); } std::map<std::string, Aws::GameLift::Server::Model::AttributeValue> sdkAttributeMap; for (auto attributeEntry : player.m_playerAttributes) { FAttributeValue value = attributeEntry.Value; Aws::GameLift::Server::Model::AttributeValue attribute; switch (value.m_type) { case FAttributeType::STRING: attribute = Aws::GameLift::Server::Model::AttributeValue(TCHAR_TO_UTF8(*value.m_S)); break; case FAttributeType::DOUBLE: attribute = Aws::GameLift::Server::Model::AttributeValue(value.m_N); break; case FAttributeType::STRING_LIST: attribute = Aws::GameLift::Server::Model::AttributeValue::ConstructStringList(); for (auto sl : value.m_SL) { attribute.AddString(TCHAR_TO_UTF8(*sl)); }; break; case FAttributeType::STRING_DOUBLE_MAP: attribute = Aws::GameLift::Server::Model::AttributeValue::ConstructStringDoubleMap(); for (auto sdm : value.m_SDM) { attribute.AddStringAndDouble(TCHAR_TO_UTF8(*sdm.Key), sdm.Value); }; break; } sdkPlayer.WithPlayerAttribute((TCHAR_TO_UTF8(*attributeEntry.Key)), attribute); } sdkRequest.AddPlayer(sdkPlayer); } auto outcome = Aws::GameLift::Server::StartMatchBackfill(sdkRequest); if (outcome.IsSuccess()) { return FGameLiftStringOutcome(outcome.GetResult().GetTicketId()); } else { return FGameLiftStringOutcome(FGameLiftError(outcome.GetError())); } #else return FGameLiftStringOutcome(""); #endif }
StopMatchBackfill()
取消使用中的比對回填要求。如需詳細資訊,請參閱FlexMatch回填功能。
語法
FGameLiftGenericOutcome StopMatchBackfill (FStopMatchBackfillRequest &stopBackfillRequest);
參數
- FStopMatchBackfillRequest
-
識別要取消配對票證的 StopMatchBackfillRequest 物件:
-
指派給回填請求的工單 ID。
-
回填要求傳送至的分房系統。
-
與回填要求相關聯的遊戲工作階段。
-
傳回值
傳回包含錯誤訊息的成功或失敗的一般結果。
範例
FGameLiftGenericOutcome FGameLiftServerSDKModule::StopMatchBackfill(const FStopMatchBackfillRequest& request) { #if WITH_GAMELIFT Aws::GameLift::Server::Model::StopMatchBackfillRequest sdkRequest; sdkRequest.SetTicketId(TCHAR_TO_UTF8(*request.m_ticketId)); sdkRequest.SetGameSessionArn(TCHAR_TO_UTF8(*request.m_gameSessionArn)); sdkRequest.SetMatchmakingConfigurationArn(TCHAR_TO_UTF8(*request.m_matchmakingConfigurationArn)); auto outcome = Aws::GameLift::Server::StopMatchBackfill(sdkRequest); if (outcome.IsSuccess()) { return FGameLiftGenericOutcome(nullptr); } else { return FGameLiftGenericOutcome(FGameLiftError(outcome.GetError())); } #else return FGameLiftGenericOutcome(nullptr); #endif }
GetComputeCertificate()
擷取 TLS 憑證的路徑,用於加密 Amazon GameLift Anywhere 運算資源和 Amazon 之間的網路連線 GameLift。將運算裝置註冊到 Amazon GameLift Anywhere 叢集時,可以使用憑證路徑。若要取得更多資訊,請參閱RegisterCompute。
語法
FGameLiftGetComputeCertificateOutcome FGameLiftServerSDKModule::GetComputeCertificate()
傳回值
返回包含以下內容的GetComputeCertificateResponse
對象:
-
CertificatePath:計算資源上 TLS 憑證的路徑。
-
HostName:計算資源的主機名稱。
範例
FGameLiftGetComputeCertificateOutcome FGameLiftServerSDKModule::GetComputeCertificate() { #if WITH_GAMELIFT auto outcome = Aws::GameLift::Server::GetComputeCertificate(); if (outcome.IsSuccess()) { auto& outres = outcome.GetResult(); FGameLiftGetComputeCertificateResult result; result.m_certificate_path = UTF8_TO_TCHAR(outres.GetCertificatePath()); result.m_computeName = UTF8_TO_TCHAR(outres.GetComputeName()); return FGameLiftGetComputeCertificateOutcome(result); } else { return FGameLiftGetComputeCertificateOutcome(FGameLiftError(outcome.GetError())); } #else return FGameLiftGetComputeCertificateOutcome(FGameLiftGetComputeCertificateResult()); #endif }
GetFleetRoleCredentials()
擷取 IAM 角色登入資料, GameLift 以授權 Amazon 與其他人互動 AWS 服務。如需詳細資訊,請參閱 與您車隊的其他AWS資源進行溝通。
語法
FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request)
參數
FGameLiftGetFleetRoleCredentialsRequest
傳回值
其會傳回 FGameLiftGetFleetRoleCredentialsOutcome 物件。
範例
FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request) { #if WITH_GAMELIFT Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest sdkRequest; sdkRequest.SetRoleArn(TCHAR_TO_UTF8(*request.m_roleArn)); sdkRequest.SetRoleSessionName(TCHAR_TO_UTF8(*request.m_roleSessionName)); auto outcome = Aws::GameLift::Server::GetFleetRoleCredentials(sdkRequest); if (outcome.IsSuccess()) { auto& outres = outcome.GetResult(); FGameLiftGetFleetRoleCredentialsResult result; result.m_assumedUserRoleArn = UTF8_TO_TCHAR(outres.GetAssumedUserRoleArn()); result.m_assumedRoleId = UTF8_TO_TCHAR(outres.GetAssumedRoleId()); result.m_accessKeyId = UTF8_TO_TCHAR(outres.GetAccessKeyId()); result.m_secretAccessKey = UTF8_TO_TCHAR(outres.GetSecretAccessKey()); result.m_sessionToken = UTF8_TO_TCHAR(outres.GetSessionToken()); result.m_expiration = FDateTime::FromUnixTimestamp(outres.GetExpiration()); return FGameLiftGetFleetRoleCredentialsOutcome(result); } else { return FGameLiftGetFleetRoleCredentialsOutcome(FGameLiftError(outcome.GetError())); } #else return FGameLiftGetFleetRoleCredentialsOutcome(FGameLiftGetFleetRoleCredentialsResult()); #endif }