Herramientas
Las 27 herramientas MCP integradas de Unreal — RQL, Blueprints, C++, Python, capturas y consola — y prompts de ejemplo para el Unreal Editor.
Esta página describe lo que un agente de IA puede hacer en el Unreal Editor con Unreal MCP. El plugin incluye 27 herramientas en 7 familias. Rara vez llamas a una herramienta por su nombre: pregunta en lenguaje natural y el agente elige la herramienta. Conocer las familias te ayuda a pedir cosas que el agente pueda hacer realmente.
Para ver las fichas y los parámetros de cada herramienta, consulta el catálogo de herramientas de Unreal.
RQL: un único lenguaje de consulta para los datos del editor
Unreal MCP no tiene una herramienta por cada operación del editor. En su lugar, los datos del editor pasan por RQL, un lenguaje de consulta que lee y modifica actores, componentes, assets, niveles y el estado del editor en una sola llamada.
| Herramienta | Qué hace |
|---|---|
rql-query | Consulta de solo lectura sobre el editor en vivo, con resultados en tablas compactas |
rql-mutate | Una consulta que termina con set o call; todo o nada, un solo paso de deshacer y una vista previa con dry_run |
rql-schema | Lista fuentes, funciones y clases; si se le indica un tipo, lista los miembros y métodos de ese tipo |
Algunos ejemplos de cómo es RQL (el agente los escribe por ti):
actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"Además de actores y componentes, RQL llega a:
- Assets y niveles: crear, copiar, mover, eliminar e importar assets, crear carpetas e instancias de material, abrir, crear y guardar niveles, añadir subniveles de streaming.
- Estado del editor: selección, estado de Play In Editor, historial de deshacer, el log del editor.
- DataTables: leer y editar filas (
Rows["Sword"].Damage), añadir, eliminar, renombrar y duplicar filas. - Gameplay tags: listar, añadir, eliminar y renombrar tags.
- Project Settings y Editor Preferences: leer y cambiar propiedades de configuración, guardadas en el archivo
.inicorrespondiente. - Grafos de Blueprint: añadir llamadas a funciones, variables, eventos, casts, ramas y bucles, conectar pines y después
call Compile(). - Widget Blueprints: recorrer y editar el árbol de widgets, añadir widgets y definir el layout.
- Structs definidos por el usuario: añadir, eliminar y renombrar campos.
- Level Sequences: vincular actores, añadir pistas y claves.
Cada mutación es una transacción del editor, así que Ctrl+Z la revierte. El agente aprende el lenguaje con la skill unreal-rql, que además indica qué añaden las extensiones instaladas.
Prompts de ejemplo:
- "Lista todas las luces puntuales del nivel con su intensidad y luego duplica la intensidad de las más tenues."
- "Genera 20 cubos en una cuadrícula de 5 por 4, separados por 200 unidades."
- "Añade una fila Bow con Damage 7 a la DataTable DT_Weapons."
- "Establece el mapa predeterminado del juego en /Game/Maps/Arena."
Familia de Blueprint
La creación de Blueprints es la principal superficie de scripting de Unreal, y el agente obtiene un ciclo de retroalimentación completo: crear, editar, compilar, leer los errores y corregir.
| Herramienta | Qué hace |
|---|---|
blueprint-create | Crea una clase Blueprint a partir de una clase padre |
blueprint-get | Resume un Blueprint: variables, componentes, funciones y eventos, y la cadena de padres |
blueprint-add-component | Añade un componente al construction script |
blueprint-remove-component | Elimina un componente |
blueprint-add-variable | Añade una variable miembro con tipo |
blueprint-modify-variable | Cambia una variable miembro |
blueprint-set-default | Establece una propiedad predeterminada de la clase |
blueprint-add-function | Añade un stub de función |
blueprint-add-event | Añade un evento como BeginPlay o Tick |
blueprint-compile | Compila y devuelve una lista estructurada de errores y advertencias |
blueprint-spawn | Coloca una instancia del Blueprint en el nivel |
Ejemplo: "Crea un Blueprint de Actor BP_Door con un componente de malla estática y una variable bool IsOpen, compílalo y coloca uno en el origen."
Familia de código fuente / C++
| Herramienta | Qué hace |
|---|---|
source-read | Lee un archivo C++ del proyecto, por fragmentos |
source-create-class | Genera el esqueleto de una nueva clase C++ (cabecera y fuente) |
source-update | Edita un archivo de código fuente |
source-delete | Elimina un archivo de código fuente |
source-list | Lista los archivos de código fuente del módulo |
source-compile | Compila con Live Coding cuando está activo; si no, con Unreal Build Tool, y devuelve un informe de errores estructurado |
Todas las operaciones de archivos están limitadas a <Project>/Source/. Ejemplo: "Crea un componente C++ UHealthComponent con MaxHealth y una función TakeDamage, compila y corrige los errores que aparezcan."
Familia de Python
| Herramienta | Qué hace |
|---|---|
python-execute | Ejecuta Python en el editor con el módulo unreal ya importado |
La última expresión se devuelve como resultado, la salida de print vuelve como logs y los errores señalan la línea que falla. include añade archivos o carpetas auxiliares desde <Project>/.ai-game-dev/snippets, y timeout (30 segundos por defecto) detiene un script descontrolado. El plugin activa el Python Editor Script Plugin de Unreal; Python es solo para el editor y nunca se incluye en un juego empaquetado. El cableado de grafos de Blueprint no está expuesto a Python; usa las herramientas de Blueprint o RQL para eso.
También puedes ejecutar Python desde una terminal con unreal-mcp-cli exec; consulta la referencia de la CLI.
Familia de capturas de pantalla
| Herramienta | Qué hace |
|---|---|
screenshot-viewport | Captura el viewport activo del editor |
screenshot-game-view | Captura la vista de juego de Play In Editor |
screenshot-camera | Renderiza desde un actor de cámara |
screenshot-isolated | Renderiza un actor por separado |
Las imágenes vuelven como contenido PNG que el modelo puede ver, 1024 píxeles por defecto y como máximo 2048 por lado. Necesitan un editor con GPU; bajo -nullrhi devuelven un error. Ejemplo: «Toma una captura desde CameraActor_Main y dime si la iluminación parece demasiado oscura».
Consola y lista de herramientas
| Herramienta | Qué hace |
|---|---|
console-run-command | Ejecuta un comando de consola de Unreal o establece una variable de consola |
unreal-tool-list | Lista todas las herramientas, incluidas las ocultas, con filtro, descripciones y entradas opcionales |
La lectura del log, el estado de Play In Editor y la selección pasan por RQL.
Herramientas que el agente nunca ve
Algunas herramientas del sistema sirven a la CLI y a la app y no se muestran a los agentes de IA:
ping: comprueba la cadena de plugin, puente y servidor.unreal-skill-generate: escribe unSKILL.mdpor herramienta en una carpeta de skills (por defecto.claude/skills); el botón Generate skill files lo utiliza.unreal-skill-create: genera un nuevo archivo de herramienta en C++ en el módulo de editor del plugin. Requiere una instalación del plugin desde código fuente y recompilar el editor antes de que la herramienta funcione.editor-quit: guarda y cierra un editor que inició una sesión de CLI.
Prompts y recursos
El plugin también incluye un prompt MCP, level-design-brief (un brief de diseño de niveles a partir de un tema), y dos recursos: unreal://project/levels (una instantánea JSON del mundo activo y sus niveles) y unreal://project/icon.
Controla lo que ve el agente
Oculta las herramientas que no necesites en la ventana MCP Tools, o sirve solo un conjunto fijo con UNREAL_MCP_TOOLS. Consulta Configuración. Para añadir capacidades, instala extensiones o escribe herramientas personalizadas.
Solo para el editor
Las 27 herramientas controlan el editor. Varias son potentes (rql-mutate, console-run-command, python-execute), así que ninguna se compila en un juego empaquetado. Un juego que opta por una conexión en tiempo de ejecución solo expone las herramientas que registra por sí mismo.
Encontrarás consejos para sacar el máximo partido a estas herramientas en las buenas prácticas de Unreal.