Referencia GameLift del SDK (Go) del servidor Amazon: acciones

Puedes usar esta referencia del SDK del servidor Amazon GameLift Go como ayuda para preparar tu juego multijugador para usarlo con Amazon GameLift. Para obtener más información sobre el proceso de integración, consulte Añade Amazon GameLift a tu servidor de juegos.

GameLiftServerAPI.go define las acciones del SDK del servidor Go.

GetSdkVersion()

Devuelve el número de versión actual del SDK integrado en el proceso del servidor.

Sintaxis

func GetSdkVersion() (string, error)

Valor devuelto

Si funciona correctamente, devuelve la versión del SDK actual como una cadena. La cadena devuelta solo incluye el número de versión (por ejemplo, 5.0.0). Si no funciona, devuelve un mensaje de error, como common.SdkVersionDetectionFailed.

Ejemplo

version, err := server.GetSdkVersion()

InitSDK()

Inicializa el Amazon GameLift SDK. Llama a este método en el lanzamiento antes de que se GameLift produzca cualquier otra inicialización relacionada con Amazon. Este método establece la comunicación entre el servidor y el GameLift servicio de Amazon.

Sintaxis

func InitSDK(params ServerParameters) error 

Parámetros

ServerParameters

Para inicializar un servidor de juegos en una GameLift Anywhere flota de Amazon, construye un ServerParameters objeto con la siguiente información:

• La URL WebSocket utilizada para conectarte a tu servidor de juegos.

• El ID del proceso utilizado para alojar su servidor de juegos.

• El ID del proceso utilizado para alojar los procesos del servidor de juegos.

• El ID de la GameLift flota de Amazon que contiene tu ordenador de GameLift Anywhere Amazon.

• El token de autorización generado por la GameLift operación de Amazon.

Para inicializar un servidor de juegos en una flota de EC2 GameLift gestionada por Amazon, construye un ServerParameters objeto sin parámetros. Con esta llamada, el GameLift agente de Amazon configura el entorno informático y se conecta automáticamente al GameLift servicio de Amazon por usted.

Valor devuelto

Si funciona correctamente, devuelve el error nil para indicar que el proceso del servidor está listo para llamar a ProcessReady().

nota

Si las llamadas a InitSDK() no funcionan en las compilaciones de juegos implementadas en las flotas de Anywhere, compruebe el parámetro ServerSdkVersion que se utiliza al crear el recurso de compilación. Debe establecer este valor de forma explícita en la versión del SDK del servidor en uso. El valor predeterminado de este parámetro es 4.x, que no es compatible. Para resolver este problema, cree una compilación nueva e impleméntela en una flota nueva.

Ejemplo

GameLift AnywhereEjemplo de Amazon

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

Ejemplo de EC2 GameLift gestionado por Amazon

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

Notifica a Amazon de GameLift que el proceso del servidor está listo para albergar sesiones de juego. Llame a este método después de invocar InitSDK(). Se debe llamar a este método solo una vez por proceso.

Sintaxis

func ProcessReady(param ProcessParameters) error

Parámetros

ProcessParameters

Es un objeto ProcessParameters que comunica la siguiente información sobre el proceso del servidor:

• Los nombres de los métodos de devolución de llamada implementados en el código del servidor del juego que el GameLift servicio de Amazon invoca para comunicarse con el proceso del servidor.

• El número de puerto de escucha del servidor de proceso.

• El tipo de LogParameters datos que contiene la ruta a cualquier archivo específico de la sesión de juego que quieras que Amazon capture y GameLift almacene.

Valor devuelto

Devuelve un error con un mensaje de error si el método falla. Devuelve nil si el método se realiza correctamente.

Ejemplo

Este ejemplo ilustra las implementaciones tanto de la función de llamada ProcessReady() como de la función de delegación.

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

Notifica a Amazon de GameLift que el proceso del servidor está finalizando. Utiliza este método después de realizar todas las demás tareas de limpieza (incluido el cierre de la sesión de juego activa) y antes de finalizar el proceso. Según el resultado de ProcessEnding(), el proceso finaliza con éxito (0) o error (-1) y genera un evento de flota. Si el proceso termina con un error, se generará el evento de flota. SERVER_PROCESS_TERMINATED_UNHEALTHY

Sintaxis

func ProcessEnding() error

Valor devuelto

Devuelve un código de error 0 o un código de error definido.

Ejemplo

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

Notifica a Amazon GameLift que el proceso del servidor ha activado una sesión de juego y ya está listo para recibir las conexiones de los jugadores. Se llama a esta acción como parte de la función de devolución de llamada onStartGameSession(), después de la inicialización de todas las sesiones de juego.

Sintaxis

func ActivateGameSession() error

Valor devuelto

Devuelve un error con un mensaje de error si el método falla.

Ejemplo

Este ejemplo muestra cómo se llama a ActivateGameSession() como parte de la función de delegación 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()

Actualiza la capacidad de la sesión de juego actual para aceptar sesiones de jugador nuevas. Una sesión de juego se puede configurar para que acepte o deniegue todas las sesiones nuevas de los jugadores.

Sintaxis

func UpdatePlayerSessionCreationPolicy(policy model.PlayerSessionCreationPolicy) error

Parámetros

playerSessionCreationPolítica

Valor de cadena que indica si la sesión de juego acepta jugadores nuevos.

Los valores válidos son:

• model.AcceptAll: se aceptan todas las sesiones de jugador nuevas.

• model.DenyAll: se rechazan todas las sesiones de jugador nuevas.

Valor devuelto

Devuelve un error con un mensaje de error si se produce un error.

Ejemplo

Este ejemplo establece la política de participación en la sesión de juego actual para aceptar todos los jugadores.

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

Recupera el ID de la sesión de juego alojada por el proceso del servidor.

Sintaxis

func GetGameSessionID() (string, error)

Parámetros

Esta acción no tiene parámetros.

Valor devuelto

Si funciona correctamente, devuelve el ID de sesión del juego y el error nil. En el caso de los procesos inactivos que no se han activado aún con una sesión de juego, la llamada devuelve una cadena vacía y el error nil.

Ejemplo

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

Devuelve la hora a la que está programada el cierre de un proceso de servidor, si hay una hora de terminación disponible. Un proceso de servidor realiza esta acción tras recibir una onProcessTerminate() llamada de Amazon GameLift. Amazon GameLift solicita onProcessTerminate() por los siguientes motivos:

• Cuando el proceso del servidor ha informado de un mal estado de salud o no ha respondido a Amazon GameLift.

• Al finalizar la instancia durante un evento de reducción vertical.

• Cuando se finaliza una instancia debido a la interrupción de una instancia de spot.

Sintaxis

func GetTerminationTime() (int64, error)

Valor devuelto

Si se ejecuta correctamente, devuelve la marca temporal en segundos en la que está previsto que el proceso del servidor se cierre y finalice el error nil. El valor es la hora de terminación expresado en ciclos transcurridos desde 0001 00:00:00. Por ejemplo, el valor de la fecha y hora 2020-09-13 12:26:40 -000Z es igual a 637355968000000000 ciclos. Si no hay una hora de terminación disponible, devuelve un mensaje de error.

Ejemplo

terminationTime, err := server.GetTerminationTime()

AcceptPlayerSession()

Notifica a Amazon GameLift que un jugador con el identificador de sesión de jugador especificado se ha conectado al proceso del servidor y necesita ser validado. Amazon GameLift verifica que el identificador de sesión del jugador sea válido. Una vez validada la sesión del jugador, Amazon GameLift cambia el estado de la ranura del jugador de RESERVED aACTIVE.

Sintaxis

func AcceptPlayerSession(playerSessionID string) error

Parámetros

playerSessionId

ID único emitido por Amazon GameLift cuando se crea una nueva sesión de jugador.

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

En este ejemplo, se administra una solicitud de conexión que incluye la validación y el rechazo de los ID de sesión de los jugadores no válidos.

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

RemovePlayerSession()

Notifica a Amazon GameLift que un jugador se ha desconectado del proceso del servidor. En respuesta, Amazon GameLift cambia el espacio del jugador para que esté disponible.

Sintaxis

func RemovePlayerSession(playerSessionID string) error

Parámetros

playerSessionId

ID único emitido por Amazon GameLift cuando se crea una nueva sesión de jugador.

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

Recupera datos de sesión de jugador, incluida la configuración, los metadatos de la sesión y los datos de jugador. Utilice este método para obtener información sobre los siguientes elementos:

• Una sesión para un jugador

• Todas las sesiones del jugador en una sesión de juego

• Todas las sesiones de jugador están asociadas a un único ID de jugador

Sintaxis

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

Parámetros

DescribePlayerSessionsRequest

Es un objeto DescribePlayerSessionsRequest que describe las sesiones de jugador a recuperar.

Valor devuelto

Si funciona correctamente, devuelve un objeto DescribePlayerSessionsResult que contiene un conjunto de objetos de sesión de jugador que se ajusta a los parámetros de la solicitud.

Ejemplo

En este ejemplo se solicitan todas las sesiones de jugador conectadas activamente a una sesión de juego específica. Al omitir NextTokeny establecer el valor límite en 10, Amazon GameLift devuelve los registros de las sesiones de los primeros 10 jugadores que coincidan con la solicitud.

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

Envía una solicitud para encontrar nuevos jugadores en las tragaperras abiertas en una sesión de juego creada con FlexMatch. Para obtener más información, consulta la función de FlexMatch relleno.

Esta acción es asíncrona. Si se emparejan nuevos jugadores, Amazon GameLift proporciona datos actualizados de los emparejadores mediante la función de devolución de llamada. OnUpdateGameSession()

Un proceso del servidor solo puede tener una solicitud de reposición de emparejamiento activa a la vez. Para enviar una nueva solicitud, en primer lugar llame a StopMatchBackfill() para cancelar la solicitud original.

Sintaxis

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

Parámetros

StartMatchBackfillRequest

Un StartMatchBackfillRequest objeto comunica la siguiente información:

• Un ID de ticket que se asignará a la solicitud de reposición. Esta información es opcional; si no se proporciona ningún identificador, Amazon GameLift generará uno.

• El creador de emparejamientos al que se enviará la solicitud. El ARN de configuración completo es obligatorio. Este valor se encuentra en los datos del emparejador de la sesión de juego.

• El ID de la sesión de juego que se va a reponer.

• Datos del emparejador disponibles para los jugadores actuales de la sesión de juego.

Valor devuelto

Devuelve un objeto StartMatchBackfillResult con el ID del ticket de reposición de emparejamiento o un error con un mensaje de error.

Ejemplo

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

Cancela una solicitud de reposición de emparejamiento activa. Para obtener más información, consulta la función de FlexMatch relleno.

Sintaxis

func StopMatchBackfill(req request.StopMatchBackfillRequest) error

Parámetros

StopMatchBackfillRequest

Un StopMatchBackfillRequest objeto que identifica el billete de emparejamiento que se va a cancelar:

• ID del ticket que se asignará a la solicitud de reposición

• El emparejador al que se envió la solicitud de reposición

• La sesión de juego asociada a la solicitud de reposición.

Valor devuelto

Devuelve un resultado genérico correcto o erróneo con un mensaje de error.

Ejemplo

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

Recupera la ruta al certificado TLS utilizado para cifrar la conexión de red entre el servidor de juegos y el cliente de juego. Puedes usar la ruta del certificado al registrar tu dispositivo informático en una GameLift Anywhere flota de Amazon. Para obtener más información, consulte RegisterCompute.

Sintaxis

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

Valor devuelto

Devuelve un objeto GetComputeCertificateResult que contiene los siguientes elementos:

• CertificatePath: La ruta al certificado TLS de su recurso informático. Cuando se utiliza una flota GameLift gestionada por Amazon, esta ruta contiene:

  • certificate.pem: el certificado del usuario final. La cadena de certificados completa es la combinación del certificateChain.pem adjunto a este certificado.

  • certificateChain.pem: la cadena de certificados que contiene el certificado raíz y los certificados intermedios.

  • rootCertificate.pem: el certificado raíz.

  • privateKey.pem: la clave privada del certificado del usuario final.

• ComputeName: el nombre de su recurso informático.

Ejemplo

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

GetFleetRoleCredentials()

Recupera las credenciales del rol de servicio que creaste para extender los permisos a tu otro Servicios de AWS rol en Amazon GameLift. Estas credenciales permiten que su servidor de juegos utilice sus recursos de AWS . Para obtener más información, consulte Configurar un rol de servicio de IAM para Amazon GameLift.

Sintaxis

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

Parámetros

GetFleetRoleCredentialsRequest

Credenciales de rol que amplían el acceso limitado a tus AWS recursos al servidor del juego.

Valor devuelto

Devuelve un objeto GetFleetRoleCredentialsResult que contiene los siguientes elementos:

• AssumedRoleUserArn - El nombre de recurso de Amazon (ARN) del usuario al que pertenece la función de servicio.

• AssumedRoleId - El ID del usuario al que pertenece el rol de servicio.

• AccessKeyId - El ID de la clave de acceso para autenticar y proporcionar acceso a sus AWS recursos.

• SecretAccessKey - El identificador de la clave de acceso secreta para la autenticación.

• SessionToken - Un token para identificar la sesión activa actual que interactúa con tus AWS recursos.

• Vencimiento: el tiempo que queda hasta que caduquen las credenciales de la sesión.

Ejemplo

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

credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

Destroy()

Libera de la memoria el SDK del servidor de GameLift juegos de Amazon. Como práctica recomendada, llame a este método después de ProcessEnding() y antes de finalizar el proceso. Si utilizas una flota de Anywhere y no vas a finalizar los procesos del servidor después de cada sesión de juego, llama Destroy() y, InitSDK() a continuación, reinicializa antes de notificar a Amazon GameLift que el proceso está listo para organizar una sesión de juego con ella. ProcessReady()

Sintaxis

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

Valor devuelto

Devuelve un error con un mensaje de error si el método falla.

Ejemplo

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