> ## 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.
# Depurando servidores de jogo localmente e integração com o PlayFab
> Descreve como integrar servidores de jogo multijogador do PlayFab ao PlayFab Game Server SDK (GSDK) e como verificar e depurar a integração.
## Visão geral
Os servidores de jogo multijogador do PlayFab exigem integração com o [PlayFab Game Server SDK (GSDK)](/pt-BR/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk). Além disso, os servidores de jogo são executados como aplicativos em contêineres na plataforma PlayFab Multiplayer.
Executá-los como aplicativos em contêineres permite executar e depurar o servidor localmente, em um ambiente que corresponde ao da plataforma PlayFab no Azure. Isso facilita iterações de desenvolvimento mais rápidas. Este artigo ajuda você a verificar se o seu servidor de jogo do PlayFab está em conformidade com os requisitos da plataforma.
O conjunto de ferramentas de depuração local do PlayFab inclui o [LocalMultiplayerAgent](https://github.com/PlayFab/MpsAgent), que fornece respostas simuladas ao GSDK e verifica se o seu servidor de jogo está integrado corretamente ao GSDK. Com as respostas simuladas, o VmAgent percorre com o servidor de jogo os vários estados do seu ciclo de vida na plataforma PlayFab Multiplayer.
Você pode configurar o agente para executar o servidor de jogo como um aplicativo em contêiner. Verifique se o seu servidor de jogo está empacotado com todas as dependências necessárias e é executado sem problemas na plataforma PlayFab Multiplayer. O LocalMultiplayerAgent funciona com servidores de jogo Windows ou Linux.
## Configuração básica - Windows
* Integre seu servidor de jogo ao GSDK e crie-o. Para obter mais informações, consulte [Integrando servidores de jogo ao PlayFab Game Server SDK (GSDK)](/pt-BR/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk).
* Compacte seu servidor de jogo e as dependências dele em um arquivo zip. Para ser executado corretamente no modo de contêiner, o arquivo zip deve conter todas as DLLs do sistema que não estão incluídas na imagem de contêiner. Para obter mais informações, consulte [determinar as DLLs do sistema necessárias](/pt-BR/services/playfab/multiplayer/servers/determining-required-dlls).
Evite este erro comum: não compacte acidentalmente uma pasta *dentro* de uma pasta no zip. Depois de compactar, navegue pela pasta zip e verifique se o seu software de compactação não adicionou uma camada extra à hierarquia de arquivos.
* Baixe o [conjunto de ferramentas de depuração local](https://github.com/PlayFab/MpsAgent/releases) e extraia-o para uma pasta de sua escolha (como *C:\PlayFabVmAgent*).
* Ao inspecionar o arquivo json do [Gerador de MultiplayerSettings.json do LocalMultiplayerAgent](https://github.com/PlayFab/MpsAgent/tree/main/LocalMultiplayerAgent/SettingsJsonGenerator), leia mais sobre as opções abaixo.
* Navegue até o local da pasta extraída e abra o arquivo *MultiplayerSettings.json* em um editor de texto (como o [Visual Studio Code](https://code.visualstudio.com/download)). Atualize as seguintes propriedades:
* `LocalFilePath`: caminho local completo (na sua estação de trabalho) para o arquivo zip de ativos do servidor de jogo criado anteriormente, por exemplo: *D:\\\MyAmazingGame\\\asset.zip* (observe que as barras invertidas precisam ser escapadas para a formatação JSON).
* `StartGameCommand`: o caminho completo para o executável do servidor de jogo dentro do contêiner. Por exemplo, se o nome do executável for *mygame.exe*, um caminho de exemplo seria *C:\\\Assets\\\mygame.exe*. Os caminhos de StartGameCommand são diferentes para um processo e para um contêiner. O caminho de StartGameCommand para um contêiner é um caminho absoluto para um recurso no contêiner ou na pasta de ativos. O caminho de StartGameCommand para um processo é um caminho relativo, em que o diretório de trabalho será o primeiro ativo especificado.
* `PortMappingsList`: são as portas disponíveis para o seu jogo durante a execução. `NodePort` é a porta aberta na sua estação de trabalho, e `GamePort.Number` é a porta à qual o servidor de jogo precisa se associar ao ser executado em um contêiner. Atualize a seção GamePort para corresponder ao protocolo e à porta em que seu servidor de jogo escuta os clientes. Se o seu servidor de jogo precisar de várias portas, copie/cole a configuração de porta existente, incremente `NodePort` e atualize `GamePort.Number` e `GamePort.Name` para a porta necessária. Ao executar como um processo, `GamePort.Number` é ignorado, e seu processo deve se associar à NodePort. Para lidar com ambos os casos, faça uma das seguintes ações:
* Defina as portas com o mesmo valor
* Verifique em runtime, na configuração do GSDK, o valor com a chave `GamePort.Name`, que sempre retorna a porta correta à qual se associar.
* Há campos adicionais no arquivo *MultiplayerSettings.json* que talvez você queira editar:
* `ResourceLimits` (opcional): se especificado, o docker limita o uso de CPU/memória. Aviso: se o seu servidor ultrapassar a memória permitida, ele será encerrado. ResourceLimits só pode ser especificado no modo de contêiner.
* `SessionCookie` (opcional): qualquer cookie de sessão que é passado ao seu servidor de jogo como parte da chamada à [API RequestMultiplayerServer](xref:titleid.playfabapi.com.multiplayer.multiplayerserver.requestmultiplayerserver).
* `OutputFolder` (opcional): caminho absoluto para uma unidade ou pasta em que as saídas e os arquivos de configuração são gerados. Verifique se há espaço suficiente disponível, pois o servidor de jogo será extraído nesse caminho. Se não for especificado, a pasta do agente será usada.
* `MountPath`: o caminho dentro do contêiner no qual o ativo será montado. Esse campo não precisa ser especificado ao executar no modo de processo. Recomendamos usar o valor de exemplo: *C:\\\Assets* (observe que as barras invertidas precisam ser escapadas para a formatação JSON).
* `AgentListeningPort`: especifica a porta à qual o agente se associa para se comunicar com o servidor de jogo. Qualquer porta aberta funcionará; se houver outro processo associado à porta 56001, você deverá alterar esse valor (ou encerrar o outro processo).
## Verificando a integração do GSDK
* No arquivo *MultiplayerSettings.json*, defina `RunContainer` como `false`.
* Em uma janela do Powershell (como Administrador):
* Altere seu diretório de trabalho para a pasta em que o conjunto de ferramentas foi extraído.
* Execute *LocalMultiplayerAgent.exe*. Neste ponto, o **LocalMultiplayerAgent** configura o ouvinte http, descompacta o ativo do jogo e inicia o servidor de jogo em um processo separado. Em seguida, o **LocalMultiplayerAgent** aguarda as pulsações do GSDK integrado ao seu servidor de jogo.
* Se o GSDK estiver integrado corretamente, o **LocalMultiplayerAgent** imprimirá as seguintes saídas:
* `CurrentGameState - Initializing` (isso é opcional e pode não aparecer se o seu servidor de jogo chamar `GSDK::ReadyForPlayers` diretamente e não chamar `GSDK::Start`)
* `CurrentGameState - StandingBy`
* `CurrentGameState - Active`
* `CurrentGameState - Terminating`
* Se os retornos de chamada de desligamento estiverem configurados corretamente, o servidor de jogo será encerrado logo depois que o estado for definido como Terminating. É importante verificar se o servidor de jogo é encerrado, para evitar desligamentos abruptos na plataforma PlayFab.
* O **LocalMultiplayerAgent** também deve ser encerrado junto com o jogo.
### Testando a conexão com o seu jogo
Quando o executável do servidor de jogo estiver em execução e o **LocalMultiplayerAgent** imprimir `CurrentGameState - Active`, você poderá se conectar ao seu servidor de jogo usando o endereço IP **127.0.0.1** e a porta `NodePort` na qual o servidor de jogo está escutando.
Após `NumHeartBeatsForActivateResponse` pulsações, o **LocalMultiplayerAgent** solicita que o servidor de jogo passe de standby para active. Em seguida, após `NumHeartBeatsForTerminateResponse` pulsações, o **LocalMultiplayerAgent** solicita que o servidor de jogo passe de active para terminated. Esse comportamento pode ser ajustado atualizando os valores no arquivo *MultiplayerSettings.json*.
## Verificando a conteinerização
Se você é novo no mundo dos contêineres, pode conferir uma introdução [aqui](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/container-docker-introduction/).
### Pré-requisitos
* Windows 10 Pro (ou superior) com a atualização de abril de 2018 (1803).
* Baixe o [Docker](https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe). Como alternativa, você pode baixá-lo na página principal do [site do Docker](https://www.docker.com/products/docker-desktop).
### Configuração
* Verifique se o Docker está configurado para [usar contêineres Windows](https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers)
* Em uma janela do Powershell (como Administrador):
* Navegue até a pasta em que o conjunto de ferramentas foi extraído.
* Execute *Setup.ps1*, que configura as redes do docker, adiciona regras de firewall para a comunicação com o **LocalMultiplayerAgent** e efetua pull da imagem do docker do PlayFab de [Microsoft/PlayFab-Multiplayer](https://hub.docker.com/r/microsoft/playfab-multiplayer/). Observe que, na primeira vez que o script é executado, o download da imagem de contêiner pode levar alguns minutos.
Para executar essa configuração com êxito, talvez seja necessário configurar o firewall de qualquer programa antivírus de terceiros (como McAfee, Norton ou Avira) que você tenha instalado.
### Executando o servidor de jogo em um contêiner
* No arquivo *MultiplayerSettings.json*, defina `RunContainer` como `true`.
* Abra uma janela do **Powershell** (como Administrador) na pasta em que o conjunto de ferramentas foi extraído (*C:\PlayFabVmAgent*) e execute `LocalMultiplayerAgent.exe`. Isso inicia o servidor de jogo em um contêiner. Em algum momento, você deverá ver a saída de alteração do estado do jogo na janela do Powershell (assim como na seção Verificando a integração do GSDK acima).
### Testando a conexão com o servidor de jogo em execução em um contêiner
Quando a saída do **LocalMultiplayerAgent** imprimir `CurrentGameState - Active`, conecte-se ao seu servidor de jogo usando o endereço IP **127.0.0.1** e a porta igual a `NodePort` (por padrão, **56100**) especificada no arquivo *MultiplayerSettings.json*.
Após `NumHeartBeatsForActivateResponse` pulsações, o **LocalMultiplayerAgent** solicita que o servidor de jogo passe de standby para active. Em seguida, após `NumHeartBeatsForTerminateResponse` pulsações, o **LocalMultiplayerAgent** solicita que o servidor de jogo passe de active para terminated. Esse comportamento pode ser ajustado atualizando os valores no arquivo *MultiplayerSettings.json*.
### Usando o LocalMultiplayerAgent com contêineres Linux
Você pode usar o LocalMultiplayerAgent para depurar seu servidor de jogo Linux executando-o em um contêiner no Windows usando o [Docker para Windows](https://docs.docker.com/docker-for-windows/). Você pode ver mais informações sobre como executar contêineres Linux no Windows [aqui](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/linux-containers). Em essência, basta executar o agente com o parâmetro *-lcow* e configurar corretamente o arquivo *LocalMultiplayerSettings.json*.
Para executar seus servidores de jogo Linux em contêineres no Windows, você precisa executar as seguintes etapas:
* Baixe a versão mais recente do LocalMultiplayerAgent na página [Releases](https://github.com/PlayFab/MpsAgent/releases) do GitHub
* [Instale o Docker Desktop no Windows](https://docs.docker.com/docker-for-windows/install/)
* Verifique se ele está sendo executado em [contêineres Linux](https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers)
* Você deve montar um dos seus discos rígidos; você pode encontrar instruções [aqui](https://docs.docker.com/docker-for-windows/#file-sharing)
* A imagem do seu servidor de jogo pode ser publicada em um registro de contêiner ou criada localmente.
* Execute o arquivo do Powershell `SetupLinuxContainersOnWindows.ps1`, que cria uma rede do Docker chamada "PlayFab"
* Configure corretamente o arquivo *LocalMultiplayerSettings.json*. Abaixo você pode ver um exemplo, incluído em `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" ]
}
}
```
Algumas observações: 1. Você deve definir
`RunContainer` como true. Isso é necessário para servidores de jogo Linux.
2. Modifique
`imageDetails` com os detalhes da imagem do docker do seu servidor de jogo. A imagem pode ser criada localmente (usando o comando [docker build](https://docs.docker.com/engine/reference/commandline/build/)) ou hospedada em um registro de contêiner remoto.
3.
`StartGameCommand` e `AssetDetails` são opcionais. Normalmente, você não os usa ao usar um contêiner do Docker, pois todos os ativos do jogo e o comando de início do servidor de jogo podem ser empacotados no [Dockerfile](https://docs.docker.com/engine/reference/builder/) correspondente
4. Por último, mas definitivamente não menos importante, preste atenção ao uso de maiúsculas e minúsculas na sua
variável `OutputFolder`, pois os contêineres Linux diferenciam maiúsculas de minúsculas. Se o uso de maiúsculas e minúsculas estiver errado, você poderá ver uma exceção do Docker semelhante a *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*
* Depois de executar todas as etapas anteriores, você pode executar o LocalMultiPlayerAgent com o comando `LocalMultiplayerAgent.exe -lcow` (lcow significa *Linux Containers On Windows*)
### Solução de problemas
* No modo de contêiner, se o servidor de jogo for encerrado imediatamente com um erro semelhante a "Container ... exited with exit code 1", mas funcionar bem no modo de processo, verifique se você incluiu todas as [DLLs do sistema](/pt-BR/services/playfab/multiplayer/servers/determining-required-dlls) necessárias no seu pacote de ativos.
* Todos os logs ficam em `OutputFolder`, especificado no arquivo *MultiplayerSettings.json*. O **LocalMultiplayerAgent** cria uma nova pasta sempre que é iniciado, com o carimbo de data/hora como nome da pasta. Todos os logs do servidor de jogo emitidos por meio do GSDK ficam na pasta GameLogs.\
Se o servidor de jogo estiver sendo executado em um contêiner, pode haver um nível adicional na hierarquia de diretórios a ser percorrido.
* O GSDK grava logs de depuração na pasta GameLogs. Esses logs ficam na pasta GameLogs junto com os logs gerados pelo servidor de jogo.
* Verifique se os firewalls (do Windows e de outros antivírus) estão configurados para permitir o tráfego pelas portas.
* Se você receber um erro semelhante a: `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.` Isso pode acontecer se o **LocalMultiplayerAgent** for encerrado prematuramente. Use o comando `docker ps` para encontrar o contêiner em execução e, em seguida, encerre-o usando `docker kill `.
* Se você receber um erro que contenha `Failed to find network 'playfab'`, tente executar *Setup.ps1* novamente
* Se você receber um erro `Unhandled Exception`, talvez esteja executando o PowerShell como Administrador.
* `OutputFolder` pode ser usado, por sua vez, por outras variáveis do sistema; portanto, verifique se você usou um caminho absoluto. Por exemplo, GSDK\_CONFIG\_FILE tem essa dependência, então um caminho relativo (ou um valor incorreto) aqui pode resultar em erros de carregamento da configuração do servidor de jogo.
### Limitações conhecidas
1. Os contêineres podem não ser encerrados ao final da depuração. Se isso ocorrer, execute os seguintes comandos do PowerShell como Administrador. Esses comandos param e removem todos os contêineres, incluindo os que não foram iniciados pelo **LocalMultiplayerAgent**.
```powershell theme={null}
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)
```
## Related topics
- [Exemplo Wrapper](/pt-BR/services/playfab/multiplayer/servers/wrapper-sample.md)
- [Noções básicas de um servidor de jogo do PlayFab](/pt-BR/services/playfab/multiplayer/servers/basics-of-a-playfab-game-server.md)
- [Integrar servidores de jogo ao PlayFab GSDK](/pt-BR/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk.md)
- [Conectar-se diretamente para depurar servidores de jogo](/pt-BR/services/playfab/multiplayer/servers/directly-debugging-game-servers.md)
- [Alocar servidores de jogo e conectar o depurador do Visual Studio](/pt-BR/services/playfab/multiplayer/servers/allocating-game-servers-and-configuring-vs-debugging-tools.md)