DocumentationSubstance 3DPython API

SourceFont

Last update: September 11, 2026

SourceFont is a type of source where you can connect a font resource.

For more information, see module resource.

Example

import substance_painter as sp

# Get the currently displayed stack
stack = sp.textureset.get_active_stack()

# Insert a fill layer
position = sp.layerstack.InsertPosition.from_textureset_stack(stack)
fill = sp.layerstack.insert_fill(position)

# Setup warp projection
params = sp.layerstack.WarpProjectionParams(
    uv_wrapping_mode=sp.layerstack.UVWrapMode.RepeatNone,
    projection_depth=0.3,
)
fill.set_projection_parameters(params)

# Pick a font resource
font = sp.resource.search("u:font")[0]
source = fill.set_source(sp.textureset.ChannelType.BaseColor, font.identifier())

# Customize font parameters
params = source.get_parameters()
params.text = "Hello World"
params.color = sp.colormanagement.Color(0.8, 0.2, 0.2)
source.set_parameters(params)

# Select the Fill layer
sp.layerstack.set_selected_nodes([fill])

class substance_painter.source.SourceFont(uid) substance_painter.source.SourceFont

A class that represents a text source.

property resource_id: ResourceID substance_painter.source.SourceFont.resource_id

The current font resource of the source.

Getter: Returns the resource identifier of the font used by the source.

get_parameters() -> SourceFontParams substance_painter.source.SourceFont.get_parameters

Get the source parameters.

Returns: The source parameters.

Return type: SourceFontParams

set_parameters(params: SourceFontParams) -> None substance_painter.source.SourceFont.set_parameters

Set the source parameters.

Parameters: params (SourceFontParams) – The source parameters.

Raises:

ValueError – If the parameters requirements are not met,
see SourceFontParams.

Return type: None

uid() -> int substance_painter.source.SourceFont.uid

Get the object internal uid.

Returns: The internal identifier of the object as an integer.

Return type: int

Params

class substance_painter.source.SourceFontParams(text: str | None, auto_size: bool, size: float | None, horizontal_alignment: HorizontalAlignment, vertical_alignment: VerticalAlignment, color: Color, background_color: Color, background_opacity: float | None, line_spacing: float, character_spacing: float, offset: Tuple[float, float], resolution: ResolutionOverride) substance_painter.source.SourceFontParams

The source font parameters.

Parameters:

  • text (str | None) – The text to render.
  • auto_size (bool) – Automatically adjust size to fit the render resolution.
  • size (float | None) – Manual size of the font, normalized and proportional to the resolution.
    Value must be positive.
  • horizontal_alignment (HorizontalAlignment) – The horizontal position of the text (left, center, right).
  • vertical_alignment (VerticalAlignment) – The vertical position of the text (top, middle, bottom).
  • color (Color) – The text color as RGB values. Values must be in range [0, 1].
  • background_color (Color) – The RGB background color. Values must be in range [0, 1].
  • background_opacity (float | None) – The background opacity value. Value must be in range [0, 1].
  • line_spacing (float) – Distance between lines of text (“leading”) relative to the font size.
  • character_spacing (float) – The amount of space between adjacent characters relative to
    the font size. Can be negative to subtract spacing.
  • offset (Tuple*[float,* float*]*) – Horizontal and vertical offset of the text. Normalized to the font size.
  • resolution (ResolutionOverride) – Resolution parameters of the resource.
  • resolution_mode (FontResolutionMode) – Deprecated since 0.3.4. Use mode attribute from resolution
    parameter instead.
  • resolution_value (Tuple*[int,* int*]*) – Deprecated since 0.3.4. Use value attribute from resolution
    parameter instead.

Enums

class substance_painter.source.FontResolutionMode(value) substance_painter.source.FontResolutionMode

Members:

Name
Description
Auto
Resolution is automatically computed.
Manual
Resolution is manually provided.
WARNING
Deprecated since 0.3.4, use ResolutionMode instead.
NOTE
The name used to define members is available as a string via the .name attribute (see python enum.Enum).

class substance_painter.source.HorizontalAlignment(value) substance_painter.source.HorizontalAlignment

Members:

Name
Description
Left
Align the text to the left.
Center
Center the text horizontally.
Right
Align the text to the right.
NOTE
The name used to define members is available as a string via the .name attribute (see python enum.Enum).

class substance_painter.source.VerticalAlignment(value) substance_painter.source.VerticalAlignment

Members:

Name
Description
Top
Align the text from the top.
Middle
Center the text vertically.
Bottom
Align the text from the bottom.
NOTE
The name used to define members is available as a string via the .name attribute (see python enum.Enum).
recommendation-more-help
substance-3d-dev-help-painter-python-guide