MaterialAttributes

DreamShader » Graph » MaterialAttributes

A struct-like Graph value that carries a whole material's attribute set as one connection, written and read member by member. (since 1.2.5)

Synopsis

MaterialAttributes <name> ;                       // creates an empty attribute set
MaterialAttributes <name> = <material-attributes-expression> ;

<name> . <member> = <expression> ;                // member write

<expression> := <name> . <member>                 // member read

., = and ; are literal DreamShaderLang punctuation. <member> is one of the names in Members.

The value type

Creating a value

[!WARNING] In a Shader, an Outputs declaration creates the variable (since 2.0.0). Every Outputs declaration is declared at the top of the material's body, and a MaterialAttributes one starts as an empty set, so Attrs.BaseColor = Tint; works with no Graph declaration at all. A MaterialAttributes Attrs; in the Graph names that same variable and adds nothing:

Outputs { MaterialAttributes Attrs; Base.MaterialAttributes = Attrs; }
Graph   { MaterialAttributes Attrs; Attrs.BaseColor = Tint; }

In a function block a MaterialAttributes output is the function's output: the attributes written to it make its set, and reading one never written is DSH4370.

[!NOTE] MaterialAttributes B = A; is a value copy, not an alias. A later B.Roughness = r; changes B only; A keeps its attributes.

Members

The attribute table is the engine's (since 2.0.0): an attribute this engine does not have is DSH5200. A member name is matched exactly first (name or alias), then ignoring case, with the warning DSH5276. Aliases are exact synonyms.

The 1.x aliases CustomizedUVs0 … CustomizedUVs7 are not in the alias table (since 2.0.0); write CustomizedUV0 … CustomizedUV7.

MaterialAttributes (alias Attributes) resolves as a member (since 2.0.0; 1.x rejected it): it is the whole set, and it is what the binding Base.MaterialAttributes = Attrs; writes. To replace a Graph variable's whole set, assign the variable itself: Attrs = Other;.

[!NOTE] The engine fork macro MOON_ENGINE adds the members MoonEncodedAttribute0 through MoonEncodedAttribute4. The pre-rename spelling MooaEncodedAttribute0 … MooaEncodedAttribute4 is accepted as an alias, so decompiled MooaToon functions still parse. They do not exist in a stock UE 5.3–5.8 build.

Reading a member

A read of an attribute the body has already written in this value is that written value; no node is made. Any other read comes from one UMaterialExpressionBreakMaterialAttributes per value, shared by all of that value's reads (since 2.0.0; 1.x made one Break node per read).

[!WARNING] A read that has to go through the Break node needs the engine's Break node to publish the attribute; one it does not publish is DSH8216. This depends on the engine build. A value with nothing to read from — a function's MaterialAttributes output before anything was written to it — is DSH4370.

The read result is a plain numeric value with the member's component count, so it may be swizzled: Attrs.BaseColor.r is an attribute read followed by a channel selection.

Writing a member

A member write records the value for that attribute; a later write of the same attribute replaces it. Nodes are made where the value is used — passed to a function or a pin, assigned to an output, bound to the material: one UMaterialExpressionSetMaterialAttributes on top of the value's set, with one pin per attribute written so far (since 2.0.0; 1.x chained one Set node per write). A value with no set underneath — a function's output — becomes one MakeMaterialAttributes with the written pins instead.

Coercion follows the normal rules: a scalar spreads, a wider value is cut to its leading components (DSH5289), and a float2 assigned to a float3 member is an error. See Conversions.

[!NOTE] Attrs.BaseColor.r = 1.0; is DSH2206. There is no per-channel attribute write in a 1.x Graph; build the full value first.

A declared name is one identifier, so MaterialAttributes A.B = x; is DSH2154 (since 2.0.0).

Brace initializers on a member

Attrs.BaseColor = {1.0, 0.35, 0.1}; is DSH2162 (since 2.0.0): a brace list is read only as a declaration's initializer. Write the constructor, Attrs.BaseColor = float3(1.0, 0.35, 0.1);.

Passing attribute values around

Binding Base.MaterialAttributes is documented in full in Output bindings.

Substrate interaction

Substrate is a separate value type, not an attribute set, and requires UE 5.4 or newer. The two never convert into each other.

See Substrate builtins for the Substrate.* call surface.

Diagnostics

Example

Shader(Name="Docs/M_MatAttrs")
{
    Properties {
        vec3            BaseTint = vec3(0.6, 0.8, 1.0);
        ScalarParameter R        = 0.35 [Group="Surface"];
    }

    Settings {
        Domain       = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode    = "Opaque";
    }

    Outputs {
        MaterialAttributes Attrs;
        Base.MaterialAttributes = Attrs;
    }

    Graph {
        MaterialAttributes Attrs;

        Attrs.BaseColor = BaseTint;
        Attrs.Roughness = R;
        Attrs.Metallic  = 0.0;

        // Read a member back out and feed it to another member.
        float Rough     = Attrs.Roughness;
        Attrs.Specular  = Rough * 0.5;
    }
}

Generated nodes:

VectorParameter           BaseTint                       (property node)
ScalarParameter           R
MakeMaterialAttributes                                    -> Attrs (empty set)
Constant                  0.0
Constant                  0.5
Multiply                  R * 0.5                         (the read of Roughness is R itself)
SetMaterialAttributes     base=Make, BaseColor=BaseTint, Roughness=R,
                          Metallic=0.0, Specular=Multiply -> Base.MaterialAttributes

The material's Use Material Attributes flag is set by the Base.MaterialAttributes binding.

See also

• Output bindings — Base.MaterialAttributes and the full target catalogue
• Declarations — declaration forms, default values and the redeclaration rule
• Statements — member assignment as a statement form
• Conversions — the conversion applied to every member write
• Constructors — the constructor to write instead of a brace list
• Swizzle — selecting channels of a member read
• if / else — choosing between two attribute values
• Calls — passing attribute values into and out of functions
• Node reuse — which nodes are deduplicated
• Substrate builtins — the Substrate.* surface and the UE 5.4 gate
• Types — every type token and where each is valid