AI Reorganization Engine

The AI Director is the central component that utilizes Large Language Models (Gemini, OpenAI, or OpenRouter) to clean and restructure messy hierarchies into production-ready layout systems based on natural language instructions.

The AI Pipeline

Restructuring a Unity scene requires deep safety limits. The engine executes a three-phase pipeline:

flowchart LR
    A[User Prompt] --> B[Scene Metadata Extraction]
    B --> C[LLM Request API]
    C --> D[JSON Action Plan returned]
    D --> E[Dry Run / Validation]
    E --> F[Undo-safe C# Execution]

1. Metadata Extraction

The local assembly collects metadata about the target hierarchy:

GameObject Instance IDs (for tracking references).
Current parent-child paths.
Component summaries (e.g., MeshRenderer, Light, AudioSource).
Spatial details (for spatial proximity grouping, like “group props on the left side”).

This structure is translated into a condensed, token-efficient JSON payload. The tool never uploads meshes, code, or textures.

2. Action Plan Generation

The LLM evaluates the metadata against your prompt and returns a structured list of action items. Supported actions include:

CreateParent: Creates a new folder/anchor GameObject.
Reparent: Moves a GameObject under a new parent.
Rename: Standardizes names.
Deactivate: Disables redundant items.
SetTagLayer: Updates tags/layers.

3. Execution & Undo integration

The SceneFixExecutor converts the JSON plan into real Editor actions. To ensure your scene remains 100% stable, the executor wraps every action in the Unity Undo pipeline:

Creation of new group parent folders uses Undo.RegisterCreatedObjectUndo.
Parenting updates use Undo.SetTransformParent.
State changes (naming, tags) call Undo.RecordObject.

How to Use the AI Director

Open the dashboard and navigate to the AI Director tab.
Select your Target Scope:
- Entire Scene: Feeds the whole hierarchy structure (recommended for small/medium scenes).
- Selected Objects: Only reorganizes items you currently have selected in the Hierarchy window (recommended for large levels).
Choose a Preset (e.g. “Organize into standard Unity folders: Lights, Cameras, Props, UI”) or write a custom instruction:
- Example prompt: `“Find all static meshes containing ‘rock’ or ‘stone’ in their name, create a parent folder called ‘_ROCKS_STATIC’, and move them inside it. Sort them by size.”*
Click Execute Prompt.
The progress bar will track the LLM query and execution. Your scene hierarchy will rearrange in real-time.

[!IMPORTANT] If the LLM suggestions don’t meet your expectations, simply press Ctrl+Z to immediately undo all structural changes in a single step. Adjust your prompt with more specific rules and run it again.