DocumentationSubstance 3DPython API

event module

Last update: September 11, 2026

The event module defines application events and allows to subscribe to
notifications.

class substance_painter.event.Event substance_painter.event.Event

Base event class.

class substance_painter.event.GraphicalUserInterfaceStarted substance_painter.event.GraphicalUserInterfaceStarted

Event triggered when the GUI has finished to initialize itself.

If you want to make sure every widget part of the UI is instanciated,
wait for this event before anything.

Event dispatcher

substance_painter.event.DISPATCHER = <substance_painter.event.Dispatcher object> substance_painter.event.DISPATCHER

The event dispatcher instance that will be used by the application.

class substance_painter.event.Dispatcher substance_painter.event.Dispatcher

The Event Dispatcher.

connect(event_cls: Type[Event], callback: Callable[[Event], Any]) -> None substance_painter.event.Dispatcher.connect

Connect a callback to handle the given event type.

The callback is stored as a weak reference, it is automatically disconnected
once the callback gets garbage collected.

Parameters:

  • event_cls (Type[Event]) – An event class.
  • callback (Callable*[[Event],* Any*]*) – A method or a bound method that will be called when
    an instance of the given event class is triggered.

Return type: None

connect_strong(event_cls: Type[Event], callback: Callable[[Event], Any]) -> None substance_painter.event.Dispatcher.connect_strong

Connect a callback to handle the given event type.

The callback is stored as a strong reference, it is never automatically disconnected.

Parameters:

  • event_cls (Type[Event]) – An event class.
  • callback (Callable*[[Event],* Any*]*) – A method or a bound method that will be called when
    an instance of the given event class is triggered.

Return type: None

disconnect(event_cls: Type[Event], callback: Callable[[Event], Any]) -> None substance_painter.event.Dispatcher.disconnect

Disconnect a previously connected callback.

This method can be called to explicitly disconnect a callback.

Parameters:

  • event_cls (Type[Event]) – An event class.
  • callback (Callable*[[Event],* Any*]*) – A method or a bound method that has been connected
    to the given event class.

Return type: None

Export events

class substance_painter.event.ExportTexturesAboutToStart(textures: Dict[Tuple[str, str], List[str]]) substance_painter.event.ExportTexturesAboutToStart

Event triggered just before a textures export.

Parameters:

textures (Dict*[Tuple[str,* str*],* List*[str]]*) – List of texture files
to be written to disk, grouped by stack (Texture Set name, stack name).

class substance_painter.event.ExportTexturesEnded(status: ExportStatus, message: str, textures: Dict[Tuple[str, str], List[str]]) substance_painter.event.ExportTexturesEnded

Event triggered after textures export is finished.

Parameters:

  • status (ExportStatus) – Status code.
  • message (str) – Human readable status message.
  • textures (Dict*[Tuple[str,* str*],* List*[str]]*) – List of texture files
    written to disk, grouped by stack (Texture Set name, stack name).

Project events

NOTE
Project loading is done asynchronously. When the event ProjectOpened or
ProjectCreated is triggered, the project may still be loading. The event
ProjectEditionEntered is triggered when the project is ready to work with.

class substance_painter.event.ProjectOpened substance_painter.event.ProjectOpened

Event triggered when an existing project has been opened.

class substance_painter.event.ProjectCreated substance_painter.event.ProjectCreated

Event triggered when a new project has been created.

class substance_painter.event.ProjectAboutToClose substance_painter.event.ProjectAboutToClose

Event triggered just before closing the current project.

class substance_painter.event.ProjectClosed substance_painter.event.ProjectClosed

Event triggered just before closing the current project.

class substance_painter.event.ProjectAboutToSave(file_path: str) substance_painter.event.ProjectAboutToSave

Event triggered just before saving the current project.

Parameters: file_path (str) – The destination file.

class substance_painter.event.ProjectSaved substance_painter.event.ProjectSaved

Event triggered once the current project is saved.

class substance_painter.event.ProjectEditionEntered substance_painter.event.ProjectEditionEntered

Event triggered when the project is fully loaded and ready to work with.

When edition is entered, it is for example possible to query/edit the project
properties, to bake textures or do project export.

class substance_painter.event.ProjectEditionLeft substance_painter.event.ProjectEditionLeft

Event triggered when the current project can non longer be edited.

class substance_painter.event.BusyStatusChanged(busy: bool) substance_painter.event.BusyStatusChanged

Event triggered when Substance 3D Painter busy state changed.

Parameters: busy (bool) – Whether Substance 3D Painter is busy now.

TIP
See also:
substance_painter.project.execute_when_not_busy(),
substance_painter.project.is_busy().

class substance_painter.event.TextureStateEvent(action: TextureStateEventAction, stack_id: int, tile_indices: Tuple[int, int], channel_type: ChannelType, cache_key: int) substance_painter.event.TextureStateEvent

Event triggered when a document texture is added, removed or updated.

Parameters:

  • action (TextureStateEventAction) – Performed action (add, remove, update).
  • stack_id (int) – The stack the texture bellongs to, can be used to create a
    substance_painter.textureset.Stack instance.
  • tile_indices (Tuple*[int,* int*]*) – The uv tile indices.
  • channel_type (ChannelType) – The document channel type.
  • cache_key (int) – The texture current cache key. Those cache keys are persistent across
    sessions.

static cache_key_invalidation_throttling_period() -> timedelta substance_painter.event.TextureStateEvent.cache_key_invalidation_throttling_period

Get the minimum duration between two texture update events (for a given texture).

Returns: The minimum duration between two update events.

Return type: datetime.timedelta

static set_cache_key_invalidation_throttling_period(period: timedelta) -> None substance_painter.event.TextureStateEvent.set_cache_key_invalidation_throttling_period

Set the minimum duration between two texture update events (for a given texture).

Warning: this setting is global and every work made in a callback associated to this event
may greatly hurt the painting experience.

Parameters:

period (datetime.timedelta) – The minimum duration between two update events, can’t
be lower than 500ms.

Raises: ValueError – If period is below 500ms.

Return type: None

class substance_painter.event.TextureStateEventAction(value) substance_painter.event.TextureStateEventAction

The TextureStateEvent possible actions.

Members:

ADD, UPDATE, REMOVE

NOTE
The name used to define members is available as a string via the .name attribute (see python enum.Enum).

Shelf events

class substance_painter.event.ShelfCrawlingStarted(shelf_name: str) substance_painter.event.ShelfCrawlingStarted

Event triggered when a shelf starts reading the file system to discover
new resources.

Parameters: shelf_name (str) – Name of the shelf discovering resources.

TIP
See also:
Shelf.is_crawling().

class substance_painter.event.ShelfCrawlingEnded(shelf_name: str) substance_painter.event.ShelfCrawlingEnded

Event triggered when a shelf has finished discovering new resources and
loading their thumbnails.

Parameters: shelf_name (str) – Name of the shelf that has finished discovering resources.

TIP
See also:
Shelf.is_crawling().

Baking events

class substance_painter.event.BakingProcessAboutToStart(stop_source: StopSource) substance_painter.event.BakingProcessAboutToStart

Event triggered when a baking is about to start.

Parameters:

stop_source (StopSource) – The baking stop source, can be compared with the StopSource
returned from the baking launch methods to identify the baking process.

TIP
See also:
substance_painter.baking.bake_async()
substance_painter.baking.bake_selected_textures_async()

class substance_painter.event.BakingProcessProgress(progress: float) substance_painter.event.BakingProcessProgress

Event triggered when baking process progress changes.

Parameters: progress (float) – The baking progress, between [0.0, 1.0].

TIP
See also:
substance_painter.baking.bake_async()
substance_painter.baking.bake_selected_textures_async()

class substance_painter.event.BakingProcessEnded(status: BakingStatus) substance_painter.event.BakingProcessEnded

Event triggered after baking is finished.

Parameters: status (BakingStatus) – Status of the baking process.

TIP
See also:
substance_painter.baking.bake_async()
substance_painter.baking.bake_selected_textures_async()

Layer stack events

import substance_painter as sp

# Define a callback function that will be called
# when the LayerStacksModelDataChanged event is triggered
def on_layerstack_changed(event: sp.event.LayerStacksModelDataChanged):
    stack = sp.textureset.get_active_stack()
    # Get the list of selected nodes
    selection = sp.layerstack.get_selected_nodes(stack)
    # Print the selection
    print(selection)

# Connect to the LayerStacksModelDataChanged event
sp.event.DISPATCHER.connect(sp.event.LayerStacksModelDataChanged, on_layerstack_changed)
# After this, each event in the layerstack will trigger the callback

# Later, it is possible to disconnect the event
# sp.event.Dispatcher.disconnect(sp.event.LayerStacksModelDataChanged, on_layerstack_changed)

class substance_painter.event.LayerStacksModelDataChanged substance_painter.event.LayerStacksModelDataChanged

Event triggered whenever the status of the Layer Stacks changes.

TIP
See also:
substance_painter.layerstack

Application wide events

class substance_painter.event.EngineComputationsStatusChanged(engine_computations_enabled: bool) substance_painter.event.EngineComputationsStatusChanged

Event triggered whenever the status of the engine computations changes.

TIP
See also:
substance_painter.application.engine_computations_status()

Parameters: engine_computations_enabled (bool)

Display events

class substance_painter.event.CameraPropertiesChanged(camera_id: int) substance_painter.event.CameraPropertiesChanged

Event triggered when the camera properties change.

TIP
See also:
substance_painter.display.Camera

Parameters: camera_id (int)

class substance_painter.event.ReloadResourcesStarted(filter: AllResourcesFilter | ProjectFilter | ResourcesListFilter | ResourcesUsedByProjectFilter | SessionFilter | ShelvesListFilter) substance_painter.event.ReloadResourcesStarted

Event triggered when a resource reload operation has started.

Parameters: filter (AllResourcesFilter | ProjectFilter | ResourcesListFilter | ResourcesUsedByProjectFilter | SessionFilter | ShelvesListFilter) – The filter object used to choose the resources that are being reloaded.

TIP
See also:
substance_painter.resource.reload_modified_resources_async()

class substance_painter.event.ReloadResourcesEnded(filter: AllResourcesFilter | ProjectFilter | ResourcesListFilter | ResourcesUsedByProjectFilter | SessionFilter | ShelvesListFilter, reloaded_resources: List[ReloadedResourceResult], resource_errors: List[ReloadedResourceError]) substance_painter.event.ReloadResourcesEnded

Event triggered when a resource reload operation has completed.

Parameters:

TIP
See also:
substance_painter.resource.reload_modified_resources_async()

class substance_painter.event.ReloadedResourceResult(old_resource_id: ResourceID, new_resource_id: ResourceID) substance_painter.event.ReloadedResourceResult

Per resource result of a succesfull resource reload operation.

Parameters:

  • old_resource_id (ResourceID) – The ResourceID of the resource that was asked to be reloaded.
  • new_resource_id (ResourceID) – The ResourceID of the newly added resource.
TIP
See also:
ReloadResourcesEnded
substance_painter.resource.reload_modified_resources_async()

class substance_painter.event.ReloadedResourceError(resource_id: ResourceID, error_msg: str) substance_painter.event.ReloadedResourceError

Per resource result of an unsuccesfull resource reload operation.

Parameters:

  • resource_id (ResourceID) – The ResourceID of the resource that was asked to be reloaded.
  • error_msg (str) – The error message detailing what prevented the resource from being reloaded.
TIP
See also:
ReloadResourcesEnded
substance_painter.resource.reload_modified_resources_async()
recommendation-more-help
substance-3d-dev-help-painter-python-guide