> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Débogage local des serveurs de jeu et intégration à PlayFab
> Explique comment intégrer les serveurs de jeu multijoueurs PlayFab au SDK du serveur de jeu PlayFab (GSDK), puis vérifier et déboguer l'intégration.
## Vue d'ensemble
Les serveurs de jeu multijoueurs PlayFab nécessitent une intégration au [SDK du serveur de jeu PlayFab (GSDK)](/fr/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk). En outre, les serveurs de jeu s'exécutent en tant qu'applications conteneurisées sur la plateforme PlayFab Multiplayer.
Leur exécution en tant qu'applications conteneurisées permet d'exécuter et de déboguer le serveur localement, dans un environnement identique à celui de la plateforme PlayFab dans Azure. Cela accélère les itérations de développement. Cet article vous aide à vérifier que votre serveur de jeu PlayFab est conforme aux exigences de la plateforme.
L'ensemble d'outils de débogage local de PlayFab comprend [LocalMultiplayerAgent](https://github.com/PlayFab/MpsAgent), qui fournit des réponses simulées au GSDK et vérifie si votre serveur de jeu est correctement intégré au GSDK. Grâce aux réponses simulées, le VmAgent fait passer le serveur de jeu par les différents états de son cycle de vie sur la plateforme PlayFab Multiplayer.
Vous pouvez configurer l'agent pour qu'il exécute le serveur de jeu en tant qu'application conteneurisée. Vérifiez que votre serveur de jeu est empaqueté avec toutes les dépendances requises et qu'il s'exécute sans problème sur la plateforme PlayFab Multiplayer. LocalMultiplayerAgent fonctionne avec les serveurs de jeu Windows comme Linux.
## 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)](/fr/services/playfab/multiplayer/servers/integrating-game-servers-with-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](/fr/services/playfab/multiplayer/servers/determining-required-dlls).
Évitez cette erreur courante : ne compressez pas par inadvertance un dossier *à l'intérieur* d'un dossier dans le zip. Après la compression, parcourez le dossier zip et vérifiez que votre logiciel de compression n'a pas ajouté de niveau supplémentaire à la hiérarchie des fichiers.
* Téléchargez l'[ensemble d'outils de débogage local](https://github.com/PlayFab/MpsAgent/releases) 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](https://github.com/PlayFab/MpsAgent/tree/main/LocalMultiplayerAgent/SettingsJsonGenerator), 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](https://code.visualstudio.com/download)). 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](xref:titleid.playfabapi.com.multiplayer.multiplayerserver.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
Lorsque l'exécutable de votre serveur de jeu est en cours d'exécution et que **LocalMultiplayerAgent** affiche `CurrentGameState - Active`, vous pouvez vous connecter à votre serveur de jeu à l'aide de l'adresse IP **127.0.0.1** et du port `NodePort` sur lequel votre serveur de jeu écoute.
Après `NumHeartBeatsForActivateResponse` pulsations, **LocalMultiplayerAgent** demande au serveur de jeu de passer de l'état en attente à l'état actif. Puis, après `NumHeartBeatsForTerminateResponse` pulsations, **LocalMultiplayerAgent** demande au serveur de jeu de passer de l'état actif à l'état arrêté. Ce comportement peut être ajusté en mettant à jour les valeurs du fichier *MultiplayerSettings.json*.
## Vérification de la conteneurisation
Si vous découvrez l'univers des conteneurs, vous pouvez consulter une introduction [ici](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/container-docker-introduction/).
### Prérequis
* Windows 10 Professionnel (ou version ultérieure) avec la mise à jour d'avril 2018 (1803).
* Téléchargez [Docker](https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe). Vous pouvez également le télécharger depuis la page principale du [site web Docker](https://www.docker.com/products/docker-desktop).
### Configuration
* Assurez-vous que Docker est configuré pour [utiliser les conteneurs Windows](https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers)
* 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](https://hub.docker.com/r/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.
Pour que cette configuration réussisse, vous devrez peut-être configurer le pare-feu de tout programme antivirus tiers (tel que McAfee, Norton ou Avira) que vous avez installé.
### 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
Lorsque la sortie de **LocalMultiplayerAgent** affiche `CurrentGameState - Active`, connectez-vous à votre serveur de jeu à l'aide de l'adresse IP **127.0.0.1** et du port égal au `NodePort` (par défaut **56100**) spécifié dans le fichier *MultiplayerSettings.json*.
Après `NumHeartBeatsForActivateResponse` pulsations, **LocalMultiplayerAgent** demande au serveur de jeu de passer de l'état en attente à l'état actif. Puis, après `NumHeartBeatsForTerminateResponse` pulsations, **LocalMultiplayerAgent** demande au serveur de jeu de passer de l'état actif à l'état arrêté. Ce comportement peut être ajusté en mettant à jour les valeurs du fichier *MultiplayerSettings.json*.
### Utilisation de LocalMultiplayerAgent avec des conteneurs Linux
Vous pouvez utiliser LocalMultiplayerAgent pour déboguer votre serveur de jeu Linux en l'exécutant dans un conteneur sous Windows à l'aide de [Docker pour Windows](https://docs.docker.com/docker-for-windows/). Vous trouverez plus d'informations sur l'exécution de conteneurs Linux sous Windows [ici](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/linux-containers). En substance, il vous suffit d'exécuter l'agent avec le paramètre *-lcow* et de configurer correctement votre fichier *LocalMultiplayerSettings.json*.
Pour exécuter vos serveurs de jeu Linux conteneurisés sous Windows, effectuez les étapes suivantes :
* Téléchargez la dernière version de LocalMultiplayerAgent depuis la page [Releases](https://github.com/PlayFab/MpsAgent/releases) sur GitHub
* [Installez Docker Desktop sur Windows](https://docs.docker.com/docker-for-windows/install/)
* Assurez-vous qu'il s'exécute en mode [conteneurs Linux](https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers)
* Vous devez monter l'un de vos disques durs ; vous trouverez des instructions [ici](https://docs.docker.com/docker-for-windows/#file-sharing)
* 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` :
```json theme={null}
{
"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" ]
}
}
```
Quelques remarques : 1. Vous devez définir
`RunContainer` sur true. Cette valeur est obligatoire pour les serveurs de jeu Linux.
2. Modifiez
`imageDetails` avec les détails de l'image Docker de votre serveur de jeu. L'image peut être générée localement (à l'aide de la commande [docker build](https://docs.docker.com/engine/reference/commandline/build/)) ou hébergée dans un registre de conteneurs distant.
3.
`StartGameCommand` et `AssetDetails` sont facultatifs. Vous ne les utilisez généralement pas avec un conteneur Docker, car toutes les ressources du jeu et la commande de démarrage du serveur de jeu peuvent être empaquetées dans le [Dockerfile](https://docs.docker.com/engine/reference/builder/) correspondant
4. Enfin, et surtout, faites attention à la casse de votre
variable `OutputFolder`, car les conteneurs Linux sont sensibles à la casse. Si la casse est incorrecte, vous pouvez rencontrer une exception Docker semblable à *error while creating mount source path '/host\_mnt/c/output/UnityServerLinux/PlayFabVmAgentOutput/2020-01-30T12-47-09/GameLogs/a94cfbb5-95a4-480f-a4af-749c2d9cf04b': mkdir /host\_mnt/c/output: file exists*
* 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](/fr/services/playfab/multiplayer/servers/determining-required-dlls) 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 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 `.
* 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**.
```powershell theme={null}
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)
```
## Related topics
- [Notions de base d'un serveur de jeu PlayFab](/fr/services/playfab/multiplayer/servers/basics-of-a-playfab-game-server.md)
- [Exemple Wrapper](/fr/services/playfab/multiplayer/servers/wrapper-sample.md)
- [Créer une build de serveur de jeu](/fr/services/playfab/multiplayer/servers/author-a-game-server-build.md)
- [Intégrer des serveurs de jeu au GSDK PlayFab](/fr/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk.md)
- [Serveurs de jeu et lobbies](/fr/services/playfab/multiplayer/lobby/lobby-server-overview.md)