Creating Library Filters For Projects


If you have custom nodes and want to share them studio-wide by integrating, you will want to integrate them into the library as seamlessly as possible. This page explains how to plan for and actually create new categories and sections in the library.

You are free to categorize filters any way you want using the single-level folder system. It does pay off however to plan in advance how you will sort your filters. Try to identify at least the major categories you want to use, as it influences how you label your graphs.

Graph Attributes

Every graph inside a package has an "Attributes" section in its properties. Most other reource types have similar Attributes. Their main purpose is Library categorization, so standard users might not be familiar with using these. The following sections can be filled out:

  • Identifier, or Base Name.
    The name of the graph inside the package. Must be filled out, can not contain spaces, does not have to be extremely descriptive. Should never be changed once it is used by other graphs, will break references otherwise!
  • Description.
    Intended for summarizing the graph's functionality.
  • Category.
    Mainly intended for sorting and categorizing in the Library.
  • Label.
    UI only label, used for naming graphs in the library view. This should be descriptive and can always be changed at a later point.
  • Author
    Used to identify the original author of a graph.
  • Author URL
    Can be used by authors who publicly release their graphs, to lead users back to their website.
  • Tags
    Additional descriptive data that is used by the Library search option. (outside of Identifier and Label, only tags are searched for keywords)
  • User Data
    Additional, uncategorized slot that can be used for any purpose, mainly library categorization. 
  • Show In Library
    Boolean flag to hide content in the library. Very useful for hiding old, deprecated content that can not be removed for compatibility reasons.
  • Icon
    Bitmap used in the Library view as thumbnail. Should be at least 128x128 pixels.


Filter Creation

Filters are simple boolean (True/False) search parameters that will result in a resource showing up inside the Library when that Filter is selected. Resources can be anything kept inside a package. Keep the following in mind:

  • A Filter will match against all resources, under all watched paths.
  • A Filter can contain multiple conditions, all of them must evaluate to True (AND-condition) for the resource to show up under that filter.
  • A resource can show up under multiple filters, it is not exclusive to any filter.
  • A resource from a watched path is still available in the Library even if it is not under any Filter, by using the search function.

Filters can be created in the Library panel of Substance Designer through a few simple buttons:

Creating Filters and Folders

The three buttons marked in red are the following:

  1. Add Folder. Creates an expandable folder in the Library view. You can not create Folders inside Folders.
  2. Add Filter. Adds a new Filter inside the selected folder. You can not add filters to the existing default Folders.
  3. Edit Item. Edits the currently selected Folder or Filter. You can not edit any of the properties of the default Folders and Filters.



Editing Filters and Folders

Folders only have the first two options, all the rest are only for Filters.

  1. Name displayed in the Library tree view.
  2. Project Configuration file (SBSPRJ) in which this item is stored. It's very important to set these up correctly, to ensure you are editing the correct project!
  3. Resource Type filter. If you only want a specific resource type, such as Graphs, set the dropdown accordingly.
  4. Attribute to apply condition to. See list above.
  5. Condition logic, allows for positive and negative, partial and whole matches.
  6. Condition keyword, must be filled out to perform any filtering beyond resource type.
  7. Buttons to add and remove more conditions. Plus adds a new Filter, X removes the current one.



Custom Library Tips

If you keep the above creation methods and attribute properties in mind, there are a few important guidelines to stick with:

  1. Don't create custom nodes that mix with the default library unless you explicitely want them to. Your nodes will show up under default filters if they match, so you'll have to make sure to use a different system to avoid that.
    The general rule for the default library is the Folder is listed in the Category Attribute, the Filter name is determined by the Tag Attribute. So avoid using the exact same names in the Category attribute of your content.
  2. Use unique, per-project identifiers. These can be put anywhere you want (such as Description, Category or User Data), as long as you are consistent between all projects. You'll need these to sort per project in the library.
  3. Introduce a system to keep track of the original author in the Attributes: that way you can identify the person initially responsible for the content, without having to dig through Version control records.
  4. For creating Icons, create a (few) substance graphs with templates for the icons. That way you can ensure consistency and save work on creating them. All default library icons were created within Designer this way!

Apart from that, there are many ways to manage adding content to the library:

  • You can add resources to existing categories if this makes more sense. It will be less work to manage and maintain filters, and you can use a special Icon style to tell them apart.
  • You can define your folders and filters in your first, global (studio-level) Project Configuration file, and then add content into them merely by adding watched paths from consecutive Project files.
  • Or you can redefine your Folders and Filters for every project to keep them separated.
  • You can mix and match and use methods from all three above: use existing filters, define new global ones, and create per-project unique ones.