Building a layer stack with the Substance Painter Python API

Why script the layer stack

Since the 2024 release (Painter 10.0), substance_painter.layerstack can insert and edit layers programmatically. That turns a documented material design into a one-click build: instead of hand-placing a dozen fills and masks, a script rebuilds the whole stack on the active texture set. It is the mechanism behind Smart Material Studio's Painter export.

The core calls

Get the active stack, then insert into it:

import substance_painter.layerstack as ls
import substance_painter.textureset as ts

stack = ts.get_active_stack()
top = ls.InsertPosition.from_textureset_stack(stack)

group = ls.insert_group(top)
fill  = ls.insert_fill(ls.InsertPosition.inside_node(group, ls.NodeStack.Content))

Set channels on a fill layer with a channel type and a colour:

import substance_painter.colormanagement as cm
from substance_painter.textureset import ChannelType

fill.set_source(ChannelType.BaseColor, cm.Color(0.40, 0.18, 0.09))
fill.active_channels = { ChannelType.BaseColor, ChannelType.Roughness, ChannelType.Metallic }

Masks and generators

Add a black mask to a layer, then insert a generator effect into the mask stack:

fill.add_mask(ls.MaskBackground.Black)
import substance_painter.resource as rsc
res = rsc.search("Metal Edge Wear")[0]
ls.insert_generator_effect(
    ls.InsertPosition.inside_node(fill, ls.NodeStack.Mask),
    res.identifier())

Wrap edits in a ScopedModification so they land as a single undo step, and guard resource lookups - a shelf that lacks a named generator returns an empty list, so fall back to a plain mask rather than crashing.

Common traps

• Channel casing: ChannelType members are exact - AO and Emissive are not Ao/emissive. Resolve via an alias table plus getattr if you support older builds.
• Missing channels: setting a source on a channel the texture set lacks fails - add the channel first, or degrade gracefully.
• Version: the layerstack module is 2024+. Guard against import errors and message the user rather than half-building.
• Resources must exist: generators reference shelf resources on the user's machine; the script cannot ship them.

Let the tool write it

Smart Material Studio generates this script for you from a visual design, including the alias resolver, the add-channel fallback and the graceful mask degradation. Design the material, tune the channels, and export the .py - then run it in Painter.