unity-mcp-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity-MCP Operator Guide

Unity-MCP 操作指南

This skill helps you effectively use the Unity Editor with MCP tools and resources.

本技能可帮助你借助MCP工具和资源高效使用Unity Editor。

Quick Start: Resource-First Workflow

快速开始：资源优先工作流

Always read relevant resources before using tools. This prevents errors and provides the necessary context.

1. Check editor state     → mcpforunity://editor/state
2. Understand the scene   → mcpforunity://scene/gameobject-api
3. Find what you need     → find_gameobjects or resources
4. Take action            → tools (manage_gameobject, create_script, script_apply_edits, apply_text_edits, validate_script, delete_script, get_sha, etc.)
5. Verify results         → read_console, capture_screenshot (in manage_scene), resources

使用工具前务必阅读相关资源。 这能避免错误并提供必要的上下文信息。

1. 检查编辑器状态     → mcpforunity://editor/state
2. 了解场景信息   → mcpforunity://scene/gameobject-api
3. 查找所需内容     → find_gameobjects 或 resources
4. 执行操作            → 工具（manage_gameobject、create_script、script_apply_edits、apply_text_edits、validate_script、delete_script、get_sha等）
5. 验证结果         → read_console、capture_screenshot（在manage_scene中）、resources

Critical Best Practices

关键最佳实践

1. After Writing/Editing Scripts: Always Refresh and Check Console

1. 编写/编辑脚本后：务必刷新并检查控制台

python

undefined

python

undefined

After create_script or script_apply_edits:

在create_script或script_apply_edits之后：

refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True) read_console(types=["error"], count=10, include_stacktrace=True)


**Why:** Unity must compile scripts before they're usable. Compilation errors block all tool execution.

refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True) read_console(types=["error"], count=10, include_stacktrace=True)


**原因：** Unity必须先编译脚本才能使用它们。编译错误会阻止所有工具执行。

2. Use

batch_execute

for Multiple Operations

2. 使用

batch_execute

执行多步操作

python

undefined

python

undefined

10-100x faster than sequential calls

比顺序调用快10-100倍

batch_execute( commands=[ {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube1", "primitive_type": "Cube"}}, {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube2", "primitive_type": "Cube"}}, {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube3", "primitive_type": "Cube"}} ], parallel=True # Read-only operations can run in parallel )


**Max 25 commands per batch.** Use `fail_fast=True` for dependent operations.


**每批最多25条命令。** 对于依赖操作，使用`fail_fast=True`。

3. Use

screenshot

in manage_scene to Verify Visual Results

3. 在manage_scene中使用

screenshot

验证视觉结果

python

undefined

python

undefined

Via manage_scene

通过manage_scene

manage_scene(action="screenshot") # Returns base64 image

manage_scene(action="screenshot") # 返回base64格式图片

After creating/modifying objects, verify visually:

创建/修改对象后，验证视觉效果：

1. Create objects

1. 创建对象

2. capture screenshot

2. 捕获截图

3. Analyze if result matches intent

3. 分析结果是否符合预期

undefined

undefined

4. Check Console After Major Changes

4. 重大更改后检查控制台

python

read_console(
    action="get",
    types=["error", "warning"],  # Focus on problems
    count=10,
    format="detailed"
)

python

read_console(
    action="get",
    types=["error", "warning"],  # 重点关注问题
    count=10,
    format="detailed"
)

5. Always Check

editor_state

Before Complex Operations

5. 复杂操作前务必检查

editor_state

python

undefined

python

undefined

Read mcpforunity://editor/state to check:

读取mcpforunity://editor/state来检查：

- is_compiling: Wait if true

- is_compiling: 如果为true则等待

- is_domain_reload_pending: Wait if true

- is_domain_reload_pending: 如果为true则等待

- ready_for_tools: Only proceed if true

- ready_for_tools: 仅当为true时才继续

- blocking_reasons: Why tools might fail

- blocking_reasons: 工具可能失败的原因

undefined

undefined

Parameter Type Conventions

参数类型约定

Vectors (position, rotation, scale, color)

向量（position、rotation、scale、color）

python

undefined

python

undefined

Both forms accepted:

接受两种格式：

position=[1.0, 2.0, 3.0] # List position="[1.0, 2.0, 3.0]" # JSON string

undefined

position=[1.0, 2.0, 3.0] # 列表 position="[1.0, 2.0, 3.0]" # JSON字符串

undefined

Booleans

布尔值

python

undefined

python

undefined

Both forms accepted:

接受两种格式：

include_inactive=True # Boolean include_inactive="true" # String

undefined

include_inactive=True # 布尔值 include_inactive="true" # 字符串

undefined

Colors

颜色

python

undefined

python

undefined

Auto-detected format:

自动检测格式：

color=[255, 0, 0, 255] # 0-255 range color=[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 normalized (auto-converted)

undefined

color=[255, 0, 0, 255] # 0-255范围 color=[1.0, 0.0, 0.0, 1.0] # 0.0-1.0归一化格式（自动转换）

undefined

Paths

路径

python

undefined

python

undefined

Assets-relative (default):

相对于Assets目录（默认）：

path="Assets/Scripts/MyScript.cs"

URI forms:

URI格式：

uri="mcpforunity://path/Assets/Scripts/MyScript.cs" uri="file:///full/path/to/file.cs"

undefined

uri="mcpforunity://path/Assets/Scripts/MyScript.cs" uri="file:///full/path/to/file.cs"

undefined

Core Tool Categories

核心工具分类

Category	Key Tools	Use For
Scene	`manage_scene` , `find_gameobjects`	Scene operations, finding objects
Objects	`manage_gameobject` , `manage_components`	Creating/modifying GameObjects
Scripts	`create_script` , `script_apply_edits` , `refresh_unity`	C# code management
Assets	`manage_asset` , `manage_prefabs`	Asset operations
Editor	`manage_editor` , `execute_menu_item` , `read_console`	Editor control
Testing	`run_tests` , `get_test_job`	Unity Test Framework
Batch	`batch_execute`	Parallel/bulk operations

分类	关键工具	用途
场景	`manage_scene` , `find_gameobjects`	场景操作、查找对象
对象	`manage_gameobject` , `manage_components`	创建/修改GameObjects
脚本	`create_script` , `script_apply_edits` , `refresh_unity`	C#代码管理
资源	`manage_asset` , `manage_prefabs`	资源操作
编辑器	`manage_editor` , `execute_menu_item` , `read_console`	编辑器控制
测试	`run_tests` , `get_test_job`	Unity测试框架
批量处理	`batch_execute`	并行/批量操作

Common Workflows

常见工作流

Creating a New Script and Using It

创建新脚本并使用

python

undefined

python

undefined

1. Create the script

1. 创建脚本

create_script( path="Assets/Scripts/PlayerController.cs", contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n}" )

2. CRITICAL: Refresh and wait for compilation

2. 重要：刷新并等待编译完成

refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)

3. Check for compilation errors

3. 检查编译错误

read_console(types=["error"], count=10)

4. Only then attach to GameObject

4. 之后再附加到GameObject

manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])

undefined

manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])

undefined

Finding and Modifying GameObjects

查找并修改GameObjects

python

undefined

python

undefined

1. Find by name/tag/component (returns IDs only)

1. 按名称/标签/组件查找（仅返回ID）

result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)

2. Get full data via resource

2. 通过资源获取完整数据

mcpforunity://scene/gameobject/{instance_id}

3. Modify using the ID

3. 使用ID修改对象

manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])

undefined

manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])

undefined

Running and Monitoring Tests

运行并监控测试

python

undefined

python

undefined

1. Start test run (async)

1. 启动测试运行（异步）

result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"]) job_id = result["job_id"]

2. Poll for completion

2. 轮询等待完成

result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)

undefined

result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)

undefined

Pagination Pattern

分页模式

Large queries return paginated results. Always follow

next_cursor

python

cursor = 0
all_items = []
while True:
    result = manage_scene(action="get_hierarchy", page_size=50, cursor=cursor)
    all_items.extend(result["data"]["items"])
    if not result["data"].get("next_cursor"):
        break
    cursor = result["data"]["next_cursor"]

大型查询返回分页结果。务必遵循

next_cursor

：

python

cursor = 0
all_items = []
while True:
    result = manage_scene(action="get_hierarchy", page_size=50, cursor=cursor)
    all_items.extend(result["data"]["items"])
    if not result["data"].get("next_cursor"):
        break
    cursor = result["data"]["next_cursor"]

Multi-Instance Workflow

多实例工作流

When multiple Unity Editors are running:

python

undefined

当多个Unity Editor运行时：

python

undefined

1. List instances via resource: mcpforunity://instances

1. 通过资源列出实例：mcpforunity://instances

2. Set active instance

2. 设置活动实例

set_active_instance(instance="MyProject@abc123")

3. All subsequent calls route to that instance

3. 后续所有调用都将路由到该实例

undefined

undefined

Error Recovery

错误恢复

Symptom	Cause	Solution
Tools return "busy"	Compilation in progress	Wait, check `editor_state`
"stale_file" error	File changed since SHA	Re-fetch SHA with `get_sha` , retry
Connection lost	Domain reload	Wait ~5s, reconnect
Commands fail silently	Wrong instance	Check `set_active_instance`

症状	原因	解决方案
工具返回“busy”	编译正在进行	等待，检查 `editor_state`
“stale_file”错误	文件自SHA后已更改	使用 `get_sha` 重新获取SHA，重试
连接丢失	域重载	等待约5秒，重新连接
命令静默失败	实例错误	检查 `set_active_instance`

Reference Files

参考文件

For detailed schemas and examples:

tools-reference.md: Complete tool documentation with all parameters
resources-reference.md: All available resources and their data
workflows.md: Extended workflow examples and patterns

如需详细架构和示例：

tools-reference.md: 包含所有参数的完整工具文档
resources-reference.md: 所有可用资源及其数据
workflows.md: 扩展工作流示例和模式

unity-mcp-orchestrator

Original

Translation

Unity-MCP Operator Guide

Unity-MCP 操作指南

Quick Start: Resource-First Workflow

快速开始：资源优先工作流

Critical Best Practices

关键最佳实践

1. After Writing/Editing Scripts: Always Refresh and Check Console

1. 编写/编辑脚本后：务必刷新并检查控制台

After create_script or script_apply_edits:

在create_script或script_apply_edits之后：

2. Use batch_execute for Multiple Operations

2. 使用batch_execute执行多步操作

10-100x faster than sequential calls

比顺序调用快10-100倍

3. Use screenshot in manage_scene to Verify Visual Results

3. 在manage_scene中使用screenshot验证视觉结果

Via manage_scene

通过manage_scene

After creating/modifying objects, verify visually:

创建/修改对象后，验证视觉效果：

1. Create objects

1. 创建对象

2. capture screenshot

2. 捕获截图

3. Analyze if result matches intent

3. 分析结果是否符合预期

4. Check Console After Major Changes

4. 重大更改后检查控制台

5. Always Check editor_state Before Complex Operations

5. 复杂操作前务必检查editor_state

Read mcpforunity://editor/state to check:

读取mcpforunity://editor/state来检查：

- is_compiling: Wait if true

- is_compiling: 如果为true则等待

- is_domain_reload_pending: Wait if true

- is_domain_reload_pending: 如果为true则等待

- ready_for_tools: Only proceed if true

- ready_for_tools: 仅当为true时才继续

- blocking_reasons: Why tools might fail

- blocking_reasons: 工具可能失败的原因

Parameter Type Conventions

参数类型约定

Vectors (position, rotation, scale, color)

向量（position、rotation、scale、color）

Both forms accepted:

接受两种格式：

Booleans

布尔值

Both forms accepted:

接受两种格式：

Colors

颜色

Auto-detected format:

自动检测格式：

Paths

路径

Assets-relative (default):

相对于Assets目录（默认）：

URI forms:

URI格式：

Core Tool Categories

核心工具分类

Common Workflows

常见工作流

Creating a New Script and Using It

创建新脚本并使用

1. Create the script

1. 创建脚本

2. CRITICAL: Refresh and wait for compilation

2. 重要：刷新并等待编译完成

3. Check for compilation errors

3. 检查编译错误

4. Only then attach to GameObject

4. 之后再附加到GameObject

Finding and Modifying GameObjects

查找并修改GameObjects

1. Find by name/tag/component (returns IDs only)

2. Use
`batch_execute`
for Multiple Operations

2. 使用
`batch_execute`
执行多步操作

3. Use
`screenshot`
in manage_scene to Verify Visual Results

3. 在manage_scene中使用
`screenshot`
验证视觉结果

5. Always Check
`editor_state`
Before Complex Operations

5. 复杂操作前务必检查
`editor_state`