unity-mcp-orchestrator

Unity-MCP 操作指南

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

模板说明

references/workflows.md 和 references/tools-reference.md 中的示例均为可复用模板。由于 Unity 版本、包配置（UGUI/TMP/Input System）和项目特定约定各不相同，这些示例可能并不准确。实现后，请检查控制台和编译错误，或使用截图进行验证。

应用模板前：

• 先通过资源和 find_gameobjects 验证目标对象和组件。
• 将名称、枚举值和属性载荷视为占位内容，并根据实际情况调整。

快速入门：资源优先工作流

使用工具前，始终先阅读相关资源。 这样可以避免错误，并提供必要的上下文。

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, manage_camera(action="screenshot"), resources

如果所需工具不在工具列表中，并不代表它一定缺失。 在排查连接问题前，请先检查以下内容：

• 项目自定义工具（C# [McpForUnityTool]）：启用服务端的项目级工具后，这些工具不能通过名称直接调用。通过 mcpforunity://custom-tools 列出它们，并使用 execute_custom_tool(tool_name="...", parameters={...}) 运行。禁用该功能时，它们会注册为普通工具并显示在工具列表中。
• 已禁用的工具组：通过 HTTP 连接时，会话启动时仅启用 core 组。通过 stdio 连接时，所有组在启动时都会启用，随后与 Unity 编辑器中的工具开关同步，因此某个工具仍可能被隐藏。manage_tools(action="list_groups") 可显示工具组，manage_tools(action="activate", group="...") 可启用工具组。

关键最佳实践

1. 编写或编辑脚本后：等待编译并检查控制台

# After create_script or script_apply_edits:
# Both tools already trigger AssetDatabase.ImportAsset + RequestScriptCompilation automatically.
# No need to call refresh_unity — just wait for compilation to finish, then check console.

# 1. Poll editor state until compilation completes
# Read mcpforunity://editor/state → wait until is_compiling == false

# 2. Check for compilation errors
read_console(types=["error"], count=10, include_stacktrace=True)

原因： Unity 必须先编译脚本，脚本才能使用。create_script 和 script_apply_edits 已自动触发导入和编译，因此之后调用 refresh_unity 是多余的。

2. 多项操作使用 batch_execute

# 10-100x faster than sequential calls
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  # Hint only: Unity may still execute sequentially
)

每批默认最多 25 条命令（可在 Unity MCP Tools 窗口中配置，最多 100 条）。 对有依赖关系的操作使用 fail_fast=True。

提示： 也可使用 batch_execute 进行查询发现——批量调用多个 find_gameobjects，而不是逐个调用：

batch_execute(commands=[
    {"tool": "find_gameobjects", "params": {"search_term": "Camera", "search_method": "by_component"}},
    {"tool": "find_gameobjects", "params": {"search_term": "Player", "search_method": "by_tag"}},
    {"tool": "find_gameobjects", "params": {"search_term": "GameManager", "search_method": "by_name"}}
])

3. 使用截图验证视觉效果

# Basic screenshot (saves to Assets/, returns file path only)
manage_camera(action="screenshot")

# Inline screenshot (returns base64 PNG directly to the AI)
manage_camera(action="screenshot", include_image=True)

# Use a specific camera and cap resolution for smaller payloads
manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)

# Batch surround: captures front/back/left/right/top/bird_eye around the scene
manage_camera(action="screenshot", batch="surround", max_resolution=256)

# Batch surround centered on a specific object
manage_camera(action="screenshot", batch="surround", view_target="Player", max_resolution=256)

# Positioned screenshot: place a temp camera and capture in one call
manage_camera(action="screenshot", view_target="Player", view_position=[0, 10, -10], max_resolution=512)

# Scene View screenshot: capture what the developer sees in the editor
manage_camera(action="screenshot", capture_source="scene_view", include_image=True)

# Scene View framed on a specific object
manage_camera(action="screenshot", capture_source="scene_view", view_target="Canvas", include_image=True)

AI 场景理解的最佳实践：

• 需要查看场景，而不只是保存文件时，使用 include_image=True。
• 使用 batch="surround" 获取全面概览（6 个角度，只需一条命令）。
• 使用 view_target/view_position 从特定视角截图，无需场景摄像机。
• 使用 capture_source="scene_view" 查看编辑器视图（辅助图标、线框、网格）。
• 将 max_resolution 保持在 256–512，以平衡画质与令牌开销。

# Agentic camera loop: point, shoot, analyze
manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player")
manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
# → Analyze image, decide next action

# Multi-view screenshot (6-angle contact sheet)
manage_camera(action="screenshot_multiview", max_resolution=480)

# Scene View for editor-level inspection (shows gizmos, debug overlays, etc.)
manage_camera(action="screenshot", capture_source="scene_view", view_target="Player", include_image=True)

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

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

5. 复杂操作前，始终检查 mcpforunity://editor/state

# Read mcpforunity://editor/state to check:
# - is_compiling: Wait if true
# - is_domain_reload_pending: Wait if true  
# - ready_for_tools: Only proceed if true
# - blocking_reasons: Why tools might fail

参数类型约定

以下是常见模式，并非严格保证。manage_components.set_property 的载荷结构可能因组件或属性而异；如果模板失败，请检查组件资源载荷并进行调整。

向量（位置、旋转、缩放、颜色）

# Both forms accepted:
position=[1.0, 2.0, 3.0]        # List
position="[1.0, 2.0, 3.0]"     # JSON string

布尔值

# Both forms accepted:
include_inactive=True           # Boolean
include_inactive="true"         # String

颜色

# 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)

路径

# Assets-relative (default):
path="Assets/Scripts/MyScript.cs"

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

核心工具类别

类别	主要工具	用途
场景	manage_scene、find_gameobjects	场景操作、查找对象。多场景编辑（以叠加方式加载、关闭、设为活动场景、在场景间移动 GO）、场景模板（3d_basic、2d_basic、empty、default）、使用 auto_repair 验证场景。要管理构建设置，请使用 manage_build(action="scenes")。
对象	manage_gameobject、manage_components	创建/修改 GameObject
脚本	create_script、script_apply_edits、validate_script	C# 代码管理（创建/编辑时自动刷新）
资源	manage_asset、manage_prefabs	资源操作。预制件实例化通过 manage_gameobject(action="create", prefab_path="...") 完成，而非 manage_prefabs。
编辑器	manage_editor、execute_menu_item、read_console	编辑器控制、包部署（deploy_package/restore_package）、撤销/重做（undo/redo 操作）
测试	run_tests、get_test_job	Unity Test Framework
批处理	batch_execute	并行/批量操作
摄像机	manage_camera	摄像机管理（Unity Camera + Cinemachine）。第 1 层（始终可用）：创建、目标、镜头、优先级、列表、截图。第 2 层（需要 com.unity.cinemachine）：brain、body/aim/noise 管线、扩展、混合、强制/释放。7 种预设：follow、third_person、freelook、dolly、static、top_down、side_scroller。资源：mcpforunity://scene/cameras。使用 ping 检查 Cinemachine 是否可用。参见 tools-reference.md。
动画	manage_animation、manage_sprite	Animator 控制、动画片段和控制器。2D 精灵图集：manage_sprite(action="get_info") 会将 PNG 或 JPEG 图集作为图像返回，以便根据图像确定网格；随后 full_setup 会切分图集并构建动画片段和控制器；动画片段名称决定状态（idle、walk/run、attack-type 触发器）。默认情况下，通过 HTTP 禁用：manage_tools(action="activate", group="animation")。
图形	manage_graphics	渲染和后期处理管理。涵盖 5 个分组的 33 项操作：Volume（创建/配置体积和效果，URP/HDRP）、Bake（光照贴图、光照探针、反射探针，仅限 Edit 模式）、Stats（绘制调用、批次、内存）、Pipeline（质量级别、管线设置）、Features（URP 渲染器功能：添加、移除、切换、重新排序）。资源：mcpforunity://scene/volumes、mcpforunity://rendering/stats、mcpforunity://pipeline/renderer-features。使用 ping 检查管线状态。参见 tools-reference.md。
包	manage_packages	安装、移除、搜索和管理 Unity 包及作用域注册表。查询操作：列出已安装包、搜索注册表、获取信息、ping、轮询状态。修改操作：添加/移除包、嵌入以便编辑、添加/移除作用域注册表、强制解析。验证标识符、对 git URL 发出警告，并在移除前检查依赖项（使用 force=true 可覆盖）。参见 tools-reference.md。
物理	manage_physics	管理 3D 和 2D 物理（21 项操作）。设置、碰撞矩阵、材质、关节（14 种类型）。查询：raycast、raycast_all、linecast、shapecast（球体/盒体/胶囊体扫掠）、overlap。力：apply_force（使用 ForceMode 的 AddForce/AddTorque/AddExplosionForce）。Rigidbody：get_rigidbody、configure_rigidbody（质量、阻力、重力、约束、碰撞检测）。验证：全场景检查。模拟：在编辑模式下使用 simulate_step。参见 tools-reference.md。
ProBuilder	manage_probuilder	3D 建模、网格编辑、复杂几何体。**安装 com.unity.probuilder 后，对于可编辑几何体、多材质面或复杂形状，优先使用 ProBuilder 形状，而非基本 GameObject。**支持 12 种形状类型、面/边/顶点编辑、平滑处理和逐面材质。参见 ProBuilder 指南。
UI	manage_ui、batch_execute（搭配 manage_gameobject + manage_components）	UI Toolkit：使用 manage_ui 创建 UXML/USS 文件、附加 UIDocument、检查视觉树。uGUI（Canvas）：使用 batch_execute 创建 Canvas、Panel、Button、Text、Slider、Toggle、Input Field。请先读取 mcpforunity://project/info，以检测 uGUI/TMP/Input System/UI Toolkit 是否可用。（参见 UI 工作流）
文档	unity_reflect、unity_docs	API 验证和文档查询。unity_reflect 通过反射检查实时 C# API（需要连接 Unity）：使用 search 跨程序集搜索类型，使用 get_type 获取成员摘要，使用 get_member 获取完整签名。unity_docs 从 docs.unity3d.com 获取官方文档（无需连接 Unity）：get_doc（ScriptReference）、get_manual（Manual 页面）、get_package_doc（包文档）、lookup（并行搜索所有来源和项目资源）。**信任层级：反射 > 项目资源 > 文档。**工作流：unity_reflect search -> get_type -> get_member -> unity_docs lookup。参见 tools-reference.md。
更多	manage_material、manage_texture、manage_shader、manage_vfx、manage_profiler、execute_code、manage_scriptable_object、generate_image、generate_model、generate_audio、import_model、import_model_file、blender_bridge	材质；纹理、着色器和 VFX（vfx 分组）；性能分析（profiling）；编辑器内 C# 和 ScriptableObjects（scripting_ext）；AI 资源生成、Sketchfab 和磁盘模型导入、Blender（asset_gen）。每种工具都在 tools-reference.md 中有对应章节。

常见工作流

创建新脚本并使用

# 1. Create the script (automatically triggers import + compilation)
create_script(
    path="Assets/Scripts/PlayerController.cs",
    contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n    void Update() { }\n}"
)

# 2. Wait for compilation to finish
# Read mcpforunity://editor/state → wait until is_compiling == false

# 3. Check for compilation errors
read_console(types=["error"], count=10)

# 4. Only then attach to GameObject
manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])

查找和修改 GameObject

# 1. Find by name/tag/component (returns IDs only)
result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)

# 2. Get full data via resource
# mcpforunity://scene/gameobject/{instance_id}

# 3. Modify using the ID
manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])

运行和监控测试

# 1. Start test run (async)
result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"])
job_id = result["job_id"]

# 2. Poll for completion
result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)

分页模式

大型查询会返回分页结果。请始终使用 next_cursor：

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"]

多实例工作流

运行多个 Unity 编辑器时：

# 1. List instances via resource: mcpforunity://instances
# 2. Set active instance
set_active_instance(instance="MyProject@abc123")
# 3. All subsequent calls route to that instance

错误恢复

症状	原因	解决方案
工具返回 "busy"	正在编译	等待并检查 mcpforunity://editor/state
"stale_file" 错误	文件自 SHA 生成后已更改	使用 get_sha 重新获取 SHA，然后重试
连接丢失	域重新加载	等待约 5 秒，然后重新连接
命令静默失败	实例错误	检查 set_active_instance

参考文件

如需详细的架构和示例：

• tools-reference.md：每个工具的主要操作、参数和示例，并附有指向完整参数表的链接
• resources-reference.md：所有可用资源及其数据
• workflows.md：扩展工作流示例和模式
• probuilder-guide.md：ProBuilder 建模模式