# Instalação — Godot · AI Game Developer Wiki

Instale o addon Godot MCP pelo app AI Game Dev, godot-cli, Godot Asset Library ou zip de release, com os pacotes NuGet exatos para o .csproj.

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

Esta página mostra todas as formas de adicionar o Godot MCP a um projeto Godot C# e o que cada uma faz por você. Se você só quer que funcione, use o app desktop ou o `godot-cli`: ambos instalam o addon, ajustam seu `.csproj` e habilitam o plugin em um único passo. Os caminhos manuais (Asset Library, zip de release) exigem dois passos extras que são fáceis de esquecer.

## Requisitos

| Requisito | Detalhes |
| --- | --- |
| Godot | Godot 4.3 ou mais recente, **edição .NET (mono)**. O addon é compilado tendo `Godot.NET.Sdk` 4.3.0 como mínimo; a CI do projeto o executa em 4.3, 4.4, 4.5, 4.6 e 4.7. |
| .NET | O SDK do .NET 8 (`net8.0`). |
| Projeto | Um projeto Godot com um `.csproj` de C# na raiz. |
| `godot-cli` (opcional) | Node.js `^20.19.0` ou `>=22.12.0`. |
| Sistema operacional | Windows, macOS ou Linux. |

**Aviso**

O download padrão do Godot (somente GDScript) não consegue compilar o addon. Baixe a build .NET do Godot. Se seu projeto ainda não tem um `.csproj`, crie um pelo Godot (Project, Tools, C#, Create C# solution) ou gere um novo projeto com `godot-cli create-project --dotnet`.

## Opção 1: o app desktop AI Game Dev

O [app AI Game Dev](https://ai-game.dev/pt-br/docs/wiki/app) pode instalar o Godot MCP em um projeto que você selecionar e então abrir o editor já conectado à sua conta. Ele traz sua própria cópia do instalador, então você não precisa de Node.js nem de npm. O app sempre instala o addon lançado mais recente e faz as mesmas três coisas que o `godot-cli install-plugin`: coloca os arquivos do addon em `addons/godot_mcp/`, adiciona os pacotes NuGet e o catálogo de extensões ao seu `.csproj`, e habilita o plugin em `project.godot`.

Baixe o app na [página de download](https://ai-game.dev/pt-br/download). Como instalá-lo e escolher um projeto está em [Instalação do app](https://ai-game.dev/pt-br/docs/wiki/app/installation); a linha de comando do app é descrita em [CLI do app](https://ai-game.dev/pt-br/docs/wiki/app/cli).

## Opção 2: godot-cli (terminal)

O `godot-cli` é o pacote npm do Godot MCP. Seu comando `install-plugin` é um instalador completo e pode ser executado novamente com segurança: uma segunda execução não altera nada.

```bash
npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject
```

O que o `install-plugin` faz, em ordem:

1. Baixa `godot-mcp-addon-<version>.zip` do release do Godot-MCP no GitHub (HTTPS, somente github.com) e o coloca em `res://addons/godot_mcp/`. A versão padrão é a versão da própria CLI.
2. Adiciona ao seu `.csproj` os `PackageReference` do NuGet de que o addon instalado precisa, usando as versões do próprio addon, e corrige versões desatualizadas.
3. Adiciona o `<EmbeddedResource>` do catálogo de extensões e define `<EnableDynamicLoading>true</EnableDynamicLoading>`.
4. Habilita o plugin na seção `[editor_plugins]` do `project.godot`.

Variantes úteis:

```bash
# A specific addon release
godot-cli install-plugin --version 0.34.0 ./MyGodotProject

# Offline or development install from a local copy of the addon
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject

# No project yet: scaffold a Godot C# project first
godot-cli create-project --dotnet ./MyGodotProject
```

Você também pode executá-lo sem uma instalação global: `npx godot-cli install-plugin ./MyGodotProject`. Todas as flags estão listadas na [referência do godot-cli](https://ai-game.dev/pt-br/docs/wiki/godot/cli).

## Opção 3: Godot Asset Library

1. No editor Godot, abra a aba **AssetLib** na parte superior.
2. Procure por **Godot-MCP** e abra o asset.
3. Clique em **Download** e depois em **Install**. O Godot descompacta o addon em `res://addons/godot_mcp/`.
4. Adicione os pacotes NuGet e a linha do catálogo ao seu `.csproj` (veja abaixo).
5. Habilite o plugin (veja abaixo).

A entrada na Asset Library sempre aponta para um release com tag, então você recebe um snapshot confiável. Ela contém apenas os arquivos do addon: os passos 4 e 5 ainda são por sua conta.

## Opção 4: zip de release do GitHub ou cópia do código-fonte

Baixe `godot-mcp-addon-<version>.zip` da página de [releases do Godot-MCP](https://github.com/IvanMurzak/Godot-MCP/releases/latest) e extraia na raiz do projeto. O arquivo já contém `addons/godot_mcp/`, então os arquivos ficam em `res://addons/godot_mcp/`. Você também pode copiar a pasta `addons/godot_mcp/` de um clone do repositório. Em seguida, faça os dois passos manuais abaixo.

## Passo manual: pacotes NuGet e o catálogo de extensões

O Godot compila todos os arquivos `.cs` do seu projeto em um único assembly, então seu `.csproj` precisa referenciar os mesmos pacotes NuGet que o addon usa, senão o addon não vai compilar. Adicione isto ao seu `.csproj` (estas são as versões para o addon 0.34.0):

```xml
<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.5.1" />
  <PackageReference Include="com.IvanMurzak.McpPlugin" Version="8.14.0" />
</ItemGroup>

<!-- Editor-only: exported games ship no RQL and no Roslyn. -->
<ItemGroup>
  <PackageReference Include="com.IvanMurzak.Rql" Version="0.3.0" Condition="'$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease'" />
  <PackageReference Include="com.IvanMurzak.CodeExec" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="com.IvanMurzak.CodeExec.Roslyn" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
</ItemGroup>

<!-- Without this line the dock's Extensions list is empty. -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>
```

| Pacote | Versão (addon 0.34.0) | Função |
| --- | --- | --- |
| `com.IvanMurzak.ReflectorNet` | 5.5.1 | Núcleo de reflexão e serialização |
| `com.IvanMurzak.McpPlugin` | 8.14.0 | Cliente MCP que conecta o editor ao servidor |
| `com.IvanMurzak.Rql` | 0.3.0 | RQL, a linguagem de consulta por trás das ferramentas do editor (somente editor) |
| `com.IvanMurzak.CodeExec` | 0.4.0 | Executa trechos de C# para `script-execute` (somente editor, a menos que você opte por habilitar) |
| `com.IvanMurzak.CodeExec.Roslyn` | 0.4.0 | Adaptador Roslyn para Code-Exec |
| `Microsoft.CodeAnalysis.CSharp` | 4.12.0 | O compilador C# Roslyn |

As versões precisam corresponder ao addon que você instalou. Cada release as lista no README, e o zip da release as traz em `addons/godot_mcp/nuget-deps.json`; o `godot-cli install-plugin` lê esse arquivo, e é por isso que ele nunca erra. O branch de desenvolvimento já avança o `com.IvanMurzak.McpPlugin` (8.18.0), então verifique novamente quando você atualizar.

Mantenha também o `<EnableDynamicLoading>true</EnableDynamicLoading>` no `<PropertyGroup>` do seu `.csproj`. O próprio template C# do Godot já o tem. Sem ele, um jogo iniciado com Play não consegue criar nenhum script C#.

Você não precisa copiar DLLs. Execute `dotnet restore` (ou compile a partir do Godot) e o addon encontra os pacotes no seu cache do NuGet em tempo de editor.

## Etapa manual: habilitar o plugin

Abra **Project, Project Settings, Plugins** e habilite **Godot-MCP**. Compile o projeto C# (o botão Build no editor, ou `godot-cli build`). Ao carregar com sucesso, o painel Output exibe:

```text
[Godot-MCP] plugin loaded
```

O dock do **AI Game Developer** aparece na área de docks no canto superior direito. Continue com [Primeiros passos](https://ai-game.dev/pt-br/docs/wiki/godot/getting-started).

## Atualização e remoção

- Atualize com a mesma ferramenta que você usou para instalar: execute novamente o `godot-cli install-plugin` (opcionalmente com `--version`), use o app, ou instale a nova release pela Asset Library e atualize as versões do NuGet manualmente.
- Atualize a própria CLI com `godot-cli update`.
- `godot-cli remove-plugin ./MyGodotProject` desabilita o addon em `project.godot`. Ele não exclui `addons/godot_mcp/` nem as entradas do `.csproj`; remova-os manualmente se quiser que desapareçam.

## Jogos exportados

Os pacotes RQL, Code-Exec e Roslyn trazem uma `Condition` que os deixa de fora das builds `ExportDebug` e `ExportRelease`, então o jogo exportado não os inclui. As ferramentas de editor do addon são compiladas apenas no editor e nunca chegam a uma build do jogo. Expor ferramentas a partir de um jogo em execução é opcional e está descrito em [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/godot/custom-tools).

---

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

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