Plug names play a key role in the usability of a graph and in the way it can be connected to other nodes or even used in Painter. And finding the right name is not easy...

Fortunately some naming conventions exist in Substance Designer. Here they are.

 
Version:
1.0
Released:22/12/2016
Substance Designer:5.4 and higher
 
 

 

 

 

 

When creating a graph in Substance Designer you have to provide a name for each input and output plug. And for the graph to be easily reused you want those plugs to be identified without ambiguity. You also would like to be consistent with other nodes so that the user doesn't have to search for a plug each time she wants to make a connection. At you also would like your graph to be able to connect with existing nodes when the Material Connection Mode is on.

All this can easily be done by following the naming conventions below. Those conventions are coming from Substance Designer, there are more or less rigorously applied in the nodes provided with the application, not introduced in the official documentation and not always consistent with Substance Painter. I hope this will help you for your next graph designs.

 

How node connections work

When you create a graph in Substance Designer you often want it to have input plugs, so as to get some images and use them inside the graph, and output plugs to return the result of the computation of this graph. These input and output plugs appear when input and output nodes are introduced into the graph.

The way 2 nodes get connected depends on the Link mode set in the graph toolbar. There are 3 modes, each one has its specificities.

 

Standard connection mode

This is the most common mode. A connection between 2 plugs is done by drag-and-dropping the output plug of a node onto the input plug of another one. Only 1 connection link is created and if the color format of the input plug is not the same a Greyscale Conversion node may be automaticaly inserted.

 

materialmode normal

 

Material connection mode

The Material connection mode allow you to make several connections between 2 nodes in a single mouse action. It saves some time and prevents mistakes in connections. To work efficiently though it requires source node output plugs and destination input plugs to be properly configured so that a correspondance is found between them.
Note that when the Material connection mode is active you will not be able to connect single plugs toghether if the plug attributes doen't match. 

 

materialmode material

 

Here are the rules the attributes of the input and output nodes must respect:

  • Group attribute: The connections will be done from plugs of a group to plugs of another group. It doesn't matter if the source and destination group names are not the same.
  • Usage attribute: A connection can be created between 2 plugs only if both the color channel AND the usage name of the source and destination graphs match.

 

Notes:

- Changing the Usage color channel doesn't affect the image itself, it is just connection information.
- On output nodes changing the Format attribute will set the color depth of the output image. It will not modify how this plug will be connected.
- A color image plug is orange on the graph instance, a greyscale image plug is grey. The fact that an input plug is a color or a greyscale one depends on the type on the input node introduced in the graph (color or greyscale inputs). For an output plug it works differently: its color type depends on the color type of the image the output node received in its own input (in other words the color type of a graph output plug is defined by the design of the graph).

 

Compact Material connection mode

Same behavior and connection rules as Material mode except that nodes get displayed in a "compact" way in the Graph View: only 1 plug appears per plug group.

 

materialmode compactmaterial 

 

How to know how plugs are configured on a graph from the default Substance Library

It would be really nice if a tooltip could appear when the mouse cursor is over a plug and would display all the plug information.

Unfortunately this is not the case, you then have to open the instanced graph and check its content manually. Right-clik on the node and choose Open Reference: the graph is then loaded, it then appears in the Package Explorer panel and gets opened in a new tab in the Graph Panel. If you double-click on the loaded graph name in the Explorer panel or on the graph background in the Graph panel the graph attritues will be displayed in the Attributes panel. At this point it would also be nice, consistent and time saving if the input and output plug attributes could be available in this parameter list, with all the other attributes. As it is not the case either you have to search for the right input or output node in the graph, select it and check its attribute values.

 

Attributes purpose explained

The input and output nodes have several attributes. Some of them play a functional role that is important to have in mind when designing a graph. Using the right name or value for each of them allows your graph to be consistent and complient with the existing nodes in Substance Designer and to have a predicatble behavior when connected to them.

Identifier attribute

The Identifier attribute is mandatory. It is the name of the node and it must be unique. If deleted or if another node of the same type with the same Identifier exists then the string provided as an Identifier will be automaticaly incremented. The Identifier does not play any role in the way plugs get connected.

 

attribute identifier

 

Identifier is:

  • displayed above nodes, in a light and italic font
  • used in functions to get the image corresponding to the plug
  • used by Mutator, the Batch Tool which allow some command line modifications of a .SBS file (note that Mutator expect the case of its parameters to match the one of the attributes in the .SBS graph)
            eg: --connect-image "position"@path@"D:\Temp\__ExportsSBS\Knot\TopoMaps\TorusKnot001_position.png"@tiling@1@format@RAW@level@0

Altough it is technically possible to have an input and an output with the same Identifier it is highly recommended to use non-ambigous names. My personnal convention consists in adding a suffix "_output" to the output node Identifier. I applyed it to the convention presented here.
As for many coding languages I also use a lower case first letter in the Identifier names.

Label attribute

The Label is the "display name" of the plug. When no Label has been defined the Identifier is used instead.
Label is not mandatory and has no functional role.

 

attribute label

 

Label is:

  • displayed in bold font above the node
  • also displayed near the plug of the graph instance when the Display Connector Name setting is checked and and the mouse cursor is over the graph instance

 

Group attribute

The Group allows several plugs to be visually gathered together and to be all connected at the same time when the connection mode of the Graph View is set to Material or Compact Material.

Group is:

  • required to connect plugs toghether in Material or Compact Material Connection mode
  • displayed before the name of the Input or Output node in the Graph Attributes Panel

 

Usage attribute

The Usage attribute is made of a color channel part and a name part. The role of the color channel is still unclear for me and I don't remember ever seeing it with another value than RGBA. At the contrary the role of the name part is decisive to define the type of the node and how it behaves during Material or Compact Material Connection modes.

 

attribute usage

 

Usage is:

  • required to connect plugs toghether in Material or Compact Material Connection mode
  • displayed in the tooltip of the Output nodes (but not on the one of Input nodes)

The attribute Usage is probably the most important one among the node parameters because it defines its type and how it is interpreted during automatic connection. For some reasons it is not put so much to the front (or event not visible at all in the case of SBSAR nodes) which often leads to unclear and frustrating situations.

 

Most common naming conventions used in Substance Designer

All those conventions are also compatible with Substance Painter. In particular this means that topo map inputs will automatically receive the topo maps baked inside Substance Painter.

The syntesis below covers the most common kinds of plugs used when creating Substance graphs in Substance Designer, and the most common way they are used. Input and output nodes may belong to an other category in some graphs.

 

Some advices:

  • In Substance Designer default nodes no distinction is done between the input and output node identifiers. To avoid any possible ambiguity I personnaly prefer to add the suffix "_output" to output node idendifiers. This has no impact on the way graphs work.
  • In your graphs match the lower and upper cases mentionned here . Although this doesn't seem to affect the way Substance Designer works using a wrong letter case with the Baker Tools can generate errors (and a huge waste of time, believe me!).
  • Respect as much as possible the same order of the inputs and outputs. This has no impact on the graphs behavior but will avoid visual crossing links.
  • It is possible to assign input or output to an other group according to the purpose of the graph.

 

Group Material  (Metallness/Roughness PBR material)

FonctionTypeIdentifierLabelUsage (*)Group (*)  
Base Color In basecolor Base Color RGBA baseColor Material  
  Out basecolor_output Base Color RGBA baseColor Material  
Metallic Grey In metallic Metallic RGBA metallic Material  
  Grey Out metallic_output Metallic RGBA metallic Material  
Roughness Grey In roughness Roughness RGBA roughness Material  
  Grey Out roughness_output Roughness RGBA roughness Material  

 (*): Required for Material Connection mode

 

Group Material  (plugs common to all material types)

The following nodes are often assigned to the specified group but may also receive another one according to the use of their parent graph.

FonctionTypeIdentifierLabelUsage (*)Group (*)  
Normal (**) In normal Normal RGBA normal Material  
  Out normal_output Normal RGBA normal Material  
Height Grey In height Height RGBA height Material or Mesh Data (***)  
  Grey Out height_output Height RGBA height Material or Mesh Data (***)  
Emissive In emissive Emissive RGBA emissive Material  
  Out emissive_output Emissive RGBA emissive Material  
Opacity Grey In opacity Opacity RGBA opacity Material  
  Grey Out opacity_output Opacity RGBA opacity Material  

 (*): Required for Material Connection mode
 (**): Normal stands for Tangent Space Normal
 (***): Height usualy belongs to the group Material but is sometimes found in Mesh Data

 

Group Mesh Data

FonctionTypeIdentifierLabelUsage (*)Group (*)  
Position In position Position RGBA position Mesh Data  
  Out position_output Position RGBA position Mesh Data  
World Space Normal In normalWS World Space Normal RGBA normalWS Mesh Data  
  Out normalWS_output World Space Normal RGBA normalWS Mesh Data  
Curvature Grey In curvature Curvature RGBA curvature Mesh Data  
  Grey Out curvature_output Curvature RGBA curvature Mesh Data  
Ambient Occlusion Grey In ambient_occlusion (**) Ambient Occlusion RGBA ambientOcclusion Mesh Data  
  Grey Out ambient_occlusion_output (**) Ambient Occlusion RGBA ambientOcclusion Mesh Data  
Thickness Grey In thickness Thickness RGBA thickness (***) Mesh Data  
  Grey Out thickness_output Thickness RGBA thickness (***) Mesh Data  

 (*): Required for Material Connection mode
 (**): Substance Designer uses the Identifier ambientOcclusion but oddly if you use this spelling Painter will not recognize it and will not automatically connect it to the Ambient Occlusion object map. As far as I've seen Ambient Occlusion is the only map in Painter where Idendifier attribute seems to be involved in the automatic connection. This is very strange and highly inconsistent.
 (***): If the name Thickness doesn't appear in the list just type it in the Usage dropdown component. Before validating make sure the name is right spelled and in lower case!

 

Group UVs

FonctionTypeIdentifierLabelUsage (*)Group (*)  
UVs In uvs UVs RGBA UVs UVs  
  Out uvs_output UVs RGBA UVs UVs  
Material IDs In materialIDs Material IDs RGBA materialIDs UVs  
  Out materialIDs_output Material IDs RGBA materialIDs UVs  
Color IDs In colorIDs Color IDs RGBA colorID UVs  
  Out colorIDs_output Color IDs RGBA colorID UVs  

 (*): Required for Material Connection mode

 

Other naming conventions

Group Material (Specular/Glossiness PBR material)

FonctionTypeIdentifierLabelUsage (*)Group (*)  
Base Color In basecolor Base Color RGBA baseColor Material  
  Out basecolor_output Base Color RGBA baseColor Material  
Specular In specular Specular RGBA specular Material  
  Out specular_output Specular RGBA specular Material  
Glossiness Grey In glossiness Glossiness RGBA glossiness Material  
  Grey Out glossiness_output Glossiness RGBA glossiness Material  

 (*): Required for Material Connection mode

 

Group Material (Diffuse/Specular material)

FonctionTypeIdentifierLabelUsage (*)Group (*)  
Diffuse In diffuse Diffuse RGBA diffuse Material  
  Out diffuse_output Diffuse RGBA diffuse Material  
Specular In specular Specular RGBA specular Material  
  Out specular_output Specular RGBA specular Material  

 (*): Required for Material Connection mode

 

 

 

SDPlugNamingConventions Package

The graphs in SDPlugNamingConventions.sbs (package can be downloaded from the top of the page) illustrates how naming conventions for input and output image plugs are used in Substance Designer.

Having these graphs under the hand is very useful when creating new graphs. You may want to declare them as templates.

 

Discussion and support

You can provide feedback or questions here:

https://forum.allegorithmic.com/index.php/topic,14548.0.html

 

Change log

     - V1.0 (22/12/2016):    Substance Designer 5.4
            - basic version