UE材质开发进阶：手把手教你创建自定义USH函数库-拓冰建站

1. 项目概述：为什么我们需要自定义ush函数库？

在UE4/UE5的材质创作中，我们经常会遇到一些重复性的、复杂的数学运算或逻辑判断。比如，你可能需要反复计算一个基于距离的衰减函数，或者实现一个特定的噪声算法。每次都在材质蓝图里用节点重新连接一遍，不仅效率低下，而且一旦逻辑需要修改，就得在所有用到的地方逐个调整，维护起来简直是噩梦。这时候，一个封装好的、可复用的自定义ush函数库，就成了提升效率和代码质量的“神器”。

简单来说，.ush文件就是Unreal Engine Shader（着色器）的源代码文件。通过创建自定义的ush函数库，你可以将那些常用的、复杂的着色器算法封装成一个个函数，然后在任何材质中像调用内置节点一样调用它们。这不仅仅是“偷懒”，更是迈向专业级材质开发的关键一步。它能让你材质图的逻辑更清晰，复用性更强，并且因为代码是预编译的，在某些情况下还能带来微小的性能优化。接下来，我就以一个从业者的角度，带你从零开始，手把手搭建一个属于你自己的ush函数库，并把它无缝集成到你的UE项目中。

2. 核心思路与文件结构规划

在动手写代码之前，理清思路和规划好文件结构至关重要。这能避免后期混乱，也符合引擎的最佳实践。

2.1 函数库的定位与设计原则

首先，你要想清楚你的函数库主要服务于什么目的。是为了简化数学运算？封装特定的视觉效果算法（如水体、毛发）？还是为了统一项目的美术规范（如特定的色彩空间转换）？我的建议是，初期可以按功能模块进行划分。

设计上要遵循几个原则：

单一职责：一个函数只做好一件事。比如，CalculateFresnel函数就只计算菲涅尔系数，不要在里面又混入颜色混合。
清晰的输入输出：函数参数命名要有意义，使用in,out,inout前缀来明确参数用途是UE HLSL的常见约定。
注释与文档：为每个函数编写清晰的注释，说明其功能、参数含义、返回值和使用示例。这对于团队协作和未来的自己至关重要。
版本与兼容性：考虑UE4和UE5的差异。虽然大部分HLSL代码通用，但一些引擎内置函数或常量可能有变。可以在函数库开头用#if ENGINE_MAJOR_VERSION >= 5这样的宏进行条件编译。

2.2 项目文件目录结构

把ush文件随便扔在项目里可不是好习惯。一个清晰的结构有助于引擎的Shader编译系统找到它们，也方便管理。我推荐的目录结构如下：

YourProject/ ├── Source/ │ └── YourProject/ (可选，如果你需要C++模块引用) └── Content/ └── CustomShaders/ ├── Functions/ │ ├── Math.ush │ ├── Noise.ush │ └── Lighting.ush └── Includes/ └── Common.ush

CustomShaders/：这是根目录，明确存放所有自定义着色器相关文件。
Functions/：存放按模块划分的具体函数库文件。
Includes/：存放一些公共的定义、常量和结构体，被其他ush文件包含。

为什么放在Content下？因为这样可以通过引擎的虚拟路径（如/Engine/，/Project/）直接引用，并且当项目移动或打包时，这些资源文件会被正确包含。虽然传统上C++代码放在Source，但纯HLSL函数库作为“内容”的一部分管理更为方便。

注意：确保在项目设置（Project Settings -> Packaging）中，将CustomShaders目录添加到“Additional Non-Asset Directories to Package”中，否则打包时这些ush文件可能不会被包含，导致运行时着色器编译错误。

3. 创建你的第一个ush函数库文件

理论说再多不如动手。我们来创建一个最实用的函数：一个平滑的阶梯函数（Smooth Step），但它比内置的SmoothStep更可控。

3.1 创建并编写Math.ush

在Content/CustomShaders/Functions/文件夹下，右键选择“新建文件”（可能需要通过“在资源管理器中显示”来手动创建）。
创建一个新文件，命名为Math.ush。注意后缀名必须是.ush或.usf（Unreal Shader File）。
用文本编辑器（如VSCode，记得安装UE的插件支持）打开它，开始编写代码。

// Content/CustomShaders/Functions/Math.ush // 自定义数学函数库 // 作者：[你的名字] // 版本：1.0 // 避免重复包含的保护宏 #ifndef MYPROJECT_MATH_INCLUDED #define MYPROJECT_MATH_INCLUDED // 引入引擎常用函数和常量，确保兼容性 #include "/Engine/Public/Platform.ush" /** * 增强型平滑阶梯函数。 * 在区间 [Edge0, Edge1] 内进行平滑插值，并允许控制平滑度。 * @param InValue 输入值。 * @param InEdge0 区间下界。 * @param InEdge1 区间上界。 * @param InSmoothness 平滑度因子 (0~1)。0为最平滑（类似SmoothStep），1为最锐利（类似Step）。 * @return 平滑过渡后的值。 */ float MySmoothStep(float InValue, float InEdge0, float InEdge1, float InSmoothness) { // 将输入值映射到[0,1]区间 float t = saturate((InValue - InEdge0) / (InEdge1 - InEdge0)); // 根据平滑度因子调整插值曲线 // InSmoothness为0时，使用三次Hermite插值（标准SmoothStep） // InSmoothness为1时，使用线性插值（锐利） float curve = lerp(t * t * (3.0 - 2.0 * t), t, InSmoothness); // 将结果映射回原区间 return lerp(InEdge0, InEdge1, curve); } /** * 将线性空间颜色转换为感知上更均匀的Luma值（近似灰度）。 * 比简单的 (R+G+B)/3 或 dot(color, float3(0.3,0.59,0.11)) 在某些色彩空间下更准确。 * @param InLinearColor 线性空间下的RGB颜色。 * @return 感知亮度值。 */ float Luminance(float3 InLinearColor) { // 使用Rec.709系数，适用于sRGB/Rec.709色彩空间 return dot(InLinearColor, float3(0.2126, 0.7152, 0.0722)); } #endif // MYPROJECT_MATH_INCLUDED

代码解析与避坑指南：

#ifndef/#define/#endif：这是头文件保护宏，绝对必不可少。它防止同一个文件在着色器编译过程中被多次包含，导致重定义错误。宏的名字最好唯一，通常用项目名_文件名_INCLUDED的格式。
#include "/Engine/Public/Platform.ush"：这行非常关键。它包含了引擎的平台抽象层定义，确保你的代码中使用的数据类型（如float,half）和内置函数（如saturate,lerp）能在所有目标平台（DX11, DX12, Vulkan, Metal等）上正确工作。没有它，在非PC平台上编译可能会失败。
函数命名：我用了MySmoothStep前缀，这是为了避免与引擎可能已有的同名函数冲突。你也可以用项目缩写，如ABC_。
saturate函数：这是HLSL内置函数，相当于clamp(x, 0, 1)。在着色器中非常常用，能确保值在安全范围内。
注释：详细的注释是函数库可维护性的生命线。务必写清楚功能、参数和返回值。

4. 在材质编辑器中调用自定义函数

函数写好了，怎么在材质蓝图里用呢？这里有两种主流方法，各有优劣。

4.1 方法一：使用“Custom”节点（最直接）

这是最快捷、无需C++编程的方法。

在材质编辑器中，右键搜索“Custom”，选择“Custom Node”。
选中这个Custom节点，在细节（Details）面板中，找到“Code”输入框。
在这里直接输入你的函数调用。关键一步：你需要告诉引擎你的函数定义在哪里。在“Description”字段下方（或某些版本在“Additional Defines”里），你需要指定包含路径。

实际操作示例：假设我们要调用刚才写的MySmoothStep函数。

在Custom节点的“Code”框里输入：
```
return MySmoothStep(Time, 0.2, 0.8, Smoothness);
```
这里Time,Smoothness是你需要连接到Custom节点输入引脚上的值。
必须设置包含路径：在细节面板，找到“Include File Paths”（或类似名称）的数组。点击“+”号，添加一条：
```
/Game/CustomShaders/Functions/Math.ush
```
/Game对应项目Content目录的虚拟路径。

优缺点分析：

优点：设置简单，迭代快，适合快速验证函数逻辑或在小范围内使用。
缺点：
- 可读性差：材质图中是一大坨代码，无法像原生节点那样直观。
- 难以复用：每个用到的地方都要重新设置包含路径和代码。
- 容易出错：代码是字符串形式，没有语法高亮和检查，容易写错。
- 性能提示缺失：Custom节点默认可能被当作复杂运算，缺少像原生节点那样的优化提示。

4.2 方法二：创建材质函数（Material Function）（推荐）

这是更专业、更可维护的做法。我们将ush函数封装成一个材质函数，这样它在材质图中就以一个整洁的节点形式出现，可以设置漂亮的颜色、输入输出名称，并且能像内置函数一样被搜索和复用。

创建材质函数：在内容浏览器右键 -> 材质与纹理 -> 材质函数。命名为MF_MySmoothStep。
打开材质函数编辑器：你会看到一个类似材质编辑器的界面，但没有主材质节点。
添加Custom节点：和上面方法一一样，拖入一个Custom节点，写入调用代码，设置包含路径（/Game/CustomShaders/Functions/Math.ush）。
定义输入输出：
- 在Custom节点的左侧，你可以通过右键“Add Input”来创建输入引脚，并命名（如Time,Edge0,Edge1,Smoothness）。类型要匹配HLSL函数参数类型（如float）。
- Custom节点的输出引脚自动作为函数输出。
- 在材质函数编辑器的“函数输出”节点上，将Custom节点的输出连接过去。
美化与注释：
- 选中材质函数的根节点（在内容浏览器里），可以在细节面板设置分类（如“MyProject/Math”），这样它就会出现在材质编辑器的对应分类下。
- 你还可以在材质函数编辑器里添加注释框，说明用法。
保存并使用：保存材质函数。现在，在任何材质中，你都可以像搜索“Lerp”一样，搜索“MySmoothStep”或你设置的分类，然后拖出这个整洁的节点来使用了。

实操心得：

将相关的多个Custom节点封装到一个材质函数中，可以形成一个功能更完整的模块。例如，一个“水下焦散”材质函数，内部可能调用了好几个你写在Noise.ush和Lighting.ush里的自定义函数。
材质函数的输入引脚可以设置默认值，这大大提高了易用性。
这是连接HLSL代码逻辑和美术友好工作流的最佳桥梁。

5. 进阶集成：与引擎源码协同工作

如果你的函数库非常庞大，或者你想让它像引擎内置函数一样，被所有项目的所有材质直接访问（无需单独设置包含路径），那么就需要将其集成到引擎的着色器编译系统中。这涉及到修改引擎的.Build.cs文件和ShaderSource目录。

警告：此操作涉及修改引擎或插件源码，建议在插件中完成，而非直接修改引擎，以保证可移植性和易于升级。

5.1 创建插件并集成函数库

创建插件：在编辑器中，选择“编辑”->“插件”->“新建插件”，选择“空白”模板，命名为“MyShaderLibrary”。
放置ush文件：在插件目录下（如Plugins/MyShaderLibrary/Shaders/Private），放入你的.ush文件。引擎编译时，会自动将这个目录加入全局着色器包含路径。
修改插件的.Build.cs文件：为了让UnrealBuildTool（UBT）在编译着色器时知道这个目录，需要打开MyShaderLibrary.Build.cs，添加以下代码：

using UnrealBuildTool; public class MyShaderLibrary : ModuleRules { public MyShaderLibrary(ReadOnlyTargetRules Target) : base(Target) { PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs; PublicIncludePaths.AddRange( new string[] { // ... 其他路径 } ); PrivateIncludePaths.AddRange( new string[] { // ... 其他路径 } ); // 关键：添加着色器目录到引擎的搜索路径 if (Target.bBuildEditor) { // 将插件的Shaders目录添加到引擎的着色器源文件搜索路径 string PluginShaderDir = Path.Combine(ModuleDirectory, "Shaders"); PublicDefinitions.Add(string.Format("MY_SHADER_DIR=\"{0}\"", PluginShaderDir.Replace('\\', '/'))); // 更直接的方式：告诉引擎这里也有.ush文件 // 这通常通过修改引擎的Shader目录配置实现，更常见的做法是下面这种 } // 更通用的方法：将Private目录下的Shaders文件夹加入包含路径 // 引擎在编译时，会递归搜索所有模块的“Private”子目录下的文件。 // 所以只要把.ush文件放在插件模块的Private/Shaders/下即可。 } }

实际上，对于简单的函数库，最无痛的做法是：将你的.ush文件放在插件模块的Private文件夹下的任意位置（例如Private/Shaders/）。因为默认情况下，引擎的着色器编译系统会扫描所有模块的Private文件夹寻找.ush和.usf文件。

在材质中直接调用：完成上述步骤并编译插件后，理论上你在任何材质（包括Custom节点）中，都可以直接使用MySmoothStep函数，而无需再在Custom节点里指定包含路径。因为引擎在全局着色器编译时已经包含了你的文件。

重要提示：这种方式要求你对Unreal的构建系统有一定了解。如果操作后函数仍然找不到，检查以下点：
插件是否已启用并成功编译。
.ush文件是否放在了插件的Private目录下。
尝试在引擎的ShaderCache相关日志中查找包含错误。

6. 函数库设计最佳实践与高级技巧

当你的函数库逐渐壮大，遵循一些最佳实践能让它更健壮、更高效。

6.1 性能考量：`half`vs`float`

在移动平台或对性能敏感的场景，精度选择很重要。

float：全精度浮点数，精度高，但计算慢，占用带宽多。
half：半精度浮点数（16位），精度较低，但计算快，省带宽。适用于颜色、UV坐标等不需要极高精度的数据。

在你的函数中，可以考虑提供half精度的版本，或者使用模板（如果HLSL版本支持）。更实用的做法是，在函数内部对中间变量使用half，如果输入输出是float，让编译器去处理转换。但要注意，过度使用half可能导致精度损失，在连续复杂的数学运算中累积误差。

// 提供一个half精度的版本 half MySmoothStep_Half(half InValue, half InEdge0, half InEdge1, half InSmoothness) { half t = saturate((InValue - InEdge0) / (InEdge1 - InEdge0)); half curve = lerp(t * t * (3.0 - 2.0 * t), t, InSmoothness); return lerp(InEdge0, InEdge1, curve); }

6.2 组织与包含策略

按功能分文件：如Math.ush,Noise.ush,Color.ush,LightingModels.ush。避免一个文件过于臃肿。
创建主包含文件：在Includes/目录下创建MyShaderLibrary.ush，里面按顺序包含所有子模块文件。这样，材质中只需要包含这一个文件，就能使用所有功能。
```
// MyShaderLibrary.ush #include "Math.ush" #include "Noise.ush" #include "Color.ush"
```
使用相对路径：在MyShaderLibrary.ush中，使用相对路径包含其他文件。前提是这些文件在同一个目录或子目录下，并且引擎的包含路径已设置正确。

6.3 调试与日志输出

着色器调试一直是个难题。一个有用的技巧是使用clip()函数或通过输出特殊颜色来调试。你可以编写一个调试函数，根据条件将像素裁剪（clip(value)，如果value小于0则丢弃该像素），或者输出高亮的颜色。

void DebugClip(float Condition, float3 DebugColor) { // 如果Condition为假（小于某个阈值），则丢弃像素并显示调试色 // 这需要与一个渲染目标叠加配合使用，实际应用较复杂 // 更简单的方式是直接返回调试色作为输出 }

更实际的做法是，在Custom节点中，临时将中间变量的值直接作为颜色输出到自发光通道，来可视化它的范围。例如，return float3(t, t, t);来查看归一化后的t值。

7. 实战：构建一个噪声函数库

让我们用一个更复杂的例子巩固一下：创建一个包含多种噪声函数的Noise.ush库。噪声是程序化材质的核心。

7.1 实现一个Value Noise

// Content/CustomShaders/Functions/Noise.ush #ifndef MYPROJECT_NOISE_INCLUDED #define MYPROJECT_NOISE_INCLUDED #include "/Engine/Public/Platform.ush" // 一个简单的伪随机函数 float Rand(float2 p) { return frac(sin(dot(p, float2(12.9898, 78.233))) * 43758.5453); } /** * 二维Value Noise。 * @param UV 输入坐标。 * @param Scale 噪声频率缩放。 * @return 范围在[0,1]的噪声值。 */ float ValueNoise2D(float2 UV, float Scale) { UV *= Scale; float2 i = floor(UV); float2 f = frac(UV); // 网格四个角点的随机值 float a = Rand(i); float b = Rand(i + float2(1.0, 0.0)); float c = Rand(i + float2(0.0, 1.0)); float d = Rand(i + float2(1.0, 1.0)); // 双线性插值 float2 u = f * f * (3.0 - 2.0 * f); // Smoothstep return lerp(lerp(a, b, u.x), lerp(c, d, u.x), u.y); } #endif

7.2 封装为材质函数并应用

创建材质函数MF_ValueNoise2D。
内部使用Custom节点，代码为return ValueNoise2D(UV, Scale);。
包含路径设置为/Game/CustomShaders/Functions/Noise.ush。
暴露UV和Scale为输入，输出噪声值。
现在你可以在材质中连接这个节点，用来驱动材质的粗糙度、高度偏移或颜色变化，创造出石头表面、云朵等效果。

实操心得：噪声叠加单一噪声往往显得单调。在函数库中，你可以进一步封装一个分形噪声（Fractal Noise，也叫Octave Noise）函数，它将多层不同频率和振幅的噪声叠加起来，产生更自然、更丰富的细节。

float FractalNoise2D(float2 UV, float Scale, int Octaves, float Persistence, float Lacunarity) { float value = 0.0; float amplitude = 1.0; float frequency = Scale; float maxAmplitude = 0.0; // 用于归一化 for (int i = 0; i < Octaves; i++) { value += ValueNoise2D(UV, frequency) * amplitude; maxAmplitude += amplitude; amplitude *= Persistence; // 振幅递减 frequency *= Lacunarity; // 频率递增 } // 归一化到[0,1]范围 return value / maxAmplitude; }

将这个也封装成材质函数，你就拥有了一个强大的程序化纹理生成工具。

8. 常见问题排查与解决方案实录

在实际操作中，你肯定会遇到各种报错和问题。这里记录了几个最常见的坑和解决办法。

8.1 编译错误：“未识别的标识符”

问题描述：在Custom节点中，提示MySmoothStep是未识别的标识符。排查步骤：

检查包含路径：这是最常见的原因。确保在Custom节点的“Include File Paths”里添加的路径完全正确。路径是虚拟路径，以/Game/或/Engine/开头，区分大小写。/Game/CustomShaders/Functions/Math.ush和/Game/CustomShaders/Functions/math.ush可能被视为不同文件。
检查文件后缀：确保文件是.ush或.usf，不是.txt或其他。
检查保护宏：确保你的.ush文件有正确的#ifndef/#define保护，并且宏名唯一，没有和其他引擎文件冲突。
检查函数签名：在Custom节点的代码里调用的函数名、参数数量和类型必须与.ush文件中的定义完全一致。
重启着色器编译：有时引擎的着色器缓存会出问题。尝试在项目设置中点击“清除着色器缓存”，然后重启编辑器。

8.2 材质函数中的Custom节点不工作

问题描述：材质函数保存正常，但拖入材质后节点是红色的，或者输出错误。解决方案：

确保材质函数已保存。未保存的函数在其他材质中无法正确加载。
双击打开材质函数，检查内部的Custom节点设置（包含路径、代码）是否正确。
检查材质函数的输出节点是否已正确连接。
尝试将材质函数复制一份（右键->复制），有时能解决奇怪的引用问题。

8.3 打包后材质变黑或错误

问题描述：在编辑器中运行正常，打包后游戏内材质失效。原因与解决：

包含路径问题：这是打包失败的头号杀手。确保所有自定义的.ush文件所在的目录，都在项目设置的“打包”（Packaging）设置中，添加到了“Additional Non-Asset Directories to Package”列表里。否则，这些文件不会被打进Pak文件，运行时自然找不到。
插件集成问题：如果你是通过插件集成，确保插件本身被打包包含。检查插件的.uplugin文件，确保"EnabledByDefault" : true，并且"CanContainContent" : true（如果你的ush文件被视为内容）。
平台特性：某些HLSL语法或函数可能在目标平台（如Switch, Android）上不被支持。尽量使用引擎提供的跨平台函数（如通过#include "/Engine/Public/Platform.ush"引入的）。避免使用太新的或特定厂商的HLSL扩展。

8.4 性能优化提示

避免在Custom节点中编写过长或循环复杂的代码：材质编辑器对Custom节点的优化有限。非常复杂的逻辑应考虑移至材质函数，或更好的方式，通过“材质图层”或“材质属性”系统来管理。
使用静态分支：如果函数中有基于常量参数的if语句，编译器可能进行优化。但基于动态变量（如像素位置）的分支，在GPU上可能导致性能下降。
采样纹理优于复杂计算：有时，将预计算好的复杂函数结果存储在一张查找纹理（Lookup Texture, LUT）中，在着色器里采样纹理，比实时计算更快。这需要在效果质量和性能之间权衡。

创建和维护自定义ush函数库是一个从“材质美术师”转向“技术美术”或“图形程序员”的标志性技能。它开始可能有些门槛，但一旦建立起自己的工作流，你会发现材质创作的速度和质量都会有质的飞跃。最重要的是，你积累的这些可复用的代码片段，会成为你个人和项目团队的宝贵资产。从今天开始，尝试将你下一个材质中重复的三连节点，封装成你的第一个自定义函数吧。