Functions

Function and GraphFunction move reusable logic out of raw Graph statements. Both take a C-style signature and an HLSL body, and every call site becomes one Custom node whose code is that body; the difference is what happens to the UE.* calls in it. The legacy front end reads both as 2.0 /// @custom functions (since 2.0.0), and dsc migrate writes them that way.

No shared .ush include is written any more: each node's Code carries all the HLSL it needs (since 2.0.0). Namespace groups either kind under an Ns:: prefix.

Synopsis

Function      [ ( <attributes> ) ] [ { Inline | SelfContained } ] [ <return-type> ] <name> ( [ <parameter-list> ] ) { <hlsl> }
GraphFunction [ ( <attributes> ) ]                                [ <return-type> ] <name> ( [ <parameter-list> ] ) { <hlsl> }

<attributes>     := Generate = <string> [ , Library = <string> ] [ , Description = <string> ]

<parameter-list> := <parameter> [ , <parameter> ] …
<parameter>      := [ { in | out } ] <type-token> <parameter-name>

The only (Key = Value) header is the optional one after the keyword (after 2.1.2): Generate, Library and Description, which mean something in a package's header only — the material function the package generates from the function; Generate = "" opts the function out of its namespace's template. Another key is DSH6331, a {...} other than {Name} in a template DSH6332. See Packages ▸ Asset headers. There are no Settings and no sections. The { … } after the parameter list is raw HLSL, kept verbatim: only its braces are read, and a brace inside a string or a comment does not count.

The keywords Function and GraphFunction are case-sensitive (function is DSH2240); the modifier, the in / out qualifiers and every type token are not.

Declaration order

The parser reads identifiers left to right and disambiguates by lookahead: after one identifier, a ( makes it the name; another identifier makes it the return type and the next identifier the name.

The modifier is therefore fixed in first position, right after the keyword.

Warning:

A function may not be named Inline or SelfContained. Function SelfContained(in float a, out float b) { … } takes the modifier branch and finds ( where the name should be: DSH6300. The old section-style body Function Name { Inputs = { … } Code = { … } } is DSH6300 too.

Parameters

A parameter is the words up to the next , or ); any whitespace — tabs and line breaks included — only separates them. Two or three words are accepted:

At least one output

A function must produce something: either at least one out parameter or a return type. Neither is DSH6305.

Return type

A return type implies exactly one output and forbids every explicit out. Multiple outputs require out parameters and no return type.

return is no longer rewritten

return stays as written (since 2.0.0). 1.x replaced every top-level return with an assignment to a synthetic __return result; now the body is the body of the HLSL function that returns the node's first output — the Custom node's own, or the helper's when another body embeds it. A return expr; therefore returns the value at any brace depth, and the nested case that bypassed __return in 1.x behaves like the top-level one.

What is still checked: a top-level bare return; under a return type (DSH6308), a return; anywhere in a function without one (DSH6256), and a return type whose body has no return at all — the warning DSH6257, the output will be 0. A body that is one bare expression is given its return. The name __return stays reserved.

Accepted parameter types

The 15 GLSL aliases are normalised to their HLSL spellings at parse time, and a scalar or vector in another case (Float3) is read in lower case. A token that names no type is DSH4201 at the declaration (since 2.0.0) (1.x failed only when the function was called).

The generated HLSL spells every type the 2.0 way: vec3 is float3, MaterialAttributes is FMaterialAttributes, VolumeTexture is Texture3D.

Warning:

Substrate is never usable on a Function or a GraphFunction: a Custom node has no Substrate pins in any engine version. Build the Substrate part in a ShaderFunction or in the Shader's Graph.

Texture parameters and samplers

Texture2D, TextureCube, Texture2DArray, Texture3D and VolumeTexture are texture parameters. On the node one is a pin carrying the texture object, and the engine declares SamplerState <Name>Sampler beside it — use that name in the body. Embedded as a helper, its HLSL signature gains SamplerState <Name>Sampler after each texture parameter, and every call to it from another body passes <argument>Sampler after the texture argument; such a call has to pass every argument (DSH6262), and its texture argument has to be a plain name (DSH6263). A parameter of your own called <Texture>Sampler collides with the pair (DSH6255). SamplerState is not a texture parameter and gets no companion.

<Texture>.Sample(UV) on a texture parameter — and SampleLevel, SampleBias, SampleGrad with one argument fewer than HLSL's own form — is rewritten to the engine's Texture2DSample(<Texture>, <Texture>Sampler, UV) family (since 2.0.0); the native HLSL spellings stay as written.

Function SampleTinted(in Texture2D tex, in vec2 uv, in vec3 tint, out vec3 rgb, out float alpha)
{
    float4 texel = Texture2DSample(tex, texSampler, uv);
    rgb   = texel.rgb * tint;
    alpha = texel.a;
}

Body normalisation

Every Function and GraphFunction body — and nothing else in the language — goes through an identifier-level rewrite before it is stored. The scan skips comments and strings and does two things: it substitutes 18 aliases (the 15 GLSL type spellings plus mix → lerp, fract → frac, mod → fmod), and it flattens A::B (no spaces around ::) to the sanitised identifier A_B.

Warning:

Because the alias match ignores case and applies to whole identifiers anywhere in the body, a helper of your own called Mix, Mod, Fract, Vec3 or Mat4 — or a variable by one of those names — is silently renamed in the emitted HLSL. There is no diagnostic — the DSH5277 warning for a GLSL spelling covers Graph text only. Rename it, or spell it so it does not collide (MixColor, ModValue).

The flattened Common_Remap01 is exactly a namespaced function's name, so a Ns::Fn(…) call inside a body now reaches that function (since 2.0.0).

Leading #include hoisting

(since 1.8.0)

#include directives at the top of a body — only whitespace and comments may precede them — are not part of the function. They are blanked out of the body (overwritten with spaces, so every later line and column still matches the source) and hoisted onto the include list (IncludeFilePaths) of every Custom node whose code holds the body: the function's own nodes, and the node of any other Function that embeds it, the embedded functions' includes first (since 2.0.0).

Function float3 SampleWind(in float3 WorldPos)
{
    #include "/Plugin/DreamWind/Shared/DreamWindShared.h"   // hoisted
    FDreamWindSample S = DW_SampleAnalytic(DW_UnpackParams(P0, P1, P2), WorldPos);
    return S.Velocity;
}

The engine puts a node's includes at file scope, so a header that defines functions works. This is what lets a header shared between C++ and HLSL be consumed directly, without copying its functions into DreamShaderLang.

Generated HLSL

A call site's Custom node carries all of its HLSL in its own Code (since 2.0.0):

struct generated_wrapper_<Name>_<CRC32>          // only when the body calls other Functions
{
	<Type0> DreamShaderFn_<Callee>(<params>)     // one member per embedded Function,
	{                                            // a callee before its caller
		// Begin DreamShader source: <file>
		// DreamShader custom: <Callee> line <N>
		<callee body, verbatim>
		// End DreamShader source: <file>
		return <Out0>;
	}
};
generated_wrapper_<Name>_<CRC32> __ds_wrapper_<CRC32>;

<Type0> <Out0> = (<Type0>)0;                     // the first out, for a function without a return type
// Begin DreamShader source: <file>
// DreamShader custom: <Name> line <N>
<body, verbatim; calls to embedded functions go through __ds_wrapper_<CRC32>>
// End DreamShader source: <file>
return <Out0>;                                   // appended only when the body has no top-level return

The node's title (its Description) is the function's name — Ns::Fn for a namespace member.

Inline / SelfContained

Every call site's node holds the function's own body and every other Function that body calls, transitively, as members of the generated_wrapper_* struct — HLSL has no nested functions, and a Custom node's code is a function body. 1.x did this only for a SelfContained function and otherwise referenced its shared include; 2.0 has no shared include, so every function gets what SelfContained asked for, and the modifier is read and changes nothing (since 2.1.1). (2.0.0 – 2.1.0 read it as /// @custom selfcontained, which embeds nothing, so each call such a body made was left for the shader compiler and failed.)

Inline is the old spelling of SelfContained; it reads the same, with the warning DSH6306. A call from a body to something that is not a Function — a ShaderFunction or a VirtualFunction — is DSH6261; to a GraphFunction with lifted UE.* calls, DSH6327. A call that matches a function only in case is the warning DSH6259 and is left for the shader compiler.

GraphFunction and UE.* hoisting

(since 1.3.1)

When the body is read it is scanned, and every UE.* call is recorded as a lifted call. When the node's code is built, the call's text is replaced by the name of a generated input pin, which carries the material expression the call evaluates to.

A call is lifted only when all of these hold, in order:

If steps 1–4 fail, the text is copied through silently. If step 5 fails, the body is DSH6314. The scan skips comments, strings and character literals, so a UE.Time() inside a comment is not lifted.

The extracted text is parsed as a Graph expression, so any UE.* builtin — UE.Expression included — is available. It is bound in the function's own scope (since 2.0.0): its parameters, replaced at each call by that call's arguments, and the file's file-scope declarations. A name only the caller has is DSH6325 — 1.x evaluated lifted calls in the caller's Graph scope; pass the value as a parameter. A name nobody has, a variable the body itself declares included, is DSH6326.

Generated pin names

So a GraphFunction WindPulse whose body contains one UE.Time() call produces a pin literally named:

_ds_WindPulse_UE0

and a namespaced Common::Pulse produces _ds_Common_Pulse_UE0. The declared in parameters take the first pins, in declaration order; lifted pins follow. These names are user-visible on the generated node and in any shader-compiler error that mentions them.

Note:

The lift consumes exactly UE.Name( … ) up to the matching ) — nothing more. A trailing swizzle or member access stays behind as HLSL applied to the pin, so UE.CameraVector().xy becomes _ds_<Fn>_UE0 .xy and is evaluated by the shader compiler; the pin carries the node's default output at its full width. The pin name is padded with spaces to the call's length, so every later column of the body still matches the source.

Warning:

Only UE. is lifted. A Substrate.* call is not, and reaches the shader compiler as text, where it is not valid HLSL; the front end says so with the warning DSH6316 (since 2.0.0). Substrate values cannot cross a Custom node boundary at all — build Substrate graphs in a ShaderFunction or a Shader's Graph.

A lifted call has to produce something a Custom input carries: a number, a bool, or a texture object (since 2.0.0). A MaterialAttributes value or a Substrate material is DSH6329. A node with several outputs feeds the pin its default output.

GraphFunction WindPulse(in float2 uv, out float pulse)
{
    float t = UE.Time();
    pulse = sin(uv.x * 8.0 + t);
}

One call generates:

UMaterialExpressionTextureCoordinate   →  Custom pin "uv"
UMaterialExpressionTime                →  Custom pin "_ds_WindPulse_UE0"
UMaterialExpressionCustom  Description="WindPulse"  OutputType=CMOT_Float1

float pulse = (float)0;
// Begin DreamShader source: DShader/Lib/Motion.dsh
// DreamShader custom: WindPulse line 4

    float t = _ds_WindPulse_UE0;
    pulse = sin(uv.x * 8.0 + t);
// End DreamShader source: DShader/Lib/Motion.dsh
return pulse;

Additional out parameters are the node's additional outputs, named after the declared parameters (since 2.0.0) (1.x named them after the caller's variables), and the body assigns them directly. Plain Function calls in the body are embedded as in a Function node.

Namespace

Namespace prefixes the names of the Function and GraphFunction declarations it contains. It is not an entity: no object is stored for it and it creates no scope. A member's name is the flattened identifier (since 2.0.0):

Namespace(Name = "Common") { Function ApplyTint(…) }   →   Common::ApplyTint   →   function Common_ApplyTint

Name lookup, binder diagnostics and the helper symbol DreamShaderFn_Common_ApplyTint all see Common_ApplyTint; the qualified spelling survives in one place — the title (Description) of the member's Custom node is Common::ApplyTint, as in 1.x.

Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }

    Function float Remap01(in float value) {
        return saturate(value * 0.5 + 0.5);
    }

    GraphFunction Pulse(in float speed, out float value) {
        value = sin(UE.Time() * speed);
    }
}

Graph = {
    vec3 Tinted;
    Common::ApplyTint(BaseColor, Tint, Tinted);   // statement call
    float K = Common::Remap01(Tinted.r);          // value call
}

Warning:

Because :: and _ flatten to the same thing, the member ApplyTint of Namespace(Name="Common") and a top-level Function Common_ApplyTint declare the same name: DSH4210.

Inside another Function or GraphFunction body, Ns::Fn(…) now reaches the function (since 2.0.0): body normalisation rewrites Common::ApplyTint to Common_ApplyTint, which is now the function's own name, so the call is embedded like any other Function call. In 1.x it reached the shader compiler as an undefined Common_ApplyTint and failed there. Write :: without spaces around it.

Calls

Both call forms live in a Graph block.

Too many arguments are DSH4224; an input left out is DSH4217. Named arguments are accepted now (since 2.0.0): they name a parameter (DSH4216 for a name it does not have), and a call that uses them is matched by name and declaration order rather than as inputs-then-receivers. The mangled spelling DreamShaderFn_Luma(c) no longer names the function (since 2.0.0): DSH4208.

Full argument rules, default and output selectors: Calls.

Notes

• One name declares one thing. Two functions of one name — in a file, or in a file and a header it imports — are DSH4210; A::B and A_B are the same name. A Function and a GraphFunction of one name are DSH4210 too (since 2.0.0) (1.x reported the call as ambiguous). A function named like a builtin (lerp, saturate, …) is DSH6206. There is no overloading.
• Names are case-sensitive (since 2.0.0). Luma and luma are two functions; a Graph call that matches one only in case still resolves when the match is unique, with the warning DSH5275.
• Headers are parsed on their own. An imported .dsh is not pasted into the file; its functions are declared into it. See Imports and Namespaces.
• A .dsm or .dsf holding only Function / GraphFunction blocks compiles and produces nothing.
• On UE 5.3 the generated Custom nodes show their code in the material graph; from UE 5.4 on ShowCode is set to false.

Example

// DShader/Lib/Color.dsh

Function float Luma(in vec3 color)
{
    return dot(color, float3(0.299, 0.587, 0.114));
}

Function Remap01(in float value, out float result)
{
    result = saturate(value * 0.5 + 0.5);
}

import "Lib/Color.dsh";

Shader(Name="Materials/M_Tinted")
{
    Properties = {
        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_Base");
        vec3                     Tint    = vec3(1.0, 0.6, 0.2);
    }
    Outputs = {
        vec3 Color;
        Base.EmissiveColor = Color;
    }
    Graph = {
        vec2 UV  = UE.TexCoord(Index = 0);
        vec4 Tex = BaseTex(Coordinates = UV);

        float Key;
        Remap01(Luma(Tex.rgb), Key);      // statement call with a nested value call

        Color = Tex.rgb * Key;
    }
}

Each call is a Custom node. The Luma node's code — note the body's own return:

// Begin DreamShader source: DShader/Lib/Color.dsh
// DreamShader custom: Luma line 4

    return dot(color, float3(0.299, 0.587, 0.114));
// End DreamShader source: DShader/Lib/Color.dsh

Diagnostics

Which one to use

Where to next

• Calls — Every argument form, default and output selectors.
• Imports and Namespaces — Bringing a helper header into the file that calls it.
• UE.* Nodes — Everything a GraphFunction body can lift.
• Types and Values — Signature type tokens and their HLSL spellings.