Generació d'assets amb IA

Per a què serveix aquest sistema

Que un agent d'IA escrigui fitxers .asset de Unity a mà és una trampa. Els GUIDs deriven, la indentació del YAML es trenca, els camps serialitzats no coincideixen silenciosament amb la classe C# en ús, i l'única resposta és una importació corrupta. L'agent no pot inspeccionar què ha trencat, de manera que endevina i reintenta en un bucle que rarament convergeix.

El mòdul ProjectRecipe de Serenity trenca aquest bucle. En lloc d'escriure directament assets binaris o YAML de Unity, l'agent emet un .serenity-recipe.json llegible per persones. Unity llegeix la recepta, la valida, opcionalment fa un dry-run per previsualitzar els resultats i després la importa a través d'AssetDatabase — de manera correcta, idempotent i amb un informe estructurat que l'agent pot interpretar.

El problema a Unity

El format d'asset serialitzat de Unity no està dissenyat per ser creat per màquines. Els noms de camp canvien entre versions, els grafs polimòrfics amb [SerializeReference] requereixen discriminadors de tipus exactes, i els GUIDs han de coincidir amb cada fitxer .meta o el projecte es trenca en silenci. Un LLM que intenta escriure fitxers .asset directament produeix una sortida versemblant que falla en la importació, amb missatges d'error que no apunten al camp concret que l'agent va errar.

Sense un contracte estable entre l'agent d'IA i l'Editor de Unity, cada sessió de generació d'assets es converteix en una sessió de depuració. L'agent consumeix la major part del seu pressupost de tokens diagnosticant errors d'importació en lloc de produir contingut, i el desenvolupador acaba corregint la sortida a mà de totes formes.

Com ho aborda Serenity

El mòdul ProjectRecipe (namespace Serenity.ProjectRecipe, només per a l'Editor) defineix un únic format d'intercanvi estable: .serenity-recipe.json. Un agent d'IA escriu JSON, mai fitxers .asset ni .meta. SerenityRecipeEngine llegeix la recepta i l'executa en un de tres modes mitjançant RecipeRunMode: Validate analitza i comprova la recepta sense tocar el disc, DryRun resol què es crearia o actualitzaria i retorna un informe de previsualització, i Import escriu els assets a través d'AssetDatabase. Les creacions i actualitzacions són idempotents.

SerenityDiscoveryRegistry.BuildJson() proporciona a l'agent el vocabulari que necessita abans d'escriure cap recepta: cada subclasse d'EventDispatcherSignal, els IDs d'acció registrats, els gestors [AutoRegisterEventAction], els tipus de ScriptableObject autoritzables amb el seu nom de secció de recepta, els vocabularis d'enums i els contractes d'IDs entre assets. L'agent consulta fets del registre en lloc d'endevinar. SerenityRecipeExporter tanca el cicle en sentit contrari: escaneja els assets de Serenity existents al projecte i emet un .serenity-recipe.json que captura l'estat actual.

Com encaixa a Serenity

El mòdul resideix a Assets/Serenity/Scripts/Unity/ProjectRecipe i està marcat com a només per a l'Editor. SerenityRecipeEngine és la pipeline d'importació: accepta una ruta de JSON de recepta, resol els importadors de secció per a cada secció declarada (clips d'àudio, pistes musicals, menús, modals, cutscenes i un importador genèric d'assets que aplica un arbre de camps serialitzats arbitrari incloent grafs de senyals polimòrfics), i produeix un informe on cada resultat és un de Created, Updated o Skipped i cada missatge té una severitat d'Info, Warning, Error o Blocker. SerenityRecipeTemplateGenerator instancia qualsevol tipus de ScriptableObject autoritzable en temps d'edició, captura el seu arbre de camps serialitzats exacte i en ús, i escriu un stub llest per editar — de manera que l'stub mai divergeixi de la definició en C#.

Cada classe del mòdul té un punt d'entrada de línia de comandes sense capçalera: ImportFromCommandLine, ExportFromCommandLine, GenerateFromCommandLine i DumpFromCommandLine. Cadascun és invocable des d'una pipeline de CI o des de qualsevol eina que pugui invocar l'Editor de Unity en mode batch. El codi de sortida és 1 quan l'informe conté elements de severitat Blocker o Error, i 0 en cas contrari. Les finestres de l'Editor a Tools/Serenity/ exposen les mateixes operacions de manera interactiva per als desenvolupadors que prefereixen una interfície gràfica. La guia d'automatització MCP (McpAutomation.md) documenta el bucle d'agent recomanat usant aquests punts d'entrada: descobrir, emetre recepta, validar, dry-run, importar.

Flux de treball pràctic

1. Comença amb l'AI Prompt Builder (Tools ▸ Serenity ▸ AI ▸ Prompt Builder): un assistent per passos que t'entrevista sobre el que vols construir, escaneja el projecte perquè el prompt faci referència a assets reals per ampliar, i lliura el prompt òptim per al teu agent al porta-retalls, un fitxer o un slash command instal·lat.
2. Crida SerenityDiscoveryRegistry.BuildJson() per obtenir un registre llegible per màquina de cada tipus, senyal, enum i ID entre assets que l'agent pot referenciar.
3. Fes servir SerenityRecipeTemplateGenerator per generar un stub amb els camps exactes del tipus de ScriptableObject que l'agent necessita omplir.
4. Crea el fitxer .serenity-recipe.json usant l'stub i el registre de descobriment com a font de veritat — sense fitxers .asset ni .meta.
5. Executa RecipeRunMode.Validate per detectar errors d'esquema o de referència abans de tocar el projecte.
6. Executa RecipeRunMode.DryRun per previsualitzar quins assets es crearien o s'actualitzarien i confirmar que els resultats són correctes.
7. Executa RecipeRunMode.Import per escriure els assets. Revisa l'informe JSON estructurat per trobar elements amb severitat Warning o Error.

Què inclou

• Format d'intercanvi .serenity-recipe.json estable — sense edició manual de GUIDs ni YAML
• SerenityRecipeEngine amb tres valors de RecipeRunMode: Validate, DryRun i Import
• Creació i actualització d'assets idempotent a través d'AssetDatabase
• Importadors de secció per a clips d'àudio, pistes musicals, menús, modals, cutscenes i un importador genèric d'arbre de camps
• Importador genèric d'assets que aplica arbres de camps serialitzats arbitraris, inclosos grafs polimòrfics amb [SerializeReference]
• SerenityDiscoveryRegistry.BuildJson() per a vocabulari llegible per màquina de tipus, senyals, enums i IDs entre assets
• SerenityRecipeExporter per convertir assets existents de tornada a un fitxer de recepta
• SerenityRecipeTemplateGenerator per a stubs de camps en temps real, sense desfasament, de qualsevol ScriptableObject autoritzable
• Punts d'entrada de línia de comandes sense capçalera per a cada operació, amb informes JSON i codis de sortida accionables
• Assistent AI Prompt Builder que converteix una entrevista sobre el teu objectiu en el prompt òptim per a l'agent, amb una biblioteca personal d'instruccions reutilitzables

Quan fer-lo servir

• Projectes on un agent d'IA o una pipeline d'automatització necessita crear o actualitzar assets ScriptableObject de Unity sense trencar el projecte.
• Equips que volen un contracte estable i revisable entre la sortida generada per LLM i l'Editor de Unity, en lloc de la creació fràgil d'assets YAML o binaris.
• Pipelines de CI que necessiten generar, validar i importar assets de contingut de joc en mode batch amb informes estructurats i analitzables.
• Qualsevol flux de treball que integri un agent d'IA compatible amb MCP amb l'automatització de l'Editor de Unity a través de punts d'entrada de línia de comandes.

Sistemes relacionats

• Workflow d'Addressables Asset prefetcher basat en servei amb contextos, etiquetes, polítiques de cau i tasques de prewarm per a Unity Addressables.
• Event Dispatcher Senyals tipades despatxades a través d'un servei, amb suport per a autoregistre i sense singletons estàtics.
• Sistema de menús Menús declaratius, temes d'UI compartits i navegació predictible, configurats com a assets en lloc de cablejats a mà sobre GameObjects.
• Sistema de localització Canvi d'idioma en temps d'execució, pistes separades per a idioma de joc i de veu, i menús i modals localitzats des del primer moment.