适用于 Amazon GameLift Servers 的 Go 服务器 SDK – 操作

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

GameLiftServerAPI.go定义了 Go 服务器软件开发工具包 操作。

适用于 Amazon GameLift Servers 的 Go 服务器 SDK – 数据类型

GetSdkVersion()

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

语法

func GetSdkVersion() (string, error)

返回值

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

示例

version, err := server.GetSdkVersion()

InitMetrics()

初始化 Amazon GameLift Servers SDK 的指标收集。此方法设置指标报告，有助于监控服务器性能和运行状况。请在 InitSDK() 之后、ProcessReady() 之前调用此方法。

语法

func InitMetrics() error
func InitMetrics(metricsParameters MetricsParameters) error

Parameters

返回值

如果成功，则返回 nil 错误，表示指标收集已成功初始化。

示例

使用默认配置初始化指标：

err := server.InitMetrics()

使用自定义配置初始化指标：

metricsParams := MetricsParameters{
    StatsdHost:        "localhost",
    StatsdPort:        8125,
    CrashReporterHost: "localhost",
    CrashReporterPort: 9125,
    FlushIntervalMs:   5000,
    MaxPacketSize:     1024,
}

err := server.InitMetrics(metricsParams)

InitMetricsFromEnvironment()

使用环境变量中的配置初始化 Amazon GameLift Servers SDK 的指标收集。此方法使用从运行时环境中派生的默认设置来设置指标报告。

请在 InitSDK() 之后、ProcessReady() 之前调用此方法。

语法

func InitMetricsFromEnvironment() error

返回值

如果成功，则返回 nil 错误，表示已使用环境配置成功初始化指标收集。

示例

err := server.InitMetricsFromEnvironment()

InitSDK()

初始化 Amazon GameLift Servers 开发工具包。在与 Amazon GameLift Servers 相关的任何其他初始化发生之前，在启动时调用此方法。此方法在服务器和 Amazon GameLift Servers 服务之间设置通信。

语法

func InitSDK(params ServerParameters) error 

Parameters

返回值

如果成功，则返回nil错误，表示服务器进程已准备好调用ProcessReady()。

示例

Amazon GameLift Servers Anywhere 示例

//Define the server parameters
serverParameters := ServerParameters {
  WebSocketURL: "wss://us-west-1.api.amazongamelift.com",
  ProcessID: "PID1234",
  HostID: "HardwareAnywhere",
  FleetID: "aarn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa",
  AuthToken: "1111aaaa-22bb-33cc-44dd-5555eeee66ff"
}

//Call InitSDK to establish a local connection with the Amazon GameLift Servers Agent to enable further communication.
err := server.InitSDK(serverParameters)

Amazon GameLift Servers 托管式 EC2 示例

//Define the server parameters
serverParameters := ServerParameters {}

//Call InitSDK to establish a local connection with the Amazon GameLift Servers Agent to enable further communication.
err := server.InitSDK(serverParameters)

ProcessReady()

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

语法

func ProcessReady(param ProcessParameters) error

Parameters

返回值

如果方法失败，则返回带有错误消息的错误。如果刷新成功，则返回 nil。

示例

此示例说明 ProcessReady() 调用和委派函数实施。

// Define the process parameters
processParams := ProcessParameters {
  OnStartGameSession: gameProcess.OnStartGameSession,
  OnUpdateGameSession: gameProcess.OnGameSessionUpdate,
  OnProcessTerminate: gameProcess.OnProcessTerminate,
  OnHealthCheck: gameProcess.OnHealthCheck,
  Port: port,
  LogParameters: LogParameters {    // logging and error example
    []string {"C:\\game\\logs", "C:\\game\\error"}
  }
}

err := server.ProcessReady(processParams)

ProcessEnding()

通知 Amazon GameLift Servers，该服务器进程即将终止。请在已完成所有其他清理任务（包括关闭活动游戏会话）但尚未终止进程时调用此方法。根据的结果ProcessEnding()，进程以成功 (0) 或错误 (-1) 退出并生成队列事件。如果进程因错误而终止，则生成的实例集事件为 SERVER_PROCESS_TERMINATED_UNHEALTHY。

语法

func ProcessEnding() error

返回值

返回 0 错误代码或定义的错误代码。

示例

// operations to end game sessions and the server process
defer func() {
  err := server.ProcessEnding()
  server.Destroy()
  if err != nil {
    fmt.Println("ProcessEnding() failed. Error: ", err)
    os.Exit(-1)
  } else {
    os.Exit(0)
  }
}

ActivateGameSession()

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

语法

func ActivateGameSession() error

返回值

如果方法失败，则返回带有错误消息的错误。

示例

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

func OnStartGameSession(GameSession gameSession) {
  // game-specific tasks when starting a new game session, such as loading map   
  // Activate when ready to receive players   
  err := server.ActivateGameSession();
}

UpdatePlayerSessionCreationPolicy()

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

语法

func UpdatePlayerSessionCreationPolicy(policy model.PlayerSessionCreationPolicy) error

Parameters

返回值

如果发生故障，则返回带有错误消息的错误。

示例

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

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

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

语法

func GetGameSessionID() (string, error)

Parameters

此操作没有参数。

返回值

如果成功，以 对象返回游戏会话 ID。对于尚未通过游戏会话激活的空闲进程，该调用会返回一个空字符串和nil错误。

示例

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到来自 Amazon GameLift Servers 的 onProcessTerminate() 回调后执行此操作。Amazon GameLift Servers 会出于以下原因调用 onProcessTerminate()：

语法

func GetTerminationTime() (int64, error)

返回值

如果成功，则返回服务器进程计划关闭和nil错误终止的时间戳（以纪元秒为单位）。该值是终止时间，以经过的刻度表示。0001 00:00:00例如，日期时间值等2020-09-13 12:26:40 -000Z于637355968000000000刻度。如果没有可用的终止时间，将返回一条错误消息。

示例

terminationTime, err := server.GetTerminationTime()

AcceptPlayerSession()

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

语法

func AcceptPlayerSession(playerSessionID string) error

Parameters

返回值

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

示例

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

func ReceiveConnectingPlayerSessionID(conn Connection, playerSessionID string) {
    err := server.AcceptPlayerSession(playerSessionID)
    if err != nil {
        connection.Accept()
    } else {
        connection.Reject(err.Error())
    }
}

RemovePlayerSession()

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

语法

func RemovePlayerSession(playerSessionID string) error

Parameters

返回值

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

示例

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

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

语法

func DescribePlayerSessions(req request.DescribePlayerSessionsRequest) (result.DescribePlayerSessionsResult, error) {
	return srv.describePlayerSessions(&req)
}

Parameters

返回值

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

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过省略 NextToken 和将 Limit 值设置为 10，Amazon GameLift Servers 会返回与请求匹配的前 10 个玩家会话记录。

// create request
describePlayerSessionsRequest := request.NewDescribePlayerSessions() 
describePlayerSessionsRequest.GameSessionID, _ = server.GetGameSessionID() // get ID for the current game session
describePlayerSessionsRequest.Limit = 10                                 // return the first 10 player sessions
describePlayerSessionsRequest.PlayerSessionStatusFilter = "ACTIVE"         // Get all player sessions actively connected to the game session

describePlayerSessionsResult, err := server.DescribePlayerSessions(describePlayerSessionsRequest)

StartMatchBackfill()

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

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

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

语法

func StartMatchBackfill(req request.StartMatchBackfillRequest) (result.StartMatchBackfillResult, error)

Parameters

返回值

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

示例

// form the request
startBackfillRequest := request.NewStartMatchBackfill()
startBackfillRequest.RequestID = "1111aaaa-22bb-33cc-44dd-5555eeee66ff"          // optional
startBackfillRequest.MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig"
var matchMaker model.MatchmakerData
if err := matchMaker.UnmarshalJSON([]byte(gameSession.MatchmakerData)); err != nil {    
    return
}
startBackfillRequest.Players = matchMaker.Players
res, err := server.StartMatchBackfill(startBackfillRequest)

// Implement callback function for backfill
func OnUpdateGameSession(myGameSession model.GameSession) {
    // game-specific tasks to prepare for the newly matched players and update matchmaker data as needed
}

StopMatchBackfill()

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

语法

func StopMatchBackfill(req request.StopMatchBackfillRequest) error

Parameters

返回值

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

示例

stopBackfillRequest := request.NewStopMatchBackfill()  // Use this function to create request
stopBackfillRequest.TicketID = "1111aaaa-22bb-33cc-44dd-5555eeee66ff"
stopBackfillRequest.MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig"
                
//error
err := server.StopMatchBackfill(stopBackfillRequest)            

GetComputeCertificate()

检索用于加密游戏服务器和游戏客户端之间网络连接的 TLS 证书的路径。当您将计算设备注册到 Amazon GameLift Servers Anywhere 实例集时，您可以使用该证书路径。有关更多信息，请参阅注册计算。

语法

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

返回值

返回包含以下内容的GetComputeCertificateResult对象：

示例

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

获取实例集角色凭证 ()

检索您创建的服务角色凭证，用于将其他 AWS 服务的权限扩展到 Amazon GameLift Servers。这些凭据允许您的游戏服务器使用您的AWS资源。有关更多信息，请参阅 为 Amazon GameLift Servers 设置 IAM 服务角色。

语法

func GetFleetRoleCredentials(
  req request.GetFleetRoleCredentialsRequest,
) (result.GetFleetRoleCredentialsResult, error) {
  return srv.getFleetRoleCredentials(&req)
}

Parameters

返回值

返回包含以下内容的GetFleetRoleCredentialsResult对象：

示例

// form the customer credentials request
getFleetRoleCredentialsRequest := request.NewGetFleetRoleCredentials()
getFleetRoleCredentialsRequest.RoleArn = "arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction"

credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

Destroy

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

语法

func Destroy() error {
	return srv.destroy()
}

返回值

如果方法失败，则返回带有错误消息的错误。

示例

// operations to end game sessions and the server process
defer func() {
  err := server.ProcessEnding()
  server.Destroy()
  if err != nil {
    fmt.Println("ProcessEnding() failed. Error: ", err)
    os.Exit(-1)
  } else {
    os.Exit(0)
  }
}