unity-mcp 的 manage_shader 工具在 Unity 中通过 MCP/CLI 完成 Shader 的增删改查【免费下载链接】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_shader是 unity-mcp 项目中vfx工具组的一员它为 AI 助手和命令行用户提供了一套完整的 Shader 资产管理能力在不离开编辑器上下文的情况下直接创建、读取、更新和删除.shader文件。本文将围绕该工具的参数契约、服务端调用链、Unity 侧 CRUD 实现以及 CLI 封装展开帮助你理解并实战运用这一工具——无论是让 LLM 生成自定义着色器还是在终端脚本里批量管理 Shader 资产都能直接复用文中的命令与代码示例。工具概览注册信息与所属模块manage_shader在仓库中的正式文档位于 website/docs/reference/tools/vfx/manage_shader.md其中标注了它的核心元数据Group工具组vfxModule服务端模块services.tools.manage_shader核心语义对 Unity 中的 Shader 脚本执行 CRUD 操作create / read / update / delete值得注意的是该文档明确区分了动作的危险级别read是只读动作create、update、delete均为修改性动作。这一区分在服务端注解中也有体现——Python 侧通过ToolAnnotations(destructiveHintTrue)声明了工具的破坏性特征见 Server/src/services/tools/manage_shader.py客户端与 CLI 可据此决定是否弹确认提示。工具的 Unity 侧实现类为ManageShader通过特性[McpForUnityTool(manage_shader, AutoRegister false, Group vfx)]声明注册源码位于 MCPForUnity/Editor/Tools/ManageShader.cs。参数契约四个参数构成完整的 CRUD 入口依据工具文档manage_shader共暴露四个参数参数名类型必填说明actionLiteral[create, read, update, delete]是对 Shader 脚本执行的 CRUD 操作namestr是Shader 名称不含扩展名pathstr是资产路径默认Assets/contentsstr \| None—用于create/update的 Shader 代码对照 Unity 侧实现 ManageShader.cs可以确认以下解析与校验细节action 归一化Unity 端会将传入的action统一转为小写后分发ToLowerInvariant()因此大小写混合的调用也能正确路由。name 正则校验name必须匹配^[a-zA-Z_][a-zA-Z0-9_]*$即只能包含字母、数字和下划线且不能以数字开头否则直接返回ErrorResponse。这保证了生成的 Shader 名在 Unity/CG 语法中合法。path 的归一化规则path被视为相对Assets/的目录。源码会先规范化分隔符、去掉首尾/若传入Assets或Assets/xxx则自动剥离Assets/前缀当path为空或省略时默认落到Shaders目录见 ManageShader.cs。提示最终磁盘路径为Assets/path/name.shader文件扩展名固定为.shader而非文档中名称注释所写的.cs。此外Unity 侧还支持一个文档未列出的内部参数contentsEncoded/encodedContents当服务端检测到 Shader 代码较长时会先将contents做 base64 编码后随encodedContents一起传输避免 JSON 转义问题详见下文大内容传输一节。完整调用链从 MCP 工具到 Unity 编辑器manage_shader的完整数据流横跨 Python 服务端与 Unity 编辑器两侧典型调用链如下AI 客户端 / CLI │ JSON-RPC 请求 manage_shader ▼ Server/src/services/tools/manage_shader.py │ base64 编码 contentscreate/update 时 │ get_unity_instance_from_context(ctx) 解析当前 Unity 实例 ▼ transport.unity_transport.send_with_unity_instance(...) │ 经 stdio/HTTP 桥接转发 ▼ MCPForUnity/Editor/Tools/ManageShader.cs HandleCommand() │ AssetDatabase 读写 .shader 文件 ▼ 成功/失败响应原路返回服务端入口 Server/src/services/tools/manage_shader.py 的关键职责有三实例路由通过get_unity_instance_from_context(ctx)从会话状态中解析当前活跃的 Unity 实例支持多开场景下的实例隔离。内容编码仅当action为create/update时才将contents做base64.b64encode并置入encodedContents字段、置contentsEncoded True其他情况下直接透传contents且发送前会剔除值为None的键。响应解码若 Unity 返回的data中带有contentsEncoded标记则服务端将encodedContents解码回明文contents后再返回给调用方保证读取大文件时传输可靠、输出可读。发送环节统一走send_with_unity_instance(async_send_command_with_retry, ...)即带重试机制的集中式发送辅助函数见 Server/src/services/tools/manage_shader.py出现连接波动时会自动重试Python 侧异常也会被捕获并包装为{success: False, message: Python error managing shader: ...}返回。四种动作的 Unity 侧实现细节Unity 端的HandleCommand按action分发到四个私有方法ManageShader.cs下面逐一说明其行为与边界。create创建 Shader 资产CreateShaderManageShader.cs的流程如下存在性检查若Assets/path/name.shader已存在返回错误并提示改用update。重名检查调用Shader.Find(name)检查项目内是否已注册同名 Shader避免创建同名冲突资产。默认内容生成未提供contents时自动生成一个基于 CGPROGRAM 的基础模板包含_MainTex贴图属性、vert/frag顶点-片元着色函数见GenerateDefaultShaderContentManageShader.cs。落盘与刷新以 UTF-8无 BOM写入文件随后AssetDatabase.ImportAssetAssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport)同步刷新资源数据库确保 Unity 立即识别新 Shader。若目标目录不存在create/update 前会自动Directory.CreateDirectory并同步刷新ManageShader.cs。read读取 Shader 内容ReadShaderManageShader.cs读取文件全文并返回path资产的相对路径contents明文 Shader 代码大文件保护当内容超过 10000 字符时额外返回encodedContentsbase64 编码版本并置contentsEncoded true由服务端解码后覆盖明文返回。源码中对该阈值留有 TODO 注释说明将来可能改为可配置项。update更新已有 ShaderUpdateShaderManageShader.cs要求目标文件必须存在且contents不能为空为空直接报错。写入逻辑与 create 一致UTF-8 无 BOM AssetDatabase 同步刷新。delete删除 Shader 资产DeleteShaderManageShader.cs优先调用AssetDatabase.DeleteAsset(relativePath)走 Unity 资产删除管线若返回失败则报错若文件仍残留罕见情况再做一次文件级删除兜底。大内容传输机制base64 编码的底层原理从调用链可以看出该项目对 Shader 这类可能较长的代码文本做了专门的传输优化写方向客户端 → UnityPython 服务端在 create/update 时把contentsbase64 编码后放入encodedContents规避 JSON 字符串中的引号、换行、反斜杠等转义问题manage_shader.py。读方向Unity → 客户端Unity 在内容超过 10000 字符时返回编码版本服务端解码为明文后交付manage_shader.py。这一机制对 MCP 传输层尤其重要Shader 代码常包含...字符串、\n转义与花括号未经编码时极易在 JSON 序列化/反序列化中失真。CLI 封装shader 子命令实战除了通过 MCP 客户端调用仓库还提供了完整的命令行封装unity-mcp shader实现于 Server/src/cli/commands/shader.py四个子命令与工具动作一一对应。读取 Shaderunity-mcp shader read Assets/Shaders/MyShader.shader命令内部从路径中提取文件名去扩展名作为name、目录作为path调用manage_shader的read动作成功后直接把 Shader 源码打印到终端shader.py。创建 Shader# 使用默认 Shader 模板无内容时自动生成标准表面着色器 unity-mcp shader create MyShader --path Assets/Shaders # 从本地文件读取着色器代码 unity-mcp shader create MyShader --file local_shader.shader # 通过 stdin 管道传入代码 echo Shader code... | unity-mcp shader create MyShader其中--path默认值为Assets/Shaders与 Unity 侧的默认目录Shaders呼应。当既未指定--contents也未指定--file且 stdin 为终端TTY时CLI 会生成一个含_Color、_MainTex属性与surf函数的 Standard 表面着色器模板shader.py。更新 Shaderunity-mcp shader update Assets/Shaders/MyShader.shader --file updated.shader echo New shader code | unity-mcp shader update Assets/Shaders/MyShader.shader更新要求提供新的代码--contents、--file或 stdin 三选一否则报错退出shader.py。删除 Shader# 删除前会弹确认提示 unity-mcp shader delete Assets/Shaders/OldShader.shader # 跳过确认直接删除 unity-mcp shader delete Assets/Shaders/OldShader.shader --force删除操作默认调用confirm_destructive_action做破坏性操作确认--force可跳过shader.py。测试与工具注册一致性在工具对称性测试 Server/tests/test_tool_test_symmetry.py 中manage_shader被列为需要校验的工具之一用于确保 MCP 工具注册表、文档生成与 Unity 侧实现三者的命名与元数据保持一致这类测试由 tools/generate_docs_reference.py 驱动的文档生成流程配套维护——这也是为什么 manage_shader.md 标注了 Auto-generated 并保护!-- examples:start --注释块的原因。Unity 侧ManageShader在 TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/CommandRegistryTests.cs 中被引用属于 EditMode 工具注册测试覆盖范围。常见错误与处理策略综合源码中的错误分支调用manage_shader时可能遇到以下情形场景行为action为空或非法值返回 Action parameter is required. 或 Unknown action 错误name为空或含非法字符正则校验失败返回命名规则提示create 时文件已存在报错并提示改用 updatecreate 时同名 Shader 已在项目注册Shader.Find命中报错要求更换名称read/update/delete 时文件不存在返回 Shader not found 错误update 未提供 contents返回 Content is required 错误目录创建失败、文件读写异常捕获异常并返回含异常消息的错误响应总结manage_shader是 unity-mcp 中实现AI 直接管理 Unity Shader 资产能力的完整闭环服务端负责参数整形、base64 编码与实例路由manage_shader.pyUnity 端负责文件 CRUD、命名校验与 AssetDatabase 刷新ManageShader.csCLI 则提供了unity-mcp shader子命令便于脚本化使用shader.py。无论你是想让 LLM 依据描述直接生成并落地一个着色器文件还是在 CI 流程中批量同步 Shader 代码都可以基于上文四个动作的参数契约与命令示例直接上手。【免费下载链接】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），仅供参考