本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
适用于 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 用于存储供以后访问的游戏服务器日志文件的目录路径列表。服务器进程在每个游戏会话期间生成这些文件。文件路径和名称在游戏服务器中定义并存储在根游戏构建目录中。 日志路径必须是绝对的。例如,如果您的游戏构建在类似于 类型: 必需:否 |
MetricsParameters
使用此数据类型配置游戏服务器的指标收集和崩溃报告功能。游戏服务器通过 InitMetrics() 调用将 MetricsParameters 传达给 Amazon GameLift Servers。
|
属性 |
描述 |
| StatsdHost |
用于指标收集的 StatsD 服务器的主机名或 IP 地址。 类型: 必需:否 |
| StatsdPort |
用于收集指标的 StatsD 服务器的端口号。 类型: 必需:否 |
| CrashReporterHost |
崩溃报告服务器的主机名或 IP 地址。 类型: 必需:否 |
| CrashReporterPort |
崩溃报告服务器的端口号。 类型: 必需:否 |
| FlushIntervalMs |
将指标数据刷新到服务器的时间间隔(以毫秒为单位)。 类型: 必需:否 |
| MaxPacketSize |
发送到服务器的指标数据包的最大大小(以字节为单位)。 类型: 必需:否 |
ProcessParameters
此数据类型包含一组在 ProcessReady() 中发送到 Amazon GameLift Servers 的参数。
|
属性 |
描述 |
| LogParameters | 一个对象,其中包含游戏会话期间生成的文件的目录路径。Amazon GameLift Servers 会复制并存储这些文件,以便将来访问。 类型: 必需:否 |
| OnHealthCheck | Amazon GameLift Servers 为向服务器进程请求运行状况报告而调用的回调函数。Amazon GameLift Servers 每隔 60 秒调用此函数一次,并等待 60 秒以获取响应。TRUE如果运行状况良好,则服务器进程会返回,FALSE如果不健康,则返回。如果没有返回任何响应,Amazon GameLift Servers 会将服务器进程记录为运行状况不佳。类型: 必需:否 |
| OnProcessTerminate | Amazon GameLift Servers 为强制关闭服务器进程而调用的回调函数。调用此函数之后,Amazon GameLift Servers 会等待 5 分钟,以确保服务器进程关闭并通过 ProcessEnding() 调用作出响应,随后才会终止该服务器进程。 类型: 是否必需:是 |
| OnStartGameSession | 调Amazon GameLift Servers用以激活新游戏会话的回调函数。 Amazon GameLift Servers应客户端请求调用此函数CreateGameSession。回调函数将传递一个 GameSession 对象。 类型: 是否必需:是 |
| OnUpdateGameSession | Amazon GameLift Servers 为向服务器进程传递更新的游戏会话对象而调用的回调函数。当对战回填请求处理完毕时,Amazon GameLift Servers 会调用此函数以提供更新的对战构建器数据。它将传递一个 GameSession 对象、一个状态更新(updateReason)以及对战回填票证 ID。类型: 必需:否 |
| 端口: | 服务器进程用于侦听新玩家连接的端口号。该值必须在部署此游戏服务器构建的任意实例集上所配置的端口范围内。此端口号包含在游戏会话和玩家会话对象中,游戏会话在连接到服务器进程时会使用该端口号。 类型: 是否必需:是 |
UpdateGameSession
此数据类型更新为游戏会话对象,其中包括更新游戏会话的原因以及相关的回填票证 ID(如果使用回填来填充游戏会话中的玩家会话)。
| Properties | 描述 |
|---|---|
| GameSession | 一个 GameSession 对象。该GameSession对象包含描述游戏会话的属性。类型: 是否必需:是 |
| UpdateReason | 更新游戏会话的原因。 类型: 是否必需:是 |
| BackfillTicketId | 尝试更新游戏会话的回填票证的 ID。 类型: 必需:否 |
GameSession
此数据类型提供游戏会话的详细信息。
| Properties | 描述 |
|---|---|
| GameSessionId |
会话的唯一标识符。游戏会话ARN具有以下格式:. 类型: 必需:否 |
| Name |
游戏会话的描述性标签。 类型: 必需:否 |
| FleetId |
运行游戏会话的集的唯一标识符。 类型: 必需:否 |
| MaximumPlayerSessionCount |
机群中已连接到游戏会话的玩家数量。 类型: 必需:否 |
| 端口: |
游戏会话的端口号。要连接到 Amazon GameLift Servers 游戏服务器,应用程序需要 IP 地址和端口号。 类型: 必需:否 |
| IpAddress |
游戏会话的 IP 地址。要连接到 Amazon GameLift Servers 游戏服务器,应用程序需要 IP 地址和端口号。 类型: 必需:否 |
| GameSessionData |
一组自定义游戏会话属性,采用单个字符串值格式。 类型: 必需:否 |
| MatchmakerData |
有关用于创建游戏会话的对战过程的信息,采用 JSON 语法,格式为字符串。除了使用的对战配置外,它还包含分配到对战的所有玩家的数据,包括玩家属性和队伍分配。 类型: 必需:否 |
| GameProperties |
游戏会话的一组自定义属性,采用键值对格式。这些属性将通过启动新游戏会话的请求传递到游戏服务器进程。 类型: 必需:否 |
| DnsName |
分配给正在运行游戏会话的实例的 DNS 标识符。CRL 采用以下格式:
连接到在支持 TLS 的队列上运行的游戏会话时,必须使用 DNS 名称,而不是 IP 地址。 类型: 必需:否 |
ServerParameters
游戏服务器进程用来与 Amazon GameLift Servers 服务建立连接的信息。仅当游戏服务器生成包将在没有 Amazon GameLift Servers 代理的情况下部署到 Anywhere 实例集或容器实例集时,才需在调用 InitSDK() 时包含这些参数。对于所有其他部署场景,请调用 InitSDK() 而不使用参数。
| Properties | 描述 |
|---|---|
| webSocketUrl |
当您为 Amazon GameLift Servers Anywhere 计算资源调用 类型: 是否必需:是 |
| ProcessID |
注册到托管游戏的服务器进程的唯一标识符。 类型: 是否必需:是 |
| hostId | HostID是在您注册计算机时ComputeName使用的。有关更多信息,请参阅RegisterCompute。类型: 是否必需:是 |
| FleetId | 计算注册到的实例集的唯一标识符。有关更多信息,请参阅RegisterCompute。 类型: 是否必需:是 |
| AuthToken | 由 Amazon GameLift Servers 生成的身份验证令牌,用于向 Amazon GameLift Servers 对您的服务器进行身份验证。有关更多信息,请参阅GetComputeAuthToken。 类型: 是否必需:是 |
StartMatchBackfillRequest
用于创建对战回填请求的信息。游戏服务器通过调用 StartMatchBackfill() 将这些信息传达给 Amazon GameLift Servers。
| Properties | 描述 |
|---|---|
| GameSessionArn |
游戏会话的唯一标识符。此 API 操作 类型: 是否必需:是 |
| MatchmakingConfigurationArn |
采用 ARN 格式的唯一标识符,适用于用于此请求的对战构建器。要查找用于创建原始游戏会话的对战构建器,请查看对战构建器数据属性中的游戏会话对象。在使用对战构建器数据中了解有关对战构建器数据的更多信息。 类型: 是否必需:是 |
| 玩家 |
一组表示当前正在游戏会话中的所有玩家的数据。对战构建器使用此信息搜索与当前玩家非常匹配的新玩家。 类型: 是否必需:是 |
| TicketId |
对战或匹配回填请求票证的唯一标识符。如果不提供值,Amazon GameLift Servers 会生成值。使用此标识符可跟踪对战回填票证状态或取消请求(如需要)。 类型: 必需:否 |
玩家
此数据类型代表对战中的玩家。启动对战请求时,玩家会有玩家 ID、属性数据以及可能的延迟数据。对战结束后,Amazon GameLift Servers 会添加团队信息。
| Properties | 描述 |
|---|---|
| LatencyInMS |
一组以毫秒为单位的值,表示玩家在连接到某个位置时所经历的延迟量。 如果使用此属性,则仅匹配列出的位置的玩家。如果对战构建器具有评估玩家延迟的规则,玩家必须报告延迟才能进行匹配。 类型: 必需:否 |
| PlayerAttributes |
键/值对的集合,其中包含用于对战的玩家信息。玩家属性键必须与配对规则集中 PlayerAttributes 使用的密钥相匹配。 有关玩家属性的更多信息,请参阅AttributeValue。 类型: 必需:否 |
| PlayerId |
玩家的唯一标识符。 类型: 必需:否 |
| Team |
玩家在对战中被分配到的团队的名称。在对战规则集中定义团队名称。 类型: 必需:否 |
DescribePlayerSessionsRequest
一个对象,用于指定要检索哪些玩家会话。服务器进程通过向 Amazon GameLift Servers 调用 DescribePlayerSessions() 来提供此信息。
| Properties | 描述 |
|---|---|
| GameSessionId |
游戏会话的唯一标识符。使用此参数可请求指定游戏会话的所有玩家会话。 游戏会话 ID 的格式为 类型: 必需:否 |
| PlayerSessionId |
玩家会话的唯一标识符。使用此参数请求单个特定的玩家会话。 类型: 必需:否 |
| PlayerId |
玩家的唯一标识符。使用此参数可请求指定游戏会话的所有玩家会话。请参阅生成玩家 ID。 类型: 必需:否 |
| PlayerSessionStatusFilter |
用于筛选结果的玩家会话状态。可能的玩家会话状态包括以下内容:
类型: 必需:否 |
| NextToken |
令牌指示结果的下一个连续页面的开头。要指定结果集的开始,请不要指定值。如果指定玩家会话 ID,将忽略此参数。 类型: 必需:否 |
| 限制 |
要返回的最大结果数量。如果指定玩家会话 ID,将忽略此参数。 类型: 必需:否 |
StopMatchBackfillRequest
用于取消对战回填请求的信息。游戏服务器通过调用 StopMatchBackfill() 将此信息传达给 Amazon GameLift Servers 服务。
| Properties | 描述 |
|---|---|
| GameSessionArn |
与被取消的请求关联的唯一游戏会话标识符。 类型: 必需:否 |
| MatchmakingConfigurationArn |
此请求发送到的对战构建器的唯一标识符。 类型: 必需:否 |
| TicketId |
要取消的回填请求票证的唯一标识符。 类型: 必需:否 |
AttributeValue
在玩家属性密钥-值对中使用。此对象允许您使用任何有效的数据类型来指定属性值:字符串、数字、字符串数组或数据映射。每个AttributeValue对象必须只使用一个可用属性:S、NSL、或SDM。
| Properties | 说明 |
|---|---|
| AttrType |
指定属性值的类型。可能的属性值类型包括:
必需:否 |
| S |
表示字符串属性值。 类型: 必需:否 |
| N |
表示属性值。 类型: 必需:否 |
| sl |
表示字符串属性值的数组。 类型: 必需:否 |
| SDM |
表示字符串键和双精度值的字典。 类型: 必需:否 |
GetFleetRoleCredentialsRequest
这种数据类型使游戏服务器只能有限地访问您的其他 AWS 资源。有关更多信息,请参阅为 Amazon GameLift Servers 设置 IAM 服务角色。
| Properties | 描述 |
|---|---|
| RoleArn | 服务角色的 Amazon 资源名称 (ARN),用于扩展对您的 AWS 资源的有限访问权限。 类型: 必需:否 |
| RoleSessionName | 可用于唯一标识会话的角色会 AWS Security Token Service AssumeRole话名称。此名称会显示在审计日志中,例如中的日志 CloudTrail。 类型: 必需:否 |
AwsLongOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 类型: 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
AwsStringOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 类型: 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
DescribePlayerSessionsOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 类型:DescribePlayerSessionsResult 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
DescribePlayerSessionsResult
一组对象,其中包含与请求相匹配的每个玩家会话的属性。
| Properties | 说明 |
|---|---|
| NextToken |
令牌指示结果的下一个连续页面的开头。使用之前的调用返回此操作的令牌。要指定结果集的开始,请不要指定值。如果指定玩家会话 ID,将忽略此参数。 类型: 是否必需:是 |
| PlayerSessions |
类型: 必填 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
GenericOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
GenericOutcomeCallable
这种数据类型是一种异步的通用结果。它具有以下属性:
| Properties | 说明 |
|---|---|
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
PlayerSession
此数据类型表示 Amazon GameLift Servers 传递给游戏服务器的玩家会话。有关更多信息,请参阅 PlayerSession。
| Properties | 说明 |
|---|---|
| CreationTime |
类型: 必需:否 |
| FleetId |
类型: 必需:否 |
| GameSessionId |
类型: 必需:否 |
| IpAddress |
类型: 必需:否 |
| PlayerData |
类型: 必需:否 |
| PlayerId |
类型: 必需:否 |
| PlayerSessionId |
类型: 必需:否 |
| 端口: |
类型: 必需:否 |
| Status |
用于筛选结果的玩家会话状态。如果提供 PlayerId 了 o PlayerSessionId r,则 PlayerSessionStatusFilter 对响应没有影响。 类型:
必需:否 |
| TerminationTime |
类型: 必需:否 |
| DnsName |
类型: 必需:否 |
StartMatchBackfillOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
StartMatchBackfillResult
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| TicketId |
对战配置的唯一标识符。如果此处未指定任何票证 ID,则 Amazon GameLift Servers 将生成一个采用 UUID 形式的 ID。使用此标识符跟踪对战回填单状态并检索匹配结果。 类型: 必需:否 |
GetComputeCertificateOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 类型:GetComputeCertificateResult 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
GetComputeCertificateResult
计算机上 TLS 证书的路径和计算机的主机名。
| Properties | 说明 |
|---|---|
| CertificatePath |
计算资源上 TLS 证书的路径。使用 Amazon GameLift Servers 托管式实例集时,此路径包含:
类型: 必需:否 |
| ComputeName |
您的计算资源的名称。 类型: 必需:否 |
GetFleetRoleCredentialsOutcome
此数据类型由操作生成,并生成具有以下属性的对象:
| Properties | 说明 |
|---|---|
| 结果 |
操作的结果。 类型:GetFleetRoleCredentialsResult 必需:否 |
| ResultWithOwnership |
操作的结果,转换为右值,以便调用代码可以拥有该对象的所有权。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
GetFleetRoleCredentialsResult
| Properties | 说明 |
|---|---|
| AccessKeyId |
用于对您的 AWS 资源进行身份验证和提供访问权限的访问密钥 ID。 类型: 必需:否 |
| AssumedRoleId |
服务角色所属的用户 ID。 类型: 必需:否 |
| AssumedRoleUserArn |
用户应承担的角色的 Amazon 资源名称 (ARN)。 类型: 必需:否 |
| 过期 |
您的会话凭证到期之前的时间。 类型: 必需:否 |
| SecretAccessKey |
指定 S3 验证的访问密钥 ID。 类型: 必需:否 |
| SessionToken |
用于识别与您的 AWS 资源交互的当前活动会话的令牌。 类型: 必需:否 |
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
初始化 SDKOutcome
注意
InitSDKOutcome仅在使用std标志构建软件开发工具包 时才会返回。如果您使用nostd标志进行构建,则会改GenericOutcome为返回。
| Properties | 说明 |
|---|---|
| 成功 |
操作是否成功。 类型: 是否必需:是 |
| 错误 |
操作失败时发生的错误。 必需:否 |
GameLiftError
| Properties | 说明 |
|---|---|
| ErrorType |
错误的类型。 类型: 必需:否 |
ErrorName |
错误类型的名称。 类型: 必需:否 |
ErrorMessage |
错误消息。 类型: 必需:否 |
枚举
为适用于 Amazon GameLift Servers(C++)的服务器 SDK 定义了以下枚举类型:
- GameLiftErrorType
-
表示错误类型的字符串值。有效值包括:
-
错误的请求_异常
-
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_AC TIVE — 服务器进程尚未处于活动状态,未绑定到 GameSession,也无法接受或处理。 PlayerSessions
-
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 – 游戏会话未设置为接受或拒绝新玩家会话。
-