Intent Tools Guide¶

Convert natural language requests into scene operations automatically.

Overview¶

Intent tools use Haiku (fast LLM) to translate plain English into structured operations. Costs ~$0.0001 per intent call.

Note: Intent tools are configurable via MCP → Settings → LLM Sampling in the Unity Editor. They are direct_only tools and cannot be used in batch commands.

do(intent, dry_run=False)¶

Create or modify scene objects from natural language.

# Execute immediately
await do("create a cube at position 5,0,0 named Player")

# Preview plan without executing
plan = await do("create a cube", dry_run=True)
# → Returns DSL plan; review before running

How it works: 1. Describe what you want in plain English 2. Haiku generates batch commands (create_object, set_property, etc.) 3. Commands are validated and executed 4. Returns success or error details

Errors: Returns "INVALID PLAN" if validation fails (e.g., component type not found, path doesn't exist).

ask(question)¶

Query scene state without modifying anything.

await ask("how many enemies have health > 50?")
await ask("what components does the Player have?")
await ask("where is the nearest collectible?")

Returns: Text answer summarized by Haiku if needed. Read-only; no mutations allowed.

Rejection: Mutating questions like "add health to player" are rejected — use do() instead.

animator_intent(target, intent, dry_run=False)¶

Setup Animator Controller parameters, states, and transitions from natural language.

await animator_intent("Player", "movement with idle/walk transition at speed 0.1")

# Preview first
await animator_intent("Enemy", "attack animation", dry_run=True)

Creates: - Float parameters (e.g., Speed) - Animation states with clip assignments - Transitions with conditions (Speed > 0.1, etc.) - Default state

Supported transitions: Speed comparisons (>, <), bool checks, custom conditions.

vfx_intent(target, intent, kind="auto", dry_run=False)¶

Configure particle systems with presets or custom properties.

# Use built-in preset
await vfx_intent("Explosion", "fire_explosion")

# Use preset by name
await vfx_intent("Enemy", intent="magic spell effect", kind="magic_burst")

# Custom properties (Haiku generates)
await vfx_intent("Dust", "small dust particles, slow fade")

5 Built-in Presets (no cost):

Customization: If preset name not recognized, Haiku designs custom particle properties (colorOverLifetime, sizeOverLifetime, speed curves).

ui_intent(intent, parent=None, template=None, dry_run=False)¶

Create UI hierarchies (Canvas, panels, buttons) from natural language.

# Use built-in template
await ui_intent("create a health bar", template="hud")

# Custom UI
await ui_intent("create a pause menu with Resume/Quit buttons")

# Specific parent
await ui_intent("add score display", parent="UI/HUD")

4 Built-in Templates (no cost):

Anchors supported: top-left, top-right, bottom-left, bottom-right, center, stretch, top-center, bottom-center.

budget_status()¶

Check daily Haiku usage.

status = await budget_status()
# → sess=$0.0450/0.50 (9%) day=$0.1200 skipped=animator_intent:3 vfx_intent:1

Budget tracking is enabled by default with a $0.50 session cap and a $5.00 daily cap. Override them with UNITY_MCP_HAIKU_BUDGET and UNITY_MCP_HAIKU_DAY_CAP, or disable tracking with UNITY_MCP_BUDGET=0.

Common Workflow¶

# 1. Ask about scene
await ask("what enemies are in the level?")

# 2. Do bulk creation
await do("create 3 platforms in a line, spaced 5 units apart")

# 3. Setup animation
await animator_intent("Player", "walk/run with speed control")

# 4. Add effects
await vfx_intent("Explosion", "fire_explosion")

# 5. Create UI
await ui_intent("health bar at top-left", template="hud")

Cost Estimate¶

See also: Batch Reference for batch operations, Getting Started for scene hierarchy.