Go サーバー SDK for Amazon GameLift Servers – アクション

サーバー SDK 5.x リファレンスを使用して、Amazon GameLift Servers でホスティングするマルチプレイヤーゲームを統合します。統合プロセスのガイダンスについては、「サーバー SDK を使用して、Amazon GameLift Servers をゲームサーバーに追加します。」を参照してください。

GameLiftServerAPI.go は、Go サーバー SDK アクションを定義します。

Go サーバー SDK for Amazon GameLift Servers -- データ型

GetSdkVersion()

サーバープロセスに組み込まれた SDK の現在のバージョン番号を返します。

構文

func GetSdkVersion() (string, error)

戻り値

成功した場合、文字列として現在の SDK バージョンを返します。返される文字列は、バージョン番号のみを含みます。(例: 5.0.0) 成功しなかった場合、common.SdkVersionDetectionFailed などのエラーメッセージを返します。

例

version, err := server.GetSdkVersion()

InitMetrics()

Amazon GameLift Servers SDK のメトリクス収集を初期化します。このメソッドは、サーバーのパフォーマンスとヘルスのモニタリングに役立つメトリクスレポートを設定します。このメソッドは、InitSDK() の後、ProcessReady() の前に呼び出します。

構文

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

パラメータ

戻り値

成功すると、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 SDK を初期化します。起動時に、他の Amazon GameLift Servers 関連の初期化が実行される前にこのメソッドを呼び出します。このメソッドで、サーバーと Amazon GameLift Servers サービスとの通信を確立します。

構文

func InitSDK(params ServerParameters) error 

パラメータ

戻り値

成功した場合は、サーバープロセスが ProcessReady() を呼び出す準備ができていることを示す nil エラーを返します。

例

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() を呼び出した後にこのメソッドを呼び出します。このメソッドは、プロセスごとに 1 回だけ呼び出す必要があります。

構文

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

戻り値

メソッドが失敗すると、エラーとエラーメッセージを返します。

例

この例では、onStartGameSession() 委任関数の一部として呼び出された ActivateGameSession() を示しています。

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

指定されたプレイヤーセッション ID を持つプレイヤーがサーバープロセスに接続し、検証が必要であることを、Amazon GameLift Servers に通知します。Amazon GameLift Servers は、プレイヤーセッション ID が有効であることを検証します。検証できたら、Amazon GameLift Servers はプレーヤースロットの状態を RESERVED から ACTIVE に変更します。

構文

func AcceptPlayerSession(playerSessionID string) error

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

この例では、無効なプレイヤーセッション 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

パラメータ

戻り値

正常またはエラーメッセージを伴うエラーの、一般的な結果を返します。

例

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

設定、セッションメタデータ、プレイヤーデータを含む、プレイヤーセッションデータを取得します。このメソッドを使用して、以下に関する情報を取得します。

構文

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

パラメータ

戻り値

成功した場合は、リクエストのパラメータに適合したプレイヤーセッションオブジェクトのセットを含む 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() を使用して更新済みマッチメーカーデータを送信します。

サーバープロセスではアクティブなマッチバックフィルリクエストは一度に 1 つだけです。新しいリクエストを送信するには、まず StopMatchBackfill() を呼び出して元のリクエストをキャンセルする必要があります。

構文

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

パラメータ

戻り値

StartMatchBackfillResult オブジェクトを、マッチバックフィルチケット ID またはエラーメッセージを伴うエラーとともに返します。

例

// 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 Servers Anywhere フリートに登録するときに使用できます。詳細については、「RegisterCompute」を参照してください。

構文

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

戻り値

以下が含まれる GetComputeCertificateResult オブジェクトを返します。

例

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

GetFleetRoleCredentials()

他の AWS のサービス リソースに対する権限を Amazon GameLift Servers へ拡張するために作成したサービスロールの認証情報を取得します。これらの認証情報により、ゲームサーバーは AWS リソースを使用できます。詳細については、「Amazon GameLift Servers 用に IAM サービスロールをセットアップする」を参照してください。

構文

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

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