Project Configuration Files - SBSPRJ


Project configuration files are the most complex and most expansive files used to configure Substance Designer. They are special in that you can use multiple Project Configuration files, where each next "Child" Project expands or overrides the previous "parent". Unless explicitly needed, settings should not be modified or added to the Project files, so Designer can fall back on its parent configuration, or even defaults.

By default, Designer has 2 Project Configurations active:

  • Default Project
    Contains all the default settings and the library Designer comes with on a fresh install. Read only, can not be modified or removed.
  • User Project
    Because the Defaults are read-only, any changes by the user go into this project by default. Can not be removed.

This basic setup ensures that the default library and other settings can not be corrupted or modified, yet still allow single, amateur users to add their own modifications without having to bother with complex setups.

Expand or Override

Most settings in a consecutive Project will override the ones from the previous Project. For example, a different Tangent Space plugin in a custom Project file will override any TS Plugin defined in the Default or User project. This means that unless explicitly needed, it's recommended not to override or change settings in child projects.

There are however some settings that expand upon parent settings, instead of overriding them. Most notably these settings are the Library paths and filters, so you always add more content to the library instead of overriding it. Additionally, there's the aliases (path keywords for relative filepaths) that expand, as well as override if a duplicate is defined. This allows for great control over content filepaths and references.

Project File contents

Project files can contain the following settings. 

  • 3D View
    Default Shader, HDR and scene state definitions.
  • Aliases
    Keyword aliases for relative paths.
  • Baking
    Settings for baking naming conventions.
  • General
    Graph Templates, Tangent Space plugins, normal and image format defaults.
  • Library
    Watched paths to display in the Library, as well as filters and categories for the Library view.
  • MDL
    MDL watched paths.
  • Scripting
    Callback scripts and interpreters.
  • Version Control
    Settings for integrating Version control into Designer.

Modifying Project Files

Project configurations are, like all other types, saved as structured XML files (using an ".sbsprj" extension) that can be modified through the  Designer UI, or through an external text editor.

When creating a Project file for a studio, the recommended workflow is to start from the user_project, modify it through the UI to get started and do the first basic setup, then move to editing with a Text Editor like Notepad++, to ensure the author fully comprehends the file's contents (especially for relative paths this is important). 

The only exception would be Defining Library Filters, as this quickly becomes cumbersome in a text-editor. See relevant page.

Preferences menu

Access the regular Designer Preferences menu: Edit > Preferences..., and click the "Projects" section on the left.

Under Project Files you select whichever Project file to modify, in the bottom half you use the tabs to navigate to the relevant settings section and change the values.

Edit XML Externally

For Windows Notepad++ is a good free option, for OSX Sublime Text 2 is an alternative. However, any editor with proper indentation, section collapsing and some form of syntax highlighting will make your life much easier.

Once you open the SBSPRJ file in an editor, you should see a fairly straightforward structured layout, with sections corresponding to tabs in the UI. Not every setting will be documented here, as it's fairly self-explanatory.

Relative paths and Aliases

Relative paths combined with Aliases are one of the more complicated, yet most important parts of a Project configuration, this section will clarify them. 

One of the major problems with files referencing other files in a system across multiple user's PC, is that absolute filepaths will not work. Users can define their SVN repositories in completely different locations (eg. C:/John/Gamedev/SubstanceLibrary or D:/Dev/SubstanceLibrary). Aliases and relative paths both work together to solve this problem. Otherwise, you might open someone else's file and it will try to look for the custom node used in the specific location that user had it locally, which you probably won't have defined in exactly the same way.

An Alias is a keyword that replaces (part of) a path. It's similar to a Windows environment variable like %TEMP%, where a single word replaces an often-used path that is then defined centrally. The advantage is simplified paths everywhere, and a way to modify all the references in one go when you decide to relocate the this path.

Alias Example

AliasActual path value
sbsC:\Program Files\Allegorithmic\Substance Designer\resources\packages
customD:\Dev\CustomProject\Substance

The default library is by default located at C:\Program Files\Allegorithmic\Substance Designer\resources\packages, and all graphs using default content reference this directory. Instead of referencing the full path, an alias of "SBS" (without quotation marks) is defined. In the case of a the default library, the exact value for the SBS path is set upon installation to whichever directory the user chooses for Substance Designer.

Internally a reference is modified the following way, when it contains a path with an alias:

C:\Program Files\Allegorithmic\Substance Designer\resources\packages\blur_hq.sbs => sbs://blur_hq.sbs


Relative paths are always relative to the file in which they are defined. That means the current location of the config file determines most of the path, and Alias paths will be based upon it, mostly by just adding a subfolder. This means it's strongly recommended to put your sbsprj files next to the folders you want to watch!

For example, take a repository at C:/Versioncontrol/Substance/ containing CustomProject.sbsprj and two folders, /Base and /Tools containing nodes.

To define two relative Aliases for Base and Tools would be done as following inside the SBSPRJ file:

CustomProject.sbsprj
			<urlaliases>
				<size>2</size>
				<_2 prefix="_">
					<path>file:Base</path>
					<name>BaseAlias</name>
				</_2>
				<_1 prefix="_">
					<path>file:Tools</path>
					<name>ToolsAlias</name>
				</_1>
			</urlaliases>

The result of this config file is the following:

BaseAlias:// will be C:/Versioncontrol/Substance/Base/ and ToolsAlias:// will be C:/Versioncontrol/Substance/Tools/.

If you would want to define just  C:/Versioncontrol/Substance/, the path would be listed as "file:.", the dot signifying the location of the file itself.