Layout and

Layout pins generated node positions and declares comment boxes, replacing the automatic layout pass. #Region groups graph statements so the automatic pass has something to draw a box around. Neither changes shader math.

The two live in different places: Layout is a section next to Graph; #Region directives are written inside the Graph body.

Synopsis

Layout [=]
{
    Node( Var = "<variable>", X = <int>, Y = <int> ) ;
    Comment( Name = "<title>", X = <int>, Y = <int>, W = <int>, H = <int>
             [, Color = float4( <r>, <g>, <b>, <a> )] ) ;
    …
}

Statements are ;-separated calls. Statement names and argument keys are matched case-insensitively, and the = before the block is optional since 1.5.0. Layout is accepted in Shader, ShaderFunction, ShaderLayer and ShaderLayerBlend, and is not accepted in a VirtualFunction, which generates no graph.

Node

Pins one already-generated expression to an exact position.

Var names a value recorded during graph construction. Three kinds of name are recorded:

Both MaterialExpressionEditorX/Y and the editor graph node's NodePosX/Y are written, so the position survives reopening the material.

Comment

Creates a comment box at an exact rectangle.

The Color literal follows the general vector-literal grammar: the token before ( is ignored, so float4(…), vec4(…) and (…) all parse. One component splats to (x, x, x, 1), two give (x, y, 0, 0), three give (x, y, z, 1), and components past the fourth are parsed and discarded.

Generated comment boxes always use FontSize = 24 and group mode, so dragging the box moves the nodes it encloses.

Argument parsing

Coordinate space

Positions are Unreal material-graph editor coordinates: X increases to the right, Y increases downward. Negative X is "upstream"; the material root node sits to the right of everything else.

The constants the automatic layout pass uses make a useful frame of reference when placing nodes by hand:

Vertical stride is 220 for property nodes and automatic layout rows, 180 for function inputs and outputs.

Explicit versus automatic layout

A Layout block does not merely add to the automatic pass — it replaces the ranking algorithm.

On the explicit path, expressions the block did not name are still placed: positions propagate iteratively from already-positioned neighbours — midway between a known consumer and a known dependency, 360 left of a known consumer, or 360 right of a known dependency — with a collision fan-out for coincident slots. Anything still unplaced goes into a fallback column to the left of everything positioned.

#Region / #EndRegion

Region directives live in Graph body text, not in Layout. They name a span of graph statements; the layout pass turns each distinct region name into a comment-box block.

Graph = {
    #Region "Surface"
    Color = BaseColor.rgb;
    Rough = Roughness;
    #EndRegion

    #Region "Emissive"
    Glow = Tint * Intensity;
    #EndRegion
}

A statement inside a region tags the variable it produces with the region name. On the automatic layout path each region becomes one comment box; on the explicit path region names contribute the block boundaries used to decide where cross-block reroutes are inserted.

There is no other # directive. #Region is recognised only inside a Graph body; a # anywhere else is not a directive.

Notes

• Comment text is always prefixed with DreamShader: . Comment(Name="Sampling", …) produces a box reading DreamShader: Sampling. That prefix is also the teardown marker: on regeneration, comment boxes whose text starts with DreamShader: are deleted and rebuilt, and boxes that do not carry the prefix survive. A hand-authored comment box is the only hand edit that survives a regeneration. See Regeneration.
• A Comment whose Name is empty or whitespace after unquoting is rejected at parse time, so no box is ever created for one.
• The decompiler emits Layout blocks in exactly this format, so a material can be exported, edited and regenerated with its positions intact. Emission is controlled by the Export Decompiled Layout project setting, on by default.
• The automatic pass gives up on very large graphs. At or above 1200 expressions it logs Skipping automatic layout for large DreamShader graph ({Count} nodes). Existing generated positions will be used. and leaves construction-time positions in place. A Layout block is the way to control those graphs.

Example

Shader(Name="Materials/M_Layout", Root="Game")
{
    Properties {
        VectorParameter Tint      = float4(0.4, 0.8, 1.0, 1.0);
        ScalarParameter Intensity = 2.0 [Slider(0, 10)];
    }

    Outputs {
        float3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        #Region "Emissive"
        float3 Boosted = Tint.rgb * Intensity;
        Color = Boosted + vec3(0.05, 0.05, 0.05);
        #EndRegion
    }

    Layout {
        Comment(Name="Emissive", X=-1300, Y=-260, W=1100, H=520,
                Color=float4(0.10, 0.22, 0.16, 0.35));
        Node(Var="Tint",      X=-1200, Y=-160);
        Node(Var="Intensity", X=-1200, Y=  60);
        Node(Var="Boosted",   X= -800, Y=-160);
        Node(Var="Color",     X= -400, Y= -60);
    }
}

Generated graph:

Comment      "DreamShader: Emissive"   at (-1300, -260)  size 1100 x 520
Tint         VectorParameter           at (-1200, -160)
Intensity    ScalarParameter           at (-1200,   60)
Boosted      Multiply                  at ( -800, -160)
Color        Add                       at ( -400,  -60)
DS_Color_<n> NamedReroute              positioned by propagation

Nothing reaches disk unless the material is persisted — see the transient-mode warning above.

Diagnostics

Where to next