UE5自定义.ush函数库：从HLSL封装到智能节点开发全流程

1. 项目概述为什么我们需要自定义.ush函数库在UE5的材质开发中你肯定遇到过这样的场景为了实现一个复杂的材质效果比如基于世界坐标的网格渐变、自定义的噪声混合或者一个特定的光照模型你需要在不同的材质节点图中反复复制粘贴同一大坨节点网络。这不仅让材质图变得臃肿不堪难以维护而且一旦核心算法需要调整你就得在所有用到的地方手动修改一遍效率极低还容易出错。这就是自定义.ush函数库要解决的问题。简单来说它允许你将一段复杂的、可复用的HLSLHigh-Level Shading Language代码逻辑封装成一个独立的.ush文件。之后你就可以像调用引擎内置的Lerp、Dot、Normalize一样在材质编辑器中通过一个简洁的“Custom”节点来调用它。这不仅仅是代码复用更是将你的材质开发从“节点连线工”提升到“着色器程序员”的关键一步。它能极大地提升开发效率、保证效果一致性并且为团队协作和知识沉淀提供了标准化工具。网络上很多教程只讲到如何创建一个简单的.ush文件并调用但真正要把它用好在生产环境中你需要了解文件组织的最佳实践、如何向函数传递复杂的参数比如纹理采样器以及最硬核的部分——如何通过修改引擎源码让你自定义的函数库拥有和内置函数一样的智能代码提示和参数验证。今天我就结合自己踩过的坑和项目实战经验带你从零到一彻底掌握创建、调用乃至深度定制自定义.ush函数库的全流程。2. 核心思路与方案设计2.1 理解.ush与材质编译管线在动手之前我们必须搞清楚.ush文件在UE5的材质编译流程中扮演什么角色。当你点击“应用”材质时UE5的材质编译器会将你绘制的节点图连同所有引用的.ush文件内容最终编译成一段完整的HLSL代码交给显卡执行。.ush文件本质上就是一个文本文件里面写的是HLSL代码片段。引擎内置了海量的.ush文件你可以在引擎目录的Shaders文件夹下找到它们它们定义了从基础数学运算到复杂光照模型的一切。我们创建自定义.ush就是在扩展这个“着色器代码库”。这里有一个关键点.ush文件是“包含”#include到最终着色器中的。这意味着你的函数定义必须在被调用之前就被“包含”进来。UE5的材质编译器会自动扫描项目目录下的特定路径来寻找这些文件。2.2 文件位置与组织策略文件放哪里是第一个要做的设计决策。放错了地方编译器找不到一切白搭。1. 项目内推荐用于项目特定功能这是最常用、最安全的方式。在你的项目根目录下创建文件夹项目名/Shaders/。例如如果你的项目叫MyProject那么路径就是MyProject/Shaders/。所有属于这个项目的自定义着色器代码都应放在这里。这样做的好处是项目完全自包含迁移、版本管理如Git都非常方便不会污染引擎目录。2. 引擎插件内推荐用于跨项目通用功能如果你开发了一个功能强大的插件并且希望插件提供的材质函数能被所有使用该插件的项目调用那么你应该将.ush文件放在插件的Shaders/目录下。例如Plugins/MyAwesomePlugin/Shaders/。引擎会自动扫描所有已启用插件的这个目录。3. 引擎目录下不推荐仅用于学习或深度修改你也可以直接放在引擎的Engine/Shaders/目录下。但这会修改引擎本身导致引擎升级时可能被覆盖也不利于团队协作和项目移植。除非你要修改引擎内置的着色器逻辑否则强烈不建议这么做。注意无论选择哪个位置请确保路径中没有中文或特殊字符使用纯英文和数字是最保险的做法可以避免很多意想不到的编译错误。2.3 函数设计原则在设计你的自定义函数时需要遵循HLSL和UE材质系统的约定函数命名建议使用清晰的前缀如MyProject_、MP_以避免与引擎内置函数或未来可能加入的同名函数冲突。例如MyProject_CellNoise。输入/输出材质节点主要通过输入引脚Input和输出引脚Output与外部交互。在HLSL函数中输入对应函数参数输出对应返回值。对于简单的浮点数、向量float3直接使用值传递。但对于纹理采样器Texture2D/SamplerState需要特殊处理我们会在实操部分详细说明。代码风格保持与引擎着色器代码一致的风格如使用in关键字修饰输入参数这能提高代码的可读性和一致性。3. 手把手创建第一个自定义.ush函数库3.1 创建.ush文件与基础模板我们从一个最简单的函数开始计算一个输入值的平方。确定路径在项目根目录下创建Shaders文件夹。完整路径你的项目/Shaders/。创建文件在该文件夹内新建一个文本文件将其重命名为MyCustomFunctions.ush。确保文件扩展名是.ush而不是.ush.txt需要关闭系统“隐藏已知文件类型的扩展名”选项。编写函数代码用任何文本编辑器推荐VSCode、Sublime Text或Notepad打开这个文件输入以下内容// MyCustomFunctions.ush // 项目自定义着色器函数库 #ifndef MY_CUSTOM_FUNCTIONS_INCLUDED #define MY_CUSTOM_FUNCTIONS_INCLUDED // 函数计算平方 // InValue: 输入值 // 返回: 输入值的平方 float MyProject_Square(float InValue) { return InValue * InValue; } // 函数线性插值这里仅作示例实际应使用内置Lerp float3 MyProject_LerpColor(float3 A, float3 B, float T) { return A * (1 - T) B * T; } #endif // MY_CUSTOM_FUNCTIONS_INCLUDED代码解析#ifndef/#define/#endif这是头文件保护。防止同一个文件在着色器编译过程中被多次包含导致重复定义错误。MY_CUSTOM_FUNCTIONS_INCLUDED这个宏名需要是唯一的通常用文件名的大写形式加_INCLUDED。float MyProject_Square(float InValue)定义了一个名为MyProject_Square的函数它接收一个float类型参数InValue并返回其平方。float3是三维向量对应RGB颜色。3.2 在材质编辑器中调用自定义函数保存好.ush文件后打开或创建一个材质。在材质图表中右键在搜索框中输入Custom选择Custom节点全称通常是Custom Node。选中这个Custom节点在细节Details面板中找到Code输入框。在Code框中直接调用我们刚才写的函数例如输入MyProject_Square(Time)。这里Time是引擎内置的节点输出当前时间作为输入参数。关键一步在细节面板下方找到Include File Paths包含文件路径。点击加号添加我们.ush文件的路径。这里只需要填写相对于项目Shaders目录的路径或者相对于引擎根目录的路径。对于放在项目/Shaders/下的文件最保险的写法是使用绝对路径引用但更规范的做法是使用相对路径。对于我们的例子因为文件在项目/Shaders/MyCustomFunctions.ush你可以尝试添加/Project/MyCustomFunctions.ush但更通用的、由引擎自动扫描的方式是你只需要确保文件在Shaders目录下然后在Code中直接调用函数即可引擎的着色器编译系统会自动包含该目录下的所有.ush文件。如果自动包含失败你可以在Include File Paths中填写文件名MyCustomFunctions.ush不包含路径编译器会在已知的着色器目录中搜索。将Custom节点的输出引脚连接到材质的某个输入上如自发光颜色。编译材质你应该能看到基于时间平方变化的效果。实操心得很多时候Custom节点报错“未识别的标识符”不是因为函数写错了而是因为.ush文件没有被正确包含。首先检查文件路径和名称拼写其次检查头文件保护宏是否正确定义且唯一。一个快速调试的方法是在Code框里直接写一小段HLSL代码如return 1.0;如果通过说明节点本身没问题问题出在函数引用或包含路径上。3.3 处理复杂参数纹理采样器传递一个浮点数或向量很简单但如何传递一张纹理并采样呢这是新手常遇到的坎。在HLSL中采样纹理需要两个对象Texture2D纹理资源和SamplerState采样器状态。在UE材质系统中纹理输入引脚背后自动关联着这两个东西。假设我们要创建一个自定义的“灰度化”函数输入纹理和UV输出灰度值。在MyCustomFunctions.ush中添加以下函数// 函数计算纹理在指定UV处的灰度值使用亮度公式 float MyProject_TextureLuminance(Texture2D InTex, SamplerState InTexSampler, float2 InUV) { // 采样纹理 float3 color InTex.Sample(InTexSampler, InUV).rgb; // 标准亮度公式0.2126*R 0.7152*G 0.0722*B float luminance dot(color, float3(0.2126, 0.7152, 0.0722)); return luminance; }在材质编辑器中创建一个Custom节点。在Code框中输入MyProject_TextureLuminance(Texture, Sampler, UV)。你需要为这个Custom节点添加三个输入引脚。在细节面板的Inputs部分点击加号添加。第一个引脚命名为Texture将Type设置为Texture 2D。第二个引脚命名为Sampler将Type设置为Sampler State。这是一个关键技巧UE材质系统会自动为纹理引脚生成对应的采样器状态其命名规则是纹理变量名Sampler。但为了清晰我们显式定义它。第三个引脚命名为UV将Type设置为Function Input - Vector2。从材质中拉出一个纹理对象节点连接到Texture引脚。系统会自动将对应的SamplerState传递到名为TextureSampler的隐含参数中但因为我们显式定义了Sampler引脚所以需要手动连接。通常你可以通过一个TextureSample节点来同时获取纹理和采样器或者直接使用TextureObject节点提供的采样器输出。连接一个TextureCoordinate节点到UV引脚。确保Include File Paths包含了你的.ush文件。这样你就实现了一个接收纹理并返回灰度值的自定义函数节点。4. 进阶修改引擎源码以实现智能提示与验证上面的方法已经能工作了但Custom节点用起来还是有些“糙”它没有代码提示参数类型容易输错也没有漂亮的图标。如果你希望你的自定义函数库看起来和Lerp、Fresnel这些原生节点一样“正规”就需要修改引擎的C源码。这属于进阶操作需要你已配置好UE5的源码版开发环境。4.1 定位与理解材质节点定义UE5中所有的材质表达式Material Expression类都定义在C中。我们自定义的节点需要继承自UMaterialExpressionCustom或更基础的类并添加我们自己的逻辑。找到相关源码引擎源码中与材质表达式相关的代码主要在Engine/Source/Runtime/Engine/Classes/Materials/目录下。例如MaterialExpression.h定义了基类MaterialExpressionCustom.h/.cpp是我们要参考的Custom节点实现。创建插件推荐为了不直接修改引擎源码便于升级和维护我们创建一个引擎插件来添加新的材质表达式。在引擎目录的Engine/Plugins/下创建一个新文件夹例如MyShaderNodes并按照插件结构创建Source/MyShaderNodes/目录以及.uplugin描述文件。4.2 创建自定义材质表达式类在插件目录下创建C类例如MaterialExpressionMyProjectSquare。.h文件示例// MaterialExpressionMyProjectSquare.h #pragma once #include \Materials/MaterialExpression.h\ #include \MaterialExpressionMyProjectSquare.generated.h\ UCLASS(MinimalAPI, collapsecategories, hidecategoriesObject) class UMaterialExpressionMyProjectSquare : public UMaterialExpression { GENERATED_UCLASS_BODY() // 输入引脚 UPROPERTY() FExpressionInput Input; //~ Begin UMaterialExpression Interface virtual int32 Compile(class FMaterialCompiler* Compiler, int32 OutputIndex) override; virtual void GetCaption(TArrayFString OutCaptions) const override; virtual const TArrayFExpressionInput* GetInputs() override; virtual FExpressionInput* GetInput(int32 InputIndex) override; virtual FName GetInputName(int32 InputIndex) const override; //~ End UMaterialExpression Interface };.cpp文件示例// MaterialExpressionMyProjectSquare.cpp #include \MaterialExpressionMyProjectSquare.h\ #include \MaterialCompiler.h\ UMaterialExpressionMyProjectSquare::UMaterialExpressionMyProjectSquare(const FObjectInitializer ObjectInitializer) : Super(ObjectInitializer) { // 定义节点在菜单中的分类和名称 MenuCategories.Add(TEXT(\MyProject\)); // 在材质编辑器右键菜单中显示的分类 } int32 UMaterialExpressionMyProjectSquare::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { // 编译输入表达式 int32 InputCode Input.Compile(Compiler); if (InputCode INDEX_NONE) { return INDEX_NONE; } // 调用我们自定义的HLSL函数。 // 注意这里假设我们的.ush文件已经被引擎的着色器编译系统自动包含。 // 我们只需要生成函数调用代码。 return Compiler-CustomExpression(this, TEXT(\MyProject_Square\), InputCode); } void UMaterialExpressionMyProjectSquare::GetCaption(TArrayFString OutCaptions) const { OutCaptions.Add(TEXT(\MySquare\)); } const TArrayFExpressionInput* UMaterialExpressionMyProjectSquare::GetInputs() { TArrayFExpressionInput* Inputs; Inputs.Add(Input); return Inputs; } FExpressionInput* UMaterialExpressionMyProjectSquare::GetInput(int32 InputIndex) { return InputIndex 0 ? Input : nullptr; } FName UMaterialExpressionMyProjectSquare::GetInputName(int32 InputIndex) const { return InputIndex 0 ? TEXT(\Input\) : NAME_None; }代码解析Compile函数是核心它接收一个材质编译器FMaterialCompiler将输入的材质表达式编译成中间代码InputCode然后通过Compiler-CustomExpression方法告诉编译器这里需要插入一个对MyProject_Square函数的调用并将InputCode作为参数传递进去。GetCaption决定了节点在材质图表中显示的名称。MenuCategories决定了这个节点在材质编辑器右键菜单中的位置。4.3 注册节点与生成着色器代码确保.ush文件被包含你需要将你的MyCustomFunctions.ush文件放到插件目录的Shaders/文件夹下例如Engine/Plugins/MyShaderNodes/Source/MyShaderNodes/Shaders/。引擎在编译着色器时会自动扫描所有插件的Shaders目录。编译插件用Visual Studio编译你的引擎解决方案确保你的插件模块已正确添加到解决方案中。编译成功后启动引擎编辑器。在材质编辑器中测试创建一个新材质在图表中右键搜索MySquare你在GetCaption中设置的名称你应该能看到你新添加的节点。连接一个输入编译材质功能应该和之前用Custom节点实现的一样。通过这种方式创建的节点拥有固定的输入引脚名称和类型显示也更规范。你还可以重写更多虚函数来定义图标的颜色、输出类型等让它完全融入引擎。5. 常见问题、调试技巧与性能考量5.1 编译错误排查当你的自定义函数导致材质编译错误时控制台会输出HLSL编译器的错误信息。这些信息可能比较晦涩。“未识别的标识符”99%是函数名拼写错误或者.ush文件没有被包含。检查Include File Paths设置并确认.ush文件中的函数名与Code中调用的完全一致包括大小写。“语法错误”检查.ush文件中的HLSL语法特别是分号、括号是否匹配。确保头文件保护格式正确。“找不到文件”检查.ush文件的物理路径是否正确是否在项目或插件的Shaders目录下。尝试使用绝对路径进行测试。调试技巧一个非常有效的方法是先在Custom节点的Code框里直接写一小段简单的HLSL代码如return 0.5;。如果能编译通过再逐步替换成你的函数调用并添加Include File Paths这样可以隔离问题。5.2 性能优化建议自定义函数虽然灵活但滥用也会影响性能。避免过度复杂化如果一个函数内部有非常复杂的循环或分支判断考虑是否可以通过预计算、查表LUT或在材质外部C端计算好再传入的方式来优化。注意纹理采样次数在自定义函数中采样纹理是昂贵的操作。确保你没有无意中在同一个函数里对同一张纹理进行多次采样。如果可能将采样结果作为参数传入函数。使用适当的精度HLSL中有half半精度浮点数16位和float全精度32位。对于颜色计算、UV偏移等使用half通常就足够了且速度更快。在函数声明中你可以使用real这个类型别名它在不同平台上可能会被映射为half或float由引擎的材质质量设置决定。5.3 版本管理与团队协作当你的项目使用了自定义.ush函数库特别是修改了引擎源码或创建了插件后团队协作时需要特别注意.ush文件必须纳入版本控制系统如Git。确保所有团队成员的项目Shaders目录或插件路径一致。自定义材质表达式插件整个插件文件夹需要纳入版本控制。团队成员需要重新编译引擎或至少编译该插件模块。文档为你的自定义函数库编写简单的说明文档记录每个函数的用途、输入输出参数和示例这对团队新成员至关重要。创建并熟练运用自定义.ush函数库是掌握UE5材质系统高级玩法的标志。它不仅能将你从重复劳动中解放出来更能让你构建出结构清晰、易于维护的复杂材质系统。从简单的工具函数开始尝试逐步过渡到封装复杂的光照模型或后处理效果你会发现材质开发的世界变得更加广阔和高效。