unity-mcp 的 manage_material 工具实战创建、着色与材质属性操作全指南【免费下载链接】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_material是 unity-mcp 中负责Unity 材质Material全生命周期操作的核心工具既能创建新材质、查询材质信息也能修改单个 Shader 属性、批量着色还能把材质或颜色直接应用到场景中任意 Renderer 上。本文以 manage_material 参考文档 为骨架结合 Python 工具注册层、CLI 命令层与 C# 实现层源码系统讲解其全部 action、参数语义、四种材质分配模式shared / instance / property_block / create_unique的底层区别与适用场景并给出可直接复制的 JSON 与命令行示例。一、工具定位一个入口七种动作manage_material归属于core工具组Python 侧注册模块为 services.tools.manage_materialUnity 编辑器侧的实际处理器是 MCPForUnity/Editor/Tools/ManageMaterial.cs标注了[McpForUnityTool(manage_material, AutoRegister false)]。它通过一个action参数分发到不同分支动作分为只读与修改两类类别action说明只读ping连通性测试返回pong及工具名只读get_material_info读取材质关联 Shader 及全部 Shader 属性的当前值修改create基于指定 Shader 创建新的.mat资产修改set_material_shader_property修改单个 Shader 属性颜色、浮点、纹理等修改set_material_color设置材质主颜色自动识别_BaseColor/_Color修改assign_material_to_renderer把已有材质资产赋给目标 GameObject 的指定材质槽修改set_renderer_color直接修改渲染器上显示的颜色支持四种模式在 C# 处理器中action被统一转为小写后经 switch 分发ManageMaterial.cs 第 25-50 行未知 action 会返回Unknown action: {action}错误任何异常都会被捕获并包装为带堆栈的错误响应。二、参数全解析参数类型必填说明actionLiteral[ping,create,set_material_shader_property,set_material_color,assign_material_to_renderer,set_renderer_color,get_material_info]是要执行的动作material_pathstr \| None视 action 而定材质资产路径Assets/...propertystr \| None视 action 而定Shader 属性名如_BaseColor、_MainTexshaderstr \| Nonecreate 时可选Shader 名称默认Standardpropertiesdict \| str \| Nonecreate 时可选初始属性字典{name: value}可传 JSON 字符串valuelist \| float \| int \| str \| bool \| Noneset_material_shader_property 时必填要设置的值颜色数组、浮点数、纹理路径/指令colorlist[float] \| dict[str,float] \| str \| Noneset 颜色类动作必填[r,g,b]或[r,g,b,a]数组、{r,g,b,a}对象或 JSON 字符串targetstr \| None涉及 GameObject 时必填目标对象名称、路径或查找指令search_methodLiteral[by_id,by_name,by_path,by_tag,by_layer,by_component] \| None否目标查找方式slotint \| None否材质槽索引0 起默认 0modeLiteral[shared,instance,property_block,create_unique] \| None否赋值/修改模式省略时由 Unity 侧按 action 决定默认行为2.1 Python 侧的参数清洗调用实际发送前Python 注册层manage_material.py 第 65-109 行会对参数做四层归一化这也是 LLM 传参容错的关键normalize_colorutils.py 第 269 行起统一输出[r,g,b,a]浮点数组。支持[r,g,b]/[r,g,b,a]列表、{r,g,b,a}对象、#RGB/#RRGGBB/#RRGGBBAA十六进制字符串以及 JSON 字符串若分量全大于 1 会按 0-255 归一化到 0-1。normalize_propertiesutils.py 第 100 行起把properties归一化为 dict拒绝[object Object]、undefined、null、等无效输入。parse_json_payload把字符串形式的value尝试解析为 JSON。coerce_int把slot转为 int。清洗失败会直接返回{success: false, message: ...}不会向 Unity 发送无效指令。2.2 Unity 侧路径归一化C# 处理器通过NormalizePathManageMaterial.cs 第 58-72 行做路径处理先经AssetPathUtility.SanitizeAssetPath统一分隔符并确保Assets/根前缀再自动补.mat扩展名——因此Materials/Red与Materials/Red.mat等价。create动作还会额外校验路径必须以Assets/开头防止写出工程目录。三、四大实战示例可直接复制以下示例均来自参考文档并补充了参数细节说明。3.1 从零创建一个红色材质创建Assets/Materials/Red.mat使用 Standard Shader基色为红色。{ action: create, material_path: Materials/Red.mat, shader: Standard, properties: { _Color: [1, 0, 0, 1] } }URP 项目请改用shader: Universal Render Pipeline/Lit与属性_BaseColor{ action: create, material_path: Materials/Red.mat, shader: Universal Render Pipeline/Lit, properties: { _BaseColor: [1, 0, 0, 1] } }底层实现要点ManageMaterial.cs 的CreateMaterial第 586-716 行Shader 解析走RenderPipelineUtility.ResolveShader解析失败会报Could not find shader防覆盖保护目标路径已存在材质资产时直接报错Material already exists at ...绝不静默覆盖properties支持 JSON 字符串或对象两种形态创建走AssetDatabase.CreateAsset后材质由 AssetDatabase 接管创建失败路径会DestroyImmediate临时对象避免内存泄漏属性应用由 MaterialOps.ApplyProperties 完成除了直接键值对还支持{shader: ...}、{color: {name, value}}、{float: {name, value}}、{texture: {name, path}}结构化写法。3.2 把已有材质赋给 GameObject将Assets/Materials/Red.mat应用到名为RedCube的对象上。{ action: assign_material_to_renderer, target: RedCube, search_method: by_name, material_path: Materials/Red.mat, slot: 0, mode: shared }实现上AssignMaterialToRenderer 第 197-244 行先按search_method解析目标 GameObject再取Renderer组件没有则报错随后把目标材质写入sharedMaterials[slot]并SetDirty。注意slot越界小于 0 或大于等于材质数组长度会返回Slot N out of bounds (count: M)mode: shared直接复用材质资产本身所有引用该资产的对象外观同时改变mode: instance会按渲染器克隆一份独立材质文档明确提示慎用会产生独立的材质实例并破坏合批 draw call。3.3 只修改一个 Shader 属性把Materials/Red.mat的_Metallic设为 0.8。{ action: set_material_shader_property, material_path: Materials/Red.mat, property: _Metallic, value: 0.8 }value的类型决定了底层转换路径MaterialOps.TrySetShaderProperty 第 207-340 行value 形态转换行为[r,g,b]/[r,g,b,a]数组尝试SetColor失败再尝试SetVector[x,y]数组尝试SetVectorVector2浮点 / 整数SetFloat布尔转为 1.0 / 0.0 浮点含/的字符串当作资产路径LoadAssetAtPath后SetTexture{find: ...}/{method: ...}对象按查找指令解析纹理后SetTexture3.4 不改共享材质、只给渲染器染色用 MaterialPropertyBlock 把立方体 MeshRenderer 染成蓝色不触碰共享材质资产。{ action: set_renderer_color, target: RedCube, search_method: by_name, color: [0, 0, 1, 1], mode: property_block }property_block模式SetRendererColor 第 291-330 行会先renderer.GetPropertyBlock(block, slot)取出当前块再按材质实际支持的属性写入_BaseColor/_Color最后SetPropertyBlock回写。该模式不创建任何材质实例克隆直接作用于渲染器级覆盖因此不会破坏合批是给某个对象单独换色的首选。四、mode 四模式深度对比set_renderer_color与assign_material_to_renderer共用同一套 mode 语义四者差异直接决定渲染性能与资源持久性mode资源形态是否持久影响范围典型场景shared修改共享材质资产持久改动落盘到 .mat所有引用该材质的对象全局调色、批量改观感instance按渲染器克隆材质renderer.materials[slot]运行期仅当前对象但产生新实例需要独立材质参数的对象property_blockMaterialPropertyBlock 覆盖无新资产随场景保存资产不变仅当前渲染器单对象染色、保留合批create_unique为对象新建独立.mat资产并赋值持久新资产落盘仅当前对象需要可复用独立材质的对象关于create_unique的实现细节CreateUniqueAndAssign 第 407-467 行材质路径按{场景目录}/Materials/{对象名}_{InstanceID}_mat.mat推导场景未保存或不在Assets/下时回退到Assets/Materials同名材质已存在如重试会复用并仅更新颜色Shader 通过RenderPipelineUtility.ResolveShader(Standard)按当前渲染管线解析。也就是说它对每个对象生成一个独立、持久、可复用的材质文件。set_renderer_color四种模式与set_material_color直接改材质资产的取舍可总结为一句口诀要落盘改共享要独立建资产要临时保合批用 property_block实例化只在运行期需要时用。五、颜色参数与属性别名的容错设计5.1 颜色格式color参数兼容四种输入参考文档与 utils.py 共同确认[r, g, b]或[r, g, b, a]数组缺 a 默认 1.0{r, g, b, a}对象JSON 字符串[1, 0, 0, 1]或{\r\:1,\g\:0,\b\:0}十六进制字符串#RGB/#RRGGBB/#RRGGBBAA。所有格式最终归一化为 0-1 浮点分量分量 1 时自动按 0-255 换算C# 侧再由 MaterialOps.ParseColor 统一解析。5.2 属性别名内置 shader 名称随渲染管线差异巨大MaterialOps.ResolvePropertyNameMaterialOps.cs 第 160-184 行为此提供别名归一化LLM 无需记忆各管线具体命名别名候选属性按序探测_Color_Color→_BaseColor_BaseColor_BaseColor→_Color_MainTex_MainTex→_BaseMap_BaseMap_BaseMap→_MainTex_Glossiness/_Smoothness_Glossiness↔_Smoothness互备metallic_Metallicsmoothness_Smoothness→_Glossinessalbedo_BaseMap→_MainTex同时set_material_color未指定property时会自动探测_BaseColorURP/HDRP→_Color内置管线的优先级写入ManageMaterial.cs 第 169-183 行create阶段的颜色参数同样遵循该回退逻辑。5.3 get_material_info 的能力get_material_info返回材质名、Shader 名及全部属性的当前值ManageMaterial.cs 第 469-584 行。属性按类型给出结构化值Color →{r,g,b,a}、Vector →{x,y,z,w}、Float/Range → 数值、Texture → 纹理名。同时兼容 Unity 6000 的shader.GetPropertyCount()新 API 与旧版ShaderUtil.GetPropertyCount()具备双版本条件编译。六、CLI 命令行入口除了通过 MCP 协议调用manage_material在 CLI 中也有完整镜像命令定义于 Server/src/cli/commands/material.py# 查询材质信息 unity-mcp material info Assets/Materials/Red.mat # 创建材质默认 Standard Shader unity-mcp material create Assets/Materials/NewMat.mat unity-mcp material create Assets/Materials/Red.mat --shader Universal Render Pipeline/Lit unity-mcp material create Assets/Materials/Blue.mat --properties {_Color: [0,0,1,1]} # 设置颜色RGBA 四个位置参数默认 _Color 属性 unity-mcp material set-color Assets/Materials/Red.mat 1 0 0 unity-mcp material set-color Assets/Materials/Mat.mat 1 1 0 --property _BaseColor # 设置任意 Shader 属性value 会先尝试按 JSON 解析 unity-mcp material set-property Assets/Materials/Mat.mat _Metallic 0.5 unity-mcp material set-property Assets/Materials/Mat.mat _MainTex Assets/Textures/Tex.png # 赋材质给对象 unity-mcp material assign Assets/Materials/Red.mat Cube unity-mcp material assign Assets/Materials/Blue.mat Player --mode instance unity-mcp material assign Assets/Materials/Mat.mat -81840 --search-method by_id --slot 1 # 直接改渲染器颜色默认 property_block 模式 unity-mcp material set-renderer-color Cube 1 0 0 unity-mcp material set-renderer-color Player 0 1 0 --mode instance几个值得注意的 CLI 细节set-color的--property默认_Color内置管线直接用即可assign的--mode默认sharedset-renderer-color的--mode默认property_blockCLI 帮助文本特别说明需要持久的每对象材质请用create_uniquesearch-method使用SEARCH_METHOD_CHOICE_RENDERER约束与工具参数枚举保持一致执行成功会额外输出Created material: .../Assigned material to: ...等成功提示。Python 侧调用形式可参考 unity-mcp-skill/references/tools-reference.md其中给出了与本文 JSON 示例一一对应的manage_material(...)函数式写法。七、返回结构与错误处理工具返回dict具体结构随 action 变化但遵循统一约定成功{success: true, message: ..., data: {...}}如Set property _Metallic on Red、Created material at Assets/Materials/Red.mat with shader Standard失败{success: false, message: ...}message 为具体原因。常见可预期的错误路径均由源码确认场景返回消息缺少actionAction is required未知 actionUnknown action: {action}材质不存在Could not find material at path: ...目标对象不存在Could not find target GameObject: ...对象无 RendererGameObject {name} has no Renderer componentslot 越界Slot N out of bounds (count: M)创建时路径已存在Material already exists at ...Shader 找不到Could not find shader: ...路径不在 Assets 内Invalid path .... Path must be within Assets/ folder.颜色格式非法Invalid color format: ...Python 注册层manage_material.py 第 103-109 行通过send_with_unity_instance走统一的重试与实例路由机制返回值非 dict 时也会兜底包装为失败响应。八、测试佐证与最佳实践EditMode 测试 ManageMaterialTests.cs 覆盖了本文涉及的核心路径可作为行为契约参考SetMaterialShaderProperty_SetsColor验证set_material_shader_property在 URP_BaseColor与内置管线_Color下均能正确写色SetMaterialColor_SetsColorWithFallback验证未指定property时的自动回退逻辑AssignMaterialToRenderer_Works验证按名字查找 赋值后sharedMaterial.name与资产一致SetRendererColor_PropertyBlock_Works验证 property_block 写入后GetPropertyBlock能读回颜色且不动共享材质GetMaterialInfo_ReturnsProperties验证返回的properties数组包含_Color/_BaseColor属性。仓库中还有 ManageMaterialPropertiesTests.cs、ManageMaterialStressTests.cs 等更多用例覆盖属性批量写入与压力场景。实战建议汇总跨管线兼容URP/HDRP 项目统一用_BaseColor与Universal Render Pipeline/Lit内置管线用_Color与Standard不确定时依靠工具的自动回退与别名机制。批量对象单独调色优先property_block绝不产生实例克隆合批不受影响。需要持久独立材质用create_unique材质文件自动落在场景目录旁的Materials/下命名含对象名与 InstanceID可重复调用不产生重复资产。全局改观感shared模式直接改共享资产改动会同步到所有引用对象并落盘改前注意影响面。先查询再修改面对不熟悉的 Shader先get_material_info拿到属性名与当前值再决定写哪个属性能显著减少试错。路径写法material_path以Assets/为根可省略.mat后缀但必须是Assets/内部路径。延伸阅读manage_material 参考文档本文档源含自动生成的参数表与示例Python 工具注册实现参数清洗与发送链路C# 编辑器处理器七种 action 的完整实现MaterialOps 辅助类属性别名与值转换底层逻辑材质 CLI 命令命令行操作入口工具参考SkillPython 函数式调用示例EditMode 测试行为契约与回归保障【免费下载链接】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），仅供参考