# Solução de problemas — Unity · AI Game Developer Wiki Resolva problemas comuns do Unity MCP: ferramentas ausentes no cliente de IA, erros de login e conexão, falhas de download e conflitos de porta. Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/unity/troubleshooting). Esta página reúne os problemas mais comuns com o Unity MCP e como corrigi-los. Comece pela lista rápida; se isso não ajudar, encontre seu sintoma abaixo. ## Lista rápida 1. Abra **Window > AI Game Developer — MCP** e veja a linha do tempo: **Unity**, **MCP server** e **AI agent** devem estar todos verdes. 2. Verifique o Console do Unity em busca de erros. Um erro de compilação em qualquer lugar do projeto impede o carregamento dos scripts de editor do plugin. 3. Execute `unity-mcp-cli status ./MyUnityProject` para ver se o Unity está em execução e qual servidor está acessível. 4. Reinicie seu cliente de IA após qualquer alteração na configuração. 5. Certifique-se de que o plugin e suas extensões estejam nas versões atuais. ## O cliente de IA não mostra nenhuma ferramenta do Unity - **O cliente se conectou antes de o Unity estar pronto.** Reconecte o servidor MCP no cliente (no Claude Code, `/mcp`) ou reinicie o cliente depois que a janela mostrar **Connected**. - **O cliente não foi configurado ou usa uma configuração antiga.** Clique em **Configure** (ou **Reconfigure**) para o seu agente na janela, ou execute `unity-mcp-cli setup-mcp .` e reinicie o cliente. - **O modo Cloud não está autenticado.** A janela mostra "Authorization Required". Clique em **Authorize** e aprove o código no navegador. - **Vários projetos estão abertos.** Uma URL `https://ai-game.dev/mcp` não fixada pode encaminhar para outro Editor. Use a URL fixada que **Configure** grava. - **O agente é iniciado de outra pasta.** Configurações em nível de projeto, como `.mcp.json` ou `.cursor/mcp.json`, só são lidas quando o cliente é executado na pasta do projeto Unity. - **No VS Code**, mude o Copilot Chat para o modo **Agent**. ## Problemas de login no Cloud - **"Authorization Required" não para de aparecer.** Sua credencial expirou ou foi revogada. Clique em **Authorize** novamente ou execute `unity-mcp-cli login --force`. - **"Connection Required".** O login funcionou, mas o Unity não está conectado. Clique em **Connect**. - **Login feito com a conta errada.** Clique em **Revoke** (isso desconecta todas as ferramentas do AI Game Dev da máquina) e depois em **Authorize** com a conta correta. O `unity-mcp-cli login` pergunta antes de trocar de conta. O gerenciamento de sessões e dispositivos da sua conta está descrito em [Autenticação](https://ai-game.dev/docs/auth). ## O servidor MCP local não inicia (modo Custom) - **O binário não foi baixado.** Ele vai para `Library/mcp-server//`. Se o download falhou (offline, firewall, proxy), a janela mostra "Server binary error" e um botão **Download / Retry server**. Você também pode usar **Tools > AI Game Developer > Server > Download Binaries**. - **O antivírus bloqueou o executável.** Permita `gamedev-mcp-server` no seu software de segurança e tente novamente. - **O transporte é stdio.** Com stdio, o agente de IA inicia o servidor por conta própria, então o botão **Start** fica desabilitado. Mude para `http` se quiser que o Unity o execute. - **Leia os logs do servidor.** Use **Tools > AI Game Developer > Server > Open Logs** e **Open Log Errors**. - **Teste o servidor diretamente.** **Tools > AI Game Developer > Server > Launch MCP Inspector** abre o MCP Inspector para o servidor local (apenas transporte HTTP; requer Node.js). ## Conflitos de porta Cada projeto recebe uma porta fixa entre 20000 e 29999, derivada do seu caminho. Se outra coisa já estiver escutando nela, a janela mostra o servidor MCP como **External**. Encontre o processo: ```powershell netstat -ano | findstr : ``` ```bash lsof -i : ``` Encerre esse processo, ou desconecte e digite outra porta em **Server URL** (por exemplo `http://localhost:25000`), e clique em **Configure** novamente para que o agente use a nova porta. ## Desconexões durante a compilação O Unity recarrega os scripts após cada alteração de código e ao entrar no modo Play. O plugin se desconecta antes da recarga e se reconecta depois, então um breve "Disconnected" ou "Connecting..." é normal. Uma chamada de ferramenta que estava em andamento durante a recarga pode falhar; peça ao agente para tentar novamente. ## Erros de compilação ou DLLs ausentes após a instalação O plugin baixa suas dependências .NET do NuGet para `Assets/Plugins/NuGet`. - **Erros sobre tipos ausentes de McpPlugin, ReflectorNet ou SignalR.** Aguarde a primeira importação terminar e use **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**. - **"Path too long" no Windows.** O runtime do Unity não consegue abrir DLLs além do limite de 260 caracteres de caminho do Windows, mesmo com caminhos longos habilitados. Mova o projeto para uma pasta mais curta, como `C:/Projects/MyGame`. - **Reinstalação limpa.** Feche o Unity, exclua `Assets/Plugins/NuGet` e seu arquivo `.meta` e reabra o projeto. ## Caminho do projeto com espaços Se o Console mostrar "The project path contains spaces", mova o projeto para uma pasta sem espaços. O plugin avisa porque esses caminhos podem causar problemas durante o uso. ## As chamadas de ferramentas falham ou expiram - **Erros como "object not found".** Peça ao agente para consultar primeiro (por exemplo com `rql-query`) em vez de adivinhar nomes ou caminhos. Caminhos de assets começam com `Assets/`. - **Operações longas expiram.** Aumente **Tool timeout (ms)** na janela (padrão 300000) para bakes lentos ou execuções de teste grandes. - **As capturas de tela falham no modo batch.** Um Editor iniciado com `-nographics` não tem dispositivo gráfico. Inicie em modo headless sem `-nographics`; `unity-mcp-cli open --headless` já faz isso. - **Uma ferramenta personalizada lança erros de thread.** Envolva as chamadas da API do Unity em `MainThread.Instance.Run`. Veja [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/unity/custom-tools#main-thread). ## Problemas com unity-mcp-cli - **`open` para em "Enter Safe Mode?"** A CLI clica em **Ignore** automaticamente. No macOS, conceda permissão de Acessibilidade ao seu terminal; no Linux, instale `xdotool`. - **`exec` espera e depois desiste.** O projeto está aberto em um Editor que a CLI não iniciou, e o plugin dele não está respondendo localmente (por exemplo, está conectado à nuvem). Conecte o plugin, mude-o para Custom ou passe `--url`. - **`setup-skills` falha.** Ele precisa de um Editor em execução com o plugin conectado. Execute `open` e `wait-for-ready` primeiro. - **Use `--verbose`** em qualquer comando para obter logs detalhados. ## Redefinição completa 1. Feche o Unity. 2. Exclua `Library/mcp-server/` no projeto. 3. Reabra o Unity e escolha **Tools > AI Game Developer > Reset Config**. 4. Faça login novamente (Cloud) ou inicie o servidor (Custom) e clique em **Configure** para o seu agente. 5. Reinicie seu cliente de IA. ## Obtendo ajuda Use **Help / Talk** (Discord) ou **Bug Report** (issues do GitHub) na parte inferior da janela do AI Game Developer. Inclua sua versão do Unity, o sistema operacional, a versão do plugin (mostrada na janela), o erro do Console e os passos para reproduzir. Você também pode consultar o [FAQ](https://ai-game.dev/pt-br/docs/wiki/unity/faq) ou o [FAQ](https://ai-game.dev/docs/faq) do site. --- Source (HTML): https://ai-game.dev/pt-br/docs/wiki/unity/troubleshooting Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/unity/troubleshooting