Amazon GameLift Server SDK (Go)-Referenz: Aktionen

Sie können diese Amazon- GameLift Go-Server-SDK-Referenz verwenden, um Ihr Multiplayer-Spiel für die Verwendung mit Amazon vorzubereiten GameLift. Weitere Informationen zum Integrationsprozess finden Sie unter Füge Amazon GameLift zu deinem Gameserver hinzu.

GameLiftServerAPI.go definiert die Go-Server-SDK-Aktionen.

GetSdkVersion()

Gibt die aktuelle Versionsnummer des SDK zurück, das in den Serverprozess integriert ist.

Syntax

func GetSdkVersion() (string, error)

Rückgabewert

Bei Erfolg gibt die aktuelle SDK-Version als Zeichenfolge zurück. Die zurückgegebene Zeichenfolge enthält die Versionsnummer (Beispiel 5.0.0). Wenn nicht erfolgreich, gibt eine Fehlermeldung wie zurückcommon.SdkVersionDetectionFailed.

Beispiel

version, err := server.GetSdkVersion()

InitSDK()

Initialisiert das Amazon GameLift SDK. Rufen Sie diese Methode beim Start auf, bevor eine andere Initialisierung im Zusammenhang mit Amazon GameLift erfolgt. Diese Methode richtet die Kommunikation zwischen dem Server und dem Amazon- GameLift Service ein.

Syntax

func InitSDK(params ServerParameters) error 

Parameter

ServerParameters

Um einen Spieleserver auf einer Amazon GameLift Anywhere-Flotte zu initialisieren, erstellen Sie ein ServerParameters Objekt mit den folgenden Informationen:

• Die URL des , der für die Verbindung mit Ihrem Spieleserver WebSocket verwendet wird.

• Die ID des Prozesses, der zum Hosten Ihres Spieleservers verwendet wird.

• Die ID der Datenverarbeitung, die Ihre Spielserverprozesse hostet.

• Die ID der Amazon- GameLift Flotte, die Ihre Amazon GameLift Anywhere-Datenverarbeitung enthält.

• Das von der Amazon- GameLift Operation generierte Autorisierungstoken.

Um einen Spieleserver auf einer von Amazon GameLift verwalteten EC2-Flotte zu initialisieren, erstellen Sie ein ServerParameters Objekt ohne Parameter. Bei diesem Aufruf richtet der Amazon- GameLift Agent die Datenverarbeitungsumgebung ein und stellt automatisch eine Verbindung zum Amazon- GameLift Service für Sie her.

Rückgabewert

Bei Erfolg gibt den nil Fehler zurück, um anzuzeigen, dass der Serverprozess bereit ist, aufzurufenProcessReady().

Anmerkung

Wenn Aufrufe von für Spiele-Builds fehlschlagen, die in Anywhere-Flotten bereitgestellt InitSDK() werden, überprüfen Sie den ServerSdkVersion Parameter, der beim Erstellen der Build-Ressource verwendet wird. Sie müssen diesen Wert explizit auf die verwendete Server-SDK-Version festlegen. Der Standardwert für diesen Parameter ist 4.x, was nicht kompatibel ist. Um dieses Problem zu beheben, erstellen Sie einen neuen Build und stellen Sie ihn für eine neue Flotte bereit.

Beispiel

Amazon GameLift Anywhere-Beispiel

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

Beispiel für Amazon GameLift Managed 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()

Benachrichtigt Amazon GameLift , dass der Serverprozess bereit ist, Spielsitzungen zu hosten. Rufen Sie diese Methode nach dem Aufruf von aufInitSDK(). Diese Methode sollte nur einmal pro Prozess aufgerufen werden.

Syntax

func ProcessReady(param ProcessParameters) error

Parameter

ProcessParameters

Ein ProcessParameters Objekt teilt die folgenden Informationen über den Serverprozess mit:

• Die Namen der Callback-Methoden, die im Spielserver-Code implementiert sind, die der Amazon- GameLift Service aufruft, um mit dem Serverprozess zu kommunizieren.

• Die Portnummer, die der Serverprozess überwacht.

• Der LogParameters Datentyp, der den Pfad zu allen für Spielsitzungen spezifischen Dateien enthält, die Amazon GameLift erfassen und speichern soll.

Rückgabewert

Gibt einen Fehler mit einer Fehlermeldung zurück, wenn die Methode fehlschlägt. Gibt zurücknil, wenn die Methode erfolgreich ist.

Beispiel

Dieses Beispiel veranschaulicht die Implementierung des ProcessReady()-Aufrufs und der Delegate-Funktion.

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

Benachrichtigt Amazon GameLift , dass der Serverprozess beendet wird. Rufen Sie diese Methode nach allen anderen Bereinigungsaufgaben (einschließlich Herunterfahren der aktiven Spielsitzung) und vor dem Beenden des Prozesses auf. Abhängig vom Ergebnis von wird ProcessEnding()der Prozess erfolgreich (0) oder mit einem Fehler (-1) beendet und generiert ein Flottenereignis. Wenn der Prozess mit einem Fehler beendet wird, ist das generierte Flottenereignis SERVER_PROCESS_TERMINATED_UNHEALTHY.

Syntax

func ProcessEnding() error

Rückgabewert

Gibt einen 0-Fehlercode oder einen definierten Fehlercode zurück.

Beispiel

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

Benachrichtigt Amazon GameLift , dass der Serverprozess eine Spielsitzung aktiviert hat und jetzt bereit ist, Spielerverbindungen zu empfangen. Diese Aktion wird nach der Initialisierung der gesamten Spielsitzung als Teil der onStartGameSession() Callback-Funktion aufgerufen.

Syntax

func ActivateGameSession() error

Rückgabewert

Gibt einen Fehler mit einer Fehlermeldung zurück, wenn die Methode fehlschlägt.

Beispiel

Dieses Beispiel zeigt, dass als Teil der onStartGameSession() Delegierungsfunktion ActivateGameSession() aufgerufen wird.

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

Aktualisiert die Kapazität der aktuellen Spielsitzung zur Aufnahme neuer Spielersitzungen. Eine Spielsitzung kann so eingerichtet werden, dass Sie alle neuen Spieler-Sitzungen akzeptiert oder ablehnt.

Syntax

func UpdatePlayerSessionCreationPolicy(policy model.PlayerSessionCreationPolicy) error

Parameter

playerSessionCreationRichtlinie

Zeichenfolgenwert, der angibt, ob die Spielsitzung neue Spieler akzeptiert.

Gültige Werte sind:

• model.AcceptAll – Akzeptieren Sie alle neuen Player-Sitzungen.

• model.DenyAll – Verweigern Sie alle neuen Player-Sitzungen.

Rückgabewert

Gibt einen Fehler mit einer Fehlermeldung zurück, wenn ein Fehler auftritt.

Beispiel

In diesem Beispiel werden die Richtlinien für die aktuelle Spielsitzung für neue Spieler so festgelegt, dass alle Spieler akzeptiert werden.

err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll)

GetGameSessionId()

Ruft die ID der Spielsitzung ab, die vom aktiven Serverprozess gehostet wird.

Syntax

func GetGameSessionID() (string, error)

Parameter

Diese Aktion hat keine Parameter.

Rückgabewert

Bei Erfolg gibt die Spielsitzungs-ID und den Nil-Fehler zurück. Bei inaktiven Prozessen, die noch nicht mit einer Spielsitzung aktiviert sind, gibt der Aufruf eine leere Zeichenfolge und einen leeren nil Fehler zurück.

Beispiel

gameSessionID, err := server.GetGameSessionID()

GetTerminationTime()

Gibt die Zeit zurück, zu der ein Serverprozess heruntergefahren werden soll, wenn eine Beendigungszeit verfügbar ist. Ein Serverprozess führt diese Aktion aus, nachdem er einen onProcessTerminate() Rückruf von Amazon erhalten hat GameLift. Amazon GameLift ruft onProcessTerminate() aus folgenden Gründen auf:

• Wenn der Serverprozess einen schlechten Zustand gemeldet oder nicht auf Amazon geantwortet hat GameLift.

• Beim Beenden der Instance während eines Herunterskalierungsereignisses.

• Wenn eine Instance aufgrund einer Spot-Instance-Unterbrechung beendet wird.

Syntax

func GetTerminationTime() (int64, error)

Rückgabewert

Bei Erfolg gibt den Zeitstempel in Epochensekunden zurück, in dem der Serverprozess heruntergefahren werden soll, und eine nil Fehlerbeendigung. Der Wert ist die Beendigungszeit, ausgedrückt in verstrichenen Ticks von 0001 00:00:00. Der Datum-/Uhrzeitwert 2020-09-13 12:26:40 -000Z entspricht beispielsweise 637355968000000000 Ticks. Wenn keine Beendigungszeit verfügbar ist, gibt eine Fehlermeldung zurück.

Beispiel

terminationTime, err := server.GetTerminationTime()

AcceptPlayerSession()

Benachrichtigt Amazon GameLift , dass ein Player mit der angegebenen Player-Sitzungs-ID eine Verbindung zum Serverprozess hergestellt hat und validiert werden muss. Amazon GameLift überprüft, ob die Player-Sitzungs-ID gültig ist. Nachdem die Player-Sitzung validiert wurde, GameLift ändert Amazon den Status des Player-Slots von RESERVED in ACTIVE.

Syntax

func AcceptPlayerSession(playerSessionID string) error

Parameter

playerSessionId

Eindeutige ID, die von Amazon ausgestellt wird GameLift , wenn eine neue Player-Sitzung erstellt wird.

Rückgabewert

Gibt ein generisches Ergebnis zurück, das aus Erfolg oder Fehlschlag mit einer Fehlermeldung besteht.

Beispiel

In diesem Beispiel wird eine Verbindungsanforderung behandelt, die die Validierung und Ablehnung ungültiger Player-Sitzungs-IDs beinhaltet.

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

RemovePlayerSession()

Benachrichtigt Amazon GameLift , dass ein Player die Verbindung zum Serverprozess getrennt hat. Als Reaktion GameLift ändert Amazon den Player-Slot in „Verfügbar“.

Syntax

func RemovePlayerSession(playerSessionID string) error

Parameter

playerSessionId

Eindeutige ID, die von Amazon ausgestellt wird GameLift , wenn eine neue Player-Sitzung erstellt wird.

Rückgabewert

Gibt ein generisches Ergebnis zurück, das aus Erfolg oder Fehlschlag mit einer Fehlermeldung besteht.

Beispiel

err := server.RemovePlayerSession(playerSessionID)

DescribePlayerSessions()

Ruft Spielersitzungsdaten ab, die Einstellungen, Sitzungsmetadaten und Spielerdaten enthalten. Verwenden Sie diese Methode, um Informationen über Folgendes zu erhalten:

• Eine Einzelplayer-Sitzung

• Alle Spielersitzungen in einer Spielsitzung

• Alle Player-Sitzungen, die einer einzelnen Player-ID zugeordnet sind

Syntax

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

Parameter

DescribePlayerSessionsRequest

Ein -DescribePlayerSessionsRequestObjekt beschreibt, welche Player-Sitzungen abgerufen werden sollen.

Rückgabewert

Bei Erfolg gibt ein DescribePlayerSessionsResult Objekt zurück, das eine Reihe von Spielersitzungsobjekten enthält, die den Anforderungsparametern entsprechen.

Beispiel

In diesem Beispiel werden alle Spielersitzungen angefordert, die aktiv mit einer bestimmten Spielsitzung verbunden sind. Wenn Sie den Grenzwert weglassen NextToken und auf 10 setzen, GameLift gibt Amazon die ersten 10 Spielersitzungsdatensätze zurück, die der Anforderung entsprechen.

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

Sendet eine Anforderung zur Suche nach neuen Spielern für offene Slots in einer Spielsitzung, die mit FlexMatch erstellt wurde. Weitere Informationen finden Sie unter FlexMatch Backfill-Feature.

Diese Aktion ist asynchron. Wenn neue Spieler abgeglichen werden, GameLift liefert Amazon aktualisierte Matchmaker-Daten mithilfe der Callback-Funktion OnUpdateGameSession().

Ein Serverprozess kann immer nur eine aktive Match-Backfill-Anforderung haben. Um eine neue Anforderung zu senden, rufen Sie zuerst StopMatchBackfill() auf, um die ursprüngliche Anforderung abzubrechen.

Syntax

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

Parameter

StartMatchBackfillRequest

Ein StartMatchBackfillRequest Objekt teilt die folgenden Informationen mit:

• Eine Ticket-ID für die Zuordnung zur Backfill-Anforderung. Diese Informationen sind optional. Wenn keine ID angegeben wird, GameLift generiert Amazon eine.

• Der Matchmaker, an den die Anfrage gesendet werden soll. Der vollständige ARN der Konfiguration ist erforderlich. Dieser Wert befindet sich in den Matchmaker-Daten der Spielsitzung.

• Die ID der Spielsitzung, die aufgefüllt werden soll.

• Die verfügbaren Matchmaking-Daten für die aktuellen Spieler der Spielsitzung.

Rückgabewert

Gibt ein StartMatchBackfillResult Objekt mit der Match-Backfill-Ticket-ID oder einen Fehler mit einer Fehlermeldung zurück.

Beispiel

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

Bricht eine aktive Match-Backfill-Anforderung ab. Weitere Informationen finden Sie unter FlexMatch Backfill-Feature.

Syntax

func StopMatchBackfill(req request.StopMatchBackfillRequest) error

Parameter

StopMatchBackfillRequest

Ein StopMatchBackfillRequest Objekt, das das zu stornierende Matchmaking-Ticket identifiziert:

• Die Ticket-ID, die der Backfill-Anforderung zugewiesen ist.

• Der Matchmaker, an den die Backfill-Anforderung gesendet wurde.

• Die Spielsitzung, die der Backfill-Anforderung zugeordnet ist.

Rückgabewert

Gibt ein generisches Ergebnis zurück, das aus Erfolg oder Fehlschlag mit einer Fehlermeldung besteht.

Beispiel

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

Ruft den Pfad zum TLS-Zertifikat ab, das zum Verschlüsseln der Netzwerkverbindung zwischen dem Spieleserver und Ihrem Spieleclient verwendet wird. Sie können den Zertifikatpfad verwenden, wenn Sie Ihr Rechengerät bei einer Amazon GameLift Anywhere-Flotte registrieren. Weitere Informationen finden Sie unter RegisterCompute.

Syntax

func GetComputeCertificate() (result.GetComputeCertificateResult, error)

Rückgabewert

Gibt ein GetComputeCertificateResult Objekt zurück, das Folgendes enthält:

• CertificatePath: Der Pfad zum TLS-Zertifikat auf Ihrer Rechenressource. Wenn Sie eine von Amazon GameLift verwaltete Flotte verwenden, enthält dieser Pfad:

  • certificate.pem: Das Endbenutzerzertifikat. Die vollständige Zertifikatkette ist die Kombination von , die an dieses Zertifikat certificateChain.pem angehängt ist.

  • certificateChain.pem: Die Zertifikatkette, die das Stammzertifikat und Zwischenzertifikate enthält.

  • rootCertificate.pem: Das Stammzertifikat.

  • privateKey.pem: Der private Schlüssel für das Endbenutzerzertifikat.

• ComputeName: Der Name Ihrer Rechenressource.

Beispiel

tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

GetFleetRoleCredentials()

Ruft die Anmeldeinformationen der Servicerolle ab, die Sie erstellen, um die Berechtigungen auf Ihre anderen auf Amazon AWS-Services zu erweitern GameLift. Diese Anmeldeinformationen ermöglichen es Ihrem Spieleserver, Ihre -AWSRessourcen zu nutzen. Weitere Informationen finden Sie unter Einrichten einer IAM-Servicerolle für Amazon GameLift.

Syntax

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

Parameter

GetFleetRoleCredentialsRequest

Rollenanmeldeinformationen, die den eingeschränkten Zugriff auf Ihre AWS Ressourcen auf den Spieleserver erweitern.

Rückgabewert

Gibt ein GetFleetRoleCredentialsResult Objekt zurück, das Folgendes enthält:

• AssumedRoleUserArn – Der Amazon-Ressourcenname (ARN) des Benutzers, zu dem die Servicerolle gehört.

• AssumedRoleId – Die ID des Benutzers, zu dem die Servicerolle gehört.

• AccessKeyId – Die Zugriffsschlüssel-ID zur Authentifizierung und Bereitstellung des Zugriffs auf Ihre -AWSRessourcen.

• SecretAccessKey – Die ID des geheimen Zugriffsschlüssels für die Authentifizierung.

• SessionToken – Ein Token zur Identifizierung der aktuellen aktiven Sitzung, die mit Ihren -AWSRessourcen interagiert.

• Ablauf – Die Zeit bis zum Ablauf Ihrer Sitzungsanmeldeinformationen.

Beispiel

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

credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest)

Zerstören ()

Entlastet das Amazon GameLift Game Server SDK aus dem Speicher. Als bewährte Methode rufen Sie diese Methode nach ProcessEnding() und auf, bevor Sie den Prozess beenden. Wenn Sie eine Anywhere-Flotte verwenden und Serverprozesse nicht nach jeder Spielsitzung beenden, rufen Sie Destroy() und auf, um sie neu InitSDK() zu initialisieren, bevor Sie Amazon benachrichtigen GameLift , dass der Prozess bereit ist, eine Spielsitzung mit zu hostenProcessReady().

Syntax

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

Rückgabewert

Gibt einen Fehler mit einer Fehlermeldung zurück, wenn die Methode fehlschlägt.

Beispiel

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