unity-mcp-orchestrator

用途

Unity-MCP Orchestrator 是一个操作指南型技能，用于通过 MCP（Model Context Protocol）工具和资源来编排 Unity 编辑器。它面向需要借助 AI 助手在 Unity 项目中执行创建、修改、查询和验证操作的场景，帮助使用者更有效地使用 Unity 编辑器与 MCP 工具。

主要能力

该技能覆盖 Unity 编辑器中的多个工具类别：

• 场景：manage_scene、find_gameobjects，支持多场景编辑、场景模板、场景校验与自动修复。
• 对象：manage_gameobject、manage_components，用于创建和修改 GameObject。
• 脚本：create_script、script_apply_edits、validate_script，管理 C# 代码，创建或编辑后自动触发导入与编译。
• 资源：manage_asset、manage_prefabs，执行资源操作；预制体实例化通过 manage_gameobject(action="create", prefab_path="...") 完成。
• 编辑器：manage_editor、execute_menu_item、read_console，控制编辑器、包部署、撤销/重做。
• 测试：run_tests、get_test_job，运行 Unity Test Framework。
• 批量：batch_execute，并行或批量操作。
• 相机：manage_camera，管理 Unity Camera 与 Cinemachine，支持截图、多视角截图、场景视图截图。
• 动画：manage_animation、manage_sprite，控制 Animator、剪辑与控制器，支持 2D 精灵表切片。
• 图形：manage_graphics，管理渲染与后处理，涵盖 Volume、烘焙、统计、管线、URP 渲染器特性。
• 包：manage_packages，安装、移除、搜索和管理 Unity 包与作用域注册表。
• 物理：manage_physics，管理 3D 和 2D 物理，包括设置、碰撞矩阵、材质、关节、查询、力、刚体、校验与模拟。
• ProBuilder：manage_probuilder，进行 3D 建模、网格编辑和复杂几何体操作。
• UI：manage_ui 用于 UI Toolkit（UXML/USS、UIDocument、视觉树）；uGUI 通过 batch_execute 配合 manage_gameobject 与 manage_components 操作。
• 文档：unity_reflect、unity_docs，进行 API 验证与文档查询。
• 其他：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 等。

使用方式

技能强调“资源优先”的工作流程：

1. 检查编辑器状态：读取 mcpforunity://editor/state。
2. 理解场景：读取 mcpforunity://scene/gameobject-api。
3. 查找所需内容：使用 find_gameobjects 或资源。
4. 执行操作：使用工具，如 manage_gameobject、create_script、script_apply_edits、apply_text_edits、validate_script、delete_script、get_sha 等。
5. 验证结果：read_console、manage_camera(action="screenshot")、资源。

关键实践包括：

• 编写或编辑脚本后，等待编译完成并检查控制台。create_script 和 script_apply_edits 已自动触发 AssetDatabase.ImportAsset 与 RequestScriptCompilation，无需再调用 refresh_unity。轮询 mcpforunity://editor/state 直到 is_compiling == false，再用 read_console 检查错误。
• 使用 batch_execute 执行多个操作，比顺序调用快 10-100 倍。默认每批最多 25 条命令（可在 Unity MCP Tools 窗口配置，最大 100）。依赖操作可使用 fail_fast=True。
• 使用截图验证视觉结果。manage_camera(action="screenshot") 可保存到 Assets/ 并返回文件路径；include_image=True 可直接返回 base64 PNG；batch="surround" 可捕获六个角度；capture_source="scene_view" 可捕获编辑器视口。建议 max_resolution 保持在 256–512 以平衡质量与 token 成本。
• 重大更改后检查控制台：read_console(action="get", types=["error", "warning"], count=10, format="detailed")。
• 复杂操作前始终检查 mcpforunity://editor/state，关注 is_compiling、is_domain_reload_pending、ready_for_tools、blocking_reasons。

参数类型约定：向量支持列表或 JSON 字符串；布尔值支持布尔或字符串；颜色自动检测 0-255 或 0.0-1.0 范围；路径支持 Assets 相对路径或 URI 形式。

常见工作流包括：创建新脚本并使用、查找和修改 GameObject、运行和监控测试、分页模式、多实例工作流。多实例时可通过 mcpforunity://instances 列出实例，用 set_active_instance 设置活动实例。

错误恢复方面：工具返回 "busy" 表示编译进行中，需等待并检查编辑器状态；"stale_file" 错误表示文件自 SHA 后已更改，需重新获取 SHA 并重试；连接丢失可能因域重载，等待约 5 秒后重连；命令静默失败可能是实例错误，需检查 set_active_instance。

适用场景

适用于通过 MCP 与 Unity 交互的自动化开发场景，包括：在 Unity 项目中创建和修改 GameObject、编写和编辑 C# 脚本、管理场景与资源、操作相机与截图、运行测试、管理包与物理、进行 ProBuilder 建模、处理 UI、查询 Unity API 文档等。

限制

参考资料中的示例为可复用模板，可能因 Unity 版本、包配置（UGUI/TMP/Input System）和项目特定约定而不准确。应用模板前应先通过资源和 find_gameobjects 验证目标/组件，将名称、枚举值和属性负载视为占位符进行调整。部分工具组默认关闭：HTTP 下会话仅启用核心组，stdio 下所有组启用后同步到 Unity 编辑器中的工具开关。项目自定义工具在启用项目作用域工具时不能按名称调用，需通过 mcpforunity://custom-tools 列出并用 execute_custom_tool 运行。