Amazon GameLift server SDK for Go: Actions

Use the Amazon GameLift Go server SDK 5.x reference to integrate your multiplayer game for hosting with Amazon GameLift. For guidance about the integration process, see Add Amazon GameLift to your game server.

GameLiftServerAPI.go defines the Go server SDK actions.

Amazon GameLift server SDK for Go: Data types

GetSdkVersion()

Returns the current version number of the SDK built into the server process.

Syntax

func GetSdkVersion() (string, error)

Return value

If successful, returns the current SDK version as a string. The returned string includes the version number (example 5.0.0). If not successful, returns an error message such as common.SdkVersionDetectionFailed.

Example

version, err := server.GetSdkVersion()

InitSDK()

Initializes the Amazon GameLift SDK. Call this method on launch before any other initialization related to Amazon GameLift occurs. This method sets up communication between the server and the Amazon GameLift service.

Syntax

func InitSDK(params ServerParameters) error 

Parameters

Return value

If successful, returns nil error to indicate that the server process is ready to call ProcessReady().

Example

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 managed EC2 example

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

Notifies Amazon GameLift that the server process is ready to host game sessions. Call this method after invoking InitSDK(). This method should be called only one time per process.

Syntax

func ProcessReady(param ProcessParameters) error

Parameters

Return value

Returns an error with an error message if the method fails. Returns nil if the method is successful.

Example

This example illustrates both the ProcessReady() call and delegate function implementations.

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

Notifies Amazon GameLift that the server process is terminating. Call this method after all other cleanup tasks (including shutting down the active game session) and before terminating the process. Depending on the result of ProcessEnding(), the process exits with success (0) or error (-1) and generates a fleet event. If the process terminates with an error, the fleet event generated is SERVER_PROCESS_TERMINATED_UNHEALTHY.

Syntax

func ProcessEnding() error

Return value

Returns a 0 error code or a defined error code.

Example

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

Notifies Amazon GameLift that the server process has activated a game session and is now ready to receive player connections. This action is called as part of the onStartGameSession() callback function, after all game session initialization.

Syntax

func ActivateGameSession() error

Return value

Returns an error with an error message if the method fails.

Example

This example shows ActivateGameSession() called as part of the onStartGameSession() delegate function.

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

Updates the current game session's ability to accept new player sessions. A game session can be set to either accept or deny all new player sessions.

Syntax

func UpdatePlayerSessionCreationPolicy(policy model.PlayerSessionCreationPolicy) error

Parameters

Return value

Returns an error with an error message if failure occurs.

Example

This example sets the current game session's join policy to accept all players.

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

Retrieves the ID of the game session hosted by the active server process.

Syntax

func GetGameSessionID() (string, error)

Parameters

This action has no parameters.

Return value

If successful, returns the game session ID and nil error. For idle processes that aren't yet activated with a game session, the call returns an empty string and nil error.

Example

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

Returns the time that a server process is scheduled to be shut down if a termination time is available. A server process takes this action after receiving an onProcessTerminate() callback from Amazon GameLift. Amazon GameLift calls onProcessTerminate() for the following reasons:

Syntax

func GetTerminationTime() (int64, error)

Return value

If successful, returns the timestamp in epoch seconds that the server process is scheduled to shut down and a nil error termination. The value is the termination time, expressed in elapsed ticks from 0001 00:00:00. For example, the date time value 2020-09-13 12:26:40 -000Z is equal to 637355968000000000 ticks. If no termination time is available, returns an error message.

Example

terminationTime, err := server.GetTerminationTime()

AcceptPlayerSession()

Notifies Amazon GameLift that a player with the specified player session ID has connected to the server process and needs validation. Amazon GameLift verifies that the player session ID is valid. After the player session is validated, Amazon GameLift changes the status of the player slot from RESERVED to ACTIVE.

Syntax

func AcceptPlayerSession(playerSessionID string) error

Parameters

Return value

Returns a generic outcome consisting of success or failure with an error message.

Example

This example handles a connection request that includes validating and rejecting non-valid player session IDs.

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

RemovePlayerSession()

Notifies Amazon GameLift that a player has disconnected from the server process. In response, Amazon GameLift changes the player slot to available.

Syntax

func RemovePlayerSession(playerSessionID string) error

Parameters

Return value

Returns a generic outcome consisting of success or failure with an error message.

Example

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

Retrieves player session data which includes settings, session metadata, and player data. Use this method to get information about the following:

Syntax

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

Parameters

Return value

If successful, returns a DescribePlayerSessionsResult object that contains a set of player session objects that fit the request parameters.

Example

This example requests all player sessions actively connected to a specified game session. By omitting NextToken and setting the Limit value to 10, Amazon GameLift returns the first 10 player session records matching the request.

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

Sends a request to find new players for open slots in a game session created with FlexMatch. For more information, see FlexMatch backfill feature.

This action is asynchronous. If new players are matched, Amazon GameLift delivers updated matchmaker data using the callback function OnUpdateGameSession().

A server process can have only one active match backfill request at a time. To send a new request, first call StopMatchBackfill() to cancel the original request.

Syntax

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

Parameters

Return value

Returns a StartMatchBackfillResult object with the match backfill ticket ID, or failure with an error message.

Example

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

Cancels an active match backfill request. For more information, see FlexMatch backfill feature.

Syntax

func StopMatchBackfill(req request.StopMatchBackfillRequest) error

Parameters

Return value

Returns a generic outcome consisting of success or failure with an error message.

Example

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

Retrieves the path to the TLS certificate used to encrypt the network connection between the game server and your game client. You can use the certificate path when you register your compute device to a Amazon GameLift Anywhere fleet. For more information, see RegisterCompute.

Syntax

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

Return value

Returns a GetComputeCertificateResult object that contains the following:

Example

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

GetFleetRoleCredentials()

Retrieves the service role credentials that you create to extend permissions to your other AWS services to Amazon GameLift. These credentials allow your game server to use your AWS resources. For more information, see Set up an IAM service role for Amazon GameLift.

Syntax

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

Parameters

Return value

Returns a GetFleetRoleCredentialsResult object that contains the following:

Example

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

credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

Destroy()

Frees the Amazon GameLift game server SDK from memory. As a best practice, call this method after ProcessEnding() and before terminating the process. If you're using an Anywhere fleet and you're not terminating server processes after every game session, call Destroy() and then InitSDK() to reinitialize before notifying Amazon GameLift that the process is ready to host a game session with ProcessReady().

Syntax

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

Return value

Returns an error with an error message if the method fails.

Example

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