反编译导出

DreamShader » 工具 » 反编译导出

这个导出器会遍历一个已有的 UMaterial 或 UMaterialFunction 节点图，写出等价的 DreamShaderLang 源文件。

[!IMPORTANT] 有两个反编译器。 本页描述的是 1.x 那个，它写 .dsm / .dsf 并留在 -Format=Legacy 后面。2.0 反编译器才是默认：它把资产的图读进编译器自己的 IR， 打印出一个 .dss —— 材质实例则是 .dsi —— 而且它的输出是被证明过的：文本会被重新编译，两份 IR 互相比较。没有图的 Custom Pass 管线 回来的是 .dsp，读回后与资产比较*（自 2.1.0 起）*。见本页末尾的 2.0 反编译器。

[!NOTE] 把 1.x 反编译器当作迁移的起点，不是往返保证。它会还原图的结构，以及它能表达的那部分 节点状态，其余的留下一条 // Warning: 注释。删掉原资产之前，下面列出的 已知往返缺口 正是值得手工核对的那几项。

调用方式

不写 -Format=Legacy（也没有 .dsm / .dsf 的 -Out）时，命令行跑的是 2.0 反编译器 （自 2.0.0 起）；每个 legacy 菜单项旁边的 Export .dss 在编辑器里做同样的事。

两个编辑器入口都要求恰好选中一个资产，写完文件后用你偏好的编辑器打开它。见 编辑器集成和命令行。

进度对话框在 0.25 秒延迟后出现，标题是 Decompiling Material '{Asset}'... 或 Decompiling Material Function '{Asset}'...，每访问一个节点走一帧。commandlet 运行中不显示该对话框。

输出路径

<SourceDirectory> 是 Source Directory 项目设置，默认 DShader。layer 和 layer blend 的目录与 Functions 是分开的，而且类判定是 blend 优先，所以 layer blend 永远不会落进 Layers。

在分类目录内部，资产的 package path 变成相对文件路径，每个 package 段一层目录：

/Game/Materials/Metal/M_Steel
  →  <Project>/DShader/Decompiled/Materials/Game/Materials/Metal/M_Steel.dsm

给 commandlet 传 -Out= 会覆盖整套计算，路径归一化后精确写到指定位置。编辑器入口不接受覆盖。

生成出来的资产名

写在文件内部的 Name= 不是文件路径。它是 Decompiled/<Category>/<package segments>，每段里的 \ / . : 都换成 _：

/Game/Materials/Metal/M_Steel
  →  Shader(Name="Decompiled/Materials/Game/Materials/Metal/M_Steel")

因此重新编译导出的文件会在 /Game/Decompiled/Materials/… 下创建一个新资产，原件原封不动。 等你准备好接管原路径时，再改 Name= 和 Root=。见 资产路径。

文件结构

// Decompiled from <full object path>
[// Warning: <text>]…

[<VirtualFunction declaration>]…

{ Shader | ShaderFunction | ShaderLayer | ShaderLayerBlend }(Name="<generated name>")
{
    [Properties = { … }]
    [Inputs     = { … }]   // function kinds only
    [Settings   = { … }]   // Shader only
    [Outputs    = { … }]
    [Graph      = { … }]
    [Layout     = { … }]
}

反编译出来的 Shader 的 Settings 块总是以 Domain、ShadingModel 和 BlendMode 开头，无条件写出。其他每一项设置只在与 UMaterial 类默认值不同时才写出； 能往返的集合见着色器设置。当反编译到 Base.FrontMaterial 绑定时， 着色模型会被强制成 Substrate，因为 Substrate 材质自己的着色模型枚举 并不描述它的表面。

Outputs 为每个已连接的材质属性声明一个变量并绑定它，顺序固定： EmissiveColor、BaseColor、Metallic、Specular、Roughness、Anisotropy、Opacity、 OpacityMask、Normal、Tangent、WorldPositionOffset、SubsurfaceColor、CustomData0、 CustomData1、AmbientOcclusion、Refraction、PixelDepthOffset、MaterialAttributes，以及 —— 在 UE 5.4 及更新版本上 —— FrontMaterial。未连接的属性整条跳过。

终端输出节点

一个 UMaterialExpressionCustomOutput（ThinTranslucentMaterialOutput、ClearCoatNormalCustomOutput、 VolumetricAdvancedMaterialOutput、VertexInterpolator……）没有输出 pin，所以材质根节点 够不到它 —— 它改为从节点列表里导出，写成 Expression( … ) 输出绑定。每个已连接的输入 pin 声明一个 Outputs 变量，以 pin 命名，pin 的整棵输入子树写进 Graph。写成哪种 形式取决于连了几个 pin：

两种写法重新生成的都是同一个节点；多 pin 节点选用块形式，是因为它把这一意图写进语法里， 而不是留给 N 份重复的参数列表去表达。1.9.0 之前反编译成语句形式的文件 仍然会逐字节反编译成语句形式。

Class= 带的是反射类名（MaterialExpressionThinTranslucentMaterialOutput，没有 U 前缀），这是 Expression(Class=…) 能解析的写法。

[!WARNING] 输出目标节点按类加参数列表去重，所以一个材质里持有两个同类的 节点就无法往返。反编译器只导出第一个，并记录警告 Material has more than one '{Class}' node; output targets are de-duplicated by class, so only the first was exported.

能忠实还原的部分

节点遍历器对下面每个类都有一条精心写好的分支。其余全部落到 通用回退。

直接写成 DreamShaderLang 语法

未连接的操作数 pin 会退回节点自己的常量属性（如果有的话）—— Min、 Max、LinearInterpolate、Power 和 Clamp 都会读它们的 Const* 值 —— 否则退到字面量 0.0。

写成 property 声明

这些会变成 Properties 段里的条目，并在 Graph 中按名字引用。名字会做唯一化处理； 当 DreamShaderLang 标识符不得不与资产的参数名不同时，会补一条 ParameterName= 元数据。

只要有任何输入 pin 被连接，TextureSampleParameter2D 就改为写成一条精选的 UE.Expression， 参数实参和采样器实参一起带上 （自 1.3.7 起）。它的 RGBA 输出被写进一个具名临时变量一次；其他每个 pin 都变成它的 swizzle。

写成精选的 UE.Expression

这些保留手写的参数列表，而不是反射 dump，所以只有真正与节点默认值不同的属性才会出现。

UE.Expression 回退

上面没有分支的类都会被导出成一个通用的 UE.Expression 调用，反编译器同时为它记一条警告。

参数列表分两趟构建：

1. 每个已连接的输入 pin，按 pin 名命名，按 pin 顺序。
2. 每个值与类默认值不同的反射字面量属性 （自 1.3.7 起）。

一个属性只有同时满足下列全部条件，才会在第 2 趟被导出：

名字比较是在归一化之后做的，所以 bTwoSided 和 Two Sided 会冲突。

[!WARNING] struct、array、map、set 和 delegate 属性会被静默丢弃。 它们不属于受支持的属性类型， 所以一个状态存在于 struct 中的节点会以该状态在类默认值处的形式导出，并且没有任何警告指出具体是哪个属性。 首次编译后请手动重新设置这些值，或者将节点保留为 UE.Expression 并自行补上缺失的参数。

OutputType 总是会被写出，并根据真实输出索引解析。当存在具名输出选择器 （Output= / OutputName=）时，OutputIndex 会被抑制，因为同时携带两者的调用是 DSH5252。参数超过三个、或长度超过 120 个字符的调用会跨多行写出。

Layout 导出

由 Export Decompiled Layout 项目设置控制，默认开启。开启时，文件会带有一个 Layout 段：

文本以 DreamShader: 开头的注释框会被跳过——那些是生成的标记，不是作者编写的注释。

与这个设置无关，每个表达式还会被归到最小的那个包住它的注释框，这些归属会变成对应 Graph 语句周围的 #Region / #EndRegion 指令。关闭 layout 导出会去掉 Layout 块，但不会去掉 region。

参见 Layout。

诊断

运行期替换写作 {Placeholder}。

写进文件里的警告

每条只写出一次，作为 // Decompiled from … 头行下面的 // Warning: … 注释。它们 不会让导出失败。

导出失败

编辑器 toast

每个 Export 菜单项弹的是同一组 toast，2.0 的那几个也一样 （自 2.0.0 起）：

日志：Display 级的 Exported '{Asset}' to '{File}'.，以及 Warning 级的 Failed to export '{Asset}' to a DreamShader source: {Reason}。

已知往返缺口

1.5.0 的实测行为。每一行都是导出文件还原不了的东西。

示例

无头导出 /Game/Materials/M_Steel，然后看结果：

& "$Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "I:\Project\Project.uproject" `
    -run=DreamShader decompile -Asset="/Game/Materials/M_Steel" -Format=Legacy `
    -unattended -nopause -nosplash -stdout -log

DreamShader decompiled '/Game/Materials/M_Steel.M_Steel' to
'I:/Project/DShader/Decompiled/Materials/Game/Materials/M_Steel.dsm' (legacy).

写出的文件：

// Decompiled from /Game/Materials/M_Steel.M_Steel
Shader(Name="Decompiled/Materials/Game/Materials/M_Steel")
{
    Properties = {
        ScalarParameter Roughness_0 = 0.35 [ParameterName="Roughness"];
        VectorParameter Tint = float4(0.8, 0.8, 0.82, 1.0);
    }
    Settings = {
        Domain = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode = "Opaque";
    }

    Outputs = {
        float3 BaseColor;
        float Metallic;
        float Roughness;

        Base.BaseColor = BaseColor;
        Base.Metallic  = Metallic;
        Base.Roughness = Roughness;
    }

    Graph = {
        BaseColor = Tint.rgb;
        Metallic  = 1.0;
        Roughness = saturate(Roughness_0);
    }

    Layout = {
        Node(Var="Tint", X=-640, Y=-208);
        Node(Var="Roughness_0", X=-640, Y=48);
    }
}

2.0 反编译器

./dsc.ps1 decompile /Game/Materials/M_Steel                  # writes DShader/Decompiled/.../M_Steel.dss
./dsc.ps1 decompile /Game/Materials/MI_Steel_Worn            # a material instance: MI_Steel_Worn.dsi
./dsc.ps1 decompile -SourceFile DShader/Functions/Lib.dss    # every asset that source builds, in one file
./dsc.ps1 decompile /Game/Materials/M_Steel -Format Legacy   # the 1.x text described above

它就是把编译器倒着跑：图 → IR → AST → 打印器。

1. 导入。 每个表达式读回成发射器为它写下的那个 IR 操作；其余的是基于内建目录的反射 UE.<Class>(...) 节点。内联 pin mask 按发射器自己的规则变回 swizzle，注释框变成 #pragma region，节点位置变成 #pragma layout 提示。有两个类把它们的 pin 保留在任何调用都无法命名的数组里，于是被读回成它们所计算的东西：一个 Convert 节点（Make / Break FloatN）读回成每个输出由哪些通道拼出（DXY.xy、float3(Gain, 0.25, 0.75)），一个 Switch 读回成引擎为它造出的那些分支（0.0 == floor(s) ? a : 1.0 == floor(s) ? b : default，或者 SwitchValue 没接任何东西时那个数字选中的唯一一个输入）—— 用于 case 没有名字的情况。已连接的 case 全都有名字的 Switch 就是 Switch 本身，正如下面的 Landscape 节点：UE.Switch(SwitchValue = s, Dry = a, Wet = b, Inputs = "((InputName=\"Dry\"),(InputName=\"Wet\"))")。VertexInterpolator 是一个自定义输出，同时也把一个值传下去，任何读它的地方读到的都是那个值。把 pin 保留在 struct 数组里、并按各自的条目命名的类 —— LandscapeLayerBlend、LandscapeGrassOutput、LandscapePhysicalMaterialOutput，以及 RenderTrace 中形状相同的 PhysicalMaterialOutput —— 用该数组作为详情面板粘贴的文本调用，pin 省略，每个 pin 用节点在标识符形式下显示的名字：UE.LandscapeLayerBlend(Layer_Grass = g, Height_Rock = h, Layers = "((LayerName=\"Grass\"),...)")。
2. 提升。 没人读的节点被剪掉，发射器手工降级的形状被读回来（static bool 上的 StaticSwitch 是 if / ?:，Set-attributes 链是 m.X = ...）。Substrate 节点保持它本身那个调用 —— Substrate.Weight(...)、SSSMFP = Substrate.TransmittanceToMFP(...).MFP —— 所以文本给图上显示的每个节点都点了名。只有可读形式才把 Substrate 语法糖读回来，在图上精确等价的地方：什么都没设置的 SubstrateAdd / SubstrateWeight / SubstrateHorizontalMixing 是 A + B、A * w 和 lerp(A, B, t)，只喂一个 BSDF、别的什么都不喂的转换节点变成那个 BSDF 上的 BaseColor = ... / Haziness = ... / Transmittance = ...。
3. 书写。 按显示顺序写 uniform（@sort 只在优先级不是该 uniform 的位置时使用），读了两次或被语句命名的值写成局部变量，从节点代码里恢复自定义函数及其辅助函数，layer 和 blend 用它们自己的签名，图里调用的每个函数资产写一个 extern 原型。
4. 证明。 打印出的文本会被再解析一次（不行是 DSH9089），往返测试会编译它并比较 IR。

语言表达不了的都会被点名，从不静默丢掉：导入阶段是 DSH9060–DSH9074（缺失的函数资产、目录外的类、Preview pin 的默认表达式、Custom 节点上的额外 define），书写阶段是 DSH9075–DSH9084（改了名的标识符、内联写出的值的位置、从其调用推断出的 extern）。

下面这些引擎类仍然把 pin 或输出放在文本没有写法的数组里；其中一个类的节点回来是一个缺少那些连线（DSH9070）或状态（DSH9068）的反射调用，需要手工补完：

Substrate 节点按源码使用的名字写出 —— Substrate.Slab(...)，目录为该类列出的第一个别名 —— 而不是反射名 SubstrateSlabBSDF；两者解析到同一个类。

普通的 UMaterialInstanceConstant 写成 .dsi：父材质、它覆盖的 #pragma instance 键，以及与父材质不同的参数。

管线（.dsp）

（自 2.1.0 起） UDreamPassPipeline 没有图可导入。它的字段被读回成 .dsp 所绑定的那个 payload —— 即发射器所应用的映射反过来跑 —— 然后打印器把那个 payload 写成 .dsp：#pragma pipeline、uniform、buffer 和 pass，按资产的顺序，并省略每一个会读回成默认值的键。

./dsc.ps1 decompile /Game/Passes/CP_Highlight                # DShader/Decompiled/Pipelines/Game/Passes/CP_Highlight.dsp
./dsc.ps1 decompile -SourceFile DShader/Passes/CP_Highlight.dsp
./dsc.ps1 decompile /Game/Passes/CP_Highlight -Out I:/Work/CP_Highlight.dsp

没有 Content Browser 或 Material Content Browser 条目会反编译管线。

文本无法按资产本身那样表达的内容是一条警告，用英文以 // Warning: DSHnnnn: … 行的形式写在文件头部，并作为诊断抛出：

固定大小 buffer 的 Scale（资产可能仍然持有）不会被写出：Size 会将其排除。

重新解析检查。 文本被交回之前会再次解析，并在不带引擎的情况下进行绑定—— 引用按原样读取，所有需要项目的检查都被跳过——然后把它绑定到的载荷与资产的载荷进行比较，只有引擎知道的事实（引用解析成什么、 .usf 的 [numthreads]）在文本以相同方式拼写引用时取自资产。一段无法解析的文本是 DSH9221； 一段无法绑定进管线的文本是 DSH9222——资产违反了 .dsp 所检查的某条规则，这可能是手动编辑造成的， 也可能是反编译器的问题；一段读回来却是不同管线的文本是 DSH9223，会指出第一处差异。三者都是警告：文件按原样写入， 它们不会被复制到文件头部。

另请参阅

• 编辑器集成 —— Export .dss 和 Export Legacy .dsm / .dsf 菜单项
• 命令行 —— -run=DreamShader decompile、-Asset 和 -Out
• UE.Expression —— 回退路径写出的那种通用调用
• Layout —— Node 和 Comment 指令，以及 #Region
• Shader 设置 —— 导出器能写出和写不出的那些设置
• 函数设置 —— 反编译出的 .dsf 会缺失的那些键
• VirtualFunction —— 为每个被调用的函数写出的声明
• VirtualFunction 工具 —— 同一个声明构建器，从资产菜单驱动
• 资产路径 —— 写出的 Name= 解析成什么
• 图布局 —— 没有 Layout 块时会发生什么
• 项目设置 —— Export Decompiled Layout 和 Source Directory
• Substrate 内置项 —— Base.FrontMaterial 背后的 UE 5.4 门槛
• Custom Pass 管线 —— .dsp —— 管线反编译出的文本
• Divergence —— 对在详情面板中编辑过的管线使用 Adopt Into Source