unity-mcp-orchestrator by coplaydev/unity-mcp
npx skills add https://github.com/coplaydev/unity-mcp --skill unity-mcp-orchestrator此技能帮助您有效使用 Unity 编辑器及 MCP 工具和资源。
references/workflows.md 和 references/tools-reference.md 中的示例是可复用的模板。它们在不同 Unity 版本、包设置(UGUI/TMP/Input System)和项目特定约定下可能不准确。请在实施后检查控制台、编译错误或使用截图。
应用模板前:
find_gameobjects 验证目标/组件。使用工具前务必先阅读相关资源。 这可以防止错误并提供必要的上下文。
1. 检查编辑器状态 → mcpforunity://editor/state
2. 理解场景 → mcpforunity://scene/gameobject-api
3. 查找所需内容 → find_gameobjects 或 resources
4. 执行操作 → tools (manage_gameobject, create_script, script_apply_edits, apply_text_edits, validate_script, delete_script, get_sha 等)
5. 验证结果 → read_console, capture_screenshot (在 manage_scene 中), resources
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
# 在 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)
原因: Unity 必须在脚本可用前编译它们。编译错误会阻止所有工具执行。
batch_execute# 比顺序调用快 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 # 仅为提示:Unity 可能仍会顺序执行
)
默认每批最多 25 个命令(可在 Unity MCP Tools 窗口中配置,最多 100 个)。 对于依赖操作,使用 fail_fast=True。
# 基本截图(保存到 Assets/,仅返回文件路径)
manage_camera(action="screenshot")
# 内联截图(直接向 AI 返回 base64 PNG)
manage_camera(action="screenshot", include_image=True)
# 使用特定相机并限制分辨率以减少负载大小
manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
# 环绕批量:捕获场景的前/后/左/右/顶/鸟瞰视角
manage_camera(action="screenshot", batch="surround", max_resolution=256)
# 围绕特定对象的环绕批量
manage_camera(action="screenshot", batch="surround", look_at="Player", max_resolution=256)
# 定位截图:放置临时相机并在一次调用中捕获
manage_camera(action="screenshot", look_at="Player", view_position=[0, 10, -10], max_resolution=512)
AI 场景理解的最佳实践:
当您需要 查看 场景而不仅仅是保存文件时,使用 include_image=True。
使用 batch="surround" 进行全面概览(6 个角度,一个命令)。
使用 look_at/view_position 从特定视点捕获,无需场景相机。
将 max_resolution 保持在 256–512 以平衡质量与令牌成本。
与 manage_gameobject 上的 look_at 结合使用,在捕获前定向游戏相机。
manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player") manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512) manage_camera(action="screenshot_multiview", max_resolution=480) # 6 角度联系表
read_console(
action="get",
types=["error", "warning"], # 关注问题
count=10,
format="detailed"
)
editor_state# 读取 mcpforunity://editor/state 以检查:
# - is_compiling: 如果为 true 则等待
# - is_domain_reload_pending: 如果为 true 则等待
# - ready_for_tools: 仅当为 true 时继续
# - blocking_reasons: 工具可能失败的原因
这些是常见模式,并非严格保证。manage_components.set_property 负载形状可能因组件/属性而异;如果模板失败,请检查组件资源负载并调整。
# 两种形式均可接受:
position=[1.0, 2.0, 3.0] # 列表
position="[1.0, 2.0, 3.0]" # JSON 字符串
# 两种形式均可接受:
include_inactive=True # 布尔值
include_inactive="true" # 字符串
# 自动检测格式:
color=[255, 0, 0, 255] # 0-255 范围
color=[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 归一化(自动转换)
# Assets 相对路径(默认):
path="Assets/Scripts/MyScript.cs"
# URI 形式:
uri="mcpforunity://path/Assets/Scripts/MyScript.cs"
uri="file:///full/path/to/file.cs"
| 类别 | 关键工具 | 用途 |
|---|---|---|
| 场景 | manage_scene, find_gameobjects | 场景操作,查找对象 |
| 对象 | manage_gameobject, manage_components | 创建/修改 GameObject |
| 脚本 | create_script, script_apply_edits, refresh_unity | C# 代码管理 |
| 资产 | manage_asset, manage_prefabs | 资产操作 |
| 编辑器 | manage_editor, execute_menu_item, read_console | 编辑器控制,包部署(deploy_package/restore_package 操作) |
| 测试 | run_tests, get_test_job | Unity 测试框架 |
| 批处理 | batch_execute | 并行/批量操作 |
| 相机 | manage_camera | 相机管理(Unity Camera + Cinemachine)。第 1 层(始终可用):创建、目标、镜头、优先级、列表、截图。第 2 层(需要 com.unity.cinemachine):大脑、身体/瞄准/噪声管道、扩展、混合、强制/释放。7 个预设:跟随、第三人称、自由视角、轨道、静态、俯视、侧滚。资源:mcpforunity://scene/cameras。使用 ping 检查 Cinemachine 可用性。参见 tools-reference.md。 |
| 图形 | manage_graphics | 渲染和后处理管理。5 个组共 33 个操作:体积(创建/配置体积和效果,URP/HDRP)、烘焙(光照贴图、光照探针、反射探针,仅编辑模式)、统计(绘制调用、批次、内存)、管线(质量级别、管线设置)、功能(URP 渲染器功能:添加、移除、切换、重新排序)。资源:mcpforunity://scene/volumes、mcpforunity://rendering/stats、mcpforunity://pipeline/renderer-features。使用 ping 检查管线状态。参见 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 工作流) |
# 1. 创建脚本
create_script(
path="Assets/Scripts/PlayerController.cs",
contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n}"
)
# 2. 关键:刷新并等待编译
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
# 3. 检查编译错误
read_console(types=["error"], count=10)
# 4. 然后才附加到 GameObject
manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])
# 1. 按名称/标签/组件查找(仅返回 ID)
result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)
# 2. 通过资源获取完整数据
# mcpforunity://scene/gameobject/{instance_id}
# 3. 使用 ID 进行修改
manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])
# 1. 开始测试运行(异步)
result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"])
job_id = result["job_id"]
# 2. 轮询完成状态
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. 通过资源列出实例:mcpforunity://instances
# 2. 设置活动实例
set_active_instance(instance="MyProject@abc123")
# 3. 所有后续调用将路由到该实例
| 症状 | 原因 | 解决方案 |
|---|---|---|
| 工具返回 "busy" | 编译进行中 | 等待,检查 editor_state |
| "stale_file" 错误 | 文件自 SHA 后已更改 | 使用 get_sha 重新获取 SHA,重试 |
| 连接丢失 | 域重新加载 | 等待约 5 秒,重新连接 |
| 命令静默失败 | 错误的实例 | 检查 set_active_instance |
有关详细模式和示例:
每周安装量
57
仓库
GitHub 星标
6.8K
首次出现
2026年2月7日
安全审计
安装于
codex55
kimi-cli54
gemini-cli54
amp54
github-copilot54
opencode54
This skill helps you effectively use the Unity Editor with MCP tools and resources.
Examples in references/workflows.md and references/tools-reference.md are reusable templates. They may be inaccurate across Unity versions, package setups (UGUI/TMP/Input System), and project-specific conventions. Please check console, compilation errors, or use screenshot after implementation.
Before applying a template:
find_gameobjects.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
# After create_script or 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.
batch_execute for Multiple Operations# 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
)
Max 25 commands per batch by default (configurable in Unity MCP Tools window, max 100). Use fail_fast=True for dependent operations.
# 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", look_at="Player", max_resolution=256)
# Positioned screenshot: place a temp camera and capture in one call
manage_camera(action="screenshot", look_at="Player", view_position=[0, 10, -10], max_resolution=512)
Best practices for AI scene understanding:
Use include_image=True when you need to see the scene, not just save a file.
Use batch="surround" for a comprehensive overview (6 angles, one command).
Use look_at/view_position to capture from a specific viewpoint without needing a scene camera.
Keep max_resolution at 256–512 to balance quality vs. token cost.
Combine with look_at on manage_gameobject to orient a game camera before capturing.
manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player") manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
read_console(
action="get",
types=["error", "warning"], # Focus on problems
count=10,
format="detailed"
)
editor_state Before Complex Operations# 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
These are common patterns, not strict guarantees. manage_components.set_property payload shapes can vary by component/property; if a template fails, inspect the component resource payload and adjust.
# 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"
| 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 |
# 1. Create the script
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
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
# 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"])
# 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)
Large queries return paginated results. Always follow 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"]
When multiple Unity Editors are running:
# 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
| 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 |
For detailed schemas and examples:
Weekly Installs
57
Repository
GitHub Stars
6.8K
First Seen
Feb 7, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex55
kimi-cli54
gemini-cli54
amp54
github-copilot54
opencode54
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
44,900 周安装
manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512) manage_camera(action="screenshot_multiview", max_resolution=480) # 6-angle contact sheet
| C# code management |
| Assets | manage_asset, manage_prefabs | Asset operations |
| Editor | manage_editor, execute_menu_item, read_console | Editor control, package deployment (deploy_package/restore_package actions) |
| Testing | run_tests, get_test_job | Unity Test Framework |
| Batch | batch_execute | Parallel/bulk operations |
| Camera | manage_camera | Camera management (Unity Camera + Cinemachine). Tier 1 (always available): create, target, lens, priority, list, screenshot. Tier 2 (requires com.unity.cinemachine): brain, body/aim/noise pipeline, extensions, blending, force/release. 7 presets: follow, third_person, freelook, dolly, static, top_down, side_scroller. Resource: mcpforunity://scene/cameras. Use ping to check Cinemachine availability. See tools-reference.md. |
| Graphics | manage_graphics | Rendering and post-processing management. 33 actions across 5 groups: Volume (create/configure volumes and effects, URP/HDRP), Bake (lightmaps, light probes, reflection probes, Edit mode only), Stats (draw calls, batches, memory), Pipeline (quality levels, pipeline settings), Features (URP renderer features: add, remove, toggle, reorder). Resources: mcpforunity://scene/volumes, mcpforunity://rendering/stats, mcpforunity://pipeline/renderer-features. Use ping to check pipeline status. See tools-reference.md. |
| ProBuilder | manage_probuilder | 3D modeling, mesh editing, complex geometry. Whencom.unity.probuilder is installed, prefer ProBuilder shapes over primitive GameObjects for editable geometry, multi-material faces, or complex shapes. Supports 12 shape types, face/edge/vertex editing, smoothing, and per-face materials. See ProBuilder Guide. |
| UI | manage_ui, batch_execute with manage_gameobject + manage_components | UI Toolkit : Use manage_ui to create UXML/USS files, attach UIDocument, inspect visual trees. uGUI (Canvas) : Use batch_execute for Canvas, Panel, Button, Text, Slider, Toggle, Input Field. Readmcpforunity://project/info first to detect uGUI/TMP/Input System/UI Toolkit availability. (see UI workflows) |