Unity Agentic Tools

Unity Agentic Tools

Use this skill for Unity Agentic Tools CLI setup, command discovery, command execution, live Editor bridge workflows, and high-level project automation.

CRITICAL: Use the CLI command runner for Unity operations. Do not manually mutate Unity serialized files (.unity, .prefab, .asset, .mat, .anim, .controller, .meta, ProjectSettings/) unless the user explicitly asks for raw file work.

Command Surface

Commands emit compact single-line JSON by default; pass --pretty for indented output. Prefer list <query> --brief for discovery.

By default, install writes the GitHub package URL. For local bridge package development, use install --local [path]; existing file: dependencies are preserved unless install --remote is passed.

Default Route

1. unity-agentic-tools status -p <project>
2. unity-agentic-tools list <query> --brief -p <project>
3. Inspect current state with query.*, scene.hierarchy, ui.snapshot, or screenshots.
4. unity-agentic-tools run <target> ... -p <project>
5. Verify with the matching query, snapshot, screenshot, tests, or console stream.

Workflow Rules

1. Author in edit mode against asset paths. Scene edits made in play mode are discarded on exit.
2. Verify structure with query.object or scene.hierarchy, not play mode or screenshots. Screenshots are for visual layout; take ui.snapshot first and reserve screenshot.annotated for when element geometry matters.
3. Play mode is for behavior. Each transition is a domain reload, so batch authoring before play.enter, run queries after, and never interleave authoring with transitions.
4. Prefer tests.run for behavior checks over manually driving input.* and reading screenshots.
5. Never sleep-and-repoll: wait.for blocks on the condition (ui, ui-gone, scene, log, compile, delay) in one call, and run --batch executes a command sequence in one process.
6. Skip project.refresh after bridge mutations; they import their own changes. It is only needed after files change outside the bridge.

Examples

unity-agentic-tools list scene --brief -p <project>
unity-agentic-tools run project.refresh -p <project>
unity-agentic-tools run query.scene Assets/Scenes/Main.unity -p <project>
unity-agentic-tools run create.gameobject Assets/Scenes/Main.unity EnemyRoot Gameplay -p <project>
unity-agentic-tools run update.transform Assets/Scenes/Main.unity Player 1,2,3 0,90,0 1,1,1 -p <project>
unity-agentic-tools stream console --type Error -p <project>
unity-agentic-tools cleanup --cache -p <project>

Pass a structured argument positionally in single quotes — the CLI encodes the outer JSON array itself, so no escaping is needed. Reserve --args '<json array>' for arguments starting with -. See reference/troubleshooting.md "JSON Args".

unity-agentic-tools run update.batch Assets/Scenes/Main.unity '[{"gameObjectPath":"Player","propertyPath":"m_Name","value":"Hero"}]' -p <project>

Raw public static APIs can be called directly when no alias or [AgenticCommand] wrapper exists.

unity-agentic-tools run UnityEditor.AssetDatabase.Refresh -p <project>
unity-agentic-tools run UnityEditor.EditorApplication.ExecuteMenuItem "File/Save" -p <project>

Project Commands

Do not add a new CLI command for each Unity operation. Expose project-specific behavior by adding [AgenticCommand] to public static methods/properties in Unity Editor C#:

using UnityAgenticTools.Commands;

public static class BuildCommands
{
    [AgenticCommand("build.addressables", "Build Addressables content.")]
    public static object BuildAddressables(string profile)
    {
        return new { success = true, profile };
    }
}

Then use:

unity-agentic-tools list build --brief -p <project>
unity-agentic-tools run build.addressables Production -p <project>

References

• reference/live-editor-workflows.md: live Editor setup, mutation, UI, and batch workflows
• reference/command-reference.md: generated alias reference with arg hints (<required> [optional])
• reference/troubleshooting.md: bridge, timeouts, refs, JSON args, and verification

Troubleshooting

Full detail lives in reference/troubleshooting.md. Quick pointers:

• Bridge won't connect: see "Bridge Not Reachable" (install, open Unity, wait for compile, status, cleanup). reachable: true with is_stable: false means busy, not broken.
• Long builds time out: run defaults to 60s; see "Long-running Commands" (--timeout 1200000, --no-wait).
• Play mode looks wrong right after play.enter: the response reports the current state, not the requested one. Poll play.state; see "Play Mode Transitions" in reference/live-editor-workflows.md.
• Recognized built-in reads are slow during a transition: expected. Those reads wait out a domain reload for up to 30s instead of failing; project commands and most raw getters use conservative command semantics. See "Domain reloads" in "Long-running Commands".
• Stale @hN/@uN refs: re-run scene.hierarchy or ui.snapshot; see "Stale Refs".
• Need console logs: unity-agentic-tools stream console --duration 5000 -p <project>.
• Need raw APIs: unity-agentic-tools list <type-or-namespace> --raw -p <project> to find one, then run <target> --raw to invoke it. run refuses an unregistered target without --raw and logs a warning in the Unity console when it accepts one. Prefer a registered alias whenever one exists.