# Primeiros passos — Godot · AI Game Developer Wiki

Conecte o Godot MCP à nuvem, configure um agente de IA como o Claude Code, verifique a conexão e rode seus primeiros prompts no editor Godot.

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

Esta página leva você de um addon instalado até um agente de IA que edita a sua cena Godot. Ela parte do princípio de que o addon já está no seu projeto; se não estiver, comece pela [Instalação](https://ai-game.dev/pt-br/docs/wiki/godot/installation). Os passos usam o modo Cloud padrão, em que o editor e o seu agente se conectam a [ai-game.dev](https://ai-game.dev) e você faz login uma única vez.

## Passo 1: abra o projeto

Abra o projeto com a CLI:

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

`open` compila o assembly C# primeiro e depois inicia o editor. A compilação é importante na primeira abertura: o Godot carrega os addons habilitados imediatamente e, sem um assembly compilado, informa que não consegue carregar `GodotMcpPlugin.cs` e desabilita o addon. Se você abrir o projeto pelo gerenciador de projetos do Godot, compile uma vez (o botão Build do editor ou `godot-cli build`) e reabilite o plugin caso o Godot o tenha desativado.

Quando o addon carrega, o painel Output do editor exibe `[Godot-MCP] plugin loaded` e o dock **AI Game Developer** aparece na área de docks no canto superior direito.

## Passo 2: faça login

O modo Cloud precisa da sua conta ai-game.dev. Escolha uma destas opções:

- No dock, mantenha o modo em **Cloud** e clique em **Authorize**. O navegador abre com um código curto; aprove-o com a sua conta ai-game.dev.
- Em um terminal, execute `godot-cli login`. Ele usa o mesmo fluxo OAuth de dispositivo e salva a credencial em `~/.ai-game-dev/credentials.json`, que o editor detecta sozinho.

Você faz login uma vez por máquina. A mesma credencial serve para o Godot MCP, o Unity MCP, o Unreal MCP, as CLIs dos engines e o app AI Game Dev. A sessão aparece nos dispositivos conectados da sua conta, onde você pode revogá-la. Detalhes: [Autenticação](https://ai-game.dev/docs/auth).

## Passo 3: conecte seu agente de IA

Escreva a configuração MCP para o agente que você usa. Para o Claude Code:

```bash
godot-cli setup-mcp claude-code ./MyGodotProject
```

Isso grava `.mcp.json` no projeto com uma URL vinculada a este projeto, para que o agente chegue a este editor mesmo quando você tem vários editores abertos. Você pode fazer o mesmo pelo dock: escolha seu agente na seção **AI agent** e clique em **Configure**. Outros agentes (Cursor, VS Code Copilot, Codex, Gemini e mais) estão listados em [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/godot/connecting-ai-clients).

Reinicie o agente, ou recarregue os servidores MCP dele, depois que a configuração for gravada. Inicie o agente a partir da pasta do projeto quando a configuração estiver lá (o Claude Code lê `.mcp.json` da pasta em que é iniciado).

## Passo 4: verifique a conexão

A seção **Connection** do dock mostra uma linha de três pontos: Godot, o servidor MCP e o agente de IA. Quando o editor está conectado e uma sessão de agente está ativa, os três ficam acesos e a linha do agente mostra o nome do cliente. Em um terminal, você também pode esperar o editor responder:

```bash
godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject
```

`wait-for-ready` consulta a sonda de prontidão (`ping`) até ela responder, por padrão por até dois minutos. `status` informa se há um editor em execução para o projeto e se o servidor responde.

No seu agente, peça para ele listar as ferramentas, ou execute `/mcp` no Claude Code. Você deve ver ferramentas como `rql-query`, `rql-mutate`, `script-create` e `screenshot-viewport`.

## Passo 5: primeiros prompts

Experimente estes no chat do seu agente. Cada um corresponde a ferramentas reais, então você pode ver a cena mudar no editor:

- "Adicione uma cena Node3D com uma Camera3D e um cubo MeshInstance3D, depois salve como Main.tscn."
- "Crie 3 cubos em um círculo com raio 2."
- "Liste todas as OmniLight3D da cena com a energia de cada uma."
- "Crie um StandardMaterial3D para o piso e defina a cor albedo dele como cinza."
- "Crie um script Player.cs com um float público Speed, anexe-o ao nó Player e compile o projeto."
- "Adicione uma ação de entrada chamada jump na tecla Space."
- "Tire um screenshot do viewport e me diga o que você vê."

As edições de cena feitas pelo agente podem ser desfeitas: pressione Ctrl+Z no editor para voltar, exatamente como nas suas próprias edições. As alterações de cena marcam a cena como não salva, então peça ao agente para salvar, ou salve você mesmo. Mais ideias de prompts estão em [Boas práticas para Godot](https://ai-game.dev/docs/best-practices/godot).

## O que o agente pode e não pode ver

O agente trabalha por meio das ferramentas que o addon expõe. Ele pode ler a árvore de cena, as propriedades do Godot (incluindo variáveis GDScript), recursos, arquivos, configurações do projeto, o mapa de entrada, autoloads, o console e o estado do editor por meio do RQL, além de poder olhar screenshots. Ele não consegue clicar na interface do editor. A lista completa está em [Ferramentas](https://ai-game.dev/pt-br/docs/wiki/godot/tools) e no [catálogo de ferramentas do Godot](https://ai-game.dev/docs/tools/godot).

## Prefere ficar offline?

Você pode executar o servidor MCP na sua própria máquina em vez de usar a nuvem. No dock, mude o modo para **Custom** e clique em **Start Server**: o addon baixa do GitHub o build do servidor correspondente, inicia-o e se conecta a ele. Depois, aponte seu agente para a URL local. Veja [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/godot/connecting-ai-clients#custom-mode).

## Próximos passos

- [Configuration](https://ai-game.dev/pt-br/docs/wiki/godot/configuration): o dock, o nível de log e quais ferramentas o agente enxerga.
- [Extensions](https://ai-game.dev/pt-br/docs/wiki/godot/extensions): adicione suporte a AnimationPlayer, CSG, navegação, tilemap e addons.
- [Solução de problemas](https://ai-game.dev/pt-br/docs/wiki/godot/troubleshooting): se algum passo acima não funcionou.

---

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

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