# Ferramentas — Godot · AI Game Developer Wiki

As ferramentas MCP do Godot no editor: RQL para nós, cenas e recursos, scripts C# e GDScript, capturas de tela e ferramentas in-game.

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

O Godot MCP traz 24 ferramentas integradas em 9 famílias. A maior parte do trabalho no editor passa por três ferramentas RQL, então o agente usa uma única linguagem de consulta para nós, cenas, recursos, arquivos e estado do editor em vez de dezenas de ferramentas separadas. Esta página explica cada família e quando o agente a utiliza. A lista pesquisável com parâmetros e exemplos de prompts é o [catálogo de ferramentas do Godot](https://ai-game.dev/docs/tools/godot).

## Famílias de ferramentas

| Família | Ferramentas | Para que serve |
| --- | --- | --- |
| rql | `rql-query`, `rql-mutate`, `rql-schema` | Lê e altera o editor em tempo real: nós, propriedades do Godot, cenas, recursos, arquivos, configurações do projeto, mapa de entrada, autoloads, grupos, sinais e estado do editor. |
| script | `script-read`, `script-create`, `script-update`, `script-delete`, `script-attach-to-node`, `script-validate`, `script-build`, `script-execute` | Arquivos C# e GDScript, anexar scripts, validar GDScript, compilar o projeto C# e executar C# no editor. |
| screenshot | `screenshot-viewport`, `screenshot-camera`, `screenshot-isolated` | Imagens PNG do viewport do editor, de uma câmera ou de um nó renderizado isoladamente. |
| console | `console-get-logs`, `console-clear-logs` | Logs de um jogo em execução. No editor, a fonte `console` do RQL. |
| reflection | `reflection-method-find`, `reflection-method-call` | Encontra e chama métodos C# em um jogo em execução. No editor, `call` do RQL. |
| runtime-errors | `runtime-errors-get`, `runtime-errors-clear` | Erros gerados dentro de um jogo em execução. Desativado por padrão. |
| ping | `ping` | Sonda de prontidão. Uma ferramenta de sistema, não exibida aos agentes. |
| skills | `godot-skill-create`, `godot-skill-generate` | Escreve um novo arquivo de ferramenta, regenera arquivos de skill. Ferramentas de sistema. |
| session | `session-close` | Salva e encerra um editor iniciado pelo `godot-cli`. Ferramenta de sistema. |

As ferramentas de sistema são acessadas pela rota `/api/system-tools/` do servidor (por exemplo, com `godot-cli run-system-tool ping`) e não são listadas aos agentes de IA. As famílias console, reflection e runtime-errors atendem um jogo em execução que você mesmo conectou; veja [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/godot/custom-tools#runtime).

## RQL: uma linguagem de consulta para o editor

O RQL (Reflection Query Language) é a camada de dados das ferramentas do editor. Uma consulta parte de uma fonte, filtra e molda com estágios separados por `|` e, em `rql-mutate`, termina com `set` ou `call`. Alguns exemplos que o agente pode enviar:

```text
nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
```

- `rql-query` é somente leitura e retorna linhas compactas.
- `rql-mutate` altera as coisas. Cada destino e valor é verificado antes, então uma consulta que falha não altera nada. `dry_run` pré-visualiza a alteração. Cada chamada é um passo de desfazer (Ctrl+Z no editor).
- `rql-schema` lista as fontes, funções e classes de nós da cena editada, ou os membros, métodos e propriedades do Godot de um tipo. Com um nome de extensão, imprime o guia dessa extensão.

As fontes incluem `nodes`, `root`, `selection`, `scenes`, `files`, `folders`, `classes`, `console`, `editor`, `project`, `settings`, `inputActions`, `autoloads`, `groups`, `layers` e `tools`. As propriedades do Godot são acessíveis como membros C# (`Position`, `Visible`) ou pelo nome Godot em `props["snake_name"]`, que inclui variáveis GDScript. O RQL também lida com sinais, grupos, TileSets, Themes, parâmetros de ShaderMaterial e MeshLibraries.

As chamadas do editor cobrem o trabalho com cenas e arquivos: `NewScene`, `OpenScene`, `SaveScene`, `SaveAllScenes`, `ReloadScene`, `CreateResource`, `MoveResource`, `DeleteResource`, `CreateFolder`, `DeleteFolder`, `Reimport`, `Undo`, `Redo`, `PlayScene` e `StopScene`. A fonte `gameLog` lê o que um jogo iniciado a partir do editor imprimiu.

Edições de cena marcam a cena como não salva, assim como suas próprias edições. Arquivos de recursos editados e o `project.godot` são salvos imediatamente.

## Scripts: C# e GDScript

- `script-read`, `script-create`, `script-update` e `script-delete` funcionam em arquivos `.cs` e `.gd`.
- `script-attach-to-node` anexa um script a um nó.
- `script-validate` retorna diagnósticos de análise sintática e compilação para arquivos GDScript; sem um caminho, verifica todos os arquivos `.gd` em `res://`.
- `script-build` executa `dotnet build` (Debug) para que novos scripts C# sejam carregados. O Godot então recarrega o assembly C# e o addon se reconecta, e o resultado da compilação (avisos ou erros) chega após a recarga.
- `script-execute` compila e executa C# no editor com Roslyn. Escreva instruções simples; a última expressão é o resultado. Ele retorna o valor e o que o código imprimiu. Os snippets expiram após 30 segundos por padrão (no máximo 4 minutos), e um loop infinito retorna um erro de timeout em vez de travar o editor.

Você também pode chamar `script-execute` a partir de um terminal:

```bash
godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject
```

## Capturas de tela

As ferramentas de captura de tela retornam imagens PNG que o modelo pode inspecionar: `screenshot-viewport` captura o viewport do editor, `screenshot-camera` renderiza a partir de um nó de câmera, e `screenshot-isolated` renderiza um nó isoladamente a partir de um ângulo escolhido. Peça uma captura de tela após mudanças visuais para que o agente possa verificar o próprio trabalho.

## Ferramentas em jogo

`console-*`, `reflection-*` e `runtime-errors-*` são executados dentro do seu jogo, não no editor. Um jogo não expõe nada até que seu código opte por participar e se conecte; `runtime-errors-get` também precisa de `WithRuntimeErrorCapture()`. Ele captura erros de runtime do GDScript, `push_error` e `push_warning`, erros de shader (Godot 4.5 e mais recentes) e exceções C# não tratadas, para que um agente possa executar o jogo e ver o que realmente quebrou. Configuração: [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/godot/custom-tools#runtime).

## Escolhendo quais ferramentas o agente vê

Toda ferramenta tem um interruptor **Visible** no dock (MCP features, Tools, Open) e em `godot-cli configure`. Ocultar uma ferramenta a remove da lista de ferramentas do agente, o que economiza contexto, mas não a bloqueia. Veja [Configuração](https://ai-game.dev/pt-br/docs/wiki/godot/configuration#mcp-features).

## Mais ferramentas

- [Extensões](https://ai-game.dev/pt-br/docs/wiki/godot/extensions) ensinam ao RQL sobre AnimationPlayer, CSG, GridMap, navegação, partículas, TileMapLayer e os addons Beehave, Dialogic, Phantom Camera e Terrain3D.
- [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/godot/custom-tools) mostram como escrever suas próprias ferramentas em C#.
- [Melhores práticas para Godot](https://ai-game.dev/docs/best-practices/godot) tem padrões de prompt que usam bem essas ferramentas.

---

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

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