适用于 C++ 的亚马逊 GameLift 服务器 SDK 5.x：操作

使用 Amazon GameLift C++ 服务器 SDK 5.x 参考将您的多人游戏集成到亚马逊 GameLift托管。有关集成过程的指导，请参阅将 Amazon GameLift 添加到您的游戏服务器。

注意

本主题介绍在使用 GameLift C++ API 标准库 (std) 进行构建时可以使用的 Amazon C++。具体而言，本文档适用于使用该-DDGAMELIFT_USE_STD=1选项编译的代码。

适用于 C++ 的亚马逊 GameLift 服务器 SDK 5.x：数据类型

GetSdkVersion()

返回服务器SDK内置进程的当前版本号。

语法

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

返回值

如果成功，则将当前SDK版本作为AwsStringOutcome对象返回。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。

示例

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

初始化 SDK ()

初始化 Amazon GameLift SDK。在启动时调用此方法，然后再执行任何其他与 Amazon 相关的初始化步骤 GameLift。此操作从主机环境中读取服务器参数，以设置游戏服务器进程与 Amazon GameLift 服务之间的通信。

如果游戏服务器版本将在没有亚马逊 GameLift 代理的情况下部署到亚马逊 GameLift Anywhere 舰队或集装箱舰队，调用初始化 SDK ()并指定一组服务器参数。

语法

Server::InitSDKOutcome Server::initSdkOutcome = InitSDK();

返回值

返回一个我 nitSDKOutcome对象，该对象指示服务器进程是否已准备好调用ProcessReady()。

示例

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = 
  Aws::GameLift::Server::InitSDK();

初始化 SDK ()

初始化 Amazon GameLift SDK。在启动时调用此方法，然后再执行任何其他与 Amazon 相关的初始化步骤 GameLift。此操作需要一组服务器参数来设置游戏服务器进程和 Amazon GameLift 服务之间的通信。

游戏服务器版本是部署到亚马逊 GameLift 托管EC2队列还是部署到亚马逊 GameLift Anywhere 使用 Amazon A GameLift gent 的舰队或集装箱舰队，初始化 SDK ()无需服务器参数即可调用。

语法

Server::InitSDKOutcome Server::initSdkOutcome = InitSDK(serverParameters);

参数

ServerParameters

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

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

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

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

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

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

返回值

返回一个我 nitSDKOutcome对象，该对象指示服务器进程是否已准备好调用ProcessReady()。

注意

如果对部署到 InitSDK() Anywhere 队列的游戏版本调用失败，请检查创建编译资源时使用的ServerSdkVersion参数。必须将此值显式设置为正在使用的服务器SDK版本。此参数的默认值为 4.x，这不兼容。要解决此问题，请创建新版本并将其部署到新队列。

示例

Amazon GameLift Anywhere 示例

//Define the server parameters
std::string websocketUrl = "wss://us-west-1.api.amazongamelift.com";
std::string processId = "PID1234";
std::string fleetId = "arn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa";
std::string hostId = "HardwareAnywhere";
std::string authToken = "1111aaaa-22bb-33cc-44dd-5555eeee66ff";
Aws::GameLift::Server::Model::ServerParameters serverParameters = 
  Aws::GameLift::Server::Model::ServerParameters(webSocketUrl, authToken, fleetId, hostId, processId);

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = Aws::GameLift::Server::InitSDK(serverParameters);

ProcessReady()

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

语法

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

参数

processParameters

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

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

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

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

返回值

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

示例

此示例说明 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 服务调用这些方法与服务器进程进行通信。

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

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

必需：是

返回值

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

示例

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

ProcessEnding()

通知 Amaz GameLift on 服务器进程即将终止。在完成所有其他清理任务（包括关闭活动游戏会话）之后和终止该进程之前，调用此方法。根据的结果ProcessEnding()，进程以成功 (0) 或错误 (-1) 退出并生成队列事件。如果流程因错误而终止，则生成的舰队事件为SERVER_PROCESS_TERMINATED_UNHEALTHY。

语法

Aws::GameLift::GenericOutcome processEndingOutcome = Aws::GameLift::Server::ProcessEnding();

返回值

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

示例

此示例在使用成功或错误退出代码终止服务器进程Destroy()之前调ProcessEnding()用和。

Aws::GameLift::GenericOutcome processEndingOutcome = Aws::GameLift::Server::ProcessEnding();
Aws::GameLift::Server::Destroy();

// Exit the process with success or failure
if (processEndingOutcome.IsSuccess()) {
  exit(0);
}
else {
  cout << "ProcessEnding() failed. Error: " << processEndingOutcome.GetError().GetErrorMessage();
  exit(-1);
}

ActivateGameSession()

通知 Amazon GameLift 服务器进程已激活游戏会话，现在可以接收玩家连接了。此操作应作为 onStartGameSession() 回调函数的一部分，在所有游戏会话初始化已完成之后调用。

语法

Aws::GameLift::GenericOutcome activateGameSessionOutcome = Aws::GameLift::Server::ActivateGameSession();

返回值

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

示例

此示例显示了 ActivateGameSession() 作为 onStartGameSession() 委派函数的一部分调用。

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

UpdatePlayerSessionCreationPolicy()

更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。

语法

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

参数

playerCreationSession政策

类型：一个 PlayerSessionCreationPolicy 枚举值。

必需：是

返回值

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

示例

此示例将当前游戏会话的接入策略设为接受所有玩家。

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

GetGameSessionId()

检索当前由服务器进程托管的游戏会话的 ID (如果服务器进程处于活动状态)。

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

语法

AwsStringOutcome GetGameSessionId()

参数

此操作没有参数。

返回值

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

对于未通过游戏会话激活的空闲进程，调用返回 Success = True 和 GameSessionId = ""。

示例

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

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() 回调，返回错误消息。有关关闭服务器进程的更多信息，请参阅回应服务器进程关闭通知。

示例

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

AcceptPlayerSession()

通知 Amazon GameLift 具有指定玩家会话 ID 的玩家已连接到服务器进程，需要验证。Amazon 会 GameLift 验证玩家会话 ID 是否有效。玩家会话经过验证后，Amazon 会将玩家位置的状态从 GameLift 更改RESERVED为ACTIVE。

语法

GenericOutcome AcceptPlayerSession(String playerSessionId)

参数

playerSessionId

创建新玩家会话 GameLift 时由 Amazon 颁发的唯一 ID。

返回值

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

示例

此示例处理的连接请求包括验证和拒绝无效的玩家会话。IDs

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

RemovePlayerSession()

通知 Amazon GameLift 有玩家已断开与服务器进程的连接。作为回应，Amazon将玩家位置 GameLift 更改为可用。

语法

GenericOutcome RemovePlayerSession(String playerSessionId)

参数

playerSessionId

创建新玩家会话 GameLift 时由 Amazon 颁发的唯一 ID。

返回值

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

示例

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

DescribePlayerSessions()

检索玩家会话数据，包括设置、会话元数据和玩家数据。使用此方法获取有关以下内容的信息：

• 单人游戏会话

• 游戏会话中的所有玩家会话

• 与单个玩家 ID 关联的所有玩家会话

语法

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

参数

DescribePlayerSessionsRequest

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

返回值

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

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过省略限制值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);

StartMatchBackfill()

发送请求，要求在使用创建的游戏会话中为空缺老虎机寻找新玩家 FlexMatch。有关更多信息，请参阅FlexMatch 回填功能。

此操作为异步操作。如果匹配了新玩家，Amazon会使用回调函数 GameLift 提供更新的匹配器数据OnUpdateGameSession()。

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

语法

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

参数

StartMatchBackfillRequest

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

• 要分配给回填请求的票证 ID。此信息是可选的；如果未提供编号，Amazon GameLift 将生成一个。

• 要将请求发送到的对战构建器。完整配置ARN是必需的。该值位于游戏会话的对战构建器数据中。

• 要回填的游戏会话的 ID。

• 游戏会话的当前玩家的可用对战数据。

返回值

返回带有匹配回填票证 ID 的 StartMatchBackfillOutcome 对象或包含错误消息的失败。

示例

// Build a backfill request
std::vector<Player> players;
Aws::GameLift::Server::Model::StartMatchBackfillRequest startBackfillRequest;
startBackfillRequest.SetTicketId("1111aaaa-22bb-33cc-44dd-5555eeee66ff");  // optional, autogenerated if not provided
startBackfillRequest.SetMatchmakingConfigurationArn("arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig"); //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()

取消使用 创建的活动对战回填请求。有关更多信息，请参阅FlexMatch回填功能。

语法

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

参数

StopMatchBackfillRequest

标识要取消的配对门票的 StopMatchBackfillRequest 对象：

• 要分配给回填请求的票证 ID

• 回填请求所发送到的对战构建器

• 与回填请求关联的游戏会话

返回值

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

示例

// Set backfill stop request parameters

Aws::GameLift::Server::Model::StopMatchBackfillRequest stopBackfillRequest;
stopBackfillRequest.SetTicketId("1111aaaa-22bb-33cc-44dd-5555eeee66ff");
stopBackfillRequest.SetGameSessionArn("the game session ARN"); // can use GetGameSessionId()
stopBackfillRequest.SetMatchmakingConfigurationArn("arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig");
// from the game session matchmaker data

Aws::GameLift::GenericOutcome stopBackfillOutcome = 
  Aws::GameLift::Server::StopMatchBackfill(stopBackfillRequest);

GetComputeCertificate()

检索用于加密您的 Amazon 之间网络连接的TLS证书的路径 GameLift Anywhere 计算资源和 Amazon GameLift。当您将计算设备注册到 Amazon 时，您可以使用证书路径 GameLift Anywhere 舰队。有关更多信息，请参阅RegisterCompute。

语法

GetComputeCertificateOutcome Server::GetComputeCertificate()

返回值

返回 GetComputeCertificateOutcome。

示例

Aws::GameLift::GetComputeCertificateOutcome certificate = Aws::GameLift::Server::GetComputeCertificate();

GetFleetRoleCredentials()

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

语法

GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

参数

GetFleetRoleCredentialsRequest

返回值

返回 GetFleetRoleCredentialsOutcome 对象。

示例

// form the fleet credentials request 
Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest getFleetRoleCredentialsRequest; 
getFleetRoleCredentialsRequest.SetRoleArn("arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction");

Aws::GameLift::GetFleetRoleCredentialsOutcome credentials = Aws::GameLift::Server::GetFleetRoleCredentials(getFleetRoleCredentialsRequest);

此示例说明如何使用可选RoleSessionName值为凭证会话分配名称以进行审计。如果您不提供角色会话名称，则为默认值”[fleet-id]-[host-id]“被使用。

// form the fleet credentials request 
Aws::GameLift::Server::Model::GetFleetRoleCredentialsRequest getFleetRoleCredentialsRequest; 
getFleetRoleCredentialsRequest.SetRoleArn("arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction");
getFleetRoleCredentialsRequest.SetRoleSessionName("MyFleetRoleSession"); 

Aws::GameLift::GetFleetRoleCredentialsOutcome credentials = Aws::GameLift::Server::GetFleetRoleCredentials(getFleetRoleCredentialsRequest);

Destroy

将 Amazon GameLift 游戏服务器SDK从内存中释放。作为最佳实操，请在终止进程之后ProcessEnding()和之前调用此方法。如果您使用的是 Anywhere 队列，并且没有在每次游戏会话后终止服务器进程，请先致电Destroy()然后InitSDK()重新初始化，然后再通知 A GameLift mazon 该进程已准备好与之托管游戏会话。ProcessReady()

语法

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

参数

没有参数。

返回值

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

示例

Aws::GameLift::GenericOutcome processEndingOutcome = Aws::GameLift::Server::ProcessEnding();
Aws::GameLift::Server::Destroy();

// Exit the process with success or failure
if (processEndingOutcome.IsSuccess()) {
  exit(0);
}
else {
  cout << "ProcessEnding() failed. Error: " << processEndingOutcome.GetError().GetErrorMessage();
  exit(-1);
}