亚马逊 GameLift 服务器 SDK（虚幻）5.x 参考：操作

你可以使用这份亚马逊 GameLift 虚幻服务器 SDK 参考来帮助你为多人游戏做好准备，以便在亚马逊上使用 GameLift。有关集成过程的详细信息，请参阅将 Amazon GameLift 添加到您的游戏服务器；有关使用 Unreal 软件开发工具包服务器插件的信息，请参阅将 Amazon GameLift 集成到虚幻引擎项目中。

注意

本主题介绍在为虚幻引擎构建时可以使用的Amazon GameLift C++ API。具体而言，本文档适用于使用该-DBUILD_FOR_UNREAL=1选项编译的代码。

GetSdkVersion()

返回当前内置到服务器进程中的开发工具包的版本号。

语法

FGameLiftStringOutcome GetSdkVersion();

返回值

如果成功，返回以 F GameLiftStringOutcome 对象返回当前软件开发工具包的版本。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。

示例

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

InitSDK()

为托管 EC2 队列初始化 Amazon GameLift 开发工具包。在启动时调用此方法，然后再进行任何其他与 Amazon GameLift 相关的初始化。此方法从主机环境读取服务器参数，以设置服务器与 Amazon GameLift 服务之间的通信。

语法

FGameLiftGenericOutcome InitSDK()

返回值

如果成功，返回 InitSdkOutcome 对象，指示服务器进程已准备好调用 。

示例

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

参数

F ServerParameters

要在 Amazon GameLift Anywhere 舰队上初始化游戏服务器，请使用以下信息构造一个ServerParameters对象：

• WebSocket 用于连接到您的游戏服务器的 URL。

• 用于托管游戏服务器的进程的 ID。

• 托管游戏服务器进程的计算的 ID。

• 包含您的亚马逊 GameLift Anywhere计算的亚马逊 GameLift 舰队的 ID。

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

返回值

如果成功，返回 InitSdkOutcome 对象，指示服务器进程已准备好调用 。

注意

如果对部署到 InitSDK() Anywhere 队列的游戏版本调用失败，请检查创建编译资源时使用的ServerSdkVersion参数。您必须将此值明确设置为正在使用的服务器软件开发工具包 版本。此参数的默认值为 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()

通知 Amaz GameLift on 服务器进程已准备好托管游戏会话。调用后调用InitSDK()此方法。每个进程只能调用一次此方法。

语法

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

参数

processParameters

F ProcessParameters 对象，用于传输有关服务器进程的以下信息：

• 游戏服务器代码中实现的回调方法的名称，Amazon GameLift 服务调用这些方法与服务器进程进行通信。

• 服务器进程正在侦听的端口号。

• 您希望 Ama GameLift zon 捕获和存储的所有游戏会话特定文件的路径。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

此示例说明 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()

通知 Amaz GameLift on 服务器进程即将终止。在完成所有其他清理任务（包括关闭活动游戏会话）之后和终止该进程之前，调用此方法。根据的结果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()

通知 Amazon GameLift 服务器进程已激活游戏会话，现在可以接收玩家连接了。此操作应作为 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 (如果服务器进程处于活动状态)。

对于未通过游戏会话激活的空闲进程，该调用将返回F GameLiftError。

语法

FGameLiftStringOutcome GetGameSessionId()

参数

此操作没有参数。

返回值

如果成功，以 F GameLiftStringOutcome 对象返回游戏会话 ID。如果不成功，将返回错误消息。

对于未通过游戏会话激活的空闲进程，调用返回 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()

通知 Amazon GameLift 有玩家已断开与服务器进程的连接。作为回应，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)

参数

F GameLiftDescribePlayerSessionsRequest

F GameLiftDescribePlayerSessionsRequest 对象描述要检索的玩家会话。

返回值

如果成功，将返回一个 F GameLiftDescribePlayerSessionsOutcome 对象，包含一组与请求参数相匹配的玩家会话对象。

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过省略限制值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会使用回调函数 GameLift 提供更新的匹配器数据OnUpdateGameSession()。

服务器进程每次只能具有一个活动的匹配回填请求。要发送新请求，请先调用 StopMatchBackfill() 以取消原始请求。

语法

FGameLiftStringOutcome StartMatchBackfill (FStartMatchBackfillRequest &startBackfillRequest);

参数

F StartMatchBackfillRequest

用于传达以下信息的 StartMatchBackfillRequest 对象：

• 要分配给回填请求的票证 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);

参数

F StopMatchBackfillRequest

标识要取消的配对门票的 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 证书的路径，该证书用于加密您的亚马逊 GameLift Anywhere计算资源与亚马逊之间的网络连接。 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()

检索授权 Amazon GameLift 与其他 AWS 服务角色互动的 IAM 角色证书。有关更多信息，请参阅 与您的实例集中的其他 AWS 资源进行通信。

语法

FGameLiftGetFleetRoleCredentialsOutcome FGameLiftServerSDKModule::GetFleetRoleCredentials(const FGameLiftGetFleetRoleCredentialsRequest &request)

参数

F GameLiftGetFleetRoleCredentialsRequest

返回值

返回 F GameLiftGetFleetRoleCredentialsOutcome 对象。

示例

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
}