Débogage local des serveurs de jeu et intégration à PlayFab

​

Vue d’ensemble

​

Configuration de base - Windows

• Intégrez votre serveur de jeu au GSDK et générez-le. Pour plus d’informations, consultez Intégration des serveurs de jeu au SDK du serveur de jeu PlayFab (GSDK).
• Compressez votre serveur de jeu et ses dépendances dans une archive zip. Pour une exécution correcte en mode conteneur, l’archive zip doit contenir toutes les DLL système qui ne sont pas incluses dans l’image de conteneur. Pour plus d’informations, consultez Déterminer les DLL système requises.

• Téléchargez l’ensemble d’outils de débogage local et extrayez-le dans le dossier de votre choix (par exemple C:\PlayFabVmAgent).
• En examinant le fichier json du générateur LocalMultiplayerAgent MultiplayerSettings.json, lisez les informations ci-dessous sur les options suivantes.
• Accédez à l’emplacement du dossier extrait et ouvrez le fichier MultiplayerSettings.json dans un éditeur de texte (tel que Visual Studio Code). Mettez à jour les propriétés suivantes :
  • LocalFilePath : chemin local complet (sur votre station de travail) du fichier zip des ressources du serveur de jeu créé précédemment, par exemple : D:\\MyAmazingGame\\asset.zip (notez que les barres obliques inverses doivent être échappées pour le format JSON).
  • StartGameCommand : chemin complet de l’exécutable du serveur de jeu dans le conteneur. Par exemple, si l’exécutable s’appelle mygame.exe, un exemple de chemin serait C:\\Assets\\mygame.exe. Les chemins de StartGameCommand diffèrent pour un processus et pour un conteneur. Pour un conteneur, le chemin StartGameCommand est un chemin absolu vers une ressource du conteneur ou du dossier des ressources. Pour un processus, le chemin StartGameCommand est un chemin relatif, le répertoire de travail étant la première ressource spécifiée.
  • PortMappingsList : il s’agit des ports disponibles pour votre jeu pendant son exécution. NodePort est le port ouvert sur votre station de travail ; GamePort.Number est le port auquel votre serveur de jeu doit se lier lorsqu’il s’exécute dans un conteneur. Mettez à jour la section GamePort pour qu’elle corresponde au protocole et au port sur lesquels votre serveur de jeu écoute les clients. Si votre serveur de jeu a besoin de plusieurs ports, copiez-collez la configuration de port existante, incrémentez NodePort, puis mettez à jour GamePort.Number et GamePort.Name avec le port requis. En mode processus, GamePort.Number est ignoré ; votre processus doit se lier au NodePort. Pour gérer les deux cas, procédez de l’une des manières suivantes :
    • Définissez les ports sur la même valeur
    • Vérifiez dans la configuration du GSDK, au moment de l’exécution, la valeur associée à la clé GamePort.Name, qui renvoie toujours le port correct auquel se lier.
• Le fichier MultiplayerSettings.json contient d’autres champs que vous pouvez souhaiter modifier :
  • ResourceLimits (facultatif) : s’il est spécifié, Docker limite l’utilisation du processeur et de la mémoire. Avertissement : si votre serveur dépasse la mémoire autorisée, il est arrêté. ResourceLimits ne peut être spécifié qu’en mode conteneur.
  • SessionCookie (facultatif) : tout cookie de session transmis à votre serveur de jeu dans le cadre de l’appel de l’API RequestMultiplayerServer.
  • OutputFolder (facultatif) : chemin absolu d’un lecteur ou d’un dossier dans lequel les sorties et les fichiers de configuration sont générés. Assurez-vous de disposer de suffisamment d’espace, car le serveur de jeu sera extrait sous ce chemin. Si ce champ n’est pas spécifié, le dossier de l’agent est utilisé.
  • MountPath : chemin du conteneur auquel monter la ressource. Ce champ n’a pas besoin d’être spécifié en mode processus. Nous recommandons d’utiliser la valeur d’exemple C:\\Assets (notez que les barres obliques inverses doivent être échappées pour le format JSON).
  • AgentListeningPort : spécifie le port auquel l’agent se lie pour communiquer avec le serveur de jeu. N’importe quel port ouvert convient ; si un autre processus est lié au port 56001, vous devez modifier cette valeur (ou arrêter l’autre processus).

​

Vérification de l’intégration du GSDK

• Dans le fichier MultiplayerSettings.json, définissez RunContainer sur false.
• Dans une fenêtre PowerShell (en tant qu’administrateur) :
  • Remplacez votre répertoire de travail par le dossier dans lequel l’ensemble d’outils a été extrait.
  • Exécutez LocalMultiplayerAgent.exe. À ce stade, LocalMultiplayerAgent configure l’écouteur http, décompresse les ressources du jeu et démarre le serveur de jeu dans un processus distinct. LocalMultiplayerAgent attend ensuite les pulsations du GSDK intégré à votre serveur de jeu.
• Si le GSDK est correctement intégré, LocalMultiplayerAgent affiche les sorties suivantes :
  • CurrentGameState - Initializing (facultatif ; cette ligne peut ne pas s’afficher si votre serveur de jeu appelle directement GSDK::ReadyForPlayers sans appeler GSDK::Start)
  • CurrentGameState - StandingBy
  • CurrentGameState - Active
  • CurrentGameState - Terminating
• Si les rappels d’arrêt sont correctement configurés, votre serveur de jeu se ferme peu après le passage à l’état Terminating. Il est important de vérifier que le serveur de jeu se ferme afin d’éviter des arrêts non contrôlés sur la plateforme PlayFab.
• LocalMultiplayerAgent doit également se terminer en même temps que le jeu.

​

Test de la connexion à votre jeu

​

Vérification de la conteneurisation

​

Prérequis

• Windows 10 Professionnel (ou version ultérieure) avec la mise à jour d’avril 2018 (1803).
• Téléchargez Docker. Vous pouvez également le télécharger depuis la page principale du site web Docker.

​

Configuration

• Assurez-vous que Docker est configuré pour utiliser les conteneurs Windows
• Dans une fenêtre PowerShell (en tant qu’administrateur) :
  • Accédez au dossier dans lequel l’ensemble d’outils a été extrait.
  • Exécutez Setup.ps1, qui configure les réseaux Docker, ajoute des règles de pare-feu permettant de communiquer avec LocalMultiplayerAgent et télécharge l’image Docker PlayFab depuis Microsoft/PlayFab-Multiplayer. Notez que lors de la première exécution du script, le téléchargement de l’image de conteneur peut prendre quelques minutes.

​

Exécution du serveur de jeu dans un conteneur

• Dans le fichier MultiplayerSettings.json, définissez RunContainer sur true.
• Ouvrez une fenêtre PowerShell (en tant qu’administrateur) dans le dossier où l’ensemble d’outils a été extrait (C:\PlayFabVmAgent) et exécutez LocalMultiplayerAgent.exe. Le serveur de jeu démarre alors dans un conteneur. Vous devriez finir par voir les changements d’état du jeu s’afficher dans la fenêtre PowerShell (comme dans la section Vérification de l’intégration du GSDK ci-dessus).

​

Test de la connexion à votre serveur de jeu exécuté dans un conteneur

​

Utilisation de LocalMultiplayerAgent avec des conteneurs Linux

• Téléchargez la dernière version de LocalMultiplayerAgent depuis la page Releases sur GitHub
• Installez Docker Desktop sur Windows
• Assurez-vous qu’il s’exécute en mode conteneurs Linux
• Vous devez monter l’un de vos disques durs ; vous trouverez des instructions ici
• Votre image de serveur de jeu peut être publiée dans un registre de conteneurs ou générée localement.
• Exécutez le fichier PowerShell SetupLinuxContainersOnWindows.ps1, qui crée un réseau Docker appelé “PlayFab”
• Configurez correctement le fichier LocalMultiplayerSettings.json. Voici un exemple, inclus dans MultiplayerSettingsLinuxContainersOnWindowsSample.json :

{
    "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" ]
    }
}

• Une fois toutes les étapes précédentes effectuées, vous pouvez exécuter LocalMultiPlayerAgent avec la commande LocalMultiplayerAgent.exe -lcow (lcow signifie Linux Containers On Windows)

​

Résolution des problèmes

• En mode conteneur, votre serveur de jeu peut se fermer immédiatement avec une erreur semblable à “Container … exited with exit code 1”, tout en fonctionnant correctement en mode processus. Dans ce cas, assurez-vous d’avoir inclus toutes les DLL système requises dans votre package de ressources.
• Tous les journaux se trouvent sous le OutputFolder spécifié dans le fichier MultiplayerSettings.json. LocalMultiplayerAgent crée un nouveau dossier à chaque démarrage, avec l’horodatage comme nom de dossier. Tous les journaux du serveur de jeu émis via le GSDK se trouvent dans le dossier GameLogs.
  Si le serveur de jeu s’exécute dans un conteneur, il peut y avoir un niveau supplémentaire dans la hiérarchie des répertoires à parcourir.
• Le GSDK écrit des journaux de débogage dans le dossier GameLogs. Ces journaux se trouvent dans le dossier GameLogs, avec les journaux générés par le serveur de jeu.
• Assurez-vous que les pare-feu (Windows et autres antivirus) sont configurés pour autoriser le trafic sur les ports.
• Si vous obtenez une erreur semblable à : 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. Cela peut se produire si LocalMultiplayerAgent se ferme prématurément. Utilisez la commande docker ps pour trouver le conteneur en cours d’exécution, puis arrêtez-le à l’aide de docker kill <container_name>.
• Si vous obtenez une erreur contenant Failed to find network 'playfab', essayez de réexécuter Setup.ps1
• Si vous obtenez une erreur Unhandled Exception, il est possible que vous exécutiez PowerShell en tant qu’administrateur.
• OutputFolder peut à son tour être utilisé par d’autres variables système ; veillez donc à utiliser un chemin absolu. Par exemple, GSDK_CONFIG_FILE dépend de cette valeur ; un chemin relatif (ou une valeur incorrecte) peut donc entraîner des erreurs de chargement de la configuration du serveur de jeu.

​

Limitations connues

1. Il est possible que les conteneurs ne s’arrêtent pas à la fin du débogage. Dans ce cas, exécutez les commandes PowerShell suivantes en tant qu’administrateur. Ces commandes arrêtent et suppriment tous les conteneurs, y compris ceux qui n’ont pas été démarrés par LocalMultiplayerAgent.

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