Generación de assets con IA

Para qué sirve este sistema

Que un agente de IA escriba archivos .asset de Unity a mano es una trampa. Los GUIDs derivan, la indentación del YAML se rompe, los campos serializados no coinciden silenciosamente con la clase C# en uso, y la única respuesta es una importación corrupta. El agente no puede inspeccionar qué ha roto, así que adivina y reintenta en un bucle que raramente converge.

El módulo ProjectRecipe de Serenity rompe ese bucle. En lugar de escribir directamente assets binarios o YAML de Unity, el agente emite un .serenity-recipe.json legible por personas. Unity lee la receta, la valida, opcionalmente hace un dry-run para previsualizar los resultados y luego la importa a través de AssetDatabase — de forma correcta, idempotente y con un informe estructurado que el agente puede interpretar.

El problema en Unity

El formato de asset serializado de Unity no está diseñado para ser creado por máquinas. Los nombres de campo cambian entre versiones, los grafos polimórficos con [SerializeReference] requieren discriminadores de tipo exactos, y los GUIDs deben coincidir con cada archivo .meta o el proyecto se rompe en silencio. Un LLM que intenta escribir archivos .asset directamente produce una salida verosímil que falla en la importación, con mensajes de error que no apuntan al campo concreto que el agente se equivocó.

Sin un contrato estable entre el agente de IA y el Editor de Unity, cada sesión de generación de assets se convierte en una sesión de depuración. El agente consume la mayor parte de su presupuesto de tokens diagnosticando errores de importación en lugar de producir contenido, y el desarrollador termina corrigiendo la salida a mano de todas formas.

Cómo lo aborda Serenity

El módulo ProjectRecipe (namespace Serenity.ProjectRecipe, solo para el Editor) define un único formato de intercambio estable: .serenity-recipe.json. Un agente de IA escribe JSON, nunca archivos .asset ni .meta. SerenityRecipeEngine lee la receta y la ejecuta en uno de tres modos mediante RecipeRunMode: Validate analiza y comprueba la receta sin tocar el disco, DryRun resuelve qué se crearía o actualizaría y devuelve un informe de previsualización, e Import escribe los assets a través de AssetDatabase. Las creaciones y actualizaciones son idempotentes.

SerenityDiscoveryRegistry.BuildJson() proporciona al agente el vocabulario que necesita antes de escribir cualquier receta: cada subclase de EventDispatcherSignal, los IDs de acción registrados, los manejadores [AutoRegisterEventAction], los tipos de ScriptableObject autorizables con su nombre de sección de receta, los vocabularios de enums y los contratos de IDs entre assets. El agente consulta hechos del registro en lugar de adivinar. SerenityRecipeExporter cierra el ciclo en sentido contrario: escanea los assets de Serenity existentes en el proyecto y emite un .serenity-recipe.json que captura el estado actual.

Cómo encaja en Serenity

El módulo reside bajo Assets/Serenity/Scripts/Unity/ProjectRecipe y está marcado como solo para el Editor. SerenityRecipeEngine es la pipeline de importación: acepta una ruta de JSON de receta, resuelve los importadores de sección para cada sección declarada (clips de audio, pistas musicales, menús, modales, cutscenes y un importador genérico de assets que aplica un árbol de campos serializados arbitrario incluyendo grafos de señales polimórficos), y produce un informe donde cada resultado es uno de Created, Updated o Skipped y cada mensaje tiene una severidad de Info, Warning, Error o Blocker. SerenityRecipeTemplateGenerator instancia cualquier tipo de ScriptableObject autorizable en tiempo de edición, captura su árbol de campos serializados exacto y en uso, y escribe un stub listo para editar — así el stub nunca diverge de la definición en C#.

Cada clase del módulo tiene un punto de entrada de línea de comandos sin cabecera: ImportFromCommandLine, ExportFromCommandLine, GenerateFromCommandLine y DumpFromCommandLine. Cada uno es invocable desde una pipeline de CI o desde cualquier herramienta que pueda invocar el Editor de Unity en modo batch. El código de salida es 1 cuando el informe contiene elementos de severidad Blocker o Error, y 0 en caso contrario. Las ventanas del Editor bajo Tools/Serenity/ exponen las mismas operaciones de forma interactiva para los desarrolladores que prefieren una interfaz gráfica. La guía de automatización MCP (McpAutomation.md) documenta el bucle de agente recomendado usando estos puntos de entrada: descubrir, emitir receta, validar, dry-run, importar.

Flujo de trabajo práctico

1. Empieza con el AI Prompt Builder (Tools ▸ Serenity ▸ AI ▸ Prompt Builder): un asistente por pasos que te entrevista sobre lo que quieres construir, escanea el proyecto para que el prompt haga referencia a assets reales que ampliar, y entrega el prompt óptimo para tu agente en el portapapeles, un archivo o un slash command instalado.
2. Llama a SerenityDiscoveryRegistry.BuildJson() para obtener un registro legible por máquina de cada tipo, señal, enum e ID entre assets que el agente puede referenciar.
3. Usa SerenityRecipeTemplateGenerator para generar un stub con los campos exactos del tipo de ScriptableObject que el agente necesita rellenar.
4. Crea el archivo .serenity-recipe.json usando el stub y el registro de descubrimiento como fuente de verdad — sin archivos .asset ni .meta.
5. Ejecuta RecipeRunMode.Validate para detectar errores de esquema o de referencia antes de tocar el proyecto.
6. Ejecuta RecipeRunMode.DryRun para previsualizar qué assets se crearían o actualizarían y confirmar que los resultados son correctos.
7. Ejecuta RecipeRunMode.Import para escribir los assets. Revisa el informe JSON estructurado en busca de elementos con severidad Warning o Error.

Qué incluye

• Formato de intercambio .serenity-recipe.json estable — sin edición manual de GUIDs ni YAML
• SerenityRecipeEngine con tres valores de RecipeRunMode: Validate, DryRun e Import
• Creación y actualización de assets idempotente a través de AssetDatabase
• Importadores de sección para clips de audio, pistas musicales, menús, modales, cutscenes y un importador genérico de árbol de campos
• Importador genérico de assets que aplica árboles de campos serializados arbitrarios, incluidos grafos polimórficos con [SerializeReference]
• SerenityDiscoveryRegistry.BuildJson() para vocabulario legible por máquina de tipos, señales, enums e IDs entre assets
• SerenityRecipeExporter para convertir assets existentes de vuelta a un archivo de receta
• SerenityRecipeTemplateGenerator para stubs de campos en tiempo real, sin desfase, de cualquier ScriptableObject autorizable
• Puntos de entrada de línea de comandos sin cabecera para cada operación, con informes JSON y códigos de salida accionables
• Asistente AI Prompt Builder que convierte una entrevista sobre tu objetivo en el prompt óptimo para el agente, con una biblioteca personal de instrucciones reutilizables

Cuándo usarlo

• Proyectos donde un agente de IA o una pipeline de automatización necesita crear o actualizar assets ScriptableObject de Unity sin romper el proyecto.
• Equipos que quieren un contrato estable y revisable entre la salida generada por LLM y el Editor de Unity, en lugar de la creación frágil de assets YAML o binarios.
• Pipelines de CI que necesitan generar, validar e importar assets de contenido de juego en modo batch con informes estructurados y analizables.
• Cualquier flujo de trabajo que integre un agente de IA compatible con MCP con la automatización del Editor de Unity a través de puntos de entrada de línea de comandos.

Sistemas relacionados

• Workflow de Addressables Asset prefetcher basado en servicio con contextos, etiquetas, políticas de caché y tareas de prewarm para Unity Addressables.
• Event Dispatcher Señales tipadas despachadas a través de un servicio, con soporte para autoregistro y sin singletons estáticos.
• Sistema de menús Menús declarativos, temas de UI compartidos y navegación predecible, configurados como assets en vez de cableados a mano sobre GameObjects.
• Sistema de localización Cambio de idioma en tiempo de ejecución, pistas separadas para idioma de juego y de voz, y menús y modales localizados desde el primer momento.