User Guide Cancel

Unreal Engine 5 Scripting | Ecosystem and Plug-ins

Last updated on May 17, 2023

Unreal Engine 5 Scripting

The Substance in Unreal Engine plugin can be scripted. Methods are listed and annotated in the plugin's SubstanceGraphInstance.h file, which is normally found in the following directory when installing the plugin from the marketplace:

Engine Install: [UE_5.X.X location]\Engine\Plugins\Marketplace\Substance\Source\SubstanceCore\Classes\SubstanceGraphInstance.h
Project Install: [project folder loacation]\Plugins\Runtime\Substance\Source\SubstanceCore\Classes\SubstanceGraphInstance.h

BlueprintCallable indicates that the method is usable in the Blueprint editor as well.

Scripting in Unreal Engine's Python Editor

When using the methods listed in the SubstanceGraphInstance.h file in Unreal Engine's Python editor, they must be converted from Pascal Case to Snake Case (with lowercase lettering an underscore in between each word). For example, SetInputColor becomes set_input_color.

The Python Editor in Unreal Engine can be accessed via Window > Output Log, and setting the lower left dropdown to Python.

Example Scripts

Below are a set of example scripts that can be used in the Python Editor.

Create a Substance Material

# Python example on creating a Substance material. 
 
import unreal 
 
# Create factory 
sf = unreal.SubstanceFactory() 
factory = sf.import_archive("/Game", "C:/4d/unreal/stylized_lava_cracked.sbsar") 
graph_descs = factory.get_graph_descs() 
mats = unreal.SubstanceUtility.get_substance_included_materials() 
 
# Create graph instance 
for graph_desc in graph_descs: 
    print(graph_desc) 
    # You could name based on label or on index or another way 
    graph_name = "/Game/FirstInstance_" + graph_desc.label 
    material_name = "/Game/FirstMaterial_" + graph_desc.label 
    # graph_name = f"/Game/FirstInstance_{graph_desc.index}" 
    # material_name = f"/Game/FirstMaterial_{graph_desc.index}" 
    graph = factory.create_graph_instance(graph_desc, graph_name) 
    graph.create_outputs() 
    graph.create_material(material_name, mats[0]) 
    graph.set_input_color("obsidian_color", unreal.LinearColor(0, 0, 1)) 
    graph.set_input_color("lava_color", unreal.LinearColor(0, 1, 0)) 
    graph.prepare_outputs_for_save() 
    graph.render_sync() 
    graph.save_all_outputs(True)

Create a single graph of a Substance Material

# Python example on creating a Substance material. 
 
import unreal 
 
# Create factory 
sf = unreal.SubstanceFactory() 
factory = sf.import_archive("/Game", "C:/4d/unreal/stylized_lava_cracked.sbsar") 
graph_descs = factory.get_graph_descs() 
mats = unreal.SubstanceUtility.get_substance_included_materials() 
 
# Create only 1 graph instance 
graph_desc = graph_descs[0] 
print(graph_desc) 
graph_name = "/Game/MyGraphInstance" 
material_name = "/Game/MyMaterial" 
graph = factory.create_graph_instance(graph_desc, graph_name) 
graph.create_outputs() 
graph.create_material(material_name, mats[0]) 
graph.set_input_color("obsidian_color", unreal.LinearColor(0, 1, 1)) 
graph.set_input_color("lava_color", unreal.LinearColor(1, 0, 0)) 
graph.prepare_outputs_for_save() 
graph.render_sync() 
graph.save_all_outputs(True)

Create multiple instances of a Substance Material with different parameters.

# Python example on creating mulitple Substance materials. 
 
import unreal 
 
# Create factory. Should only need 1 factory, even if multiple instances are created 
sf = unreal.SubstanceFactory() 
factory = sf.import_archive("/Game", "C:/4d/unreal/stylized_lava_cracked.sbsar") 
graph_descs = factory.get_graph_descs() 
mats = unreal.SubstanceUtility.get_substance_included_materials() 
 
# Create first graph instance 
for graph_desc in graph_descs: 
    graph_name = "/Game/FirstInstance_" + graph_desc.label 
    material_name = "/Game/FirstMaterial_" + graph_desc.label 
    graph = factory.create_graph_instance(graph_desc, graph_name) 
    graph.create_outputs() 
    graph.create_material(material_name, mats[0]) 
    graph.set_input_color("obsidian_color", unreal.LinearColor(0, 0, 1)) 
    graph.set_input_color("lava_color", unreal.LinearColor(0, 1, 0)) 
    graph.prepare_outputs_for_save() 
    graph.render_sync() 
    graph.save_all_outputs(True) 
 
# Create second graph instance 
for graph_desc in graph_descs: 
    graph_name = "/Game/SecondInstance_" + graph_desc.label 
    material_name = "/Game/SecondMaterial_" + graph_desc.label 
    graph = factory.create_graph_instance(graph_desc, graph_name) 
    graph.create_outputs() 
    graph.create_material(material_name, mats[0]) 
    graph.set_input_color("obsidian_color", unreal.LinearColor(1, 0, 1)) 
    graph.set_input_color("lava_color", unreal.LinearColor(1, 1, 0)) 
    graph.prepare_outputs_for_save() 
    graph.render_sync() 
    graph.save_all_outputs(True)

Duplicate a Substance Graph

# Python example on duplicating a Subtance material. 
 
import unreal 
 
# Create factory 
sf = unreal.SubstanceFactory() 
factory = sf.import_archive("/Game", "C:/4d/unreal/stylized_lava_cracked.sbsar") 
graph_descs = factory.get_graph_descs() 
mats = unreal.SubstanceUtility.get_substance_included_materials() 
 
# Create first graph 
for graph_desc in graph_descs: 
    print(graph_desc) 
    graph_name = "/Game/FirstGraph_" + graph_desc.label 
    material_name = "/Game/FirstMaterial_" + graph_desc.label 
    graph = factory.create_graph_instance(graph_desc, graph_name) 
    graph.create_outputs() 
    graph.create_material(material_name, mats[0]) 
    graph.set_input_color("obsidian_color", unreal.LinearColor(0, 0, 1)) 
    graph.set_input_color("lava_color", unreal.LinearColor(0, 1, 0)) 
    graph.prepare_outputs_for_save() 
    graph.render_sync() 
 
# Duplicate graph 
new_material_name = "/Game/SecondMaterial" 
new_graph = graph.duplicate() 
new_graph.create_outputs() 
new_graph.create_material(new_material_name, mats[0]) 
new_graph.prepare_outputs_for_save() 
new_graph.render_sync()

Get help faster and easier

New user?