AI Asset Generation

What the system is for

Having an AI agent hand-author Unity .asset files is a trap. GUIDs drift, YAML indentation breaks, serialized fields silently mismatch the live C# class, and the only feedback is a corrupt import. The agent cannot inspect what it broke, so it guesses and retries in a loop that rarely converges.

The Serenity ProjectRecipe module breaks that loop. Instead of writing binary or YAML Unity assets directly, an AI agent emits a human-readable .serenity-recipe.json. Unity reads the recipe, validates it, optionally dry-runs it to preview outcomes, and then imports it through the AssetDatabase — correctly, idempotently, with a structured report the agent can parse.

The Unity problem

Unity's serialized asset format is not designed for machine authorship. Field names change between versions, [SerializeReference] polymorphic graphs require exact type discriminators, and GUIDs must match every .meta file or the project breaks silently. An LLM that tries to write .asset files directly will produce plausible-looking output that breaks on import, with error messages that do not map back to the specific field the agent got wrong.

Without a stable contract between the AI agent and the Unity Editor, every asset-generation session becomes a debugging session. The agent spends most of its token budget diagnosing import errors rather than producing content, and the developer ends up fixing the output by hand anyway.

How Serenity approaches it

The ProjectRecipe module (namespace Serenity.ProjectRecipe, Editor-only) defines a single stable interchange format: .serenity-recipe.json. An AI agent writes JSON, never .asset or .meta files. SerenityRecipeEngine reads the recipe and runs in one of three modes via RecipeRunMode: Validate parses and checks the recipe without touching disk, DryRun resolves what would be created or updated and returns a preview report, and Import writes the assets through AssetDatabase. Creates and updates are idempotent.

SerenityDiscoveryRegistry.BuildJson() gives an agent the vocabulary it needs before writing any recipe: every EventDispatcherSignal subclass, registered action IDs, [AutoRegisterEventAction] handlers, authorable ScriptableObject types with their recipe section name, enum vocabularies, and curated cross-asset ID contracts. The agent looks up facts from the registry instead of guessing. SerenityRecipeExporter rounds the loop the other way: scan existing Serenity assets in the project and emit a .serenity-recipe.json that captures the current state.

How it fits into Serenity

The module lives under Assets/Serenity/Scripts/Unity/ProjectRecipe and is marked Editor-only. SerenityRecipeEngine is the import pipeline: it accepts a recipe JSON path, resolves section importers for each declared section (audio clips, music tracks, menus, modals, cutscenes, and a generic asset importer that applies an arbitrary serialized field tree including polymorphic signal graphs), and produces a report where every outcome is one of Created, Updated, or Skipped and every message carries a severity of Info, Warning, Error, or Blocker. SerenityRecipeTemplateGenerator instantiates any authorable ScriptableObject type at editor time, captures its exact live serialized field tree, and writes a ready-to-edit stub — so the stub never drifts from the C# definition.

Every class in the module has a headless command-line entry point: ImportFromCommandLine, ExportFromCommandLine, GenerateFromCommandLine, and DumpFromCommandLine. Each is callable from a CI pipeline or from any tooling that can invoke the Unity Editor in batch mode. Exit code is 1 when the report contains Blocker or Error severity items, 0 otherwise. Editor windows under Tools/Serenity/ expose the same operations interactively for developers who prefer a GUI. The MCP automation guide (McpAutomation.md) documents the recommended agent loop using these entry points: discover, emit recipe, validate, dry-run, import.

Practical workflow

1. Start with the AI Prompt Builder (Tools ▸ Serenity ▸ AI ▸ Prompt Builder): a stepped wizard that interviews you about what you want to build, scans the project so the prompt references real assets to extend, and delivers an optimal agent prompt to the clipboard, a saved file, or an installed slash command.
2. Call SerenityDiscoveryRegistry.BuildJson() to get a machine-readable registry of every type, signal, enum, and cross-asset ID the agent can reference.
3. Use SerenityRecipeTemplateGenerator to generate a field-accurate stub for the ScriptableObject type the agent needs to populate.
4. Author the .serenity-recipe.json file using the stub and the discovery registry as ground truth — no .asset or .meta files.
5. Run RecipeRunMode.Validate to catch schema or reference errors before touching the project.
6. Run RecipeRunMode.DryRun to preview which assets would be created or updated and confirm outcomes look correct.
7. Run RecipeRunMode.Import to write the assets. Review the structured JSON report for any Warning or Error items.

What you get

• Schema-stable .serenity-recipe.json interchange format — no GUID or YAML hand-authoring
• SerenityRecipeEngine with three RecipeRunMode values: Validate, DryRun, and Import
• Idempotent asset creation and update through AssetDatabase
• Section importers for audio clips, music tracks, menus, modals, cutscenes, and a generic field-tree importer
• Generic asset importer that applies arbitrary serialized field trees including polymorphic [SerializeReference] signal graphs
• SerenityDiscoveryRegistry.BuildJson() for machine-readable vocabulary of types, signals, enums, and cross-asset IDs
• SerenityRecipeExporter to round-trip existing assets back to a recipe file
• SerenityRecipeTemplateGenerator for live, drift-free field stubs of any authorable ScriptableObject
• Headless command-line entry points for every operation, with JSON reports and actionable exit codes
• AI Prompt Builder wizard that turns an interview about your goal into the optimal agent prompt, with a personal library of reusable instruction snippets

When to use this

• Projects where an AI agent or automation pipeline needs to create or update Unity ScriptableObject assets without breaking the project.
• Teams that want a stable, reviewable contract between LLM-generated output and the Unity Editor instead of fragile YAML or binary asset authoring.
• CI pipelines that need to generate, validate, and import game content assets in batch mode with structured, parseable reports.
• Any workflow that integrates an MCP-capable AI agent with Unity Editor automation through command-line entry points.

Related systems

• Addressables Workflow Service-based asset prefetcher with contexts, labels, cache policies and prewarm tasks for Unity Addressables.
• Event Dispatcher Typed signals dispatched through a service, with auto-registration support and no static singletons.
• Menu System Declarative menus, shared UI themes and predictable navigation, configured as assets instead of hand-wired GameObjects.
• Localization System Runtime language switching, separate game and voice language tracks, and localized menus and modals out of the box.