Ferramentas

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.

Famílias de ferramentas#

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.

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:

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:

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.

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.

Mais ferramentas#

• Extensões ensinam ao RQL sobre AnimationPlayer, CSG, GridMap, navegação, partículas, TileMapLayer e os addons Beehave, Dialogic, Phantom Camera e Terrain3D.
• Ferramentas personalizadas mostram como escrever suas próprias ferramentas em C#.
• Melhores práticas para Godot tem padrões de prompt que usam bem essas ferramentas.