Amazon GameLift 服務器開發套件（Go）參考：操作

您可以使用此 Amazon GameLift Go 伺服器開發套件參考來協助您準備好與 Amazon 搭配使用的多人遊戲 GameLift。如需有關整合程序的詳細資訊，請參閱添加亞馬遜GameLift到您的遊戲服務器。

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

GetSdkVersion()

傳回內建至伺服器程序的目前開發套件版本編號。

語法

func GetSdkVersion() (string, error)

傳回值

如果成功，則返回當前 SDK 版本作為字符串。傳回的字串包含版本號碼 (範例5.0.0)。如果不成功，則會傳回錯誤訊息，例如common.SdkVersionDetectionFailed。

範例

version, err := server.GetSdkVersion()

InitSDK()

初始化 Amazon 開 GameLift 發套件。在與 Amazon 相關的任何其他初始化發生之前，請在啟動 GameLift 時呼叫此方法。此方法設置服務器和 Amazon GameLift 服務之間的通信。

語法

func InitSDK(params ServerParameters) error 

參數

ServerParameters

若要初始化 Amazon GameLift Anywhere 叢集上的遊戲伺服器，請使用下列資訊建構ServerParameters物件：

• WebSocket 用來連線到遊戲伺服器的 URL。

• 用來託管遊戲伺服器的程序 ID。

• 主控遊戲伺服器處理程序的運算 ID。

• 包含您的 Amazon GameLift Anywhere 運算的 Amazon GameLift 車隊的 ID。

• Amazon GameLift 操作生成的授權令牌。

若要在 Amazon GameLift 受管 EC2 叢集上初始化遊戲伺服器，請建構不含參數的ServerParameters物件。透過此呼叫，Amazon GameLift 代理程式會設定運算環境，並自動為您連線到 Amazon GameLift 服務。

傳回值

如果成功，則返回 nil error 以指示服務器進程已準備好調用ProcessReady()。

注意

如果部署到 InitSDK() Anywhere 叢集的遊戲組建時呼叫失敗，請檢查建立組建資源時使用的ServerSdkVersion參數。您必須明確地將此值設定為使用中的伺服器 SDK 版本。此參數的預設值為 4.x，不相容。若要解決此問題，請建立新組建並將其部署到新的叢集。

範例

Amazon GameLift 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 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()

通 GameLift 知 Amazon 伺服器程序已準備好主持遊戲工作階段。調用後調用InitSDK()此方法。這種方法應該被調用每個進程只有一次。

語法

func ProcessReady(param ProcessParameters) error

參數

ProcessParameters

ProcessParameters物件會傳達有關伺服器處理序的下列資訊：

• Amazon GameLift 服務呼叫以與伺服器處理序通訊之遊戲伺服器程式碼中實作的回呼方法名稱。

• 伺服器處理序偵聽的連接埠號碼。

• 包含您希望 Amazon GameLift 擷取和LogParameters存放之任何遊戲工作階段特定檔案路徑的資料類型。

傳回值

如果方法失敗，則傳回錯誤訊息的錯誤。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()

通 GameLift 知 Amazon 服務器進程正在終止。在所有其他清理任務（包括關閉活動的遊戲會話）之後以及終止進程之前調用此方法。根據的結果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()

通 GameLift 知 Amazon 伺服器程序已啟動遊戲工作階段，現在已準備好接收玩家連線。在所有遊戲會話初始化之後，此操作被稱為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

參數

playerSessionCreation政策

指出遊戲階段作業是否接受新玩家的字串值。

有效值包含：

• model.AcceptAll— 接受所有新玩家會話.

• model.DenyAll— 拒絕所有新玩家會話.

傳回值

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

範例

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

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

擷取使用中伺服器處理序主控的遊戲工作階段 ID。

語法

func GetGameSessionID() (string, error)

參數

此動作沒有參數。

傳回值

如果成功，返回遊戲會話 ID 和零錯誤。對於尚未通過遊戲會話激活的空閒進程，調用返回一個空字符串和nil錯誤。

範例

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

返回一個服務器進程被計劃關閉，如果終止時間是可用的時間。服務器進程在收到來自 Amazon 的onProcessTerminate()回調後採取此操作 GameLift。Amazon GameLift 呼叫onProcessTerminate()的原因如下：

• 當服務器進程報告健康狀況不佳或沒有響應 Amazon 時 GameLift。

• 在縮小事件期間終止執行個體時。

• 執行個體因為現場執行個體中斷而終止時。

語法

func GetTerminationTime() (int64, error)

傳回值

如果成功，會傳回伺服器處理序排定關閉的時間戳記 (以紀元秒為單位)，並終止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

參數

playerSessionId

創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例會處理包含驗證和拒絕非有效玩家工作階段 ID 的連線要求。

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

RemovePlayerSession()

通 GameLift 知 Amazon 播放器已與服務器進程斷開連接。作為回應，Amazon 將播放器插槽 GameLift 更改為可用。

語法

func RemovePlayerSession(playerSessionID string) error

參數

playerSessionId

創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

檢索播放器會話數據，其中包括設置，會話元數據和播放器數據。使用此方法可取得下列項目的相關資訊：

• 單一玩家工作階段

• 遊戲工作階段中的所有玩家工作階

• 與單一玩家 ID 關聯的所有玩家工作階段

語法

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

參數

DescribePlayerSessionsRequest

DescribePlayerSessionsRequest物件描述要擷取哪些玩家工作階段。

傳回值

如果成功，會傳回包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 會使用回調函OnUpdateGameSession()數 GameLift 提供更新的分房系統資料。

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

語法

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

參數

StartMatchBackfillRequest

StartMatchBackfillRequest 物件會傳達下列資訊：

• 指派給回填請求的票證 ID。此資訊是選擇性的；如果未提供 ID，Amazon GameLift 會產生一個 ID。

• 傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值會顯示在遊戲工作階段的分房系統資料中。

• 要回填的遊戲工作階段 ID。

• 遊戲工作階段目前玩家的可用配對資料。

傳回值

傳回具有相符回填工單 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

參數

StopMatchBackfillRequest

識別要取消的配對票證的 StopMatchBackfillRequest 物件：

• 指派給回填請求的工單 ID。

• 回填要求傳送至的分房系統。

• 與回填要求相關聯的遊戲工作階段。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

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物件：

• CertificatePath：計算資源上 TLS 憑證的路徑。使用 Amazon 受 GameLift 管叢集時，此路徑包含：

  • certificate.pem：一般使用者憑證。完整憑證鏈結是certificateChain.pem附加至此憑證的組合。

  • certificateChain.pem：包含根憑證和中繼憑證的憑證鏈結。

  • rootCertificate.pem：根憑證。

  • privateKey.pem：一般使用者憑證的私密金鑰。

• ComputeName：計算資源的名稱。

範例

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

參數

GetFleetRoleCredentialsRequest

將有限AWS資源存取權限延伸至遊戲伺服器的角色認證。

傳回值

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

• AssumedRoleUserArn -服務角色所屬之使用者的 Amazon 資源名稱 (ARN)。

• AssumedRoleId -服務角色所屬的使用者識別碼。

• AccessKeyId -用於驗證並提供對AWS資源的訪問權限的訪問密鑰 ID。

• SecretAccessKey -用於驗證的密鑰訪問密鑰 ID。

• SessionToken -用於識別與AWS資源交互的當前活動會話的令牌。

• 到期-您的工作階段認證到期之前的時間量。

範例

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

credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

摧毀（）

從記憶體中釋放 Amazon GameLift 遊戲伺服器 SDK。最佳做法是在終止程序之後ProcessEnding()和之前呼叫此方法。如果您使用的是 Anywhere 叢集，且未在每個遊戲工作階段後終止伺服器程序，請先呼叫Destroy()然InitSDK()後重新初始化，然後通知 Amazon GameLift 程序已準備好主持遊戲工作階段。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)
  }
}