Lokales Debuggen von Spielservern und Integration in PlayFab

Artikel
07/11/2023

Übersicht

PlayFab-Multiplayer-Spieleserver erfordern die Integration in das PlayFab Game Server SDK (GSDK). Darüber hinaus werden Spieleserver als Containeranwendungen auf der PlayFab Multiplayer-Plattform ausgeführt.

Die Ausführung als Containeranwendungen ermöglicht das lokale Ausführen und Debuggen des Servers in einer Umgebung, die der PlayFab-Plattform in Azure entspricht. Dies ermöglicht schnellere Entwicklungsiterationen. In diesem Artikel können Sie überprüfen, ob Ihr PlayFab-Spielserver den Plattformanforderungen entspricht.

Das lokale PlayFab-Toolset enthält LocalMultiplayerAgent , das Simulierte Antworten auf das GSDK bereitstellt und überprüft, ob Ihr Spielserver ordnungsgemäß in das GSDK integriert ist. Mit den Simulierten Antworten durchläuft der VmAgent den Spielserver durch verschiedene Zustände in seinem Lebenszyklus auf der PlayFab Multiplayer-Plattform.

Sie können den Agent so konfigurieren, dass der Spielserver als Containeranwendung ausgeführt wird. Vergewissern Sie sich, dass Ihr Spielserver mit allen erforderlichen Abhängigkeiten gepackt ist und ohne Probleme auf der PlayFab Multiplayer-Plattform ausgeführt wird. LocalMultiplayerAgent kann mit Windows- oder Linux-Spielservern verwendet werden.

Grundlegendes Setup – Windows

Integrieren Sie Ihren Spielserver in das GSDK, und erstellen Sie ihn. Weitere Informationen finden Sie unter Integrieren von Spielservern in das PlayFab Game Server SDK (GSDK).
Komprimieren Sie Ihren Spielserver und seine Abhängigkeiten in ein ZIP-Archiv. Um im Containermodus ordnungsgemäß ausgeführt zu werden, muss das ZIP-Archiv alle System-DLLs enthalten, die nicht im Containerimage enthalten sind. Weitere Informationen finden Sie unter Ermitteln der erforderlichen System-DLLs.

Notiz

Vermeiden Sie diesen häufigen Fehler: Zippen Sie nicht versehentlich einen Ordner innerhalb eines Ordners in der ZIP-Datei. Durchsuchen Sie nach dem Zippen den ZIP-Ordner, und überprüfen Sie, ob Ihre Komprimierungssoftware keine zusätzliche Ebene der Dateihierarchie hinzugefügt hat.
Laden Sie das lokale Debugtoolset herunter, und extrahieren Sie es in einen Ordner Ihrer Wahl (z. B. C:\PlayFabVmAgent).
Lesen Sie beim Untersuchen der JSON-Datei LocalMultiplayerAgent MultiplayerSettings.json Generator weiter unten mehr über die folgenden Optionen.
Navigieren Sie zum Speicherort des extrahierten Ordners, und öffnen Sie die MultiplayerSettings.json-Datei in einem Text-Editor (z. B. Visual Studio Code). Aktualisieren Sie die folgenden Eigenschaften:
- LocalFilePath – Vollständiger lokaler Pfad (auf Ihrer Arbeitsstation) zur zuvor erstellten ZIP-Datei des Spielserverobjekts, z. B.D:\\MyAmazingGame\\asset.zip (beachten Sie, dass umgekehrte Schrägstriche für die JSON-Formatierung mit Escapezeichen versehen werden müssen).
- StartGameCommand : Der vollständige Pfad zur ausführbaren Datei des Spielservers im Container. Wenn der Name der ausführbaren Datei beispielsweise mygame.exelautet, lautet ein Beispielpfad C:\\Assets\\mygame.exe. Die Pfade für startGameCommand unterscheiden sich für einen Prozess und einen Container. Der StartGameCommand-Pfad für einen Container ist ein absoluter Pfad zu einer Ressource im Container oder Ressourcenordner. Der StartGameCommand-Pfad für einen Prozess ist ein relativer Pfad, bei dem das Arbeitsverzeichnis das erste angegebene Objekt ist.
- PortMappingsList - Dies sind die Ports, die für Ihr Spiel während der Ausführung verfügbar sind. NodePort ist der Port, der auf Ihrer Arbeitsstation geöffnet wird, ist der Port, GamePort.Number an den Ihr Spielserver bei der Ausführung in einem Container gebunden werden muss. Aktualisieren Sie den Abschnitt GamePort so, dass er dem Protokoll und port entspricht, an dem Ihr Spielserver auf Clients lauscht. Wenn Ihr Spielserver mehrere Ports benötigt, kopieren Sie die vorhandene Portkonfiguration und inkrementieren NodePort sie, und aktualisieren GamePort.Number Sie dann und GamePort.Name auf den erforderlichen Port. Wenn als Prozess ausgeführt wird, GamePort.Number wird ignoriert, sollte Ihr Prozess an NodePort gebunden werden. Führen Sie einen der folgenden Schritte aus, um beide Fälle zu behandeln:
  - Festlegen der Ports auf denselben Wert
  - Überprüfen Sie die GSDK-Konfiguration zur Laufzeit auf den Wert mit dem Schlüssel GamePort.Name , der immer den richtigen Port für die Bindung zurückgibt.
Die MultiplayerSettings.json Datei enthält zusätzliche Felder, die Sie möglicherweise bearbeiten möchten:
- ResourceLimits (optional): Falls angegeben, schränkt Docker die CPU-/Arbeitsspeicherauslastung ein. Warnung: Wenn Ihr Server den zulässigen Arbeitsspeicher überschreitet, wird er beendet. ResourceLimits kann nur im Containermodus angegeben werden.
- SessionCookie (optional): Alle Sitzungscookies, die im Rahmen des RequestMultiplayerServer-API-Aufrufs an Ihren Spielserver übergeben werden.
- OutputFolder (optional): Absoluter Pfad zu einem Laufwerk oder Ordner, in dem die Ausgaben und Konfigurationsdateien generiert werden. Stellen Sie sicher, dass genügend Speicherplatz verfügbar ist, da der Spielserver unter diesem Pfad extrahiert wird. Wenn nicht angegeben, wird der Agent-Ordner verwendet.
- MountPath – Der Pfad innerhalb des Containers, an dem die Ressource bereitgestellt werden soll. Dieses Feld muss bei der Ausführung im Prozessmodus nicht angegeben werden. Es wird empfohlen, den Beispielwert C:\\Assets zu verwenden (beachten Sie, dass umgekehrte Schrägstriche für die JSON-Formatierung mit Escapezeichen versehen werden müssen).
- AgentListeningPort – Gibt den Port an, an den der Agent gebunden ist, um mit dem Spielserver zu kommunizieren. Jeder geöffnete Port funktioniert. Wenn Sie über eine andere Prozessbindung zu 56001 verfügen, müssen Sie diesen Wert ändern (oder den anderen Prozess beenden).

Überprüfen der GSDK-Integration

Legen Sie in der MultiplayerSettings.json-Datei auf fest RunContainerfalse.
In einem PowerShell-Fenster (als Administrator):
- Ändern Sie Ihr Arbeitsverzeichnis in den Ordner, in den das Toolset extrahiert wurde.
- Führen Sie LocalMultiplayerAgent.exeaus. An diesem Punkt richtet LocalMultiplayerAgent den HTTP-Listener ein, entpackt das Spielobjekt und startet den Spielserver in einem separaten Prozess. LocalMultiplayerAgent wartet dann auf Heartbeats aus dem GSDK, das in Ihren Spielserver integriert ist.
Wenn das GSDK ordnungsgemäß integriert ist, gibt LocalMultiplayerAgent die folgenden Ausgaben aus:
- CurrentGameState - Initializing (Dies ist optional und wird möglicherweise nicht angezeigt, wenn Ihr Spielserver direkt aufruft GSDK::ReadyForPlayers und nicht aufruft GSDK::Start)
- CurrentGameState - StandingBy
- CurrentGameState - Active
- CurrentGameState - Terminating
Wenn die Rückrufe zum Herunterfahren ordnungsgemäß eingerichtet sind, wird ihr Spielserver kurz nach dem Beenden des Zustands beendet. Es ist wichtig, sicherzustellen, dass der Spielserver beendet wird, um nicht ordnungsgemäßes Herunterfahren auf der PlayFab-Plattform zu vermeiden.
Der LocalMultiplayerAgent sollte ebenfalls zusammen mit dem Spiel beendet werden.

Testen der Verbindung mit Ihrem Spiel

Wenn die ausführbare Datei Ihres Spielservers CurrentGameState - Activeausgeführt wird und LocalMultiplayerAgent ausgibt, können Sie eine Verbindung mit Ihrem Spielserver herstellen, indem Sie die IP-Adresse 127.0.0.1 und den Port NodePort verwenden, an dem Ihr Spielserver lauscht.

Nach Heartbeats NumHeartBeatsForActivateResponse fordert LocalMultiplayerAgent den Spielserver auf, vom Standbymodus in den aktiven Modus zu wechseln. Nach heartbeats NumHeartBeatsForTerminateResponse fordert LocalMultiplayerAgent den Spielserver auf, von aktiv zu beendet zu wechseln. Dieses Verhalten kann durch Aktualisieren der Werte in der MultiplayerSettings.json-Datei optimiert werden.

Überprüfen der Containerisierung

Wenn Sie noch nicht mit der Containerwelt sind, können Sie sich hier eine Einführung ansehen.

Voraussetzungen

Windows 10 Pro (oder höher) mit dem Update vom April 2018 (1803).
Laden Sie Docker herunter. Alternativ können Sie sie von der seite Standard der Docker-Website herunterladen.

Einrichtung

Sicherstellen, dass Docker für die Verwendung von Windows-Containern festgelegt ist
In einem PowerShell-Fenster (als Administrator):
- Navigieren Sie zu dem Ordner, in den das Toolset extrahiert wurde.
- Führen Sie Setup.ps1 aus, die die Docker-Netzwerke einrichten, Firewallregeln für die Kommunikation mit LocalMultiplayerAgent hinzufügen und das PlayFab-Docker-Image aus Microsoft/PlayFab-Multiplayer pullen. Beachten Sie, dass es bei der ersten Ausführung des Skripts einige Minuten dauern kann, bis das Containerimage heruntergeladen wurde.
  
  Notiz
  
  Um dieses Setup erfolgreich auszuführen, müssen Sie möglicherweise die Firewall eines Antivirenprogramms eines Drittanbieters (z. B. McAfee, Norton oder Avira) konfigurieren, das Sie installiert haben.

Ausführen des Spielservers in einem Container

Legen Sie in der MultiplayerSettings.json-Datei auf fest RunContainertrue.
Öffnen Sie ein PowerShell-Fenster (als Administrator) in dem Ordner, in den das Toolset extrahiert wurde (C:\PlayFabVmAgent), und führen Sie aus LocalMultiplayerAgent.exe. Dadurch wird der Spielserver in einem Container gestartet. Schließlich sollte die Ausgabe der Spielzustandsänderung im PowerShell-Fenster angezeigt werden (genau wie im Abschnitt Überprüfen der GSDK-Integration oben).

Testen der Verbindung mit ihrem Spielserver, der in einem Container ausgeführt wird

Wenn localMultiplayerAgent-Ausgabe ausgibt CurrentGameState - Active, stellen Sie eine Verbindung mit Ihrem Spielserver her, indem Sie die IP-Adresse 127.0.0.0.1 und den Port NodePort (standardmäßig 56100) verwenden, der in der MultiplayerSettings.json-Datei angegeben ist.

Verwenden von LocalMultiplayerAgent mit Linux-Containern

Sie können LocalMultiplayerAgent verwenden, um Ihren Linux-Spielserver zu debuggen, indem Sie ihn mithilfe von Docker für Windows in einem Container in Windows ausführen. Weitere Informationen zum Ausführen von Linux-Containern unter Windows finden Sie hier. Im Wesentlichen müssen Sie nur den Agent mit dem Parameter -lcow ausführen und Ihre LocalMultiplayerSettings.json-Datei ordnungsgemäß konfigurieren.

Um Ihre containerisierten Linux-Spieleserver unter Windows auszuführen, müssen Sie die folgenden Schritte ausführen:

Laden Sie die neueste Version von LocalMultiplayerAgent von der Releaseseite auf GitHub herunter.
Installieren von Docker Desktop unter Windows
Stellen Sie sicher, dass sie unter Linux-Containern ausgeführt wird.
Sie sollten eine Ihrer Festplatten einbinden. Anweisungen finden Sie hier.
Ihr Spielserverimage kann in einer Containerregistrierung veröffentlicht oder lokal erstellt werden.
Führen Sie SetupLinuxContainersOnWindows.ps1 eine PowerShell-Datei aus, die ein Docker-Netzwerk namens "PlayFab" erstellt.
Konfigurieren Sie die LocalMultiplayerSettings.json-Datei ordnungsgemäß. Unten sehen Sie ein Beispiel, das in MultiplayerSettingsLinuxContainersOnWindowsSample.jsonenthalten ist:

{
    "RunContainer": true,
    "OutputFolder": "C:\\output\\UnityServerLinux",
    "NumHeartBeatsForActivateResponse": 10,
    "NumHeartBeatsForTerminateResponse": 60,
    "TitleId": "",
    "BuildId": "00000000-0000-0000-0000-000000000000",
    "Region": "WestUs",
    "AgentListeningPort": 56001,
    "ContainerStartParameters": {
        "ImageDetails": {
            "Registry": "mydockerregistry.io",
            "ImageName": "mygame",
            "ImageTag": "0.1",
            "Username": "",
            "Password": ""
        }
    },
    "PortMappingsList": [
        [
            {
                "NodePort": 56100,
                "GamePort": {
                    "Name": "game_port",
                    "Number": 7777,
                    "Protocol": "TCP"
                }
            }
        ]
    ],
    "SessionConfig": {
        "SessionId": "ba67d671-512a-4e7d-a38c-2329ce181946",
        "SessionCookie": null,
        "InitialPlayers": [ "Player1", "Player2" ]
    }
}

Einige Hinweise:

Sie müssen auf true festlegen RunContainer . Dies ist für Linux-Spieleserver erforderlich.

Ändern Sie imageDetails mit den Docker-Imagedetails Ihres Spieleservers. Das Image kann lokal erstellt werden (mit dem Befehl docker build ) oder in einer Remotecontainerregistrierung gehostet werden.

StartGameCommand und AssetDetails sind optional. Sie verwenden sie normalerweise nicht, wenn Sie einen Docker-Container verwenden, da alle Spielobjekte und der Befehl zum Starten des Spieleservers in der entsprechenden Dockerfile-Datei gepackt werden können.

Achten Sie zu guter Letzt auf die Groß-/Kleinschreibung Ihrer OutputFolder Variablen, da bei Linux-Containern die Groß-/Kleinschreibung beachtet wird. Wenn die Groß-/Kleinschreibung falsch ist, Möglicherweise wird beim Erstellen des Bereitstellungsquellpfads "/host_mnt/c/output/UnityServerLinux/PlayFabVmAgentOutput/2020-01-30T12-47-2020-01-30T12-47-47-2020 eine Docker-Ausnahme ähnlich wie ein Fehler angezeigt.09/GameLogs/a94cfbb5-95a4-480f-a4af-749c2d9cf04b': mkdir /host_mnt/c/output: file exists

Nachdem Sie alle vorherigen Schritte ausgeführt haben, können Sie localMultiPlayerAgent mit dem Befehl LocalMultiplayerAgent.exe -lcow ausführen (lcow steht für Linux-Container unter Windows).

Problembehandlung

Im Containermodus, wenn Ihr Spielserver sofort mit einem Fehler wie "Container ... exited with exit code 1", but it works in process mode.exited with exit code 1", but it works in process mode. <Stellen Sie sicher, dass Sie alle erforderlichen System-DLLs in Ihr Ressourcenpaket eingeschlossen haben.
Alle Protokolle befinden sich unter OutputFolder , das in der MultiplayerSettings.json-Datei angegeben ist. LocalMultiplayerAgent erstellt bei jedem Start einen neuen Ordner mit dem Zeitstempel als Ordnernamen. Alle über GSDK ausgegebenen Spielserverprotokolle befinden sich im Ordner GameLogs.
Wenn der Spielserver in einem Container ausgeführt wird, gibt es möglicherweise eine zusätzliche Ebene der Verzeichnishierarchie, durch die Siehen können.
Das GSDK schreibt Debugprotokolle in den Ordner GameLogs. Diese Protokolle befinden sich zusammen mit den vom Spielserver ausgegebenen Protokollen im Ordner GameLogs.
Stellen Sie sicher, dass Firewalls (Windows und andere Virenschutz) so konfiguriert sind, dass der Datenverkehr über die Ports zugelassen wird.
Wenn Sie einen Fehler ähnlich dem folgenden erhalten: Docker API responded with status code=InternalServerError, response={"message":"failed to create endpoint <container_name> on network playfab: hnsCall failed in Win32: The specified port already exists". It's likely there is already a container running on the specified port. Dies kann passieren, wenn LocalMultiplayerAgent vorzeitig beendet wird. Verwenden Sie den Befehl docker ps , um den container zu suchen, der ausgeführt wird, und beenden Sie ihn dann mithilfe von docker kill <container_name>.
Wenn Sie einen Fehler erhalten, der enthält Failed to find network 'playfab'. Versuchen Sie erneut ,Setup.ps1
Wenn Sie einen Unhandled Exception Fehler erhalten, führen Sie PowerShell möglicherweise als Administrator aus.
OutputFolder kann wiederum von anderen Systemvariablen verwendet werden. Stellen Sie daher sicher, dass Sie einen absoluten Pfad verwendet haben. Für instance weist GSDK_CONFIG_FILE eine solche Abhängigkeit auf, sodass ein relativer Pfad (oder ein falscher Wert) hier zu Fehlern beim Laden der Spielserverkonfiguration führen kann.

Bekannte Einschränkungen

Container werden am Ende des Debuggens möglicherweise nicht beendet. Führen Sie in diesem Fall die folgenden PowerShell-Befehle als Administrator aus. Diese Befehle beenden und entfernen alle Container, einschließlich der container, die nicht von LocalMultiplayerAgent gestartet wurden.

docker stop $(docker ps -aq)
docker rm $(docker ps -aq)

Freigeben über