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

适用于 — 操作的 C++ 服务器 SDK 5.x Amazon GameLift Servers

使用服务器 SDK 5.x 参考来集成用于托管的Amazon GameLift Servers多人游戏。有关集成过程的指南，请参阅Amazon GameLift Servers添加到您的游戏服务器。

注意

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

适用于 Amazon GameLift Servers — 数据类型的 C++ 服务器 SDK 5.x

主题

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

GetSdkVersion()

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

语法


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

返回值

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

示例


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

InitSDK()

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

如果要在没有Amazon GameLift Servers代理的情况下将游戏服务器版本部署到 Amazon GameLift Servers Anywhere 队列或容器队列中，请调用InitSDK()并指定一组服务器参数。

语法


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

返回值

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

示例


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

InitSDK()

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

如果要将游戏服务器版本部署到Amazon GameLift Servers托管 EC2 队列、Amazon GameLift Servers Anywhere 队列或带有Amazon GameLift Servers代理的容器队列，请InitSDK()不使用服务器参数进行调用。

语法


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

参数

ServerParameters

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

WebSocket 用于连接到游戏服务器的 URL。
用于托管游戏服务器的进程的 ID。
托管游戏服务器进程的计算的 ID。
包含你的 Amazon GameLift Servers Anywhere 计算的Amazon GameLift Servers队列的 ID。
Amazon GameLift Servers操作生成的授权令牌。

返回值

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

注意

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

示例

Amazon GameLift Servers任何地方的例子


//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 Amazon GameLift Servers Agent to enable further communication.
Aws::GameLift::Server::InitSDKOutcome initSdkOutcome = Aws::GameLift::Server::InitSDK(serverParameters);

ProcessReady()

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

语法

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

参数

processParameters

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

在游戏服务器代码中实现的回调方法的名称，Amazon GameLift Servers服务调用这些方法与服务器进程进行通信。
服务器进程正在侦听的端口号。
您希望 Amazon GameLift Servers 捕获和存储的任何游戏会话特定文件的路径。

返回值

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

示例

此示例说明 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 Servers 服务，服务器进程已准备好托管游戏会话。在服务器进程准备好托管游戏会话后，应调用此方法。这些参数指定了在某些情况下Amazon GameLift Servers要调用的回调函数名称。游戏服务器代码必须执行这些函数。

此调用为异步操作。要进行同步调用，请使用 ProcessReady()。有关更多信息，请参阅初始化服务器进程。

语法


GenericOutcomeCallable ProcessReadyAsync(
    const Aws::GameLift::Server::ProcessParameters &processParameters);

参数

processParameters

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

在游戏服务器代码中实现的回调方法的名称，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<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()

Amazon GameLift Servers通知服务器进程即将终止。请在已完成所有其他清理任务（包括关闭活动游戏会话）但尚未终止进程时调用此方法。根据的结果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 Servers通知服务器进程已激活游戏会话，现在可以接收玩家连接了。此操作应作为 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()

如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到来自的onProcessTerminate()回调后采取行动Amazon GameLift Servers。 Amazon GameLift Servers致电onProcessTerminate()的原因如下：

当服务器进程报告运行状况不佳或没有响应时Amazon GameLift Servers。
在缩减事件期间终止实例时。
当实例因竞价型实例中断而终止时。

语法


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 Servers具有指定玩家会话 ID 的玩家已连接到服务器进程并需要验证。 Amazon GameLift Servers验证玩家会话 ID 是否有效。玩家会话通过验证后，将玩家位置的状态从 “已保留” Amazon GameLift Servers 更改为 “已激活”。

语法


GenericOutcome AcceptPlayerSession(String playerSessionId)

参数

playerSessionId: 创建新玩家会话Amazon GameLift Servers时颁发的唯一 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 Servers玩家已与服务器进程断开连接。作为响应，将玩家位置Amazon GameLift Servers更改为可用。

语法


GenericOutcome RemovePlayerSession(String playerSessionId)

参数

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

返回值

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

示例


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

DescribePlayerSessions()

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

单人游戏会话
游戏会话中的所有玩家会话
与单个玩家 ID 关联的所有玩家会话

语法


DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

参数

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

返回值

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

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。省略NextToken并将 L im it 值设置为 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);

StartMatchBackfill()

发送请求以为使用 FlexMatch 创建的游戏会话中的开放位置查找新玩家。有关更多信息，请参阅FlexMatch回填功能。

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

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

语法


StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

参数

StartMatchBackfillRequest

传达以下信息的 StartMatchBackfillRequest 对象：

要分配给回填请求的票证 ID。此信息是可选的；如果未提供 ID，则Amazon GameLift Servers会生成一个。
要将请求发送到的对战构建器。需要完整的配置 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()

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

语法


GetComputeCertificateOutcome Server::GetComputeCertificate()

返回值

返回 GetComputeCertificateOutcome。

示例


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

GetFleetRoleCredentials()

检索授权Amazon GameLift Servers与其他 AWS 服务角色交互的 IAM 角色证书。有关更多信息，请参阅与舰队中的其他 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值为凭证会话分配名称以进行审计。如果您不提供角色会话名称，则使用默认值 [host-id] “[fleet-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 Servers游戏服务器 SDK。作为最佳实操，请在终止进程之后ProcessEnding()和之前调用此方法。如果您使用的是 Anywhere 队列，并且没有在每次游戏会话后终止服务器进程，请先调用Destroy()然后InitSDK()重新初始化，然后再通知Amazon GameLift Servers该进程已准备好托管游戏会话。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);
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

迁移到服务器 SDK 5.x

数据类型