本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Amazon GameLift 服务器软件开发工具包 (C++) 参考:操作
您可以使用这份 Amazon GameLift C++ 服务器软件开发工具包 参考来帮助您为多人游戏做好准备,以便在 Amazon GameLift 上使用。有关集成过程的详细信息,请参阅将 Amazon GameLift 添加到您的游戏服务器。
操作
- AcceptPlayerSession()
- ActivateGameSession()
- DescribePlayerSessions()
- GetGameSessionId()
- GetInstanceCertificate()
- GetSdkVersion()
- GetTerminationTime()
- InitSDK()
- ProcessEnding()
- ProcessReady()
- ProcessReadyAsync()
- RemovePlayerSession()
- StartMatchBackfill()
- StopMatchBackfill()
- TerminateGameSession()
- UpdatePlayerSessionCreationPolicy()
- Destroy
AcceptPlayerSession()
通知 服务,具有所指定玩家会话 ID 的玩家已连接到服务器进程,需要进行验证。 需要确保玩家会话 ID 有效,即该玩家 ID 在游戏会话中有保留的玩家位置。通过验证后, 将玩家位置的状态从 RESERVED 更改为 ACTIVE。
语法
GenericOutcome AcceptPlayerSession(const std::string& playerSessionId);
参数
- PlayerSessionId
-
Amazon GameLift 服务为响应调用软件开发工具包 Amazon GameLift API 操作 createPlayerSessi AWS on 而颁发的唯一身份证。连接到服务器进程时,游戏客户端会引用此 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()
通知 服务,服务器进程已启动游戏会话,现在已准备好接收玩家连接。此操作应作为 onStartGameSession()
回调函数的一部分,在所有游戏会话初始化已完成之后调用。
语法
GenericOutcome ActivateGameSession();
参数
此操作没有参数。
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
此示例显示作为 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);
参数
- describePlayerSessionsRequest
-
DescribePlayerSessionsRequest 对象描述要检索的玩家会话。
必需:是
返回值
如果成功,将返回一个 DescribePlayerSessionsOutcome
对象,包含一组与请求参数相匹配的玩家会话对象。玩家会话对象与 API PlayerSession 数据类型具有相同的结构。
示例
此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过忽略 NextToken
和将 值设置为 10, 将返回符合请求条件的前 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:<region>::gamesession/fleet-<fleet
ID>/<ID string>
。
对于尚未通过游戏会话激活的空闲进程,该调用返回 Success
= True
和 GameSessionId
=""
(空字符串)。
语法
AwsStringOutcome GetGameSessionId();
参数
此操作没有参数。
返回值
如果成功,以 AwsStringOutcome
对象返回游戏会话 ID。如果不成功,将返回错误消息。
示例
Aws::GameLift::AwsStringOutcome sessionIdOutcome = Aws::GameLift::Server::GetGameSessionId();
GetInstanceCertificate()
检索与队列及其实例关联的 PEM 编码 TLS 证书的文件位置。 AWS Certificate Manager当您在证书配置设置为 GENERATED 的情况下创建新队列时,将生成此证书。使用此证书可与游戏客户端建立安全连接并加密客户端/服务器通信。
语法
GetInstanceCertificateOutcome GetInstanceCertificate();
参数
此操作没有参数。
返回值
如果成功,则返回一个 GetInstanceCertificateOutcome
对象,该对象包含实例集的 TLS 证书文件的位置(该证书文件存储在实例上)。从证书链中提取的根证书文件也存储在实例上。如果不成功,将返回错误消息。
有关证书和证书链数据的更多信息,请参阅 AWS Certificate Manager API 参考中的获取证书响应元素。
示例
Aws::GameLift::GetInstanceCertificateOutcome certificateOutcome = Aws::GameLift::Server::GetInstanceCertificate();
GetSdkVersion()
返回正在使用中的软件开发工具包的当前版本号。
语法
AwsStringOutcome GetSdkVersion();
参数
此操作没有参数。
返回值
如果成功,返回以 AwsStringOutcome
对象返回当前软件开发工具包的版本。返回的字符串仅包含版本号 (例如:如果不成功,将返回错误消息。
示例
Aws::GameLift::AwsStringOutcome SdkVersionOutcome = Aws::GameLift::Server::GetSdkVersion();
GetTerminationTime()
如果终止时间可用,则返回安排服务器进程关闭的时间。收到来自 服务的 回调后,服务器进程将执行此操作。Amazon GameLift 可能出于以下原因onProcessTerminate()调用:(1) 当服务器进程报告运行状况不佳或未响应 Amazon GameLift 时,(2) 在缩小规模事件期间终止实例时,或 (3) 由于竞价中断而终止实例时。
如果该进程已收到 onProcessTerminate()
回调,则返回的值是估计的终止时间 (纪元秒)。如果进程未收到onProcessTerminate()
回调,则会返回一条错误消息。了解有关关闭服务器进程的更多信息。
语法
AwsLongOutcome GetTerminationTime();
参数
此操作没有参数。
返回值
如果成功,则以AwsLongOutcome
对象形式返回终止时间。该值是终止时间,以自 0001 00:00:00 起经过的报价表示。例如,日期时间值 2020-09-13 12:26:40-000Z 等于 637355968000000000 滴答作响。如果没有可用的终止时间,将返回一条错误消息。
示例
Aws::GameLift::AwsLongOutcome TermTimeOutcome = Aws::GameLift::Server::GetTerminationTime();
InitSDK()
初始化 Amazon GameLift 软件开发工具包。应在启动之后、进行任何其他 相关的初始化之前调用此方法。
语法
InitSDKOutcome InitSDK();
参数
此操作没有参数。
返回值
如果成功,返回 InitSdkOutcome 对象,指示服务器进程已准备好调用 ProcessReady()。
示例
Aws::GameLift::Server::InitSDKOutcome initOutcome = Aws::GameLift::Server::InitSDK();
ProcessEnding()
通知 服务,该服务器进程正在关闭。应在所有其他清除任务 (包括关闭所有活动游戏会话) 之后调用此方法。此方法应退出,退出代码为 0;非零退出代码将导致生成一条事件消息,提示进程未完全退出。
当该方法以代码为 0 退出后,您可以使用成功的退出代码终止该进程。您也可以退出,并返回错误代码。如果您退出时出现错误代码,则队列事件将指示进程异常终止(SERVER_PROCESS_TERMINATED_UNHEALTHY
)。
语法
GenericOutcome ProcessEnding();
参数
此操作没有参数。
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::ProcessEnding(); if (outcome.Success) exit(0); // exit with success // otherwise, exit with error code exit(errorCode);
ProcessReady()
通知 服务,服务器进程已准备好托管游戏会话。在成功调用 InitSDK() 并完成了服务器进程托管游戏会话所需的全部设置任务后,应调用此方法。每个进程只能调用一次此方法。
此调用为同步操作。要进行异步调用,请使用 ProcessReadyAsync()。有关更多信息,请参阅 初始化服务器进程。
语法
GenericOutcome ProcessReady( const Aws::GameLift::Server::ProcessParameters &processParameters);
参数
- processParameters
-
ProcessParameters 对象,用于传输有关服务器进程的以下信息:
-
回调方法的名称,在游戏服务器代码中实现, 服务调用它来与服务器进程通信。
-
服务器进程正在侦听的端口号。
-
您希望 捕获和存储的任何游戏会话特定文件的路径。
必需:是
-
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
此示例演示了 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()
通知 服务,服务器进程已准备好托管游戏会话。在服务器进程准备好托管游戏会话后,应调用此方法。该方法的参数用于指定 在特定环境下应调用的回调函数的名称。游戏服务器代码必须执行这些函数。
此调用为异步操作。要进行同步调用,请使用 ProcessReady()。有关更多信息,请参阅 初始化服务器进程。
语法
GenericOutcomeCallable ProcessReadyAsync( const Aws::GameLift::Server::ProcessParameters &processParameters);
参数
- processParameters
-
ProcessParameters 对象,用于传输有关服务器进程的以下信息:
-
回调方法的名称,在游戏服务器代码中实现, 服务调用它来与服务器进程通信。
-
服务器进程正在侦听的端口号。
-
您希望 捕获和存储的任何游戏会话特定文件的路径。
必需:是
-
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
// 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; }
RemovePlayerSession()
通知 服务,具有所指定玩家会话 ID 的玩家已从服务器进程断开连接。作为响应, 将玩家位置更改为可用,这使得该玩家位置可以分配给新玩家。
语法
GenericOutcome RemovePlayerSession( const std::string& playerSessionId);
参数
- PlayerSessionId
-
Amazon GameLift 服务为响应调用软件开发工具包 Amazon GameLift API 操作 createPlayerSessi AWS on 而颁发的唯一身份证。连接到服务器进程时,游戏客户端会引用此 ID。
类型:std:: string
必需:是
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
Aws::GameLift::GenericOutcome disconnectOutcome = Aws::GameLift::Server::RemovePlayerSession(playerSessionId);
StartMatchBackfill()
发送请求以为使用 创建的游戏会话中的开放位置查找新玩家。另请参阅 AWS 软件开发工具包操作 AWSStartMatchBackfill()。通过此操作,托管游戏会话的游戏服务器进程可以发出匹配回填请求。在中了解有关 FlexMatch 回填功能的更多信息。
此操作为异步操作。如果成功匹配了新玩家,则 服务会使用回调函数 提供更新的对战构建器数据。
服务器进程每次只能具有一个活动的匹配回填请求。要发送新请求,请先调用 StopMatchBackfill() 以取消原始请求。
语法
StartMatchBackfillOutcome StartMatchBackfill ( const Aws::GameLift::Server::Model::StartMatchBackfillRequest &startBackfillRequest);
参数
- StartMatchBackfillRequest
-
一个 StartMatchBackfillRequest 对象,用于传递以下信息:
-
要分配给回填请求的票证 ID。此信息是可选的;如果未提供任何 ID,则 将自动生成一个 ID。
-
要将请求发送到的对战构建器。需要完整的配置 ARN。可从游戏会话的对战构建器数据中获得此值。
-
正在进行回填的游戏会话的 ID。
-
游戏会话的当前玩家的可用对战数据。
必需:是
-
返回值
返回带有对战回填票证的 StartMatchBackfillOutcome 对象或包含错误消息的失败。使用 AWS 软件开发工具包操作 AWSDescribeMatchmaking() 可跟踪票证状态。
示例
// Build a backfill request std::vector<Player> 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() 创建的活动对战回填请求。另请参阅 AWS 软件开发工具包操作 AWSStopMatchmaking()。在中了解有关 FlexMatch 回填功能的更多信息。
语法
GenericOutcome StopMatchBackfill ( const Aws::GameLift::Server::Model::StopMatchBackfillRequest &stopBackfillRequest);
参数
- StopMatchBackfillRequest
-
一个 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()后调用。
通知 Amazon GameLift 服务服务器进程已结束当前游戏会话。当服务器进程保持活动状态并准备托管新游戏会话时,将调用此操作。只有在游戏会话终止程序完成后才应调用它,因为它会向 Amazon GameLift 发出信号,表明服务器进程可以立即用于托管新的游戏会话。
如果服务器进程将在游戏会话停止后关闭,则不会调用此操作。取而代之的是,调用ProcessEnding()表示游戏会话和服务器进程都将结束。
语法
GenericOutcome TerminateGameSession();
参数
此操作没有参数。
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
UpdatePlayerSessionCreationPolicy()
更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。另请参阅 AWS 软件开发工具包操作 AWSUpdateGameSession()。
语法
GenericOutcome UpdatePlayerSessionCreationPolicy( Aws::GameLift::Model::PlayerSessionCreationPolicy newPlayerSessionPolicy);
参数
- newPlayerSessionPolicy
-
用于指示游戏会话是否接受新玩家的字符串值。
类型: Aws::GameLift::Model::PlayerSessionCreationPolicy 枚举。有效值包括:
-
ACCEPT_ALL - 接受所有新玩家会话。
-
DENY_ALL - 拒绝所有新玩家会话。
必需:是
-
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
此示例将当前游戏会话的接入策略设为接受所有玩家。
Aws::GameLift::GenericOutcome outcome = Aws::GameLift::Server::UpdatePlayerSessionCreationPolicy(Aws::GameLift::Model::PlayerSessionCreationPolicy::ACCEPT_ALL);
Destroy
在游戏服务器初始化期间清理 initSDK () 分配的内存。在结束游戏服务器进程后使用此方法,以避免浪费服务器内存。
语法
GenericOutcome Aws::GameLift::Server::Destroy();
参数
没有参数。
返回值
返回由成功或失败组成的通用结果,并显示错误消息。
示例
此示例在游戏服务器进程结束后清理 InitSDK 分配的内存。
if (Aws::GameLift::Server::ProcessEnding().IsSuccess()) { Aws::GameLift::Server::Destroy(); exit(0); }