# Solução de problemas — Unreal Engine · AI Game Developer Wiki Corrija problemas comuns do Unreal MCP: plugin não carrega, bridge ausente, conexão travada, agente sem ferramentas do Unreal e erros. Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/unreal/troubleshooting). Esta página lista os problemas que as pessoas mais encontram com o Unreal MCP e como corrigi-los. Comece pelas verificações rápidas e depois vá para a seção correspondente. ## Verificações rápidas 1. **O plugin está carregado?** O Output Log deve conter `[Unreal-MCP] plugin loaded` depois que o editor iniciar. 2. **O que a janela diz?** Abra **Tools**, **AI Game Developer** e leia a linha de status (Connected, Connecting, Reconnecting, Disconnected ou No MCP bridge). 3. **O que a CLI vê?** Execute `unreal-mcp-cli status --path ./YourProject`. 4. **Leia o log.** Use **Open log file** na janela, filtre o Output Log pela categoria `LogUnrealMcp` ou peça ao agente `console | where Verbosity == "Error"`. ## O plugin não carrega Se não houver a linha `[Unreal-MCP] plugin loaded`, o módulo do editor falhou ao iniciar. - Procure no Output Log um erro de inicialização do plugin ou um `.uplugin` corrompido. - Certifique-se de que o projeto é um **projeto C++** com um toolchain de compilador funcional. Veja [Instalação](https://ai-game.dev/pt-br/docs/wiki/unreal/installation#requirements). - Se o Unreal disser que faltam módulos ou que o plugin é incompatível, deixe-o recompilar, ou abra o projeto com `unreal-mcp-cli open ./YourProject`, que compila primeiro os módulos nativos e dispensa esses avisos. ## Uma atualização não tem efeito O build incremental do Unreal pode manter código antigo do plugin quando o código-fonte do plugin muda, mas a pasta `Intermediate/` antiga sobrevive. - Atualize com `unreal-mcp-cli update ./YourProject`, que limpa o cache de build por padrão. - Após uma cópia manual: feche o editor, exclua `Plugins/UnrealMCP/Intermediate/` e os arquivos C++ em `Plugins/UnrealMCP/Binaries/` (mantenha `Binaries/ThirdParty/`) e reabra. ## "No MCP bridge" ou a bridge reinicia sem parar O plugin precisa do seu processo de bridge, `unreal-mcp-bridge`. A janela mostra o estado da bridge e um contador de reinícios. - Se o log disser `no sidecar binary resolved for rid `, nenhuma bridge foi encontrada. - **Instalação pelo app ou CLI:** a bridge vem incluída. Reinstale com `unreal-mcp-cli install-plugin ./YourProject` (ou pelo app); o pacote pode não ter a sua plataforma. - **Checkout do código-fonte:** compile uma com `unreal-mcp-cli bootstrap-local ./YourProject`, ou defina `UNREAL_MCP_BRIDGE_PATH`. - Clique em **Restart bridge** no rodapé da janela depois de corrigir a causa. ## Travado em "Connecting" ou "Reconnecting" - **Modo Cloud:** verifique se você está autenticado. Se a janela mostrar "Sign in required", sua sessão salva expirou; clique em **Authorize** e aprove o novo código. - Verifique se a máquina consegue acessar ai-game.dev (regras de proxy ou firewall). - **Modo Custom:** certifique-se de que o servidor local está em execução (**Start** no card do servidor MCP, ou `--start-server`) e que o **Server URL** aponta para ele. - Use **Disconnect** e depois **Connect**, ou **Restart bridge**. ## O servidor local diz "No connected clients" Se um `gamedev-mcp-server` local registra `No connected clients. Retrying` e depois responde com HTTP 500, o editor ainda está no modo **Cloud** e conectado a ai-game.dev em vez do seu servidor local. Mude para **Custom** na janela, defina `UNREAL_MCP_CONNECTION_MODE=Custom`, ou passe `--connection-mode Custom` (ou `--host`) para `unreal-mcp-cli open`. ## O agente de IA não tem ferramentas do Unreal - Verifique a configuração do agente: execute `unreal-mcp-cli setup-mcp --path ./YourProject --dry-run` e compare, ou clique em **Configure** (ou **Reconfigure**) na seção do agente de IA. - Reinicie ou recarregue o agente depois das mudanças de configuração. Muitos clientes leem as configurações de MCP apenas na inicialização. - O Claude Code lê o `.mcp.json` da pasta em que você o inicia; inicie-o na pasta do projeto. - Se você configurou com `setup-mcp` antes de abrir o editor alguma vez, a configuração pode apontar para `localhost` em vez da nuvem. Abra o projeto uma vez e execute `setup-mcp` de novo, ou passe `--url`. - Verifique a linha **AI agents** na seção Connection. Se o seu agente não estiver listado, ele não está conectado ao mesmo servidor que o editor. - Se você ocultou ferramentas na janela **MCP Tools** ou definiu `UNREAL_MCP_TOOLS`, o agente vê menos ferramentas. ## O agente acessa o editor errado Com vários editores em uma conta, use a URL fixada ao projeto (`/mcp/p/`), que o `setup-mcp` grava por padrão. Execute `setup-mcp` de novo sem `--no-pin`. Veja [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unreal/connecting-ai-clients#pinned-url). ## Erros 401 no agente - No modo Cloud, uma configuração apenas com URL exige que o agente faça login por conta própria. Ou deixe-o executar o login OAuth dele, ou faça login na máquina (`unreal-mcp-cli login`) e execute `setup-mcp` novamente para que a configuração carregue uma project key. - Se a project key foi revogada, use **Regenerate key** no editor ou `setup-mcp --regenerate-key`. - No modo Custom com autenticação por **token**, a configuração deve carregar o mesmo token que o editor. Use **Reconfigure** após gerar um novo token. ## As chamadas de ferramentas expiram Uma chamada de ferramenta pode durar 5 minutos por padrão. Aumente `UNREAL_MCP_TOOL_TIMEOUT` (em milissegundos) para scripts Python longos ou importações grandes. `python-execute` também tem seu próprio `timeout` (padrão de 30 segundos) que o agente pode definir por chamada. ## As ferramentas de captura de tela retornam um erro A captura de pixels precisa de um editor com suporte a GPU. Sob `-nullrhi`, as ferramentas de captura de tela retornam um erro estruturado. `unreal-mcp-cli exec` e `open --headless` iniciam editores que renderizam fora da tela, então as capturas ainda funcionam neles. ## As ferramentas Python falham `python-execute` usa o Python Editor Script Plugin do Unreal, que o Unreal MCP habilita. Se o Python não estiver disponível, verifique se o plugin está habilitado em **Edit, Plugins**. Os erros apontam para linhas de `snippet.py`, que é o código enviado pelo agente. ## A extensão não aparece - As extensões exigem Unreal Engine 5.7 ou superior e Unreal MCP 0.26.0 ou superior. - Após instalar, a extensão precisa ser compilada: reabra o editor, use `--build` ou **Compile (Live Coding)** na seção Extensions. - Verifique se a extensão está habilitada na seção Extensions. ## Ainda com problemas? - Consulte o [FAQ](https://ai-game.dev/pt-br/docs/wiki/unreal/faq) e o [FAQ](https://ai-game.dev/docs/faq) geral. - Use **Help / Talk** na janela para perguntar no Discord, ou **Bug Report** para abrir uma issue no GitHub. Inclua a versão do Unreal, seu sistema operacional, a linha de status da janela e as linhas de log relevantes (nunca seus tokens). --- Source (HTML): https://ai-game.dev/pt-br/docs/wiki/unreal/troubleshooting Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/unreal/troubleshooting