Graph instances in Substance model graphs
This pages explains the concept of graph instances and their use for Substance model graphs in Adobe Substance 3D Designer.
Overview
You can use graphs in other graphs. This lets you split graphs into pieces of functionality which can be reused in multiple other graphs, even in different packages. This accelerates your workflow and makes work more efficient.
- A graph A used in another graph B is called a subgraph of graph B
- The node that references graph A in graph B is called an instance node of graph A
All changes made in a subgraph apply to all instance nodes of that graph.
Instance nodes can be identified by their icon:
Instance nodes create dependencies
If an instance node for a subgraph in package A is created in a graph in package B, then package A becomes a dependency of package B.
I.e., Designer needs to be able to load package A in order to load package B properly.
If package A is misplaced – e.g., renamed, moved or deleted – then instance nodes referencing subgraphs in that package become Ghost instance nodes: nodes that reference a subgraphs which cannot be found.
To learn more about ghost instances and how to fix them, go to Warnings in Substance model graphs.
Creating instance nodes
There are multiple ways of creating an instance node for a subgraph inside another graph:
A - Drag and drop the subgraph from the Explorer into the Graph View
B - Drag and drop the item referencing the subgraph from the Library into the Graph View
C - Press Spacebar in the Graph View to display the Node menu, input a search term which includes the subgraph's label or identifier, select the item referencing the subgraph in the list, then press Enter
Options B and C both require that the package which includes the subgraph is added to the Library. Go to the Library section of the Project settings page to learn more about adding your own content. Then, find out about managing this content.
An instance node labeled after the subgraph label – or identifier if no label is set – is added to the graph.
Cyclical dependencies
It is not possible to create instance nodes for graph A in graph B when graph B is itself a direct or indirect dependency of graph A. This also applies to any other recursive combination (A in A, A in B in C in A, ...).
These operations would result in cyclical dependencies, which is forbidden.
Accessing a subgraph from its instance
If you need to inspect and edit a subgraph, you can access it quickly from its instance node by performing either of these operations:
- Select the instance node and press the Ctrl+E keystroke
- Click RMB on the instance node and select the Open reference option in the contextual menu
The subgraph is then opened in a separate Graph View tab. If the subgraph is located in a separate package, that package is loaded in the Explorer.
You may then perform any edits on the subgraph, and they will be carried over to all its instances.
Atomic nodes
The nodes listed in the Nodes reference (...) section are atomic nodes. You can find them in the Substance model graphs section of the Library.
These are implemented directly through code, which means there is no subgraph driving them and their functionality cannot be edited.
Outputs
To send their result in other graphs, subgraphs need output nodes – e.g., Output scene, Output float, Output vector3...
Each output of a subgraph appears as an output connector on its instance nodes.
When a change is applied on an output of a subgraph, the change is carried over to all its instance nodes.
The order of the connectors matches the order of the subgraph's outputs.
The label of the connectors match the label of the subgraph's outputs – or identifier if no label is set – and use those outputs' descriptions as tooltips.
After the label, the data type of the output appears between parentheses.
E.g.: My Output (Scene), My Float Value (Float)
Inputs
A subgraph's inputs – i.e., its exposed parameters – are listed in the Properties panel when its instance is selected.
When a change is applied on an input of a subgraph, the change is carried over to all its instances.
To learn more about creating inputs in subgraphs, go to the Exposing parameters section.
Input parameter widget
Exposed parameters can be tweaked using its control widget in the Properties panel.
This widget lets you tweak a value within of bounds of the soft range that is set for that parameter in the subgraph.
Alternatively, you may double-click the widget to set an arbitrary value outside of the soft range. In that case, that value is restricted to the bounds of the hard range that is set for that parameter in the subgraph.
Soft and hard ranges
The hard range defines the bounds of accepted values. It is fixed and defined by the user. Input values out of this range are clamped to the range's closest limit.
The soft range is used to set the bounds of the parameter's widget in graph properties and instance nodes, and is always adjusted to both fit in the hard range and contain the value.
Input connector
An input connector appears for each parameter where that input is enabled.
You can choose to have an input connector enabled by default when creating new instance nodes,
by setting the Connector visible by default property to True for an exposed parameter in the subgraph.
You may connect these input connectors to output connectors of other nodes which reference data of matching type.
The order of parameters and connectors match the order of the subgraph's inputs.
The label of the connectors match the label of the subgraph's inputs – or identifier if no label is set – and use those inputs' descriptions as tooltips.
After the label, the data type of the input appears between parentheses.
E.g.: My Input (Scene), My Float Value (Float)
Default value and connected behaviour
The value set for an exposed parameter in a subgraph becomes the default value for that parameter is all its instances.
When the connector for an input parameter is connected to another node in the graph, its current value is overridden by the value received from that other node. All nodes follow this behaviour.
Inputs visibility
The Visible If property of input parameters lets you control whether the parameter appears in the instance node's properties and its input connectors – depending on the Connector visible by default parameter value, see above.
The parameter is visible if the expression written in the Visible If property evaluates to True. The syntax and behaviour is identical to Visible if property in Substance graphs.
