Unity-MCP Operator Guide基于 MCP 工具与资源编排 Unity Editor 的完整实战手册【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本指南围绕 unity-mcp-skill/SKILL.md 展开系统讲解如何通过 MCPModel Context Protocol工具与资源编排 Unity Editor——包括资源优先的工作流、脚本编译等待、批量执行、截图验证、参数类型约定、核心工具分类与常见工作流模式。读完本文你将掌握一套可复用的 Unity-MCP 操作规范能够稳定地让 AI 在 Unity 中创建与修改 GameObject、编辑脚本、管理场景、运行测试并自动化验证结果。模板提示先验证再套用SKILL 文档明确提示references/workflows.md与references/tools-reference.md中的示例是可复用模板但可能因 Unity 版本、包配置UGUI/TMP/Input System和项目约定不同而产生偏差。因此在使用模板之前必须先通过资源和find_gameobjects验证目标/组件是否真实存在将名称、枚举值和属性 payload 视为占位符按当前项目实际情况适配实施后检查 Console、编译错误必要时使用截图确认结果。模板是起点验证是底线——这是整个 SKILL 文档反复强调的第一原则。快速开始资源优先Resource-First工作流在使用任何工具之前永远先读取相关资源。这是 SKILL 文档给出的第一铁律它能避免错误并提供必要上下文。标准流程如下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(actionscreenshot)、资源回读这一先读后写、读写分离的模式在 resources-reference.md 中被归纳为 Use Find Then Read Pattern先用find_gameobjects拿到 instance ID再通过mcpforunity://scene/gameobject/{instance_id}读取完整数据最后用 ID 执行修改避免名称歧义。关键最佳实践1. 写/改脚本后等待编译完成并检查 Consolecreate_script与script_apply_edits两个工具会自动触发AssetDatabase.ImportAssetRequestScriptCompilation因此无需再调用refresh_unity只需等待编译结束并检查控制台# create_script 或 script_apply_edits 之后 # 两个工具都会自动触发导入与编译请求无需 refresh_unity # 1. 轮询编辑器状态直到编译完成 # 读取 mcpforunity://editor/state → 等待 is_compiling false # 2. 检查编译错误 read_console(types[error], count10, include_stacktraceTrue)从源码层面看EditorStateCache.cs 负责维护这一就绪快照它通过CompilationPipeline.compilationStarted/Finished与AssemblyReloadEvents事件跟踪真实编译状态GetActualIsCompiling()专门绕开 Unity 已知的EditorApplication.isCompiling误报如 issue #549 的 Recompile-After-Finished-Playing 和 issue #1276 的 LockReloadAssemblies保证is_compiling字段可信。而mcpforunity://editor/state资源由 EditorState.cs 提供直接读取该缓存快照因此即使 Unity 繁忙也能快速响应。2. 批量操作用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}} ], parallelTrue # 仅提示Unity 仍可能串行执行 )默认每批最多 25 条命令可在 Unity MCP Tools 窗口配置硬上限 100 条。存在依赖关系的操作请使用fail_fastTrue。底层实现在 BatchExecute.csDefaultMaxCommandsPerBatch 25、AbsoluteMaxCommandsPerBatch 100实际上限通过EditorPrefKeys.BatchExecuteMaxCommands读取用户配置并Math.Clamp到 1-100超过上限会直接返回错误。parallel参数仅是提示——代码中会记录parallelRequested并输出警告命令始终在主线程上串行执行以保证确定性与 Unity API 安全parallelApplied false。同时批量执行不是事务性的若后续命令失败之前的命令不会被回滚。小技巧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. 用截图验证视觉效果AI 的眼睛来自截图。manage_camera(actionscreenshot)提供多种采集方式# 基础截图保存到 Assets/仅返回文件路径 manage_camera(actionscreenshot) # 内联截图直接把 base64 PNG 返回给 AI manage_camera(actionscreenshot, include_imageTrue) # 指定相机并限制分辨率减小 payload manage_camera(actionscreenshot, cameraMainCamera, include_imageTrue, max_resolution512) # 环绕批拍围绕场景一次拍前/后/左/右/顶/鸟瞰六视角 manage_camera(actionscreenshot, batchsurround, max_resolution256) # 环绕批拍并以指定物体为中心 manage_camera(actionscreenshot, batchsurround, view_targetPlayer, max_resolution256) # 定位拍摄一次调用放置临时相机并取景 manage_camera(actionscreenshot, view_targetPlayer, view_position[0, 10, -10], max_resolution512) # Scene View 截图拍下开发者看到的编辑器视口含 Gizmos、线框、网格 manage_camera(actionscreenshot, capture_sourcescene_view, include_imageTrue) # Scene View 聚焦特定物体 manage_camera(actionscreenshot, capture_sourcescene_view, view_targetCanvas, include_imageTrue)AI 理解场景的最佳实践需要看见场景而非仅仅保存文件时使用include_imageTrue需要全局概览时用batchsurround一次命令拍 6 个角度用view_target/view_position从任意视角取景无需场景中存在相机用capture_sourcescene_view查看编辑器视口Gizmos、线框、网格将max_resolution控制在 256-512在画质与 token 成本之间取得平衡。Agentic 相机循环瞄准 → 拍摄 → 分析 → 决策manage_gameobject(actionlook_at, targetMainCamera, look_at_targetPlayer) manage_camera(actionscreenshot, cameraMainCamera, include_imageTrue, max_resolution512) # → 分析图片决定下一步行动 # 六视角联系表contact sheet manage_camera(actionscreenshot_multiview, max_resolution480) # 编辑器级检查显示 Gizmos、调试叠加层等 manage_camera(actionscreenshot, capture_sourcescene_view, view_targetPlayer, include_imageTrue)4. 重大变更后检查 Consoleread_console( actionget, types[error, warning], # 聚焦问题 count10, formatdetailed )5. 复杂操作前永远检查mcpforunity://editor/state# 读取 mcpforunity://editor/state检查 # - is_compiling: 为 true 则等待 # - is_domain_reload_pending: 为 true 则等待 # - ready_for_tools: 仅当为 true 时才继续 # - blocking_reasons: 工具可能失败的原因参数类型约定以下为常见约定而非严格保证。manage_components.set_property的 payload 形态可能随组件/属性不同而变化若模板失败请检查对应组件的资源 payload 后调整。向量position、rotation、scale、color# 两种写法均被接受 position[1.0, 2.0, 3.0] # 列表 position[1.0, 2.0, 3.0] # JSON 字符串布尔值# 两种写法均被接受 include_inactiveTrue # 布尔 include_inactivetrue # 字符串颜色# 自动识别格式 color[255, 0, 0, 255] # 0-255 范围 color[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 归一化自动转换路径# 相对 Assets默认 pathAssets/Scripts/MyScript.cs # URI 形式 urimcpforunity://path/Assets/Scripts/MyScript.cs urifile:///full/path/to/file.cs源码级佐证这套宽松类型转换由 ParamCoercion.cs 实现。它提供了CoerceInt、CoerceFloat、CoerceBool、CoerceString、CoerceEnum等系列方法能从容处理字符串、数字、布尔混用的输入布尔值支持1/yes/on与0/no/off等写法数字支持整数与浮点字符串的解析。此外NormalizePropertyName会把Use Gravity、is_kinematic、max-angular-velocity等五花八门的命名统一转为 camelCase如useGravity、isKinematic、maxAngularVelocity这是 LLM 生成的参数能被 Unity 序列化字段正确匹配的关键机制。核心工具分类类别关键工具用途Scenemanage_scene、find_gameobjects场景操作、查找对象Objectsmanage_gameobject、manage_components创建/修改 GameObjectScriptscreate_script、script_apply_edits、validate_scriptC# 代码管理创建/编辑时自动刷新Assetsmanage_asset、manage_prefabs资源操作。Prefab 实例化通过manage_gameobject(actioncreate, prefab_path...)完成而非manage_prefabsEditormanage_editor、execute_menu_item、read_console编辑器控制、包部署deploy_package/restore_package动作Testingrun_tests、get_test_jobUnity Test FrameworkBatchbatch_execute并行/批量操作Cameramanage_camera相机管理Unity Camera Cinemachine。Tier 1始终可用create、target、lens、priority、list、screenshot。Tier 2需com.unity.cinemachinebrain、body/aim/noise pipeline、extensions、blending、force/release。7 种预设follow、third_person、freelook、dolly、static、top_down、side_scroller。资源mcpforunity://scene/cameras。用ping检查 Cinemachine 可用性。详见 tools-reference.mdGraphicsmanage_graphics渲染与后处理管理。5 组共 33 个动作Volume创建/配置 Volume 与特效URP/HDRP、Bake光照贴图、Light Probe、Reflection Probe仅 Edit 模式、Statsdraw calls、batches、memory、Pipeline质量等级、管线设置、FeaturesURP renderer featuresadd、remove、toggle、reorder。资源mcpforunity://scene/volumes、mcpforunity://rendering/stats、mcpforunity://pipeline/renderer-features。用ping检查管线状态。详见 tools-reference.mdPackagesmanage_packages安装、移除、搜索、管理 Unity 包与 scoped registry。查询动作列出已装、搜索 registry、获取信息、ping、轮询状态。变更动作增删包、嵌入编辑、增删 scoped registry、强制 resolve。会校验标识符、对 git URL 发出警告、移除前检查依赖forcetrue可覆盖。详见 tools-reference.mdPhysicsmanage_physics3D/2D 物理管理21 个动作。设置、碰撞矩阵、材质、关节14 种。查询raycast、raycast_all、linecast、shapecast球/盒/胶囊扫描、overlap。力apply_forceAddForce/AddTorque/AddExplosionForce 配合 ForceMode。Rigidbodyget_rigidbody、configure_rigidbodymass、drag、gravity、constraints、collision detection。校验场景级检查。模拟Edit 模式下simulate_step。详见 tools-reference.mdProBuildermanage_probuilder3D 建模、网格编辑、复杂几何。当com.unity.probuilder已安装时可编辑几何、多材质面或复杂形状优先用 ProBuilder 而非原始 GameObject。支持 12 种形状、面/边/顶点编辑、平滑与逐面材质。详见 ProBuilder GuideUImanage_ui、batch_execute配合manage_gameobjectmanage_componentsUI Toolkit用manage_ui创建 UXML/USS 文件、挂 UIDocument、检查视觉树。uGUICanvas用batch_execute创建 Canvas、Panel、Button、Text、Slider、Toggle、Input Field。先读mcpforunity://project/info检测 uGUI/TMP/Input System/UI Toolkit 可用性。见 UI workflowsDocsunity_reflect、unity_docsAPI 验证与文档查询。unity_reflect通过反射检查实时 C# API需 Unity 连接search跨程序集搜索类型、get_type获取成员摘要、get_member获取完整签名。unity_docs从 docs.unity3d.com 抓取官方文档无需 Unity 连接get_docScriptReference、get_manualManual 页、get_package_doc包文档、lookup并行搜索所有来源 项目资源。信任层级反射 项目资源 文档。工作流unity_reflectsearch → get_type → get_member →unity_docslookup。详见 tools-reference.md工具注册机制可参考源码标注如 ManageCamera.cs 中的[McpForUnityTool(manage_camera, AutoRegister false)]与 ManageGameObject.cs 中的[McpForUnityTool(manage_gameobject, AutoRegister false)]——所有工具通过特性注册到统一命令注册表供 MCP 层按名称调度。常见工作流创建新脚本并使用它# 1. 创建脚本自动触发导入 编译 create_script( pathAssets/Scripts/PlayerController.cs, contentsusing UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n} ) # 2. 等待编译完成 # 读取 mcpforunity://editor/state → 等待 is_compiling false # 3. 检查编译错误 read_console(types[error], count10) # 4. 然后才挂到 GameObject 上 manage_gameobject(actionmodify, targetPlayer, components_to_add[PlayerController])查找并修改 GameObject# 1. 按名称/标签/组件查找仅返回 ID result find_gameobjects(search_termEnemy, search_methodby_tag, page_size50) # 2. 通过资源获取完整数据 # mcpforunity://scene/gameobject/{instance_id} # 3. 用 ID 执行修改 manage_gameobject(actionmodify, targetinstance_id, position[10, 0, 0])运行并监控测试# 1. 启动测试异步 result run_tests(modeEditMode, test_names[MyTests.TestSomething]) job_id result[job_id] # 2. 轮询完成状态 result get_test_job(job_idjob_id, wait_timeout60, include_failed_testsTrue)分页模式Pagination Pattern大型查询会返回分页结果。始终跟随next_cursorcursor 0 all_items [] while True: result manage_scene(actionget_hierarchy, page_size50, cursorcursor) all_items.extend(result[data][items]) if not result[data].get(next_cursor): break cursor result[data][next_cursor]分页参数在各工具中遵循一致约定例如find_gameobjects的page_size默认 50、最大 500返回{ids: [...], next_cursor: 50, ...}资源侧mcpforunity://scene/gameobject/{id}/components的page_size默认 25、最大 100可通过include_propertiesfalse先取组件清单再按需读取单个组件。多实例工作流Multi-Instance当同时运行多个 Unity Editor 时# 1. 通过资源列出实例mcpforunity://instances # 2. 设置活动实例 set_active_instance(instanceMyProjectabc123) # 3. 之后的所有调用都路由到该实例在不确定当前连接的是哪个实例、或命令意外失败时都应回查mcpforunity://instances确认目标。错误恢复Error Recovery症状原因解决方案工具返回 busy编译进行中等待检查mcpforunity://editor/statestale_file 错误文件自上次 SHA 后已变更用get_sha重新获取 SHA 后重试连接丢失Domain reload等待约 5 秒后重连命令静默失败实例不对检查set_active_instance其中 stale_file 机制与get_sha、apply_text_edits的precondition_sha256参数、script_apply_edits的 SHA 前置条件密切相关——先取哈希、再编辑、用哈希做并发/陈旧校验可有效避免在已变更的文件上盲目写入。参考文件需要完整参数与更多示例时tools-reference.md全部工具的完整文档与所有参数resources-reference.md全部可用资源及其数据结构mcpforunity://URI 体系、editor/state 快照、scene/gameobject、prefab、project/info、instances、tests 等workflows.md扩展工作流示例与模式场景搭建、脚本开发、资源管理、测试驱动开发、调试、UI 创建、相机与 Cinemachine、ProBuilder、图形渲染、包管理、批量操作等这套资源优先读取 编译状态轮询 批量合并 截图验证 Console 复核的操作纪律构成了 Unity-MCP 集成的核心方法论让 AI 不再是盲目调用工具而是在充分掌握编辑器上下文的前提下可靠、可验证地完成 Unity 自动化任务。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Unity-MCP Operator Guide：基于 MCP 工具与资源编排 Unity Editor 的完整实战手册
Unity-MCP Operator Guide基于 MCP 工具与资源编排 Unity Editor 的完整实战手册【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本指南围绕 unity-mcp-skill/SKILL.md 展开系统讲解如何通过 MCPModel Context Protocol工具与资源编排 Unity Editor——包括资源优先的工作流、脚本编译等待、批量执行、截图验证、参数类型约定、核心工具分类与常见工作流模式。读完本文你将掌握一套可复用的 Unity-MCP 操作规范能够稳定地让 AI 在 Unity 中创建与修改 GameObject、编辑脚本、管理场景、运行测试并自动化验证结果。模板提示先验证再套用SKILL 文档明确提示references/workflows.md与references/tools-reference.md中的示例是可复用模板但可能因 Unity 版本、包配置UGUI/TMP/Input System和项目约定不同而产生偏差。因此在使用模板之前必须先通过资源和find_gameobjects验证目标/组件是否真实存在将名称、枚举值和属性 payload 视为占位符按当前项目实际情况适配实施后检查 Console、编译错误必要时使用截图确认结果。模板是起点验证是底线——这是整个 SKILL 文档反复强调的第一原则。快速开始资源优先Resource-First工作流在使用任何工具之前永远先读取相关资源。这是 SKILL 文档给出的第一铁律它能避免错误并提供必要上下文。标准流程如下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(actionscreenshot)、资源回读这一先读后写、读写分离的模式在 resources-reference.md 中被归纳为 Use Find Then Read Pattern先用find_gameobjects拿到 instance ID再通过mcpforunity://scene/gameobject/{instance_id}读取完整数据最后用 ID 执行修改避免名称歧义。关键最佳实践1. 写/改脚本后等待编译完成并检查 Consolecreate_script与script_apply_edits两个工具会自动触发AssetDatabase.ImportAssetRequestScriptCompilation因此无需再调用refresh_unity只需等待编译结束并检查控制台# create_script 或 script_apply_edits 之后 # 两个工具都会自动触发导入与编译请求无需 refresh_unity # 1. 轮询编辑器状态直到编译完成 # 读取 mcpforunity://editor/state → 等待 is_compiling false # 2. 检查编译错误 read_console(types[error], count10, include_stacktraceTrue)从源码层面看EditorStateCache.cs 负责维护这一就绪快照它通过CompilationPipeline.compilationStarted/Finished与AssemblyReloadEvents事件跟踪真实编译状态GetActualIsCompiling()专门绕开 Unity 已知的EditorApplication.isCompiling误报如 issue #549 的 Recompile-After-Finished-Playing 和 issue #1276 的 LockReloadAssemblies保证is_compiling字段可信。而mcpforunity://editor/state资源由 EditorState.cs 提供直接读取该缓存快照因此即使 Unity 繁忙也能快速响应。2. 批量操作用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}} ], parallelTrue # 仅提示Unity 仍可能串行执行 )默认每批最多 25 条命令可在 Unity MCP Tools 窗口配置硬上限 100 条。存在依赖关系的操作请使用fail_fastTrue。底层实现在 BatchExecute.csDefaultMaxCommandsPerBatch 25、AbsoluteMaxCommandsPerBatch 100实际上限通过EditorPrefKeys.BatchExecuteMaxCommands读取用户配置并Math.Clamp到 1-100超过上限会直接返回错误。parallel参数仅是提示——代码中会记录parallelRequested并输出警告命令始终在主线程上串行执行以保证确定性与 Unity API 安全parallelApplied false。同时批量执行不是事务性的若后续命令失败之前的命令不会被回滚。小技巧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. 用截图验证视觉效果AI 的眼睛来自截图。manage_camera(actionscreenshot)提供多种采集方式# 基础截图保存到 Assets/仅返回文件路径 manage_camera(actionscreenshot) # 内联截图直接把 base64 PNG 返回给 AI manage_camera(actionscreenshot, include_imageTrue) # 指定相机并限制分辨率减小 payload manage_camera(actionscreenshot, cameraMainCamera, include_imageTrue, max_resolution512) # 环绕批拍围绕场景一次拍前/后/左/右/顶/鸟瞰六视角 manage_camera(actionscreenshot, batchsurround, max_resolution256) # 环绕批拍并以指定物体为中心 manage_camera(actionscreenshot, batchsurround, view_targetPlayer, max_resolution256) # 定位拍摄一次调用放置临时相机并取景 manage_camera(actionscreenshot, view_targetPlayer, view_position[0, 10, -10], max_resolution512) # Scene View 截图拍下开发者看到的编辑器视口含 Gizmos、线框、网格 manage_camera(actionscreenshot, capture_sourcescene_view, include_imageTrue) # Scene View 聚焦特定物体 manage_camera(actionscreenshot, capture_sourcescene_view, view_targetCanvas, include_imageTrue)AI 理解场景的最佳实践需要看见场景而非仅仅保存文件时使用include_imageTrue需要全局概览时用batchsurround一次命令拍 6 个角度用view_target/view_position从任意视角取景无需场景中存在相机用capture_sourcescene_view查看编辑器视口Gizmos、线框、网格将max_resolution控制在 256-512在画质与 token 成本之间取得平衡。Agentic 相机循环瞄准 → 拍摄 → 分析 → 决策manage_gameobject(actionlook_at, targetMainCamera, look_at_targetPlayer) manage_camera(actionscreenshot, cameraMainCamera, include_imageTrue, max_resolution512) # → 分析图片决定下一步行动 # 六视角联系表contact sheet manage_camera(actionscreenshot_multiview, max_resolution480) # 编辑器级检查显示 Gizmos、调试叠加层等 manage_camera(actionscreenshot, capture_sourcescene_view, view_targetPlayer, include_imageTrue)4. 重大变更后检查 Consoleread_console( actionget, types[error, warning], # 聚焦问题 count10, formatdetailed )5. 复杂操作前永远检查mcpforunity://editor/state# 读取 mcpforunity://editor/state检查 # - is_compiling: 为 true 则等待 # - is_domain_reload_pending: 为 true 则等待 # - ready_for_tools: 仅当为 true 时才继续 # - blocking_reasons: 工具可能失败的原因参数类型约定以下为常见约定而非严格保证。manage_components.set_property的 payload 形态可能随组件/属性不同而变化若模板失败请检查对应组件的资源 payload 后调整。向量position、rotation、scale、color# 两种写法均被接受 position[1.0, 2.0, 3.0] # 列表 position[1.0, 2.0, 3.0] # JSON 字符串布尔值# 两种写法均被接受 include_inactiveTrue # 布尔 include_inactivetrue # 字符串颜色# 自动识别格式 color[255, 0, 0, 255] # 0-255 范围 color[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 归一化自动转换路径# 相对 Assets默认 pathAssets/Scripts/MyScript.cs # URI 形式 urimcpforunity://path/Assets/Scripts/MyScript.cs urifile:///full/path/to/file.cs源码级佐证这套宽松类型转换由 ParamCoercion.cs 实现。它提供了CoerceInt、CoerceFloat、CoerceBool、CoerceString、CoerceEnum等系列方法能从容处理字符串、数字、布尔混用的输入布尔值支持1/yes/on与0/no/off等写法数字支持整数与浮点字符串的解析。此外NormalizePropertyName会把Use Gravity、is_kinematic、max-angular-velocity等五花八门的命名统一转为 camelCase如useGravity、isKinematic、maxAngularVelocity这是 LLM 生成的参数能被 Unity 序列化字段正确匹配的关键机制。核心工具分类类别关键工具用途Scenemanage_scene、find_gameobjects场景操作、查找对象Objectsmanage_gameobject、manage_components创建/修改 GameObjectScriptscreate_script、script_apply_edits、validate_scriptC# 代码管理创建/编辑时自动刷新Assetsmanage_asset、manage_prefabs资源操作。Prefab 实例化通过manage_gameobject(actioncreate, prefab_path...)完成而非manage_prefabsEditormanage_editor、execute_menu_item、read_console编辑器控制、包部署deploy_package/restore_package动作Testingrun_tests、get_test_jobUnity Test FrameworkBatchbatch_execute并行/批量操作Cameramanage_camera相机管理Unity Camera Cinemachine。Tier 1始终可用create、target、lens、priority、list、screenshot。Tier 2需com.unity.cinemachinebrain、body/aim/noise pipeline、extensions、blending、force/release。7 种预设follow、third_person、freelook、dolly、static、top_down、side_scroller。资源mcpforunity://scene/cameras。用ping检查 Cinemachine 可用性。详见 tools-reference.mdGraphicsmanage_graphics渲染与后处理管理。5 组共 33 个动作Volume创建/配置 Volume 与特效URP/HDRP、Bake光照贴图、Light Probe、Reflection Probe仅 Edit 模式、Statsdraw calls、batches、memory、Pipeline质量等级、管线设置、FeaturesURP renderer featuresadd、remove、toggle、reorder。资源mcpforunity://scene/volumes、mcpforunity://rendering/stats、mcpforunity://pipeline/renderer-features。用ping检查管线状态。详见 tools-reference.mdPackagesmanage_packages安装、移除、搜索、管理 Unity 包与 scoped registry。查询动作列出已装、搜索 registry、获取信息、ping、轮询状态。变更动作增删包、嵌入编辑、增删 scoped registry、强制 resolve。会校验标识符、对 git URL 发出警告、移除前检查依赖forcetrue可覆盖。详见 tools-reference.mdPhysicsmanage_physics3D/2D 物理管理21 个动作。设置、碰撞矩阵、材质、关节14 种。查询raycast、raycast_all、linecast、shapecast球/盒/胶囊扫描、overlap。力apply_forceAddForce/AddTorque/AddExplosionForce 配合 ForceMode。Rigidbodyget_rigidbody、configure_rigidbodymass、drag、gravity、constraints、collision detection。校验场景级检查。模拟Edit 模式下simulate_step。详见 tools-reference.mdProBuildermanage_probuilder3D 建模、网格编辑、复杂几何。当com.unity.probuilder已安装时可编辑几何、多材质面或复杂形状优先用 ProBuilder 而非原始 GameObject。支持 12 种形状、面/边/顶点编辑、平滑与逐面材质。详见 ProBuilder GuideUImanage_ui、batch_execute配合manage_gameobjectmanage_componentsUI Toolkit用manage_ui创建 UXML/USS 文件、挂 UIDocument、检查视觉树。uGUICanvas用batch_execute创建 Canvas、Panel、Button、Text、Slider、Toggle、Input Field。先读mcpforunity://project/info检测 uGUI/TMP/Input System/UI Toolkit 可用性。见 UI workflowsDocsunity_reflect、unity_docsAPI 验证与文档查询。unity_reflect通过反射检查实时 C# API需 Unity 连接search跨程序集搜索类型、get_type获取成员摘要、get_member获取完整签名。unity_docs从 docs.unity3d.com 抓取官方文档无需 Unity 连接get_docScriptReference、get_manualManual 页、get_package_doc包文档、lookup并行搜索所有来源 项目资源。信任层级反射 项目资源 文档。工作流unity_reflectsearch → get_type → get_member →unity_docslookup。详见 tools-reference.md工具注册机制可参考源码标注如 ManageCamera.cs 中的[McpForUnityTool(manage_camera, AutoRegister false)]与 ManageGameObject.cs 中的[McpForUnityTool(manage_gameobject, AutoRegister false)]——所有工具通过特性注册到统一命令注册表供 MCP 层按名称调度。常见工作流创建新脚本并使用它# 1. 创建脚本自动触发导入 编译 create_script( pathAssets/Scripts/PlayerController.cs, contentsusing UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n} ) # 2. 等待编译完成 # 读取 mcpforunity://editor/state → 等待 is_compiling false # 3. 检查编译错误 read_console(types[error], count10) # 4. 然后才挂到 GameObject 上 manage_gameobject(actionmodify, targetPlayer, components_to_add[PlayerController])查找并修改 GameObject# 1. 按名称/标签/组件查找仅返回 ID result find_gameobjects(search_termEnemy, search_methodby_tag, page_size50) # 2. 通过资源获取完整数据 # mcpforunity://scene/gameobject/{instance_id} # 3. 用 ID 执行修改 manage_gameobject(actionmodify, targetinstance_id, position[10, 0, 0])运行并监控测试# 1. 启动测试异步 result run_tests(modeEditMode, test_names[MyTests.TestSomething]) job_id result[job_id] # 2. 轮询完成状态 result get_test_job(job_idjob_id, wait_timeout60, include_failed_testsTrue)分页模式Pagination Pattern大型查询会返回分页结果。始终跟随next_cursorcursor 0 all_items [] while True: result manage_scene(actionget_hierarchy, page_size50, cursorcursor) all_items.extend(result[data][items]) if not result[data].get(next_cursor): break cursor result[data][next_cursor]分页参数在各工具中遵循一致约定例如find_gameobjects的page_size默认 50、最大 500返回{ids: [...], next_cursor: 50, ...}资源侧mcpforunity://scene/gameobject/{id}/components的page_size默认 25、最大 100可通过include_propertiesfalse先取组件清单再按需读取单个组件。多实例工作流Multi-Instance当同时运行多个 Unity Editor 时# 1. 通过资源列出实例mcpforunity://instances # 2. 设置活动实例 set_active_instance(instanceMyProjectabc123) # 3. 之后的所有调用都路由到该实例在不确定当前连接的是哪个实例、或命令意外失败时都应回查mcpforunity://instances确认目标。错误恢复Error Recovery症状原因解决方案工具返回 busy编译进行中等待检查mcpforunity://editor/statestale_file 错误文件自上次 SHA 后已变更用get_sha重新获取 SHA 后重试连接丢失Domain reload等待约 5 秒后重连命令静默失败实例不对检查set_active_instance其中 stale_file 机制与get_sha、apply_text_edits的precondition_sha256参数、script_apply_edits的 SHA 前置条件密切相关——先取哈希、再编辑、用哈希做并发/陈旧校验可有效避免在已变更的文件上盲目写入。参考文件需要完整参数与更多示例时tools-reference.md全部工具的完整文档与所有参数resources-reference.md全部可用资源及其数据结构mcpforunity://URI 体系、editor/state 快照、scene/gameobject、prefab、project/info、instances、tests 等workflows.md扩展工作流示例与模式场景搭建、脚本开发、资源管理、测试驱动开发、调试、UI 创建、相机与 Cinemachine、ProBuilder、图形渲染、包管理、批量操作等这套资源优先读取 编译状态轮询 批量合并 截图验证 Console 复核的操作纪律构成了 Unity-MCP 集成的核心方法论让 AI 不再是盲目调用工具而是在充分掌握编辑器上下文的前提下可靠、可验证地完成 Unity 自动化任务。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考