blender-shader-nodes

Blender 着色器节点专家

概述

此技能为 Blender 5.x 着色器节点提供专家指导：设计材质设置、编写 Python 脚本以编程方式构建着色器节点树、了解渲染引擎差异（Cycles 与 EEVEE），以及访问完整的着色器节点目录。包含 5.0 和 5.1 的变更（Raycast 节点、Normal Map 的 OpenGL/DirectX 切换、OpenColorIO 2.5）。

MCP 优先方案

创建材质、连接着色器节点树，以及直接在运行中的 Blender 会话里采样视口渲染时，优先使用官方 Blender MCP Server（Blender Lab，Blender 5.1+）。仅当 MCP 服务未连接时，才回退为输出 Python 脚本。

**检测：**在会话开始时，查找名称与 execute_blender_code、get_objects_summary 或 search_api_docs 匹配的工具——这些工具属于官方 blender-mcp 服务。如果其中任意工具存在，即表示 MCP 可用。

此技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 在修改前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 清点文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 在调用前确认正确的 API／操作符名称
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉结果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操作 UI，让更改可见
• render_thumbnail_to_path、render_viewport_to_path — 获取快速视觉反馈

**工作流：**使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持简短且幂等，以便轻松定位故障。

设置说明：参见 docs/blender-mcp-setup.md。

任务决策树

• “为 X 创建材质” -> 确定材质类型，设计节点树，生成 Python 代码（参见“材质方案”）
• “我的材质看起来不对” -> 按照调试工作流处理
• “X 对应什么节点？” -> 查阅 references/node_reference.md
• “设置世界光照 / HDRI” -> 参见 Python API 参考中的“世界／环境”模式
• “编写着色器节点树脚本” -> 查阅 references/python_api.md 了解 API 模式
• “Cycles 和 EEVEE 哪个更好？” -> 查看 node_reference.md 中的渲染引擎兼容性部分

生成着色器节点树

通过 Python 创建材质时：

1. 阅读 references/python_api.md，了解正确的 API 模式和节点类型字符串
2. 按照以下模式组织脚本：
   • 使用 use_nodes = True 创建材质
   • 清除默认节点
   • 添加所有节点，并使用正确的类型字符串
   • 从左到右排列节点（x 间距约为 300，y 间距约为 200）
   • 设置输入的默认值
   • 创建节点之间的所有连接
   • 将材质指定给目标对象
3. 使用 Frame 节点将复杂设置整理为逻辑分区

节点类型字符串约定

• 大多数着色器节点：ShaderNode<PascalCaseName>（例如，ShaderNodeBsdfPrincipled、ShaderNodeTexNoise）
• 几何输入：ShaderNodeNewGeometry（不是 ShaderNodeGeometry）
• 颜色属性：ShaderNodeVertexColor
• Mix 节点：ShaderNodeMix，并将 data_type 设为 'RGBA'、'FLOAT' 或 'VECTOR'
• Color Ramp：ShaderNodeValToRGB
• 不确定确切的类型字符串时，请查阅 references/python_api.md

材质方案

PBR 材质（基于纹理）

1. Texture Coordinate -> Mapping -> Image Texture(s) -> Principled BSDF -> Material Output
2. 连接贴图：Base Color（sRGB）、Roughness（Non-Color）、Metallic（Non-Color）、Normal Map（Non-Color）-> Normal Map 节点 -> Normal 输入
3. 将非颜色图像设为 image_tex.image.colorspace_settings.name = 'Non-Color'

程序化材质

1. Texture Coordinate -> Noise/Voronoi/Wave Texture -> Color Ramp -> Principled BSDF
2. 使用 Mix 节点叠加多种纹理，增加复杂度
3. 对 Texture Coordinate 使用 Separate XYZ，创建依赖轴向的图案

玻璃 / 透明材质

1. Principled BSDF 的 Transmission Weight = 1.0、Roughness = 0.0（清澈）或 >0（磨砂），IOR = 1.45-1.52
2. 另一种方法：使用 Glass BSDF 节点，设置更简单
3. EEVEE：在材质和渲染设置中启用 Screen Space Refraction

金属

1. Principled BSDF 的 Metallic = 1.0、Base Color = 金属色调（金色：1.0, 0.766, 0.336）、Roughness = 0.1-0.4
2. 另一种方法（5.0）：使用 Metallic BSDF 节点，实现物理上准确的复杂 IOR
3. 添加指纹/划痕：将 Roughness 与程序化纹理混合

皮肤 / 次表面散射

1. Principled BSDF 的 Subsurface Weight = 0.3-1.0、Subsurface Radius = (1.0, 0.2, 0.1)，用于 RGB 散射
2. 将皮肤纹理连接到 Base Color，将细节法线贴图连接到 Normal
3. Cycles：使用 Random Walk 方法获得最佳质量

自发光 / 霓虹

1. 将 Principled BSDF 的 Emission Color 设为所需颜色，Emission Strength 设为 1-50+
2. 或者：Standalone Emission 节点 -> Material Output（Surface）
3. 在渲染设置（EEVEE）中启用 Bloom，获得辉光效果

卡通 / 色调着色（EEVEE）

1. Principled BSDF（或任意 BSDF）-> Shader to RGB -> Color Ramp（Constant 插值）-> Material Output（通过 Emission 或自定义输出）
2. Color Ramp 色标可创建离散的着色带
3. Shader to RGB 仅适用于 EEVEE

世界 / HDRI 环境

1. Environment Texture（加载 .exr/.hdr）-> Background -> World Output
2. 在 Texture Coordinate（Generated）与 Environment Texture 之间添加 Mapping 节点，以旋转环境
3. 设置 Background Strength 来调整强度

置换

1. Texture -> Displacement 节点 -> Material Output（Displacement 插槽）
2. 设置材质置换方法：mat.cycles.displacement_method = 'BOTH' 96#HB|3. 网格需要细分（Subdivision Surface 修改器或 Cycles 中的 Adaptive Subdivision）

Raycast 节点（Blender 5.1）

1. ShaderNodeRaycast 从着色点发射射线并返回命中信息
2. 输出：Position、Normal、Distance、Object、Is Hit
3. 适用于材质驱动的接近效果、遮挡和交叉检测
4. 支持指定射线方向和长度限制
5. 在 Cycles 和 EEVEE 中均可使用

法线贴图改进（Blender 5.1）

1. 新增 OpenGL/DirectX 开关，用于设置法线贴图的切线空间约定
2. OpenGL（默认）与 DirectX 翻转 — 修复来自游戏引擎的反向法线贴图
3. 新增在置换网格上计算法线贴图的选项（仅限 Cycles）
4. 使用 normal_map_node.invert_y 或 normal_map_node.tangent_space_convention 进行切换

体积（雾/烟）

1. Principled Volume -> Material Output（Volume 插槽）
2. 或者：Volume Absorption + Volume Scatter -> Add Shader -> Material Output（Volume）
3. 设置 Density、Color、Anisotropy

调试与优化

常见视觉问题

• 材质显示为黑色：检查 Material Output 是否有有效的 Surface 连接。如果纹理需要 UV 坐标，请确认对象具有 UV 坐标
• 材质显示为白色/平面：纹理连接缺失，或所有纹理都设置了错误的色彩空间
• 玻璃/透明效果在 EEVEE 中无效：在渲染设置和材质设置中都启用 Screen Space Refraction。将混合模式设为 Alpha Hashed 或 Alpha Blend
• 法线贴图看起来凹凸不平/不正确：确保法线贴图图像的色彩空间设为 Non-Color。检查 Normal Map 节点是否设为正确的空间（大多数情况下为 Tangent）
• 纹理拉伸：对象需要正确展开 UV。或者，使用 Object 或 Generated 纹理坐标，并配合 Mapping 节点
• Cycles 渲染出现亮点噪声：减少光线反弹次数，在渲染设置中使用 Clamp Direct/Indirect，或进行降噪

性能提示

1. 优先使用 Principled BSDF，而非单独着色器：Principled BSDF 在内部经过优化；手动组合 Diffuse、Glossy 和 Glass 的速度较慢
2. 尽量降低纹理分辨率：大多数情况下使用 2K 纹理，仅在需要近距离细节时使用 4K
3. 避免堆叠过多 Noise Texture：每次噪波计算都很耗费资源。对于动画，请烘焙复杂的程序化纹理
4. EEVEE 屏幕空间效果：屏幕空间反射、折射和 SSS 会增加每种材质的开销。仅在材质需要时启用
5. 简化视口效果：在视口预览模式下使用较低分辨率的纹理或较简单的着色器

EEVEE 与 Cycles 快速指南

特性	Cycles	EEVEE
渲染	路径追踪（精确）	光栅化（快速、近似）
SSS	随机漫步（精确）	屏幕空间（近似）
反射	光线追踪	屏幕空间 + 探针
透明度	光线追踪	Alpha 混合 / 哈希
体积	完整体积渲染	有限的体积支持
置换	真置换 + 自适应细分	不支持（请使用 Normal Map）
OSL	支持（仅 CPU）	不支持
Shader to RGB	不支持	支持（卡通着色）

节点参考

如需查阅按类别（输入、输出、着色器、纹理、颜色、向量、转换器、脚本）整理的完整着色器节点目录，请参阅 references/node_reference.md。

可搜索的重点章节：

• BSDF/着色器类型：在 node_reference.md 中搜索“BSDF”或“Shader”
• 纹理节点：搜索“Texture”
• Principled BSDF 输入：搜索“Principled BSDF - Detailed”
• 渲染引擎兼容性：搜索“Cycles Only”或“EEVEE”
• Blender 5.0 更改：搜索“5.0”
• Blender 5.1 更改：搜索“5.1”、“Raycast”或“Normal Map”
• OpenColorIO 2.5：更新了色彩管理，并改进了显示变换

Python API 参考

如需查阅完整的 Python API 用法模式，包括节点类型字符串、插槽类型、连接、材质分配、世界设置和 Color Ramp 配置，请参阅 references/python_api.md。