Unity MCP manage_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导读manage_editor是 Unity MCPMCP for Unity核心工具组core中负责控制与查询 Unity 编辑器状态和设置的桥接工具由 Python 服务端与 Unity 编辑器端共同实现。通过它LLM 可以一键进入/退出播放模式、切换场景工具、增删 Tag 与 Layer、触发 MCPForUnity 包部署/回滚以及执行 Undo/Redo从而把“操作编辑器本身”纳入自动化工作流。读完本文你将掌握manage_editor的全部 14 个 action 的参数与返回值、底层调用链、以及如何与只读资源配合实现完整的编辑器自动化。一、工具定位与 action 总览根据 manage_editor 参考文档该工具属于core组模块名为services.tools.manage_editor。它同时提供只读与修改型两类 action只读Read-onlytelemetry_status、telemetry_ping修改Modifyingplay、pause、stop、set_active_tool、add_tag、remove_tag、add_layer、remove_layer、deploy_package、restore_package、undo、redo注意Prefab 编辑打开/保存/关闭 Prefab Stage不属于本工具职责应使用manage_prefabs。参数表NameTypeRequiredDescriptionactionLiteral[telemetry_status, telemetry_ping, play, pause, stop, set_active_tool, add_tag, remove_tag, add_layer, remove_layer, deploy_package, restore_package, undo, redo]yes获取和更新 Unity 编辑器状态。deploy_package将配置的 MCPForUnity 源码复制到项目包目录会触发重编译restore_package从备份恢复最近一次部署undo/redo执行编辑器撤销/重做。Prefab 编辑请使用manage_prefabs。tool_namestr \| None—设置活动工具时使用的工具名tag_namestr \| None—添加/删除标签时的标签名layer_namestr \| None—添加/删除图层时的图层名返回值返回一个包含 Unity 响应的dict具体形状随 action 不同而变化。通用成功形态为{success: true, message: ..., data: ...}失败时为{success: false, message: ...}详见下文源码解析。二、播放模式控制play / pause / stop三个 action 分别对应进入、暂停/恢复、退出播放模式是自动化验证场景行为的最常用入口manage_editor(actionplay) # 进入 Play Mode manage_editor(actionpause) # 暂停再次调用则恢复 manage_editor(actionstop) # 退出 Play ModeUnity 端的实现位于 ManageEditor.cs核心逻辑围绕EditorApplication.isPlaying与EditorApplication.isPausedplay若!EditorApplication.isPlaying则置为true并返回Entered play mode.已在播放模式则幂等地返回Already in play mode.。pause仅在播放模式下生效将isPaused取反返回Game paused.或Game resumed.非播放模式返回错误Cannot pause/resume: Not in play mode.。stop播放中则退出并返回Exited play mode.否则返回Already stopped (not in play mode).。从 manage_editor.py 可以看到Python 服务端只负责参数组装与转发真正执行动作的是 Unity 编辑器进程。三、切换活动工具set_active_toolset_active_tool用于切换 Unity 场景视图的当前工具等价于点击工具栏的 View/Move/Rotate/Scale 等按钮manage_editor(actionset_active_tool, tool_nameMove) # View | Move | Rotate | Scale | Rect | Transform在 ManageEditor.cs 中tool_name会通过Enum.TryParseTool(toolName, true, ...)大小写不敏感地解析为 Unity 内置Tool枚举。合法取值包括View、Move、Rotate、Scale、Rect、Transform解析成功后通过UnityEditor.Tools.current targetTool生效。需要注意两点边界若解析出的值属于Tool.None、Tool.Custom或超出标准枚举范围会返回错误Cannot directly set tool to ...因为这两者无法直接通过Tools.current切换解析失败时提示可用的标准工具列表View, Move, Rotate, Scale, Rect, Transform, Custom。四、标签管理add_tag / remove_tag用于向项目TagManager.asset添加或移除标签manage_editor(actionadd_tag, tag_nameEnemy) manage_editor(actionremove_tag, tag_nameOldTag)Unity 端实现细节ManageEditor.csadd_tag先通过InternalEditorUtility.tags检查标签是否已存在存在则报错再调用InternalEditorUtility.AddTag(tagName)随后AssetDatabase.SaveAssets()强制持久化到磁盘。remove_tag拒绝移除内置的Untagged标签Cannot remove the built-in Untagged tag.标签不存在时报Tag ... does not exist.移除成功后同样执行SaveAssets()。空字符串或纯空白名称一律被拒绝。配合只读资源使用在调用前可以通过mcpforunity://get_tags资源实现见 Tags.cs读取当前全部标签避免重复添加或删除不存在的标签。五、图层管理add_layer / remove_layer用于向ProjectSettings/TagManager.asset的 layers 数组添加或移除用户图层manage_editor(actionadd_layer, layer_nameProjectiles) manage_editor(actionremove_layer, layer_nameOldLayer)Unity 端实现ManageEditor.cs通过SerializedObject直接操作ProjectSettings/TagManager.asset的layers属性其关键约束体现了 Unity 图层机制本身用户图层区间仅使用索引 8~31FirstUserLayerIndex 8TotalLayerCount 32前 8 层是 Unity 内置层不可由用户修改。add_layer先做全数组大小写不敏感的重名检查重复则返回已存在的索引再查找第一个空的用户图层槽位若 8~31 全部被占用返回No empty User Layer slots available (8-31 are full).。写入后调用ApplyModifiedProperties()与AssetDatabase.SaveAssets()。remove_layer仅在用户图层区间内按名称忽略大小写查找找不到返回User layer ... not found.找到后将对应槽位字符串置空实现“删除”。图层名称同样不允许为空或纯空白。六、包部署与回滚deploy_package / restore_package这是本工具中风险最高也最实用的能力专门服务于“LLM 驱动迭代”场景将配置好的 MCPForUnity 源码目录复制到当前项目已安装的包目录中立即触发重编译且无确认弹窗。manage_editor(actiondeploy_package) # 复制源码到已安装包位置并触发 AssetDatabase.Refresh manage_editor(actionrestore_package) # 从上次部署的备份中恢复底层调用链Unity 端入口在 ManageEditor.cs分别调用MCPServiceLocator.Deployment.DeployFromStoredSource()与RestoreLastBackup()返回结果中携带source_path、target_path、backup_path。真正实现位于 PackageDeploymentService.cs源码路径来源存储在EditorPrefs的PackageDeploySourcePath键中对应 EditorPrefKeys.cs需先在 MCP for Unity 的 Advanced Settings 中设置。未设置时DeployFromStoredSource()返回Select a MCPForUnity folder first.。源码校验目录必须同时包含Editor和Runtime两个子文件夹否则拒绝部署。目标路径解析优先使用PackageInfo.FindForAssembly(...)获取已安装包的resolvedPath/assetPath失败则回退到AssetPathUtility.GetMcpPackageRootPath()计算的包根目录。部署过程先在Library/MCPForUnityDeployBackups/backup_时间戳创建目标目录的完整备份再用FileUtil.DeleteFileOrDirectoryCopyFileOrDirectory覆盖目标的Editor、Runtime两个核心文件夹最后AssetDatabase.Refresh(ImportAssetOptions.ForceUpdate)触发重编译。回滚从EditorPrefs读取最近一次备份与目标路径将备份目录整体覆盖回目标路径并再次Refresh。部署工作流建议按 tools-reference.md 中的说明完整的自动化部署链路应为在编辑器 Advanced Settings 中设置 MCPForUnity 源码文件夹路径manage_editor(actiondeploy_package)完成复制 备份 Refresh由于部署会触发脚本重编译随后调用refresh_unity(modeif_dirty, wait_for_readyTrue)等待编辑器重新编译完成再进行后续操作。七、撤销与重做undo / redoundo/redo直接调用 Unity 的 Undo 系统并返回受影响的撤销组名称便于 LLM 感知操作上下文manage_editor(actionundo) manage_editor(actionredo)Unity 端实现ManageEditor.csundo先通过Undo.GetCurrentGroupName()取得当前撤销组名执行Undo.PerformUndo()若组名为空则提示Undo performed (stack may be empty).。返回数据包含undone_group被撤销的组名与next_group撤销后的当前组名。redo执行Undo.PerformRedo()返回current_group。播放模式警告在播放模式下执行 undo/redo 时返回消息会附加Warning: undo during play mode may have unexpected effects.提醒调用方该操作在播放模式下的行为可能与预期不符。八、只读遥测telemetry_status / telemetry_ping这两个 action 是唯二由 Python 服务端直接处理、不转发到 Unity的动作属于诊断类接口manage_editor(actiontelemetry_status) # 返回: {success: true, telemetry_enabled: true|false} manage_editor(actiontelemetry_ping) # 返回: {success: true, message: telemetry ping queued}telemetry_status直接调用 telemetry.py 中的is_telemetry_enabled()读取服务端遥测开关状态。telemetry_ping通过record_tool_usage(diagnostic_ping, True, 1.0, None)向遥测队列写入一条工具使用记录异步、非阻塞用于验证遥测链路是否可用。从 test_manage_editor.py 的测试用例可以确认这两个 action 由 Python 端就地处理不会出现在转发给 Unity 的参数中assert params not in mock_unity。九、服务端转发机制与参数裁剪所有需要 Unity 执行的 action 都遵循统一的转发流程其源码在 manage_editor.py通过get_unity_instance_from_context(ctx)从请求上下文中获取当前活动的 Unity 实例由中间件注入支持多实例路由组装{action, toolName, tagName, layerName}参数字典并剔除所有值为None的键——测试 test_undo_omits_none_params 专门验证了这一点调用send_with_unity_instance(async_send_command_with_retry, unity_instance, manage_editor, params)经由统一的重试辅助函数发送命令对响应做统一包装成功时展开为{success: true, message: ..., data: ...}失败时原样返回结构化错误任何异常兜底为{success: false, message: Python error managing editor: ...}。UNITY_FORWARDED_ACTIONS参数化测试test_manage_editor.py逐一验证了play、pause、stop、set_active_tool、add_tag、remove_tag、add_layer、remove_layer、deploy_package、restore_package、undo、redo这 12 个动作都会以manage_editor工具名正确转发到 Unity。另外该工具在注册时通过ToolAnnotations标注了readOnlyHintFalse、destructiveHintTrue见 manage_editor.py向 MCP 客户端明确提示它属于破坏性/修改型工具调用时应谨慎。十、与只读资源的分工何时用工具何时用资源manage_editor负责写操作而读取编辑器状态应优先使用 MCP 资源二者形成清晰分工需求推荐方式仓库依据进入/退出/暂停播放模式manage_editor(actionplay/stop/pause)ManageEditor.cs切换场景工具manage_editor(actionset_active_tool, tool_nameMove)ManageEditor.cs增删 Tagmanage_editor(actionadd_tag/remove_tag)ManageEditor.cs增删 Layermanage_editor(actionadd_layer/remove_layer)ManageEditor.cs部署/回滚包manage_editor(actiondeploy_package/restore_package)PackageDeploymentService.cs撤销/重做manage_editor(actionundo/redo)ManageEditor.cs查询当前 Tag 列表资源mcpforunity://get_tagsTags.cs查询编辑器动态状态含活动工具、播放状态等资源mcpforunity://get_editor_stateEditorState.cs、EditorStateCache.cs当 action 参数非法或缺失时Unity 端会返回包含全部受支持 action 列表的错误信息并在其中提示“Use MCP resources for reading editor state, project info, tags, layers, selection, windows, prefab stage, and active tool.”见 ManageEditor.cs即读取类操作请走资源通道。十一、使用注意事项与最佳实践deploy_package 会触发重编译且无确认弹窗部署会覆盖已安装包的Editor/Runtime目录并立即刷新资源库。执行前请确认 Advanced Settings 中的源码路径指向正确的 MCPForUnity 目录且目标与源目录不同服务端会拒绝“源等于目标”的情况。部署后务必等待重编译完成建议紧跟refresh_unity(wait_for_readyTrue)避免在编译中继续下发依赖新代码的命令。备份即保险每次deploy_package都会在Library/MCPForUnityDeployBackups/下生成带时间戳的完整备份restore_package依赖该备份路径存储在EditorPrefs中。若无备份可用回滚会返回No backup available to restore.。修改前先查询增删 Tag/Layer 前先读get_tags或查看 TagManager 当前内容图层仅能操作索引 8~31 的用户层删除内置层会失败。播放模式下谨慎 undo/redo工具会主动附加警告建议在编辑模式下执行撤销/重做。参数大小写不敏感但校验严格tool_name解析忽略大小写Tag/Layer 名称不允许空串重复添加与删除不存在对象都会返回明确错误信息LLM 可直接依据 message 字段进行纠偏。小结manage_editor将 Unity 编辑器“自身”变为可编程对象播放控制、工具切换、Tag/Layer 维护、包部署回滚与撤销重做共 14 个 action配合mcpforunity://get_editor_state、get_tags等只读资源足以支撑“LLM 全自动驱动编辑器状态流转”的复杂工作流。其架构上采取 Python 服务端参数裁剪 实例路由、Unity 端EditorApplication/InternalEditorUtility/SerializedObject落地执行的清晰分层详见 manage_editor.py 与 ManageEditor.cs并有 test_manage_editor.py 对转发行为与参数裁剪做了完整回归保障。需要编辑 Prefab 时请转向manage_prefabs工具完整的工具体系参考可见 tools-reference.md。【免费下载链接】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），仅供参考