Search public documentation:


Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > Materials & Textures > Allegorithmic Substance Integration

Allegorithmic Substance Integration

header.jpg width=

Substances in UDK

Substances are a new texture format offering multiple advantages over standard bitmaps:

  • Multi-output - One file can contain all the maps needed for one or more materials
  • Resolution independent - scales dynamically up to 2048x2048
  • Parametric and dynamic - modify the textures in the UDK editor or even in-game
  • Can be used as multi-purpose filters using dynamic bitmap inputs
  • Non-linear and non-destructive creation process

The Substance Ecosystem


  • Don’t know what a substance is? Check out this page for a quick overview of the technology.
  • Want to know more about Substance Designer? This is the place you are looking for.
  • Want to learn fast? Video Tutorials are available over here.
  • Don’t want to buy stuff? Substance Utilities is free.

Substance Utilities allows you to convert your textures to substances, allowing faster import times, automatic material creation and dynamic texture tweaking in the editor.

File formats

There are two main file formats in the Substance ecosystem. The editable one, text based and easily put under source control, is the sbs file format. This format is used to save packages made in Substance Designer, it can contain multiple graph, each one with several output. External resources like SVGs and bitmaps can be embedded in the sbs file, it can be compared to a .PSD file.

Before using substance files in the UDK, you have to publish it. The result of this process is a Substance archive, or sbsar file. This is the format supported in the UDK and other software where Substance is integrated. It is a compressed, binary file format and it is no longer editable.

Note: It is possible to save the values of the inputs of a Substance as presets. Those files have the extension sbsprs, and can be used to save multiple variations of a single Substance. They are text based and very light. Presets can be imported or exported from Substance Graph Instances (see "Substance Graph Instances").



SBSAR Import

When importing a sbsar, two objects are created: a Substance Instance Factory and one Graph Instance for each Graph contained in the sbsar file. The Instance Factory can be used to create other Graph Instances. An Unreal Material can also be created for each Substance Graph Instance.


  • Create Material will create a material in a subgroup of the package where the Graph Instance is created. The substance's outputs will automatically be plugged in the right material slots.

  • You can specify a destination for the Graph Instances of the Substance you are importing. In this case, both the Graph Instances and their outputs will be stored in the specified package.


Substance Graph Instances

Each graph contained in a sbsar can be instanced as many times as necessary, allowing to have different variations of a single substance. Those Graph Instances can be saved in different packages.

Modifying parameters

Graph Instance Editor

To edit input values in the Graph Instance Editor, double click on the Graph Instance of your choice and you will have access to the dynamic parameters (including image inputs).


  • Outputs
You can disable some of the outputs of the Substance depending on your needs.
  • Image inputs
Dynamic image inputs are supported through a new type of object, Substance Image Inputs. They are created by importing jpeg or tga images or by converting standard existing textures. Substance outputs can also be used directly as image inputs. Any resolution can be used, image inputs will be resized when the substance ouputs are rendered.
  • Inputs
Numeric and color inputs allow you to modify the look of the substances in real time in the UDK viewport.
  • Bake Outputs
When the Bake Outputs option if off, the substance’s outputs will be generated when their package is loaded. When it is switched on, the bitmap will be kept during the unreal cooking process (ie it will not need to be rendered at load time). The trade-off offered with this option is CPU usage (load time generation) versus size of the package (bake outputs option on). In both cases, the inputs can be still be modified and the outputs recomputed at runtime.

During the game

  • Kismet
To modify inputs using Kismet, create the appropriate sequence action from the Substance category: Set Input Float, Int or Image.


Be careful to use the identifier, which is displayed as a tool-tip of the label. Once you have modified your inputs, you have to trigger the rendering using the "Substance Render" sequence action.


  • Matinee
Create a Graph Instance Actor in your scene which will be plugged in the matinee’s data. To modify inputs, you need to create Substance Input tracks in which in you specify the input’s identifier. This works like the Material Instance Actor when modifying Material Instances.

Technical Information

Modifying Instances from Unreal Script

To modify inputs, use the Graph Instance objects (SubstanceAirGraphInstance class). The interface is the following:

// retrieve the input list
native final function array<string> GetInputNames();

// retrieve an input's type
native final function SubstanceAirInputType GetInputType(const string InputName);

// modify the input value of the specified input (by name)
native final function bool SetInputInt(const string InputName, const array<int> Value);
native final function bool SetInputFloat(const string InputName, const array<float> Value);

// modify an image input, object must be a SubstanceAirImageInput or a SubstanceAirTexture2D
native final function bool SetInputImg(const string InputName, Object Value);

// get the input value of the specified input (by name)
native final function array<int> GetInputInt(const string InputName);
native final function array<float> GetInputFloat(const string InputName);
native final function Object GetInputImg(const string InputName);

Specific INI values

  • During the cooking step, it is possible to limit the number of mip-maps kept in the packages, allowing to save significant amount of space. It is possible to setup how many mips are kept in the BaseEngine.ini config file, under the Substance section, with the MipCountAfterCooking parameter:

; number of mipmaps to keep during cooking

  • The CPU and memory budget attributed to the Substance Engine is setup in the BaseEngine.ini file, in the following section:

; memory budget
; allow use of every CPU core available for generation (will leave one free for the main thread)

Free substance resources

  • More than 60 substances are bundled with Autodesk Maya and 3dsMax (2012 and up).