unity-shader

**调用此模块中的任何技能之前：**如果你打算根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可以直接进行 dryRun。

触发条件

• 创建或编辑手写着色器
• 列出或查找 .shader 文件
• 检查属性/关键字
• 创建或编辑手写 shader、列出/查找 .shader 文件、检查属性与关键字

Unity 着色器技能

处理 .shader HLSL/ShaderLab 文件（从模板创建、读取源代码、列出、查找、获取关键字/属性/变体、检查错误、删除、切换全局关键字）。对于基于节点的 ShaderGraph，请使用 shadergraph 模块。

操作模式

• 查询技能（shader_read、shader_list、shader_find、shader_get_properties、shader_check_errors、shader_get_keywords、shader_get_variant_count）属于 SkillMode.SemiAuto——无需授权即可在所有三种模式下运行。
• 修改技能（shader_create、shader_create_urp、shader_set_global_keyword）属于 SkillMode.FullAuto——在 Approval 模式下需要用户授权（授权会触发一次服务器端执行并返回结果）；在 Auto / Bypass 模式下会直接执行。
• shader_delete 带有 SkillOperation.Delete，在 Approval / Auto 模式下会被自动禁止（NeverInSemi）。只有 Bypass 或用户管理的 Allowlist 可以运行它。

防护措施

请勿（常见幻觉）：

• shader_set_property 不存在 → 请对材质使用 material_set_float/material_set_color/等，而非对着色器使用
• shader_apply / shader_assign 不存在 → 请使用 material_set_shader 更改材质的着色器
• shader_get_properties 返回的是着色器属性定义（名称/类型/范围），而非当前值 → 若要获取材质实例值，请使用 material_get_properties
• 着色器名称区分大小写且类似路径："Standard"、"Universal Render Pipeline/Lit"，而非 "standard" 或 "URP Lit"

路由：

• 更改材质属性 → 使用 material 模块
• 控制着色器关键字 → 使用 material 模块中的 material_set_keyword
• 控制全局着色器关键字 → 使用此模块中的 shader_set_global_keyword

技能概览

技能	描述
shader_create	创建着色器文件
shader_read	读取着色器源代码
shader_list	列出所有着色器
shader_find	按名称查找着色器
shader_delete	删除着色器文件
shader_get_properties	获取着色器属性
shader_check_errors	检查着色器是否存在编译错误
shader_get_keywords	获取着色器关键字列表
shader_get_variant_count	获取着色器变体数量，用于性能分析
shader_create_urp	从模板创建 URP 着色器
shader_set_global_keyword	启用或禁用全局着色器关键字

---

技能

shader_create

创建着色器文件。template 参数是原始着色器源代码，会原样写入 .shader 文件——它不是预设名称。如果传入 template="Standard"，字面字符串 Standard 将被写入磁盘，着色器也将无法编译。

参数	类型	必填	默认值	描述
shaderName	string	是	-	写入 Shader "..." 声明的着色器名称（例如："Custom/MyShader"）
savePath	string	是	-	保存路径（例如："Assets/Shaders/My.shader"）
template	string	否	null	完整的 ShaderLab/HLSL 源代码字符串。省略时，将使用内置的**无光照（Unlit）**模板（_MainTex + _Color，单个 CGPROGRAM 通道）。没有其他内置预设。

如需 URP 无光照 / Lit 预设，请改用 shader_create_urp（type: "Unlit" | "Lit"）——它会按名称选择模板。

shader_read

读取着色器源代码。

参数	类型	必填	描述
shaderPath	string	是	着色器资源路径

返回：{path, lines, content}

shader_list

列出项目中的所有着色器。

参数	类型	必填	默认值	描述
filter	string	否	null	名称筛选条件
limit	int	否	100	最大结果数

返回：{count, shaders: [{path, name, propertyCount}]}

shader_find

按名称查找着色器。

参数	类型	必填	描述
searchName	string	是	要查找的着色器名称

返回：{found, name, path}

shader_delete

删除着色器文件。

参数	类型	必填	描述
shaderPath	string	是	着色器资源路径

shader_get_properties

获取着色器中定义的所有属性。

参数	类型	必填	描述
shaderNameOrPath	string	是	着色器名称或着色器资源路径

返回：{success, shaderName, propertyCount, properties: [{name, type, description}]}

shader_check_errors

检查着色器是否存在编译错误。

参数	类型	必填	默认值	描述
shaderNameOrPath	string	是	-	着色器名称或资源路径（例如："Custom/MyShader" 或 "Assets/Shaders/My.shader"）

返回： { shaderName, hasErrors, messageCount }

shader_get_keywords

获取着色器关键字列表。

参数	类型	必填	默认值	描述
shaderNameOrPath	string	是	-	着色器名称或资源路径（例如："Custom/MyShader" 或 "Assets/Shaders/My.shader"）

返回： { shaderName, keywordCount, keywords: [{ name, type }] }

shader_get_variant_count

获取着色器变体数量，用于性能分析。

参数	类型	必填	默认值	描述
shaderNameOrPath	string	是	-	着色器名称或资源路径（例如："Custom/MyShader" 或 "Assets/Shaders/My.shader"）

返回： { shaderName, subshaderCount, totalPasses }

shader_create_urp

根据模板创建 URP 着色器（类型：Unlit 或 Lit）。

参数	类型	必填	默认值	描述
shaderName	string	是	-	着色器名称（例如："Custom/MyURPShader"）
savePath	string	是	-	保存路径（例如："Assets/Shaders/MyURP.shader"）
type	string	否	"Unlit"	模板类型："Unlit" 或 "Lit"

返回： { success, shaderName, path, type }

shader_set_global_keyword

启用或禁用全局着色器关键字。

参数	类型	必填	默认值	描述
keyword	string	是	-	全局着色器关键字名称
enabled	bool	是	-	true 表示启用，false 表示禁用

返回： { success, keyword, enabled }

---

使用示例

import unity_skills

# Create an unlit shader
unity_skills.call_skill("shader_create",
    shaderName="Custom/MyUnlit",
    savePath="Assets/Shaders/MyUnlit.shader",
    template="Unlit"
)

# Create a surface shader
unity_skills.call_skill("shader_create",
    shaderName="Custom/MyPBR",
    savePath="Assets/Shaders/MyPBR.shader",
    template="Standard"
)

# Read shader source
source = unity_skills.call_skill("shader_read",
    shaderPath="Assets/Shaders/MyUnlit.shader"
)
print(source['content'])

# List all custom shaders
shaders = unity_skills.call_skill("shader_list", filter="Custom")
for shader in shaders['shaders']:
    print(f"{shader['name']}: {shader['path']}")

最佳实践

1. 使用一致的着色器命名方式（Category/Name）
2. 将着色器整理到专用文件夹中
3. 从模板开始，并根据需要修改
4. 在不同光照条件下测试着色器
5. 构建时考虑移动设备兼容性

---

精确签名

确切的名称、参数、默认值和返回值以 GET /skills/schema 或 unity_skills.get_skill_schema() 定义为准，而非此文件。