# Solução de problemas — Godot · AI Game Developer Wiki

Corrija problemas do Godot MCP: addon que não carrega ou compila, Extensões vazias, ferramentas ausentes, erros de reload e crashes no .NET 10.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/godot/troubleshooting).

A maioria dos problemas do Godot MCP vem de um de quatro lugares: a build errada do Godot, um `.csproj` que não corresponde ao addon, um assembly C# que não foi compilado ou um cliente de IA que não aponta para o servidor certo. Percorra a seção que corresponde ao que você está vendo. Se travar, aumente o **Log Level** do dock para `Debug`, reproduza o problema e leia o painel Output.

## O addon não carrega

### "Unable to load addon script" na primeira abertura

O Godot instancia os addons habilitados assim que o editor inicia. Na primeiríssima abertura de um projeto C# que nunca foi compilado, ainda não existe assembly, então o Godot informa que não consegue carregar `res://addons/godot_mcp/Editor/GodotMcpPlugin.cs` e desativa o addon.

Correção: compile primeiro e depois habilite o plugin novamente em **Project, Project Settings, Plugins**.

```bash
godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject
```

O `godot-cli open` sempre compila antes de iniciar o editor, então evita esse problema.

### O addon não compila

- Você está usando a build padrão do Godot. O Godot MCP precisa da build **.NET (mono)** do Godot 4.3 ou mais recente.
- O `.csproj` está sem os pacotes NuGet, ou tem versões diferentes das do addon que você instalou. Rode `godot-cli install-plugin` novamente, ou copie o bloco de [Instalação](https://ai-game.dev/pt-br/docs/wiki/godot/installation#nuget-packages) com as versões da sua release do addon.
- O projeto não tem um `.csproj`. Crie a solução C# pelo Godot, ou use `godot-cli create-project --dotnet` para um projeto novo.
- O SDK do .NET 8 não está instalado ou não está no `PATH`.

### FileNotFoundException para um assembly NuGet

O Godot não resolve os pacotes NuGet de um projeto no editor por conta própria; o addon faz isso lendo o `.deps.json` da build e o seu cache do NuGet. Se um assembly ainda não for encontrado, rode `dotnet restore` e compile de novo. Se o problema persistir, exclua `.godot/mono/temp/obj` e `.godot/mono/temp/bin` e recompile: uma saída de build antiga costuma ser a causa.

## Um jogo iniciado com Play não consegue criar scripts C#

Sintoma: todo script C# falha com "Cannot instantiate C# script because the associated class could not be found", depois de uma `TypeLoadException` citando uma classe `EditorPlugin`. Seu `.csproj` está sem `<EnableDynamicLoading>true</EnableDynamicLoading>`, então os assemblies do pacote não são copiados ao lado do assembly do jogo. Adicione essa linha ao `<PropertyGroup>` junto de `<TargetFramework>` e recompile. `godot-cli install-plugin` e `create-project` já configuram isso para você.

## A lista de Extensões está vazia

O dock lê o catálogo de extensões do seu projeto compilado. Seu `.csproj` precisa desta linha e, depois, de uma recompilação:

```xml
<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
```

O `LogicalName` deve ser exatamente `Godot-MCP.extensions.catalog.json`. Se o dock disser que nenhum `.csproj` foi encontrado, o addon não está dentro de um projeto C# do Godot. Veja [Extensions](https://ai-game.dev/pt-br/docs/wiki/godot/extensions#catalog).

## O editor não conecta

- **Modo Cloud, sem login.** Clique em **Authorize** no dock, ou rode `godot-cli login`. O dock mostra seu status de login.
- **Sobrescrito pelo ambiente.** Uma nota amarela "Overridden by environment (GODOT\_MCP\_\*)" significa que uma variável ou um arquivo `.env` força o modo ou o host, e mudanças no dock não fazem efeito. Remova a variável ou altere-a.
- **Modo Custom, sem servidor.** Clique em **Start Server** no dock, ou inicie seu próprio servidor. Quando offline, o download do servidor falha com um aviso no painel Output e nenhum servidor local inicia; use o modo Cloud ou rode um servidor que você já tenha.
- **Modo Custom com `oauth` em um host remoto.** O addon envia o token da sua conta apenas para um servidor localhost. Para outros hosts, defina `GODOT_MCP_TOKEN`, caso contrário a conexão falha com "Refusing to send your ai-game.dev account token".

Verifique em um terminal com `godot-cli status ./MyGodotProject` e `godot-cli wait-for-ready ./MyGodotProject`.

## O agente de IA não vê nenhuma ferramenta do Godot

- O agente foi iniciado antes de sua config ser escrita. Reinicie-o, ou recarregue seus servidores MCP.
- O Claude Code lê o `.mcp.json` da pasta em que é iniciado. Inicie-o na pasta do projeto, ou escreva a config onde você o inicia.
- Vários editores estão conectados e o agente usa a URL `/mcp` simples. Use a URL fixada que o `setup-mcp` escreve por padrão, para que o agente alcance o projeto certo.
- A config aponta para um servidor diferente do editor (cloud vs local). Rode `godot-cli setup-mcp <agent>` novamente depois de mudar de modo, ou clique em **Reconfigure** no dock.
- As ferramentas estão ocultas. Verifique a seção de recursos MCP do dock ou `godot-cli configure --list`. Uma ferramenta oculta não é listada para o agente.

## As chamadas de ferramentas falham durante uma recompilação de C#

O Godot recarrega o assembly C# do projeto cerca de meio segundo depois que a DLL compilada muda (`script-build`, o botão Build ou um `dotnet build`). O addon faz parte desse assembly, então ele é desmontado, recompilado e se reconecta em poucos segundos. Em torno de uma recarga, novas chamadas são recusadas com um erro que permite nova tentativa ("O Godot está prestes a recarregar o assembly C# do projeto … Tente novamente em alguns segundos"). Aguarde e tente de novo; o `script-build` entrega seu resultado após a recarga.

## O editor trava ou congela após uma recarga no .NET 10

Este é um bug do runtime .NET (dotnet/runtime#135441). Até que a correção de manutenção do .NET 10 seja lançada, defina esta variável de ambiente para o processo do editor e reinicie o Godot:

```text
DOTNET_ThreadPool_ThreadsToKeepAlive=-1
```

No Windows, você pode defini-la com `setx DOTNET_ThreadPool_ThreadsToKeepAlive -1`. Editores iniciados por `godot-cli open` ou `exec` a recebem automaticamente. Remova-a quando seu runtime .NET incluir a correção.

## As chamadas vão para uma build antiga

Se as chamadas de ferramentas se comportam como uma versão mais antiga do seu código, pode haver mais de um editor conectado ao mesmo projeto, por exemplo um editor headless esquecido. Feche os extras (`godot-cli close --owned-only` fecha os editores que o `godot-cli` iniciou) e mantenha um único editor conectado.

## Uma build falha com MissingMethodException

A versão do `Godot.NET.Sdk` do projeto deve corresponder ao editor que você usa. Um projeto compilado para 4.3 pode lançar `MissingMethodException` em um editor 4.4 ou mais recente, onde as APIs mudaram. Atualize a versão `Sdk="Godot.NET.Sdk/…"` no seu `.csproj` para a versão do seu editor e recompile.

## Ainda com problemas

Consulte o [FAQ](https://ai-game.dev/pt-br/docs/wiki/godot/faq) e o [FAQ](https://ai-game.dev/docs/faq) do site, ou relate o problema no [rastreador de issues do Godot-MCP](https://github.com/IvanMurzak/Godot-MCP/issues) com o log do painel Output e suas versões do Godot, do .NET e do addon.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/godot/troubleshooting

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/godot/troubleshooting