本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Amazon GameLift Server SDK for Go： 動作

使用 Amazon GameLift Go 伺服器 SDK 5.x 參考，整合您的多人遊戲以與 Amazon 託管 GameLift。如需整合程序的指引，請參閱 將 Amazon GameLift 新增至您的遊戲伺服器。

GameLiftServerAPI.go 定義 Go 伺服器SDK動作。

Amazon GameLift Server SDK for Go：資料類型

GetSdkVersion()

傳回伺服器程序中SDK內建 的目前版本編號。

語法

func GetSdkVersion() (string, error)

傳回值

如果成功， 會將目前SDK版本傳回為字串。傳回的字串包含版本號碼 （範例 5.0.0）。如果不成功， 會傳回錯誤訊息，例如 common.SdkVersionDetectionFailed。

範例

version, err := server.GetSdkVersion()

Init SDK（）

初始化 Amazon GameLift SDK。在與 Amazon 相關的任何其他初始化 GameLift 發生之前，請在啟動時呼叫此方法。此方法設定伺服器與 Amazon GameLift 服務之間的通訊。

語法

func InitSDK(params ServerParameters) error 

參數

傳回值

如果成功， 會傳回nil錯誤，指出伺服器程序已準備好呼叫 ProcessReady()。

範例

Amazon GameLift Anywhere example

//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 GameLift agent to enable further communication.
err := server.InitSDK(serverParameters)

Amazon GameLift 受管EC2範例

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

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

ProcessReady()

通知 Amazon GameLift 伺服器程序已準備好託管遊戲工作階段。叫用 後呼叫此方法Init SDK（）。每個程序只能呼叫此方法一次。

語法

func ProcessReady(param ProcessParameters) error

參數

傳回值

如果方法失敗，則傳回包含錯誤訊息的錯誤。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 伺服器程序正在終止。在所有其他清除任務 （包括關閉作用中的遊戲工作階段） 之後，以及在終止程序之前呼叫此方法。根據 的結果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 伺服器程序已啟用遊戲工作階段，現在已準備好接收玩家連線。在所有遊戲工作階段初始化後，此動作稱為回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

參數

傳回值

如果發生失敗，則傳回包含錯誤訊息的錯誤。

範例

此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

擷取作用中伺服器程序託管的遊戲工作階段 ID。

語法

func GetGameSessionID() (string, error)

參數

此動作沒有參數。

傳回值

如果成功， 會傳回遊戲工作階段 ID 和 nil 錯誤。對於尚未透過遊戲工作階段啟用的閒置程序，呼叫會傳回空字串和nil錯誤。

範例

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

傳回伺服器程序排程在可用終止時間時關閉的時間。伺服器程序在收到來自 Amazon 的回onProcessTerminate()呼後，會採取此動作 GameLift。Amazon onProcessTerminate() GameLift 呼叫原因如下：

語法

func GetTerminationTime() (int64, error)

傳回值

如果成功， 會以 epoch 秒為單位傳回伺服器程序排程關閉的時間戳記，並終止nil錯誤。此值是終止時間，以 的已過勾號表示0001 00:00:00。例如，日期時間值2020-09-13 12:26:40 -000Z等於637355968000000000勾號。如果沒有可用的終止時間， 會傳回錯誤訊息。

範例

terminationTime, err := server.GetTerminationTime()

AcceptPlayerSession()

通知 Amazon GameLift 具有指定播放器工作階段 ID 的播放器已連線至伺服器程序，且需要驗證。Amazon 會 GameLift 驗證播放器工作階段 ID 是否有效。驗證播放器工作階段後，Amazon 會將播放器插槽的狀態從 GameLift 變更為 RESERVED ACTIVE。

語法

func AcceptPlayerSession(playerSessionID string) error

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例會處理連線請求，其中包含驗證和拒絕無效播放器工作階段 IDs。

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

RemovePlayerSession()

通知 Amazon GameLift 播放器已中斷與伺服器程序的連線。為了回應，Amazon 會將播放器插槽 GameLift 變更為可用。

語法

func RemovePlayerSession(playerSessionID string) error

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

擷取播放器工作階段資料，包括設定、工作階段中繼資料和播放器資料。使用此方法取得下列相關資訊：

語法

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

參數

傳回值

如果成功， 會傳回物件DescribePlayerSessionsResult，其中包含一組符合請求參數的播放器工作階段物件。

範例

此範例會請求主動連線到指定遊戲工作階段的所有玩家工作階段。透過省略NextToken並將限制值設定為 10，Amazon 會 GameLift 傳回符合請求的前 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 提供更新的相符者資料OnUpdateGameSession()。

一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 StopMatchBackfill() 取消原始請求。

語法

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

參數

傳回值

傳回具有相符回填票證 ID 的StartMatchBackfillResult物件，或具有錯誤訊息的失敗。

範例

// 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

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

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 Anywhere 機群。如需詳細資訊，請參閱 RegisterCompute。

語法

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

傳回值

傳回包含下列項目的GetComputeCertificateResult物件：

範例

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

GetFleetRoleCredentials()

擷取您建立的服務角色憑證，將許可擴展至 AWS 服務 Amazon 的其他 GameLift。這些憑證可讓您的遊戲伺服器使用您的 AWS 資源。如需詳細資訊，請參閱設定 Amazon IAM的服務角色 GameLift。

語法

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

參數

傳回值

傳回包含下列項目的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（）

從記憶體中SDK釋放 Amazon GameLift 遊戲伺服器。最佳實務是在終止程序之後ProcessEnding()和之前呼叫此方法。如果您使用的是 Anywhere 機群，而且沒有在每次遊戲工作階段後終止伺服器程序，請呼叫 Destroy()，然後在通知 Amazon GameLift 程序已準備好使用 託管遊戲工作階段之前InitSDK()重新初始化ProcessReady()。

語法

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)
  }
}