# Herramientas — Godot · AI Game Developer Wiki

Herramientas MCP de Godot para agentes de IA: consultas RQL de nodos, escenas y recursos, scripts de C# y GDScript, capturas y herramientas en juego.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/godot/tools).

Godot MCP incluye 24 herramientas integradas en 9 familias. La mayor parte del trabajo en el editor pasa por tres herramientas RQL, así que el agente usa un único lenguaje de consultas para nodos, escenas, recursos, archivos y el estado del editor en lugar de decenas de herramientas separadas. Esta página explica cada familia y cuándo la usa el agente. La lista con búsqueda, con parámetros y prompts de ejemplo, es el [catálogo de herramientas de Godot](https://ai-game.dev/docs/tools/godot).

## Familias de herramientas

| Familia | Herramientas | Para qué sirve |
| --- | --- | --- |
| rql | `rql-query`, `rql-mutate`, `rql-schema` | Leer y modificar el editor en vivo: nodos, propiedades de Godot, escenas, recursos, archivos, ajustes del proyecto, mapa de entrada, autoloads, grupos, señales y estado del editor. |
| script | `script-read`, `script-create`, `script-update`, `script-delete`, `script-attach-to-node`, `script-validate`, `script-build`, `script-execute` | Archivos de C# y GDScript, adjuntar scripts, validar GDScript, compilar el proyecto de C# y ejecutar C# en el editor. |
| screenshot | `screenshot-viewport`, `screenshot-camera`, `screenshot-isolated` | Imágenes PNG del viewport del editor, de una cámara o de un nodo renderizado por separado. |
| console | `console-get-logs`, `console-clear-logs` | Registros de un juego en ejecución. En el editor, la fuente `console` de RQL. |
| reflection | `reflection-method-find`, `reflection-method-call` | Buscar y llamar métodos de C# en un juego en ejecución. En el editor, `call` de RQL. |
| runtime-errors | `runtime-errors-get`, `runtime-errors-clear` | Errores producidos dentro de un juego en ejecución. Desactivado por defecto. |
| ping | `ping` | Sonda de disponibilidad. Una herramienta del sistema, no se muestra a los agentes. |
| skills | `godot-skill-create`, `godot-skill-generate` | Escribir un archivo de herramienta nuevo, regenerar los archivos de skills. Herramientas del sistema. |
| session | `session-close` | Guardar y cerrar un editor que inició `godot-cli`. Herramienta del sistema. |

Se accede a las herramientas del sistema por la ruta `/api/system-tools/` del servidor (por ejemplo, con `godot-cli run-system-tool ping`) y no se listan a los agentes de IA. Las familias console, reflection y runtime-errors sirven a un juego en ejecución que hayas conectado tú mismo; consulta [Herramientas personalizadas](https://ai-game.dev/es/docs/wiki/godot/custom-tools#runtime).

## RQL: un único lenguaje de consultas para el editor

RQL (Reflection Query Language) es la capa de datos de las herramientas del editor. Una consulta parte de una fuente, la filtra y le da forma con etapas separadas por `|`, y en `rql-mutate` termina con `set` o `call`. Algunos ejemplos que el agente podría 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` es de solo lectura y devuelve filas compactas.
- `rql-mutate` modifica cosas. Cada destino y cada valor se comprueba primero, así que una consulta fallida no cambia nada. `dry_run` previsualiza el cambio. Cada llamada es un paso de deshacer (Ctrl+Z en el editor).
- `rql-schema` lista las fuentes, funciones y clases de nodo de la escena editada, o los miembros, métodos y propiedades de Godot de un tipo. Con un nombre de extensión, imprime la guía de esa extensión.

Las fuentes incluyen `nodes`, `root`, `selection`, `scenes`, `files`, `folders`, `classes`, `console`, `editor`, `project`, `settings`, `inputActions`, `autoloads`, `groups`, `layers` y `tools`. Se puede acceder a las propiedades de Godot como miembros de C# (`Position`, `Visible`) o por su nombre de Godot en `props["snake_name"]`, que incluye las variables de GDScript. RQL también maneja señales, grupos, TileSets, Themes, parámetros de ShaderMaterial y MeshLibraries.

Las llamadas del editor cubren el trabajo con escenas y archivos: `NewScene`, `OpenScene`, `SaveScene`, `SaveAllScenes`, `ReloadScene`, `CreateResource`, `MoveResource`, `DeleteResource`, `CreateFolder`, `DeleteFolder`, `Reimport`, `Undo`, `Redo`, `PlayScene` y `StopScene`. La fuente `gameLog` lee lo que imprimió un juego iniciado desde el editor.

Las ediciones de escena marcan la escena como no guardada, igual que tus propias ediciones. Los archivos de recursos editados y `project.godot` se guardan inmediatamente.

## Scripts: C# y GDScript

- `script-read`, `script-create`, `script-update` y `script-delete` trabajan sobre archivos `.cs` y `.gd`.
- `script-attach-to-node` adjunta un script a un nodo.
- `script-validate` devuelve diagnósticos de análisis y compilación de los archivos GDScript; sin una ruta, comprueba todos los archivos `.gd` bajo `res://`.
- `script-build` ejecuta `dotnet build` (Debug) para que se carguen los scripts de C# nuevos. Después, Godot recarga el ensamblado de C# y el addon se reconecta, y el resultado de la compilación (advertencias o errores) llega tras la recarga.
- `script-execute` compila y ejecuta C# en el editor con Roslyn. Escribe instrucciones simples; la última expresión es el resultado. Devuelve el valor y lo que imprimió el código. Los fragmentos agotan el tiempo de espera tras 30 segundos por defecto (como máximo 4 minutos), y un bucle infinito devuelve un error de tiempo de espera en lugar de congelar el editor.

También puedes llamar a `script-execute` desde una terminal:

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

## Capturas de pantalla

Las herramientas de captura de pantalla devuelven imágenes PNG que el modelo puede inspeccionar: `screenshot-viewport` captura el viewport del editor, `screenshot-camera` renderiza desde un nodo de cámara y `screenshot-isolated` renderiza un nodo por sí solo desde un ángulo elegido. Pide una captura de pantalla después de cambios visuales para que el agente pueda comprobar su propio trabajo.

## Herramientas en el juego

`console-*`, `reflection-*` y `runtime-errors-*` se ejecutan dentro de tu juego, no en el editor. Un juego no expone nada hasta que tu código lo habilita y se conecta; `runtime-errors-get` además necesita `WithRuntimeErrorCapture()`. Captura errores de tiempo de ejecución de GDScript, `push_error` y `push_warning`, errores de shaders (Godot 4.5 y posteriores) y excepciones de C# no controladas, de modo que un agente puede ejecutar el juego y ver qué falló realmente. Configuración: [Herramientas personalizadas](https://ai-game.dev/es/docs/wiki/godot/custom-tools#runtime).

## Elegir qué herramientas ve el agente

Cada herramienta tiene un interruptor **Visible** en el dock (MCP features, Tools, Open) y en `godot-cli configure`. Ocultar una herramienta la elimina de la lista de herramientas del agente, lo que ahorra contexto, pero no la bloquea. Consulta [Configuración](https://ai-game.dev/es/docs/wiki/godot/configuration#mcp-features).

## Más herramientas

- [Extensiones](https://ai-game.dev/es/docs/wiki/godot/extensions) enseñan a RQL sobre AnimationPlayer, CSG, GridMap, navegación, partículas, TileMapLayer y los addons Beehave, Dialogic, Phantom Camera y Terrain3D.
- [Herramientas personalizadas](https://ai-game.dev/es/docs/wiki/godot/custom-tools) muestra cómo escribir tus propias herramientas en C#.
- [Buenas prácticas para Godot](https://ai-game.dev/docs/best-practices/godot) contiene patrones de prompts que usan bien estas herramientas.

---

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

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