Herramientas y 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, y el lenguaje de consultas está documentado en la referencia de 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:

Una lista corta cuesta menos tokens y deja al modelo más espacio para razonar. Las demás herramientas siguen instaladas; consulta Herramientas ocultas.

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:

roots | recurse children | select name active

Encuentra al jugador:

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

Crea un plano de suelo:

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

Añade un componente y guarda:

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

Lee solo los errores de la Console:

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#

Se accede a los assets por ruta con unity.asset("Assets/…") o se buscan con unity.assets("t:Material"). Cada extensión 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.

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:

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.

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:

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 y referencia de RQL.
• Herramientas personalizadas para añadir las tuyas.
• Buenas prácticas de Unity para el prompting.