godot-material-manager

name: Godot Material Manager version: 1.0.0 description: 专业的Godot材质管理系统，支持StandardMaterial3D和ShaderMaterial的创建、配置、批量操作和性能优化，与Context7集成获取最新材质技术

Godot 材质管理技能

本技能为Godot开发者提供专业的材质创建和管理能力，支持StandardMaterial3D和ShaderMaterial的创建、配置、批量操作和性能优化，与Context7集成获取最新材质技术。

触发条件

需要创建或修改材质（StandardMaterial3D、ShaderMaterial）
提及"材质"、"material"、"着色器"、"Shader"
需要批量创建或修改多个材质
需要设置PBR材质属性（metallic、roughness、albedo等）
需要创建自定义ShaderMaterial
需要优化材质性能或减少Draw Call

核心功能

1. StandardMaterial3D 管理

创建PBR材质
配置基础颜色（albedo）、金属度（metallic）、粗糙度（roughness）
设置法线贴图、AO贴图、高度贴图
配置透明度和混合模式
设置UV缩放和偏移

2. ShaderMaterial 管理

创建ShaderMaterial并关联.gdshader文件
配置Shader参数
动态修改Shader uniform变量
Shader模板和复用

3. 批量材质操作

批量创建材质
批量修改材质属性
材质继承和变体创建
材质库管理

4. 性能优化

Draw Call优化建议
材质合并和图集使用
移动平台材质优化
Shader复杂度分析

执行步骤

创建 StandardMaterial3D

确定材质类型
- 不透明材质（Opaque）
- 透明材质（Transparency）
- 镂空材质（Alpha Scissor）
- 混合材质（Alpha Blend）
配置基础属性
- albedo_color: 基础颜色
- metallic: 金属度（0.0-1.0）
- roughness: 粗糙度（0.0-1.0）
- specular: 高光强度
设置纹理贴图
- albedo_texture: 颜色贴图
- normal_texture: 法线贴图
- roughness_texture: 粗糙度贴图
- metallic_texture: 金属度贴图
测试和调整
- 在场景中应用材质
- 调整光照查看效果
- 微调参数

创建 ShaderMaterial

编写或选择Shader
- 编写 .gdshader 文件
- 或使用现有的Shader模板
创建ShaderMaterial
- 创建 ShaderMaterial 资源
- 关联 .gdshader 文件
配置Shader参数
- 设置Shader的uniform变量
- 关联纹理参数
应用和测试
- 将材质应用到Mesh
- 运行场景查看效果

批量材质操作

选择目标材质
- 按路径模式匹配
- 或按材质类型筛选
定义操作
- 确定修改的属性
- 准备新值
执行批量修改
- 遍历所有匹配材质
- 应用修改
验证结果
- 检查修改后的材质
- 确保项目正常运行

代码示例

示例 1: 创建标准PBR材质

# 创建草地材质
claude godot create_standard_material --project_path="/mnt/d/godot-project" \
  --material_path="res://materials/ground_grass.tres" \
  --albedo_color="Color(0.2, 0.5, 0.2, 1)" \
  --roughness="0.9" \
  --metallic="0.0" \
  --albedo_texture="res://textures/grass_diffuse.png" \
  --normal_texture="res://textures/grass_normal.png"

示例 2: 创建ShaderMaterial

# 创建水面ShaderMaterial
claude godot create_shader_material \
  --material_path="res://materials/water.tres" \
  --shader_path="res://shaders/water.gdshader" \
  --shader_params='{
    "wave_speed": 1.5,
    "wave_height": 0.3,
    "color": "Vector3(0.1, 0.4, 0.8)"
  }'

示例 3: 批量修改材质属性

# 将所有材质的metallic设为0
claude godot batch_modify_materials --material_pattern="res://materials/*.tres" \
  --property="metallic" \
  --value="0.0"

示例 4: 创建材质变体

# 基于已有材质创建变体
claude godot create_material_variant \
  --base_material="res://materials/base_metal.tres" \
  --variant_path="res://materials/rusty_metal.tres" \
  --overrides='{
    "albedo_color": "Color(0.6, 0.4, 0.2, 1)",
    "roughness": "0.8"
  }'

示例 5: Godot场景设置材质（GDScript）

# 在脚本中创建并应用材质
func _ready():
    # 创建StandardMaterial3D
    var material = StandardMaterial3D.new()
    material.albedo_color = Color(1, 0, 0, 1)  # 红色
    material.metallic = 0.5
    material.roughness = 0.2

    # 应用到MeshInstance3D
    if self is MeshInstance3D:
        self.material_override = material

示例 6: ShaderMaterial动态参数

# 动态修改Shader参数
func update_shader_time(material: ShaderMaterial, time: float):
    if material and material.shader:
        material.set_shader_parameter("time", time)
        material.set_shader_parameter("color", Vector3(0.5, 0.8, 1.0))

最佳实践

✅ 应该做的

PBR原则
- metallic + roughness 总和应接近 1.0
- 真实材质参考物理参数
- 使用适当的高光（specular 0.0-1.0）
纹理使用
- 法线贴图使用正确的空间（OpenGL或DirectX）
- 纹理尺寸使用2的幂（256, 512, 1024...）
- UI纹理关闭过滤，设置为Nearest
移动平台优化
- 使用简单Shader，避免复杂计算
- 纹理压缩使用ETC2或ASTC
- 减少纹理采样次数
着色器优化
- 避免在fragment shader中复杂计算
- 预计算能移到vertex shader的内容
- 使用uniform而不是硬编码值
材质复用
- 创建基础材质，变体使用继承
- 相同属性的材质合并

❌ 不应该做的

过度使用透明材质
- 透明材质有排序性能开销
- 能用不透明+镂空（Alpha Scissor）的就不用透明
Shader中复杂分支
- 避免在shader中使用if-else
- 使用step、smoothstep等内置函数
过高纹理分辨率
- 根据显示尺寸选择纹理大小
- 移动端避免使用2K+纹理
运行时创建材质
- 预创建材质资源文件
- 运行时使用material.duplicate()创建实例
忽略性能分析
- 使用 Godot 的 Profiler
- 检查每帧的Draw Call数

Context7 集成

当创建材质时，自动使用 Context7 MCP 获取：

最新 Godot 材质系统文档
PBR参数最佳实践
Shader语言最新特性
性能优化建议

示例工作流程：

用户请求创建特定材质
触发 Context7 查询 Godot 材质文档
获取参数说明和示例代码
结合本技能生成完整材质
提供优化建议

MVP 模式

MVP（Minimum Viable Product）策略推荐：

如果项目对材质系统要求不高，可以：

创建少数几个基础材质（不透明、透明、发光）
使用 StandardMaterial3D 而非自定义Shader
适当使用纹理而非程序化纹理

示例MVP材质设置：

claude godot mvp_materials_setup --project_path="/mnt/d/game" \
  --create_basic_materials=true

版本控制

材质文件（.tres）应该：

提交到版本控制（文本格式）
使用相对路径引用纹理
避免硬编码的绝对路径

ShaderMaterial vs StandardMaterial3D

StandardMaterial3D 适用场景

常规PBR材质
不需要自定义效果
性能优先
快速迭代

ShaderMaterial 适用场景

特殊视觉效果（水面、熔岩、魔法）
需要动态参数
顶点动画
高级光照计算

常见问题

Q: 材质看起来太暗/太亮？

A: 检查albedo_color是否使用了纯白色（Color(1,1,1)），这会导致过曝。调整roughness和metallic值。

Q: 法线贴图看起来不对？

A: 检查法线贴图空间（OpenGL vs DirectX），在材质设置中调整Normal Map的Flip Y选项。

Q: 透明材质排序错误？

A: 在材质设置中调整Render Priority，或使用Alpha Scissor代替Alpha Blend。

Q: Shader编译错误？

A: 使用Context7查询Shader语法，确保uniform类型匹配，检查Shader Mode（Spatial, CanvasItem, Particle）。

性能监控

使用 Godot 的 Debugger Monitor 检查：

Draw Calls：每个材质至少增加1个Draw Call
Shader 编译时间
VRAM 使用量：纹理 + 材质