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

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

使用 Amazon GameLift Servers C++ 服务器 SDK 5.x 参考,将要托管的多人游戏与 Amazon GameLift Servers 集成。有关集成过程的指南,请参阅借助服务器 SDK 将 Amazon GameLift Servers 添加到游戏服务器

注意

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

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

LogParameters

一个对象,用于标识游戏会话期间生成的文件,您希望 Amazon GameLift Servers 在游戏会话结束后上传和存储这些文件。游戏服务器在 ProcessReady() 调用中,作为 ProcessParameters 对象的一部分向 Amazon GameLift Servers 提供 LogParameters

属性

描述
LogPaths

您希望 Amazon GameLift Servers 用于存储供以后访问的游戏服务器日志文件的目录路径列表。服务器进程在每个游戏会话期间生成这些文件。文件路径和名称在游戏服务器中定义并存储在根游戏构建目录中。

日志路径必须是绝对的。例如,如果您的游戏构建在类似于 MyGame\sessionLogs\ 的路径中存储游戏会话日志,则日志路径将为 (在 Windows 实例上) 或 (在 Linux 实例上)。

类型:std:vector<std::string>

必需:否

MetricsParameters

使用此数据类型配置游戏服务器的指标收集和崩溃报告功能。游戏服务器通过 InitMetrics() 调用将 MetricsParameters 传达给 Amazon GameLift Servers。

属性

描述
StatsdHost

用于指标收集的 StatsD 服务器的主机名或 IP 地址。

类型:std::string

必需:否

StatsdPort

用于收集指标的 StatsD 服务器的端口号。

类型:int

必需:否

CrashReporterHost

崩溃报告服务器的主机名或 IP 地址。

类型:std::string

必需:否

CrashReporterPort

崩溃报告服务器的端口号。

类型:int

必需:否

FlushIntervalMs

将指标数据刷新到服务器的时间间隔(以毫秒为单位)。

类型:int

必需:否

MaxPacketSize

发送到服务器的指标数据包的最大大小(以字节为单位)。

类型:int

必需:否

ProcessParameters

此数据类型包含一组在 ProcessReady() 中发送到 Amazon GameLift Servers 的参数。

属性

描述
LogParameters 一个对象,其中包含游戏会话期间生成的文件的目录路径。Amazon GameLift Servers 会复制并存储这些文件,以便将来访问。

类型:Aws::GameLift::Server::LogParameters

必需:否

onHealthCheck Amazon GameLift Servers 为向服务器进程请求运行状况报告而调用的回调函数。Amazon GameLift Servers 每隔 60 秒调用此函数一次,并等待 60 秒以获取响应。TRUE如果运行状况良好,则服务器进程会返回,FALSE如果不健康,则返回。如果没有返回任何响应,Amazon GameLift Servers 会将服务器进程记录为运行状况不佳。

类型:std::function<bool()> onHealthCheck

必需:否

onProcessTerminate Amazon GameLift Servers 为强制关闭服务器进程而调用的回调函数。调用此函数之后,Amazon GameLift Servers 会等待 5 分钟,以确保服务器进程关闭并通过 ProcessEnding() 调用作出响应,随后才会终止该服务器进程。

类型:std::function<void()> onProcessTerminate

必需:是

onStartGameSession Amazon GameLift Servers 为激活新游戏会话而调用的回调函数。Amazon GameLift Servers 调用此函数以响应客户端请求 CreateGameSession。回调函数将传递一个 GameSession 对象。

类型:const std::function<void(Aws::GameLift::Model::GameSession)> onStartGameSession

必需:是

onUpdateGameSession Amazon GameLift Servers 为向服务器进程传递更新的游戏会话对象而调用的回调函数。当对战回填请求处理完毕时,Amazon GameLift Servers 会调用此函数以提供更新的对战构建器数据。它将传递一个 GameSession 对象、一个状态更新(updateReason)以及对战回填票证 ID。

类型:std::function<void(Aws::GameLift::Server::Model::UpdateGameSession)> onUpdateGameSession

必需:否

端口 服务器进程用于侦听新玩家连接的端口号。该值必须在部署此游戏服务器构建的任意实例集上所配置的端口范围内。此端口号包含在游戏会话和玩家会话对象中,游戏会话在连接到服务器进程时会使用该端口号。

类型:Integer

必需:是

UpdateGameSession

此数据类型更新为游戏会话对象,其中包括更新游戏会话的原因以及相关的回填票证 ID(如果使用回填来填充游戏会话中的玩家会话)。

属性 描述
GameSession 一个 GameSession 对象。该GameSession对象包含描述游戏会话的属性。

类型:Aws::GameLift::Server::GameSession

必需:是

更新原因 更新游戏会话的原因。

类型:Aws::GameLift::Server::UpdateReason

必需:是

backfilltTicketID 尝试更新游戏会话的回填票证的 ID。

类型:std::string

必需:否

GameSession

此数据类型提供游戏会话的详细信息。

属性 描述
GameSessionId

会话的唯一标识符。游戏会话ARN具有以下格式:. arn:aws:gamelift:<region>::gamesession/<fleet ID>/<custom ID string or idempotency token>

类型:std::string

必需:否

名称

游戏会话的描述性标签。

类型:std::string

必需:否

FleetId

运行游戏会话的集的唯一标识符。

类型:std::string

必需:否

最大玩家会话数

机群中已连接到游戏会话的玩家数量。

类型:int

必需:否

端口

游戏会话的端口号。要连接到 Amazon GameLift Servers 游戏服务器,应用程序需要 IP 地址和端口号。

类型:in

必需:否

IpAddress

游戏会话的 IP 地址。要连接到 Amazon GameLift Servers 游戏服务器,应用程序需要 IP 地址和端口号。

类型:std::string

必需:否

GameSessionData

一组自定义游戏会话属性,采用单个字符串值格式。

类型:std::string

必需:否

MatchmakerData

有关用于创建游戏会话的对战过程的信息,采用 JSON 语法,格式为字符串。除了使用的对战配置外,它还包含分配到对战的所有玩家的数据,包括玩家属性和队伍分配。

类型:std::string

必需:否

GameProperties

游戏会话的一组自定义属性,采用键值对格式。这些属性将通过启动新游戏会话的请求传递到游戏服务器进程。

类型:std :: vector < GameProperty >

必需:否

DnsName

分配给正在运行游戏会话的实例的 DNS 标识符。CRL 采用以下格式:

  • 支持 TLS 的实例集:. <unique identifier>.<region identifier>.amazongamelift.com

  • 未启用 TLS 的实例集:. ec2-<unique identifier>.compute.amazonaws.com

连接到在支持 TLS 的队列上运行的游戏会话时,必须使用 DNS 名称,而不是 IP 地址。

类型:std::string

必需:否

服务器参数

游戏服务器进程用来与 Amazon GameLift Servers 服务建立连接的信息。仅当游戏服务器生成包将在没有 Amazon GameLift Servers 代理的情况下部署到 Anywhere 实例集或容器实例集时,才需在调用 InitSDK() 时包含这些参数。对于所有其他部署场景,请调用 InitSDK() 而不使用参数。

属性 描述
WebSockeTurl

当您为 Amazon GameLift Servers Anywhere 计算资源调用 RegisterCompute 时,GameLiftServerSdkEndpoint Amazon GameLift Servers 会返回结果。

类型:std::string

必需:是

ProcessID

注册到托管游戏的服务器进程的唯一标识符。

类型:std::string

必需:是

hostId HostID是在您注册计算机时ComputeName使用的。有关更多信息,请参阅 Register Compute。

类型:std::string

必需:是

FleetId 计算注册到的实例集的唯一标识符。有关更多信息,请参阅 Register Compute。

类型:std::string

必需:是

AuthToken 由 Amazon GameLift Servers 生成的身份验证令牌,用于向 Amazon GameLift Servers 对您的服务器进行身份验证。有关更多信息,请参阅 getComputeaut hToken。

类型:std::string

必需:是

StartMatchBackfillRequest

用于创建对战回填请求的信息。游戏服务器通过调用 StartMatchBackfill() 将这些信息传达给 Amazon GameLift Servers。

属性 描述
GameSessionArn

游戏会话的唯一标识符。此 API 操作 GetGameSessionId 返回采用 ARN 格式的标识符。

类型:std::string

必需:是

MatchmakingConfigurationArn

采用 ARN 格式的唯一标识符,适用于用于此请求的对战构建器。要查找用于创建原始游戏会话的对战构建器,请查看对战构建器数据属性中的游戏会话对象。在使用对战构建器数据中了解有关对战构建器数据的更多信息。

类型:std::string

必需:是

玩家

一组表示当前正在游戏会话中的所有玩家的数据。对战构建器使用此信息搜索与当前玩家非常匹配的新玩家。

类型:std::vector<Player>

必需:是

TicketId

对战或匹配回填请求票证的唯一标识符。如果不提供值,Amazon GameLift Servers 会生成值。使用此标识符可跟踪对战回填票证状态或取消请求(如需要)。

类型:std::string

必需:否

玩家

此数据类型代表对战中的玩家。启动对战请求时,玩家会有玩家 ID、属性数据以及可能的延迟数据。对战结束后,Amazon GameLift Servers 会添加团队信息。

属性 描述
Latencyinms

一组以毫秒为单位的值,表示玩家在连接到某个位置时所经历的延迟量。

如果使用此属性,则仅匹配列出的位置的玩家。如果对战构建器具有评估玩家延迟的规则,玩家必须报告延迟才能进行匹配。

类型:Dictionary<string,int>

必需:否

玩家属性

键/值对的集合,其中包含用于对战的玩家信息。玩家属性键必须与对战规则集中使用的玩家属性相匹配。

有关玩家属性的更多信息,请参阅 Atri buteValue

类型:std::map<std::string,AttributeValue>

必需:否

PlayerId

玩家的唯一标识符。

类型:std::string

必需:否

Team

玩家在对战中被分配到的团队的名称。在对战规则集中定义团队名称。

类型:std::string

必需:否

DescribePlayerSessionsRequest

一个对象,用于指定要检索哪些玩家会话。服务器进程通过向 Amazon GameLift Servers 调用 DescribePlayerSessions() 来提供此信息。

属性 描述
GameSessionId

游戏会话的唯一标识符。使用此参数可请求指定游戏会话的所有玩家会话。

游戏会话 ID 的格式为arn:aws:gamelift:<region>::gamesession/fleet-<fleet ID>/<ID string>GameSessionID是自定义 ID 字符串或

类型:std::string

必需:否

PlayerSessionId

玩家会话的唯一标识符。使用此参数请求单个特定的玩家会话。

类型:std::string

必需:否

PlayerId

玩家的唯一标识符。使用此参数可请求指定游戏会话的所有玩家会话。请参阅生成玩家 ID

类型:std::string

必需:否

PlayerSessionStatusFilter

用于筛选结果的玩家会话状态。可能的玩家会话状态包括以下内容:

  • RESERVED - 已收到玩家会话请求,但玩家尚未连接到服务器进程和/或进行验证。

  • ACTIVE - 服务器进程已验证玩家,当前已连接。

  • COMPLETED - 玩家连接已断开。

  • TIMEDOUT - 收到了玩家会话请求,但玩家未连接和/或在超时限制 (60 秒) 内验证。

类型:std::string

必需:否

NextToken

令牌指示结果的下一个连续页面的开头。要指定结果集的开始,请不要指定值。如果指定玩家会话 ID,将忽略此参数。

类型:std::string

必需:否

限制

要返回的最大结果数量。如果指定玩家会话 ID,将忽略此参数。

类型:int

必需:否

StopMatchBackfillRequest

用于取消对战回填请求的信息。游戏服务器通过调用 StopMatchBackfill() 将此信息传达给 Amazon GameLift Servers 服务。

属性 描述
GameSessionArn

与被取消的请求关联的唯一游戏会话标识符。

类型:char[]

必需:否

MatchmakingConfigurationArn

此请求发送到的对战构建器的唯一标识符。

类型:char[]

必需:否

TicketId

要取消的回填请求票证的唯一标识符。

类型:char[]

必需:否

AttributeValue

玩家属性密钥-值对中使用。此对象允许您使用任何有效的数据类型来指定属性值:字符串、数字、字符串数组或数据映射。每个AttributeValue对象必须只使用一个可用属性:SNSL、或SDM

属性 描述
属性类型

指定属性值的类型。可能的属性值类型包括:

  • NONE

  • string

  • DOUBLE

  • 字符串列表

  • 字符串_DOUBLE_MAP

必需:否

S

表示字符串属性值。

类型:std::string

必需:否

N

表示属性值。

类型:double

必需:否

sl

表示字符串属性值的数组。

类型:std::vector<std::string>

必需:否

SDM

表示字符串键和双精度值的字典。

类型:std::map<std::string, double>

必需:否

获取实例集角色凭证申请

这种数据类型使游戏服务器只能有限地访问您的其他AWS资源。有关更多信息,请参阅为 Amazon GameLift Servers 设置 IAM 服务角色

属性 描述
RoleArn 可以扩展对资源的有限访问权限的服务角色的 Amazon 资源名称(ARN)。AWS

类型:std::string

必需:否

roleSessionName 可用于唯一标识 A AWS Security Token Service ssumeRol e 会话的角色会话名称。此名称会在审计日志(例如 CloudTrail 中的日志)中公开。

类型:std::string

必需:否

awsLong结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:long

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:long&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

awsString结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:std::string

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:long&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

描述玩家会话结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:描述 PlayerSessions 结果

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:Aws::GameLift::Server::Model::DescribePlayerSessionsResult&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

描述 PlayerSessions 结果

一组对象,其中包含与请求相匹配的每个玩家会话的属性。

属性 描述
NextToken

令牌指示结果的下一个连续页面的开头。使用之前的调用返回此操作的令牌。要指定结果集的开始,请不要指定值。如果指定玩家会话 ID,将忽略此参数。

类型:std::string

必需:是

玩家会话

类型:IList<PlayerSession>

必填

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:std::string&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

通用结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

GenericOutcomeCallable

这种数据类型是一种异步的通用结果。它具有以下属性:

属性 描述
成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

PlayerSession

此数据类型表示 Amazon GameLift Servers 传递给游戏服务器的玩家会话。有关更多信息,请参阅 PlayerSession

属性 描述
CreationTime

类型:long

必需:否

FleetId

类型:std::string

必需:否

GameSessionId

类型:std::string

必需:否

IpAddress

类型:std::string

必需:否

PlayerData

类型:std::string

必需:否

PlayerId

类型:std::string

必需:否

PlayerSessionId

类型:std::string

必需:否

端口

类型:int

必需:否

Status

用于筛选结果的玩家会话状态。如果提供了 PlayerSessionID 或 PlayerID,则 PlayerSessionStatusFilter 对响应没有影响。

类型:PlayerSessionStatus枚举。可能的值包括:

  • ACTIVE (处于活动状态

  • COMPLETED

  • NOT_SET

  • 预留

  • 超时

必需:否

终止时间

类型:long

必需:否

DnsName

类型:std::string

必需:否

StartMatchBackfillOutcome

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:开始匹配回填结果

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:StartMatchBackfillResult&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

开始匹配回填结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
TicketId

对战配置的唯一标识符。如果此处未指定任何票证 ID,则 Amazon GameLift Servers 将生成一个采用 UUID 形式的 ID。使用此标识符跟踪对战回填单状态并检索匹配结果。

类型:std::string

必需:否

获取计算证书结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:获取计算证书结果

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:Aws::GameLift::Server::Model::GetComputeCertificateResult&&

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

获取计算证书结果

计算机上 TLS 证书的路径和计算机的主机名。

属性 描述
证书路径

计算资源上 TLS 证书的路径。使用 Amazon GameLift Servers 托管式实例集时,此路径包含:

  • certificate.pem:最终用户证书。完整的证书链是certificateChain.pem附加到此证书的组合。

  • certificateChain.pem:包含根证书和中间证书的证书链。

  • 根证书。

  • privateKey.pem:最终用户证书的私钥。

类型:std::string

必需:否

计算名称

您的计算资源的名称。

类型:std::string

必需:否

获取实例集角色凭证结果

此数据类型由操作生成,并生成具有以下属性的对象:

属性 描述
结果

操作的结果。

类型:获取 FleeTroleCredentials 结果

必需:否

带所有权的结果

操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。

类型:Aws::GameLift::Server::Model::GetFleetRoleCredentialsResult

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

获取 FleeTroleCredentials 结果

属性 描述
AccessKeyId

用于对您的AWS资源进行身份验证和提供访问权限的访问密钥 ID。

类型:string

必需:否

假设角色ID

服务角色所属的用户 ID。

类型:string

必需:否

假设角色UserRarn

用户应承担的角色的 Amazon 资源名称 (ARN)。

类型:string

必需:否

过期

您的会话凭证到期之前的时间。

类型:DateTime

必需:否

SecretAccessKey

指定 S3 验证的访问密钥 ID。

类型:string

必需:否

SessionToken

用于识别与您的AWS资源交互的当前活动会话的令牌。

类型:string

必需:否

成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

initsdk结果

注意

InitSDKOutcome仅在使用std标志构建软件开发工具包 时才会返回。如果您使用nostd标志进行构建,则会改通用结果为返回。

属性 描述
成功

操作是否成功。

类型:bool

必需:是

错误

操作失败时发生的错误。

类型:GameLift 错误

必需:否

GameLift 错误

属性 描述
ErrorType

错误的类型。

类型:GameLiftErrorType枚举

必需:否

错误名称

错误类型的名称。

类型:std::string

必需:否

ErrorMessage

错误消息。

类型:std::string

必需:否

枚举

为适用于 Amazon GameLift Servers(C++)的服务器 SDK 定义了以下枚举类型:

GameLift 错误类型

表示错误类型的字符串值。有效值包括:

  • 错误的请求_异常

  • GAMESESSION_ID_NOT_SET – 尚未设置游戏会话 ID。

  • 内部服务异常

  • LOCAL_CONNECTION_FAILED – 与 Amazon GameLift Servers 的本地连接失败。

  • NETWORK_NOT_INITIALIZED – 网络尚未初始化

  • SERVICE_CALL_FAILED – 对服务的调用失败。AWS

  • 网络套接字连接失败

  • 禁止网络套接字连接失败

  • WEBSOCKET_CONNECT_FAILURE_INVALID_UR

  • WEBSOCKET_CONNECT_FAILURE

  • ALREADY_INITIALIZED – Amazon GameLift Servers 服务器或客户端已使用 Initialize() 进行初始化。

  • FLEET_MISMATCH – 目标实例集与 GameSession 或 PlayerSession 的实例集不匹配。

  • GAMELIFT_CLIENT_NOT_INITIALIZED – Amazon GameLift Servers 客户端尚未初始化。

  • GAMELIFT_SERVER_NOT_INITIALIZED – Amazon GameLift Servers 服务器尚未初始化。

  • GAME_SESSION_ENDED_FAILED – 适用于 Amazon GameLift Servers 的服务器 SDK 无法联系服务部门报告游戏会话已结束。

  • GAME_SESSION_NOT_READY – Amazon GameLift Servers 服务器游戏会话未激活。

  • GAME_SESSION_READY_FAILED – 适用于 Amazon GameLift Servers 的服务器 SDK 无法联系服务部门报告游戏会话已准备就绪。

  • INITI@@ ALIZATION_MISMATCH – 在 Server::In itialization () 之后调用了客户端方法,反之亦然。

  • NOT_INITIALIZED – Amazon GameLift Servers 服务器或客户端尚未使用 Initialize() 进行初始化。

  • NO_TARGET_ALIASID_SET – 尚未设置目标 AliasID。

  • NO_TARGET_FLEET_SET – 尚未设置目标实例集。

  • PROCESS_ENDING_FAILED – 适用于 Amazon GameLift Servers 的服务器 SDK 无法联系服务部门报告流程即将结束。

  • PROCESS_NOT_ACTI VE – 服务器进程尚未激活,未绑定到游戏会话,也无法接受或处理 PlayerSession。

  • PROCESS_NOT_READ Y – 服务器进程尚未准备好激活。

  • PROCESS_READY_FAILED – 适用于 Amazon GameLift Servers 的服务器 SDK 无法联系服务部门报告流程已准备就绪。

  • SDK_VERSION_DETECTION_FAILED – 软件开发工具包 版本检测失败。

  • STX_CALL_FAILED – 对 xstX 服务器后端组件的调用失败

  • STX_INITIALIZATION_FAILED – xSTX 服务器后端组件无法初始化

  • E@@ XPRENTED_PLAYER_SESSION – 服务器遇到了未注册的玩家会话

  • 网络套接字连接失败

  • 禁止网络套接字连接失败

  • WEBSOCKET_CONNECT_FAILURE_INVALID_UR

  • WEBSOCKET_CONNECT_FAILURE

  • WEBSOCKET_RETRIABLE_SEND_MESSAGE_FAILURE – 向 GameLift 服务 WebSocket 发送消息时可重试失败

  • WEBSOCKET_SEND_MESSAGE_FAILURE – 无法向 GameLift 服务 WebSocket 发送消息

  • MATCH_BACKFILL_REQUEST_VALIDATION – 请求验证失败

  • PLAYER_SESSION_REQUEST_VALIDATION – 请求验证失败

类型:PlayerSessionCreationPolicy 枚举。

用于指示游戏会话是否接受新玩家的字符串值。有效值包括:

  • ACCEPT_ALL - 接受所有新玩家会话。

  • DENY_ALL - 拒绝所有新玩家会话。

  • NOT_SET – 游戏会话未设置为接受或拒绝新玩家会话。