# Herramientas y RQL — Unity · AI Game Developer Wiki

Qué puede hacer un agente de IA en el Editor de Unity con Unity MCP: RQL, capturas de pantalla, scripts de C#, tests, paquetes y profiling.

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

Esta página explica qué puede hacer el agente de IA en tu proyecto de Unity una vez conectado Unity MCP: qué herramientas ve, cómo RQL le permite leer y cambiar casi cualquier cosa del Editor y qué herramientas están instaladas pero ocultas. La lista completa y con búsqueda, con sus parámetros, está en el [catálogo de herramientas de Unity](https://ai-game.dev/docs/tools/unity), y el lenguaje de consultas está documentado en la [referencia de RQL](https://ai-game.dev/docs/rql).

## Las herramientas que el agente ve por defecto

Desde la versión 1.0.0 el plugin mantiene corta la lista de herramientas del agente. Estas siete herramientas son visibles tras la instalación:

| Herramienta | Qué hace |
| --- | --- |
| `rql-query` | Lee datos del Editor con una consulta RQL: escenas, GameObjects, componentes, assets, la Console, ajustes, tests, el profiler. |
| `rql-mutate` | Cambia datos del Editor o llama a operaciones del Editor con RQL: crear, modificar, mover y eliminar objetos y assets, abrir y guardar escenas. |
| `rql-schema` | Describe las fuentes, tipos, miembros y llamadas que RQL puede usar, e imprime guías por temática. El agente empieza aquí cuando tiene dudas. |
| `script-execute` | Compila y ejecuta código C# en el Editor con Roslyn y devuelve el resultado. |
| `screenshot-isolated` | Renderiza un GameObject de forma aislada desde un ángulo elegido, opcionalmente como un compuesto 2x2, para que el modelo pueda verlo. |
| `tests-run` | Ejecuta tests EditMode o PlayMode y devuelve los resultados por test. |
| `unity-tool-list` | Lista todas las herramientas e indica si el agente las ve. |

Una lista corta cuesta menos tokens y deja al modelo más espacio para razonar. Las demás herramientas siguen instaladas; consulta [Herramientas ocultas](https://ai-game.dev/es/docs/wiki/unity/tools-and-rql#hidden-tools).

## RQL: un solo lenguaje para todo el Editor

RQL es un lenguaje de consultas sobre los datos en vivo del Editor. Una consulta empieza con una **fuente** y pasa el resultado por etapas separadas por `|`, como `where`, `select`, `get`, `set` y `call`. En lugar de una herramienta por acción (las antiguas `gameobject-create`, `scene-save`, `console-get-logs` y decenas más), el agente escribe una sola consulta.

Lee toda la jerarquía de las escenas abiertas:

```text
roots | recurse children | select name active
```

Encuentra al jugador:

```text
objects | where name == "Player" | select path name active
```

Crea un plano de suelo:

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

Añade un componente y guarda:

```text
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()
```

Lee solo los errores de la Console:

```text
console | where logType == "Error"
```

Cada llamada a `rql-mutate` es un único grupo de Undo, así que Ctrl+Z la revierte, y los assets, las escenas y el prefab abierto modificados se guardan después de la mutación. `rql-mutate` también acepta `dry_run` para previsualizar qué cambiaría y `max_targets` para limitar cuántos objetos puede tocar una mutación.

### Fuentes RQL en Unity

| Fuente | Contenido |
| --- | --- |
| `scenes`, `roots`, `objects` | Escenas cargadas, sus GameObjects raíz y todos los GameObject que contienen. |
| `selection` | La selección actual del Editor. |
| `prefab` | El prefab abierto en modo prefab. |
| `editor` | Operaciones del Editor: crear GameObjects, materiales, carpetas y escenas; abrir y guardar escenas y prefabs; copiar, mover y eliminar assets; ejecutar elementos de menú; estado del modo de reproducción. |
| `settings` | Ajustes del proyecto. |
| `console` | Entradas del log del Editor capturadas. |
| `shaders`, `componentTypes` | Shaders y tipos de componentes disponibles. |
| `tests`, `testResults` | El árbol de tests y los últimos resultados. |
| `profiler` | Datos de memoria, renderizado, scripts y frames; iniciar, detener, guardar y cargar capturas. |
| `lighting` | El entorno de la escena activa (ambiente, niebla, skybox, sol, reflejos), los Lighting Settings y el bake. |

Se accede a los assets por ruta con `unity.asset("Assets/…")` o se buscan con `unity.assets("t:Material")`. Cada [extensión](https://ai-game.dev/es/docs/wiki/unity/extensions) instalada añade sus propias fuentes y tipos, por ejemplo `tilemap` o `cinemachine`.

Como RQL funciona mediante reflexión, el agente también puede leer y establecer miembros de tus propios componentes, no solo de los integrados de Unity. Puedes enseñar a RQL tus propios tipos con [adaptadores personalizados](https://ai-game.dev/docs/rql/custom-adapters).

## Scripts y ejecución de C#

`script-execute` compila un fragmento de C# con Roslyn y lo ejecuta en el Editor. Recibe el código y, opcionalmente, `className`, `methodName`, `usings` adicionales y archivos auxiliares para `include`. Es la vía de escape para todo lo que RQL no cubre. Desde una terminal, `unity-mcp-cli exec` llama a la misma herramienta:

```bash
unity-mcp-cli exec 'Application.unityVersion'
```

Para escribir archivos en lugar de ejecutar código, las herramientas ocultas `script-read`, `script-update-or-create` y `script-delete` gestionan los archivos `.cs` del proyecto. Unity recompila tras un cambio; la conexión se interrumpe brevemente durante la recarga de dominio y vuelve por sí sola.

## Tests

`tests-run` ejecuta tests EditMode o PlayMode (`testMode`, por defecto EditMode). Filtra por ensamblado, namespace, clase o método, o pasa una selección RQL sobre la fuente `tests` para ejecutar exactamente los tests que elijas en una sola ejecución. Los resultados se pueden filtrar con RQL sobre `testResults`. Las opciones controlan si se incluyen los tests que pasan, los mensajes, las trazas de pila y los logs de la Console, lo que mantiene pequeña la salida.

```bash
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'
```

## Capturas de pantalla

`screenshot-isolated` está visible por defecto. Otras tres están ocultas: `screenshot-scene-view`, `screenshot-game-view` y `screenshot-camera`. Las imágenes se limitan a 3840 píxeles en el lado más largo para que quepan en el transporte MCP. Las capturas necesitan un dispositivo gráfico: un Editor iniciado con `-nographics` devuelve un error en lugar de una imagen en blanco.

## Herramientas ocultas

Están instaladas pero no aparecen en la lista del agente. Una herramienta oculta sigue ejecutándose cuando se la llama por nombre.

- Capturas de pantalla: `screenshot-scene-view`, `screenshot-game-view`, `screenshot-camera`.
- Scripts: `script-read`, `script-update-or-create`, `script-delete`.
- Paquetes: `package-list`, `package-search`, `package-add`, `package-remove` para el Unity Package Manager.
- Gestión de herramientas: `tool-set-visibility` y su alias obsoleto `tool-set-enabled-state`.

Muéstralas en la ventana de AI Game Developer (**Tools > Open**), con la herramienta `tool-set-visibility` o con:

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list
```

## Prompts y skills

El plugin también incluye 46 prompts MCP (plantillas de comandos con barra como `setup-basic-scene` o `add-event-system`) en seis grupos: scripting, GameObjects y componentes, escenas, depuración y testing, gestión de assets, animación y timeline. Están ocultos por defecto; activa los que quieras en **Prompts > Open**.

Las **skills** son archivos Markdown que el plugin genera en la carpeta de skills de tu agente. Incluyen la guía `unity-rql` con la sintaxis RQL para Unity y cada extensión instalada, además de notas de configuración y de CLI. Actívalas con **Skills > Auto-generate** en la ventana, o ejecuta `unity-mcp-cli setup-skills <agent>`.

## Nombres de herramientas de tutoriales antiguos

La versión 1.0.0 eliminó las herramientas de una por acción. Si un tutorial menciona alguna de ellas, usa RQL en su lugar:

- `gameobject-create`, `gameobject-find`, `gameobject-modify`, `gameobject-destroy`, `gameobject-component-*`: RQL sobre `objects`, `roots` y `selection` con `set` y `call`.
- `scene-create`, `scene-open`, `scene-save`: `editor | call NewScene(…)`, `OpenScene(…)`, `SaveScenes()`.
- `assets-*`, `assets-prefab-*`, `assets-material-create`: `unity.asset(…)`, `unity.assets(…)` y llamadas a `editor` como `CreateMaterial`, `CopyAsset`, `InstantiatePrefab`.
- `console-get-logs`, `console-clear-logs`: la fuente `console` y `editor | call ClearConsole()`.
- `editor-application-*`, `editor-selection-*`: miembros de `editor` como `isPlaying` y `selection`.
- `reflection-method-find`, `reflection-method-call`, `type-get-json-schema`: `call` de RQL y `rql-schema`.
- `profiler-*`: la fuente `profiler`.

## Páginas relacionadas

- [Catálogo de herramientas de Unity](https://ai-game.dev/docs/tools/unity) y [referencia de RQL](https://ai-game.dev/docs/rql).
- [Herramientas personalizadas](https://ai-game.dev/es/docs/wiki/unity/custom-tools) para añadir las tuyas.
- [Buenas prácticas de Unity](https://ai-game.dev/docs/best-practices/unity) para el prompting.

---

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

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