Lexical Elements

This page covers the character-level rules: which tokens care about case, how comments and literals are read, and how a section body is cut into statements. Most of it is unsurprising. The three parts that are not — the case-sensitivity matrix, the tolerant numeric conversion, and the tab pitfalls — are the reason this page exists.

Case sensitivity

Top-level block keywords are the only case-sensitive tokens in the language. Everything else keyword-like is matched ignoring case.

So shader(Name="X") and SHADER(Name="X") are both syntax errors, while properties = { … }, settings { domain = "ui"; } and Shader(name="X") are all accepted.

A keyword match additionally requires a right word boundary: the character after the keyword must not be a letter, a digit or _. That rule is what stops ShaderFunction from matching as Shader, and ShaderLayerBlend from matching as ShaderLayer.

Synopsis

<token> := <identifier> | <keyword> | <string-literal> | <numeric-text> | <punctuation>

<identifier>     := { <letter> | _ } { <letter> | <digit> | _ }…
<qualified-name> := <identifier> :: <identifier>
<string-literal> := " { <character> | \<escape> }… "
<punctuation>    := { | } | ( | ) | [ | ] | ; | = | , | . | :: | #

Whitespace and comments may appear between any two tokens and are otherwise insignificant.

Whitespace

Any character the engine considers whitespace separates tokens: space, tab, carriage return, line feed and the other Unicode whitespace characters. Newlines carry no syntactic weight in the declaration grammar — they matter only to line-oriented processing: import directives, #Region directives inside a Graph body, and diagnostic line numbers.

Comments

• Block comments do not nest. /* a /* b */ c */ ends at the first */; the trailing c */ is code again.
• An unterminated block comment is accepted silently. A /* with no */ consumes the rest of the file and produces no diagnostic. Contrast an unterminated { block, which fails with Unterminated block.
• Comments are recognised identically everywhere in the declaration grammar, including while counting {}, () and [] nesting, so a brace or quote inside a comment never unbalances a block.
• Comment removal happens a second time, textually, before statements are split in Properties, Settings, Outputs, Layout and typed-parameter sections. That pass is string-aware and preserves the line feed that terminates a line comment, so line numbers survive.
• Graph bodies are not comment-stripped by the declaration parser. Comments inside a Graph block are stored verbatim with the body and handled later by the expression tokenizer.
• There is no # preprocessor at the declaration level. #Region / #EndRegion are recognised only inside Graph bodies — see Layout and #Region.

Identifiers

There is no length limit, and no keyword is reserved against identifiers: nothing rejects a property, variable, parameter or function named Shader, Graph or float. Whether the name then resolves is a matter for the context it appears in.

A stricter check applies to declaration names in Inputs, Outputs, Results and Layout calls: the whole trimmed token must match the identifier rule. Names in Properties are only required to be non-empty, so Properties { float 1Bad = 0; } parses — the declaration is simply unreachable from Graph.

Namespace-qualified names use ::, as in Common::ApplyTint. See Functions.

Sanitisation

When a name reaches generated HLSL it is sanitised: every character outside A–Z a–z 0–9 _ becomes _, a leading digit gains a _ prefix, runs of consecutive __ collapse to one, and a result that is empty or entirely underscores becomes DreamShaderSymbol.

Common::ApplyTint   →   Common__ApplyTint   →   Common_ApplyTint

That collapse is why Common::ApplyTint and a top-level Common_ApplyTint collide in generated code.

String literals

A quoted value opens with ", ends at the next unescaped ", and is unescaped on the way in. A backslash always consumes the following character, so \" never terminates the literal.

Anywhere a value may be quoted — settings values, metadata values, attribute values, argument values — quoting is optional. The raw text is trimmed, and quotes are stripped only if the result is at least two characters long and both starts and ends with ". Domain = UI; and Domain = "UI"; are equivalent.

There are no numeric escapes. \0, \xNN and \uNNNN fall into the "any other character" row, so \0 yields 0 and \x41 yields x41.

The Graph expression grammar uses the same five escapes and the same pass-through rule; an unterminated string there is closed silently at end of input instead of erroring.

Numeric literals

The declaration grammar and the Graph expression grammar disagree here, and the difference is a common source of surprise.

Declaration grammar

The declaration grammar has no numeric token. Values are captured as raw text and converted only when a consumer asks for a number.

The vector-literal form is deliberately loose. The first ( and the last ) delimit the components, and the text before ( is ignored entirely — float3(1,0,0), vec3(1,0,0), (1,0,0) and Nonsense(1,0,0) all parse identically. The interior is split on , without tracking nesting, so a nested call in a component breaks the split. Each component may be a number or true / false.

The unfilled default is (0, 0, 0, 1).

Graph expression grammar

Inside a Graph block a number is a real token.

A suffix is consumed only when the character after it is not a letter, a digit or _, and it is excluded from the token text: 0.55f is the number 0.55. Because only one suffix is consumed, 1.0ul lexes as the number 1.0 followed by the identifier ul.

The expression tokenizer accepts these single-character tokens: ( ) , . + - * / =, plus the two-character ::.

Statement separation

A section body is a list of ;-separated statements.

• A ; separates statements only at parenthesis depth 0 and bracket depth 0, and never inside a string literal.
• Braces are not tracked by the generic splitter. Properties uses its own brace-aware walker so that Group("…") { … } scopes work; every other section treats { as an ordinary character.
• Empty statements are dropped, so a stray ;; is harmless.
• The final statement is flushed even without a terminator — the last ; in a block is optional.
• The ; after a section's closing } is optional, and so is the = between a section name and its block since 1.5.0.

Three different splitters then divide a statement into parts, and they do not agree on what counts as whitespace:

Argument lists are split on , with the same depth and string tracking, which is why an unquoted attribute value may not contain , or ): Root=Game works, Name=Foo(1,2) does not.

Example

// Line comment before the top-level declaration.
Shader(Name="Materials/M_Comments")
{
    /* Block comment
       spanning multiple lines. */
    Settings = {
        Domain = "UI";        // trailing line comment
        ShadingModel = Unlit; // quotes are optional
    }

    Properties {
        // Any whitespace may separate a Properties type from its name.
        ScalarParameter Rough = 0.5 [Group="Surface"; Slider(0, 1)];
        vec3            Tint  = vec3(1.0, 0.4, 0.1);
        float           Fudge = 1.0f;   // parses as 1.0 — the suffix is ignored, not rejected
    }

    Outputs {
        vec3 Color;                     // a literal space is required here
        Base.EmissiveColor = Color
    }                                   // the last ';' in a block is optional

    Graph {
        vec2 UV = UE.TexCoord(Index = 0);
        Color = vec3(Rough, Rough, UV.x) * Tint;
    }
}

Diagnostics

Only messages ending in near index {Index} carry a position the diagnostic mapper can turn into a file, line and column. See Imports.

Where to next