unity-mcp scripting_ext 工具组指南在 Unity 编辑器中执行任意 C# 代码与批量管理 ScriptableObject【免费下载链接】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导读scripting_ext是 unity-mcpMCP for Unity提供的脚本扩展工具组包含两个把 AI 助手能力直接注入 Unity 编辑器的核心工具execute_code与manage_scriptable_object。前者允许 LLM 在编辑器进程内即时编译并运行任意 C# 方法体无需创建任何脚本文件后者则通过 Unity 原生的SerializedObject/SerializedProperty属性路径批量创建、修改 ScriptableObject 资源。读完本文你将掌握这两个工具的完整参数语义、四种 action 的使用方式、编译器后端auto/roslyn/codedom的选择逻辑、patch 结构与对象引用/子资源Sprite的赋值技巧以及它们在服务端、Unity 端与测试中的底层实现原理。工具组概览scripting_ext定位scripting_ext的索引文档 index.md 将本工具组定义为一句话ScriptableObject management以及代码执行。它在工具目录体系中属于脚本扩展分组与core、asset_gen、probuilder、profiling、testing、ui、vfx等分组并列见 tools/index.md 与 scripting_ext/category.json。两个工具在manifest.json中均以scripting_ext分组注册execute_code见 manifest.jsonmanage_scriptable_object见 manifest.json。从源码结构看它们的 Python 端入口分别位于 Server/src/services/tools/execute_code.py 与 Server/src/services/tools/manage_scriptable_object.pyUnity 端处理器分别为 MCPForUnity/Editor/Tools/ExecuteCode.cs 与 MCPForUnity/Editor/Tools/ManageScriptableObject.cs。两个工具都被标记了destructiveHintTrue破坏性提示意味着 MCP 客户端会要求用户显式确认后才允许调用。execute_code在 Unity 编辑器内即时编译并执行 C# 代码功能定位与执行模型execute_code的核心价值在于代码以方法体method body形式运行可直接访问UnityEngine与UnityEditor命名空间通过return把数据回传给 LLM。编译在内存中完成不创建任何 .cs 脚本文件也不会污染项目 Assets 目录。Unity 端的实现封装在 ExecuteCode.cs 中其执行模型为用户代码被包装进一个固定模板WrapUserCode生成类似下面的动态类using System; using System.Collections.Generic; using System.Linq; using System.Reflection; using UnityEngine; using UnityEditor; public static class MCPDynamicCode { public static object Execute() { // -- 你的代码插入在这里 return ...; } }动态程序集以每次编译一个全新的内存程序集的方式产生。由于 Mono 无法卸载已加载的程序集重复编译相同代码会导致内存泄漏因此实现引入了一个以包装后源码 编译器为 key 的编译缓存_compiledCache上限 64 条见 ExecuteCode.cs同时InitializeOnLoadMethod会在域重载domain reload时清空全部缓存与 Roslyn 反射缓存。代码长度上限为 50,000 字符MaxCodeLength历史记录最多保留 50 条MaxHistoryEntries历史条目中的代码预览截断为 500 字符、结果预览截断为 200 字符。参数总览参数类型必填说明actionLiteral[execute, get_history, replay, clear_history]是要执行的动作codestr \| None—待执行的 C# 代码仅execute使用。必须是合法方法体可访问 UnityEngine/UnityEditor用return返回数据safety_checksbool—是否启用危险模式拦截File.Delete、Process.Start、死循环等。注意不是完整沙箱高级绕过仍可能。默认trueindexint \| None—要重放的历史条目索引仅replay使用limitint—get_history返回的历史条数1–50。默认 10compilerLiteral[auto, roslyn, codedom]—编译器后端。auto在安装了 Microsoft.CodeAnalysis 时用 Roslyn否则回退 CodeDomroslyn强制 RoslynC# 12codedom强制旧版 CSharpCodeProvider仅 C# 6。默认auto服务端 execute_code.py 会校验参数的组合关系execute动作必须携带code缺失时直接返回Parameter code is required for execute action.replay动作必须携带index而get_history的limit会被钳制在 1–50 之间max(1, min(limit, 50))随后把参数通过send_with_unity_instance以命令名execute_code转发给 Unity 端。四种 action 的用法execute执行代码最基本的用法让 LLM 读取当前场景信息后回传数据。例如查询场景中 GameObject 数量action: execute code: return Object.FindObjectsOfTypeGameObject().Length;执行结果会以{ success: true, message: ..., data: { result: ..., compiler: roslyn } }形式返回。返回值序列化遵循 SerializeResult原始类型isPrimitive、string、decimal直接返回其余对象尝试用JToken.FromObject转 JSON失败则回退为ToString()。get_history查看历史列出最近的执行记录每条包含index、codePreview500 字符截断、success、resultPreview200 字符截断、elapsedMs耗时毫秒、timestamp、safetyChecksEnabled、compiler。limit控制返回条数历史为空时返回No execution history.。replay重放历史按index取回某条历史中的原始code并以该条记录当时的safety_checks与compiler设置重新走一遍 execute 流程见 HandleReplay。这在上一条代码执行成功但后续修改搞坏了状态时特别有用可以快速回滚到可用版本。注意索引越界或历史为空时会返回错误合法范围是0 ~ 历史条数-1。clear_history清空历史清空全部历史记录并返回被清除的条数。safety_checks拦截的黑名单模式当safety_checkstrue默认时CheckBlockedPatterns 会做大小写不敏感的字符串包含匹配命中即拒绝执行。完整黑名单见 ExecuteCode.csSystem.IO.File.Delete System.IO.Directory.Delete FileUtil.DeleteFileOrDirectory AssetDatabase.DeleteAsset AssetDatabase.MoveAssetToTrash EditorApplication.Exit Process.Start Process.Kill while(true) / while (true) for(;;) / for (;;)命中时的错误信息形如Blocked pattern detected: AssetDatabase.DeleteAsset并提示如属有意为之可用 safety_checksfalse 关闭。请务必理解文档与源码中的双重强调这是一道防呆而不是防攻击的关卡——字符串匹配很容易被改写绕过如File.Delete(...)绝不能在不可信输入场景下把它当作安全边界。两个工具在ToolAnnotations上都标记了destructiveHint也是同样的提醒。三种编译器后端auto / roslyn / codedom后端语言能力依赖说明auto默认Roslyn 可用则 C# 12否则 C# 6Microsoft.CodeAnalysis可选自动探测并择优roslynC# 12必须安装 Microsoft.CodeAnalysis否则报错并提示改用 codedom推荐用于现代语法与更清晰的诊断信息codedom仅 C# 6随 .NET 内置的CSharpCodeProvider兜底方案处理旧语法Roslyn 后端通过纯反射调用RoslynCompiler对Microsoft.CodeAnalysis没有任何编译期依赖——包未安装时IsAvailable返回 falseauto模式自动回退到 CodeDomroslyn模式则返回Roslyn (Microsoft.CodeAnalysis) is not available.。CSharpParseOptions的语言版本被设为Latest因此支持最新的 C# 语法特性。CodeDom 路径有两个值得一提的工程细节源码注释均有交代响应文件.rsp规避命令行超长CSharpCodeProvider会把每个ReferencedAssemblies转成csc命令行的字面/r:...参数。当项目有 100 个 asmdef 时引用路径会击穿 Windows 的 32 KBCreateProcess参数长度上限报 The filename or extension is too long。实现改为把所有/r:引用写入临时 .rsp 响应文件命令行只传一个短参数...。重复程序集去重CSharpCodeProvider 无法解析类型转发type-forwarding当netstandard.dll与mscorlib/System.Runtime/System.Collections同时加载时ListT等类型会出现在多个程序集中导致 type defined multiple times 错误。因此 FilterAssemblyPathsForCodeDom 会在存在 netstandard 时剔除这组重复程序集并按被引用次数优先、版本次之的策略对同名程序集去重。此外CodeDom 编译先输出到临时 DLL 再Assembly.Load而非直接内存编译——这是因为 Mono 的 CodeDom 会把 mcs 输出到 stdout 的 BOM 行误判为一条伪造错误导致明明编译成功却拿不到程序集详见 CodeDomCompile。编译与运行错误处理编译错误错误行号会通过WrapperLineOffset值为 10减去包装模板占用的行数映射回用户代码的真实行号返回形如Line 3: ...的诊断。运行错误反射调用抛出的TargetInvocationException会被解包返回Runtime error: message并附带exceptionType、stackTrace与compiler字段便于 LLM 定位问题。服务端行为与测试佐证服务端把 Unity 的原始响应归一化为{success, message, data}三字段结构。单元测试 Server/tests/test_execute_code.py 覆盖了code正确透传test_execute_forwards_code_to_unity、safety_checks默认true与显式false的传递、返回值透传data.result 42、code缺失时报错以及get_history的limit透传等场景。典型实战场景快速验证 API不确定某个UnityEditorAPI 的写法直接执行一段代码验证无需新建脚本、等待编译。批量只读查询统计场景/资源数据后return给 LLM 决策。临时修复对运行态数据做即时修补注意对资源的持久化修改推荐走manage_scriptable_object这类专用工具语义更安全。manage_scriptable_object基于 SerializedProperty 路径的 ScriptableObject 资产管理功能定位与设计理念manage_scriptable_object把 ScriptableObject 的创建 修改合并到一个工具中且修改走的是 Unity 原生SerializedObject/SerializedProperty路径而非反射见 ManageScriptableObject.cs 的注释。这意味着支持 Undo、属性变更可被 Inspector 正确识别、不依赖字段名的大小写/命名约定天然兼容序列化系统的各种规则。Unity 端在收到命令时首先检查EditorStateCache.GetActualIsCompiling() || EditorApplication.isUpdating处于编译/刷新状态会返回compiling_or_reloading错误并带hint retry客户端可据此稍后重试见 ManageScriptableObject.cs。参数总览参数类型必填说明actionLiteral[create, modify]是create 或 modifytype_namestr \| None—ScriptableObject 类型的完整命名空间限定名create 用folder_pathstr \| None—Assets/... 下的目标文件夹create 用asset_namestr \| None—资源文件名不含扩展名create 用overwritebool \| str \| None—为 true 时覆盖同路径已存在资源create 用targetdict \| str \| None—目标资源引用{guid \| path}modify 用patcheslist \| str \| None—补丁列表或 JSON 字符串。对象引用用{ref: {guid: ...}}或{value: {guid: ...}}Sprite 子资源需在 ref/value 对象中携带spriteName单精灵贴图可仅凭 guid/path 自动解析dry_runbool \| str \| None—为 true 时只校验不落地仅 modifycreate 动作创建 ScriptableObject 资源create需要type_name、folder_path、asset_name三个参数缺任一都会报invalid_params并做以下校验见 HandleCreateasset_name不得包含路径分隔符/或\folder_path会被规范化并确保文件夹存在不存在则自动创建type_name会被解析为实际类型且必须可赋值给ScriptableObject否则返回type_not_found。create同样可以携带patches在创建实例后立即应用属性补丁再保存资源实现一步建好并填好内容。此外 action 还兼容了createso/modifyso的别名经NormalizeAction归一化见 ManageScriptableObject.cs。modify 动作按属性路径打补丁modify通过target{guid}或{path}定位资源patches是核心参数。服务端 manage_scriptable_object.py 会先用parse_json_payload容忍 LLM 把复杂对象序列化成 JSON 字符串的情况target必须是对象、patches必须是数组否则直接报错再以typeName/folderPath/assetName/overwrite/target/patches/dryRun的驼峰键转发给 Unity。patch 结构每条补丁对象字段说明propertyPath也兼容property_path/path目标属性路径支持displayName、nested.field等点分路径op操作类型set默认或array_resizevalue要写入的值对象引用属性也接受ref键ref优先于value向后兼容例如把displayName设置为Hello的补丁[ { propertyPath: displayName, op: set, value: Hello } ]友好路径自动归一化写数组属性时Unity 内部路径格式是myList.Array.data[0]手工书写繁琐且易错。工具内置了NormalizePropertyPath见 ManageScriptableObject.csmyList[5]、nested.list[0].field这类中括号写法会自动转换为myList.Array.data[5]而已处于.Array.data[...]格式的路径则原样保留。数组操作set与array_resize批量 set当属性是数组/列表且value为 JSON 数组时TrySetValueRecursive 会先把arraySize调整为数组长度再逐个元素递归赋值支持部分成功返回Set 2/3 elements. ...。array_resize单独调整数组长度常用于先扩容再逐元素赋值的多步流程例如[ { propertyPath: materials.Array.size, op: array_resize, value: 2 } ]array_resize要求value为非负整数应用后立即ApplyModifiedProperties()并Update()保证后续补丁能基于新数组解析元素路径见 ApplyPatches。对象引用ref/value guid当目标属性是ObjectReference类型时赋值必须携带引用来源。推荐的写法是详见 ApplySet[ { propertyPath: someMaterial, op: set, value: { guid: 3f2a...c9d1 } } ]或使用旧的ref键优先于value{ propertyPath: ..., op: set, ref: { guid: 3f2a...c9d1 } }。ref/value也会被解析为纯字符串 GUID 的形态。引用解析实现在 ComponentOps.SetObjectReference 中它需要同时处理 guid、路径、fileID 以及 spriteName 子资源等形态见 ComponentOps.cs 附近注释。设置成功会返回Set reference to name.传 null 则清除引用。Sprite 子资源spriteName 与自动解析Sprite 通常作为贴图Texture导入资源的**子资源sub-asset**存在仅凭 guid/path 无法唯一确定引用哪个 Sprite。为此工具约定单精灵贴图仅凭guid/path即可自动解析精灵图集atlas或多精灵贴图必须在ref/value对象里携带spriteName[ { propertyPath: icon, op: set, value: { guid: 5b1a...e0ff, spriteName: coin } } ]实现会在目标资源中按名称查找匹配的Sprite子资源找不到时报Sprite name not found in atlas path.类型不匹配时报对应兼容性错误见 ComponentOps.cs。Generic 复杂对象映射对Generic类型的结构体/类字段如自定义可序列化类可直接传 JSON 对象做字段级递归映射见 TrySetValueRecursive例如{ propertyPath: settings, value: { volume: 0.8, loop: true } }。递归深度上限为 20防止循环引用导致的栈溢出。dry_run安全演练模式dry_runtrue仅 modify会进入 ValidatePatches 分支校验每条 patch 的属性路径是否存在、值类型是否兼容、array_resize的 value 是否为非负整数但不做任何写入。对AnimationCurve与Quaternion还会做格式校验通过 VectorParsing.ValidateAnimationCurveFormat / ValidateQuaternionFormat。每个 patch 返回{index, propertyPath, op, ok, message}形式的校验结果。这是 LLM 在不确定属性路径是否正确时最稳妥的探索手段——先 dry_run 验证再正式执行。变更落盘流程成功应用的补丁会按序执行所有 patch 处理完后统一so.ApplyModifiedProperties()、EditorUtility.SetDirty(target)、AssetDatabase.SaveAssets()见 ApplyPatches确保资源变更立即持久化到磁盘。Unity 处于编译/刷新状态时返回compiling_or_reloading并提示retry。测试佐证集成测试 Server/tests/integration/test_manage_scriptable_object_tool.py 覆盖了create 参数的透传、modify 时 patches 的转发含displayNameset 与materials.Array.sizearray_resize 两种形态、dry_run参数的转发以及 dry_run 以 JSON 字符串形式传入时的强制转换test_manage_scriptable_object_dry_run_string_coercion等场景可作为服务端如何把 LLM 的字符串化参数还原为结构化数据的参考。实战组合一条完整的脚本化工作流将两个工具串联可以在一次多轮对话中完成创建配置资源 → 批量填值 → 校验 → 落地的完整闭环createactioncreate、type_nameMyGameConfig、folder_pathAssets/Configs、asset_nameLevel01。dry_run 预演actionmodify、target{guid:...}、dry_runtrue先确认playerSettings.speed、levels.Array.size等路径无误。modify 落地携带完整 patches普通字段 set、数组 array_resize 后再逐元素赋值、对象引用{ref:{guid:...}}、精灵图集引用加spriteName正式执行。如需临时逻辑修补再配合execute_code执行一段只读/验证代码利用return获取反馈。安全边界与最佳实践小结execute_code不是沙箱文档execute_code.md与源码注释都明确警告safety_checks只是拦截已知危险模式高级绕过是可能的。仅在可信环境下对受信任的 LLM 开启并善用destructiveHint确认机制。优先专用工具涉及资源持久化、序列化属性修改时优先manage_scriptable_object原生 SerializedObject 路径 Undo 落盘把execute_code留给探索性与一次性验证任务。善用 dry_run 与 get_history不确定路径用dry_run探路执行出错用get_historyreplay找回可用版本。理解编译器差异需要 C# 12 现代语法时确保安装了 Microsoft.CodeAnalysisRoslyn安装引导可参考 website/docs/guides/roslyn.md 中关于USE_ROSLYN定义符号与Assets/Plugins/Roslyn/的说明仓库内另有独立的运行时编译演示组件 CustomTools/RoslynRuntimeCompilation/RoslynRuntimeCompiler.cs 可作参考。scripting_ext这两个工具共同构成了 unity-mcp 中让 AI 直接操作编辑器运行时与序列化数据的底层通道一个面向瞬时执行一个面向资源持久化配合core组的场景/资源管理工具可以覆盖绝大多数自动化游戏开发工作流。【免费下载链接】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），仅供参考