Python

Material Smith’s editor subsystem, TAMaterialSmithSubsystem, exposes the same steps as the panel to Blueprint and Python: find texture sets, preview them, create the material instances and pack channels.

Note

Python scripting requires Unreal’s Python Editor Script Plugin to be enabled in your project.

Get the subsystem

import unreal

smith = unreal.get_editor_subsystem(unreal.TAMaterialSmithSubsystem)

In Blueprint, get the editor subsystem and use the functions in the ta Material Smith category.

Functions

Function	Returns
find_texture_sets_in_folders(folders, recursive=True, find_meshes=True)	Array of TAMaterialSmithTextureSet
find_texture_sets(assets, find_meshes=True)	Array of TAMaterialSmithTextureSet
get_default_options()	TAMaterialSmithOptions
preview_texture_set(set, options)	(notes, warnings), two lists of strings
get_preview(set, options)	TAMaterialSmithPreview
create_material_instances(sets, options)	TAMaterialSmithResult
pack_channels(request, save)	(texture, error)
get_master_material(virtual_textures=False, create_if_missing=True)	Material or None
get_master_profile(material)	TAMaterialSmithMasterProfile
save_master_profile(profile)	Nothing
is_built_in_master(material)	bool
open_panel_with_folders(folders)	Nothing
open_panel_with_assets(assets)	Nothing
open_channel_packer(textures)	Nothing

find_texture_sets_in_folders

Finds texture sets among the Texture2D assets in content folders such as "/Game/Props". With recursive the subfolders are searched too. With find_meshes each set’s meshes are filled; see Meshes.

find_texture_sets

Finds texture sets among a list of unreal.AssetData, for example the Content Browser selection. Assets that are not 2D textures are ignored.

Both functions use the detection settings from Project Settings and return the sets sorted by folder and name. Textures that don’t match any name ending are not returned.

get_default_options

Returns the options from Project Settings > Plugins > ta Material Smith: Default Master as master, and the Defaults settings except Two Sided when Masked, which applies when sets are found. update_existing is always True.

preview_texture_set and get_preview

Return what create_material_instances would do for one set, without changing anything. The master material is not created by a preview. preview_texture_set returns the lines of What will happen as two lists; get_preview returns a TAMaterialSmithPreview with note types and counts.

create_material_instances

Creates or updates one material instance for every set whose enabled is True, exactly like Create in the panel: master material, channel packing, texture settings, the instance and its mesh slots. Assets are saved when options.save_assets is True; the master material is always saved when it is created.

Unlike the panel, it does not save the guessed profile of a custom master to Project Settings. Call save_master_profile for that.

pack_channels

Combines channels of up to four textures into one, like the Pack button of the Channel packer. With save the new texture is saved. Returns the texture and an empty error string, or None and the error.

get_master_material

Returns M_Smith_Standard from the Master Material Folder, or M_Smith_Standard_VT with virtual_textures=True. With create_if_missing (the default) it is created when it doesn’t exist.

get_master_profile and save_master_profile

get_master_profile returns the saved profile of a master material from Master Profiles, or a guess from its parameter names if there is none. save_master_profile stores a profile in Project Settings, replacing the entry of the same material. See Custom master materials.

is_built_in_master

True for M_Smith_Standard, M_Smith_Standard_VT, copies and instances of them.

open_panel_with_folders, open_panel_with_assets and open_channel_packer

Open the Material Smith panel with the texture sets of these folders (and their subfolders) or assets, or open the Channel packer page with these textures filled in as Fill from selection does.

Types

TAMaterialSmithTextureSet

Property	Type	Meaning
name	str	Set name, for example Rock for T_Rock_BaseColor.
texture_path	str	Folder of the textures, for example /Game/Props/Rock/Textures.
textures	Array of TAMaterialSmithTexture	The textures of the set.
instance_name	str	Name of the material instance to create or update, for example MI_Rock.
instance_path	str	Folder of the material instance.
meshes	Array of TAMaterialSmithMeshTarget	Mesh slots that get the instance.
blend_mode	TAMaterialSmithBlendMode	AUTO, OPAQUE, MASKED or TRANSLUCENT.
two_sided	bool	Turn on the Two Sided override.
enabled	bool	False: skipped by create_material_instances.

TAMaterialSmithTexture

Property	Type	Meaning
texture	Soft reference to a Texture2D	The texture.
map	TAMaterialSmithMap	BASE_COLOR, NORMAL, PACKED, ROUGHNESS, METALLIC, AMBIENT_OCCLUSION, EMISSIVE, OPACITY, HEIGHT, UNUSED (Not Used) or NONE.
red, green, blue, alpha	TAMaterialSmithChannel	Packed textures: content of each channel. NONE (Empty), AMBIENT_OCCLUSION, ROUGHNESS, METALLIC, HEIGHT or OPACITY.
open_gl_normal	bool	Normal map in OpenGL convention; Flip Green Channel is turned on for it.
invert	bool	Roughness map that stores glossiness; it is inverted.
matched_suffix	str, read-only	The name ending that identified the map, for example BaseColor.

TAMaterialSmithMeshTarget

Property	Type	Meaning
mesh	SoftObjectPath	Static or skeletal mesh.
material_index	int	Index of the material slot.
slot_name	Name	Name of the material slot.
current_material	SoftObjectPath, read-only	Material in the slot when the set was found.
enabled	bool	False: the slot is left alone.

TAMaterialSmithOptions

Property	Type	Meaning
master	Soft reference to a MaterialInterface	Parent of the instances. Empty: the Material Smith master.
fix_texture_settings	bool	Fix texture settings.
pack_channels	bool	Pack channels.
assign_to_meshes	bool	Assign to meshes.
update_existing	bool	Update existing instances; otherwise sets with an existing instance are skipped.
use_height_for_parallax	bool	Parallax for height maps.
save_assets	bool	Save created and changed assets.

TAMaterialSmithResult

All properties are read-only.

Property	Type	Meaning
created_instances	Array of SoftObjectPath	New material instances.
updated_instances	Array of SoftObjectPath	Existing material instances that were updated.
packed_textures	Array of SoftObjectPath	Packed textures created or updated.
changed_textures	Array of SoftObjectPath	Textures whose settings were changed.
changed_meshes	Array of SoftObjectPath	Meshes that got an instance.
created_master	SoftObjectPath	The master material created during this run, if any.
warnings	Array of str	Problems that didn’t stop a set, each starting with the set name.
errors	Array of str	Problems that stopped a set.
skipped_sets	int	Sets skipped because their instance existed (with update_existing off) or another set created the same instance.

TAMaterialSmithPreview

Property	Type	Meaning
notes	Array of TAMaterialSmithNote	Lines of What will happen. Each note has a type (INFO, MASTER, PACK, TEXTURE_FIX, INSTANCE, MESH or UNUSED) and a text.
warnings	Array of str	Problems to look at before creating the instance.
texture_fixes	int	Textures whose settings change.
mesh_slots	int	Mesh slots that get the instance.
creates_master	bool	The master material will be created.
packs_channels	bool	Maps will be packed into one texture.
instance_exists	bool	The material instance exists already.

TAMaterialSmithPackRequest and TAMaterialSmithChannelSource

Property	Type	Meaning
red, green, blue, alpha	TAMaterialSmithChannelSource	One source per output channel.
use_alpha	bool	Keep the alpha channel. Default False: the alpha source is ignored and the texture compresses without alpha.
package_path	str	Folder of the new texture, for example /Game/Props/Rock/Textures.
asset_name	str	Name of the new texture, for example T_Rock_ORM.
size	int	Width and height of the result. 0 (default): the size of the largest source.
overwrite	bool	Replace the texture if it exists. Default True. Textures imported from a file are never replaced.

Each TAMaterialSmithChannelSource has:

Property	Type	Meaning
texture	Soft reference to a Texture2D	Source texture. Empty: the channel is filled with default_value.
channel	TAMaterialSmithSourceChannel	Channel of the source that is read: RED (default), GREEN, BLUE, ALPHA or AVERAGE.
invert	bool	Use 1 − value.
default_value	float	Value (0 to 1) of the channel when there is no source texture. Default 0.

TAMaterialSmithMasterProfile

Property	Type	Meaning
material	Soft reference to a MaterialInterface	The master material.
texture_parameters	Map of TAMaterialSmithMap to Name	Texture parameter that receives each map.
switches	Map of TAMaterialSmithMap to Name	Static switch turned on when the map is found and off when it is missing.
packed_red, packed_green, packed_blue, packed_alpha	TAMaterialSmithChannel	Channel layout the master expects in its packed texture. Default AMBIENT_OCCLUSION, ROUGHNESS, METALLIC, NONE.

Examples

Find, preview and create

import unreal

smith = unreal.get_editor_subsystem(unreal.TAMaterialSmithSubsystem)
options = smith.get_default_options()

sets = smith.find_texture_sets_in_folders(["/Game/Props"])
for s in sets:
    notes, warnings = smith.preview_texture_set(s, options)
    print(s.name, "->", s.instance_path, s.instance_name, list(warnings))

result = smith.create_material_instances(sets, options)
print(len(result.created_instances), "created,", len(result.updated_instances), "updated")
for line in result.errors:
    unreal.log_error(line)

Use the Content Browser selection

selected = unreal.EditorUtilityLibrary.get_selected_asset_data()
sets = smith.find_texture_sets(selected)

Change sets before creating them

Build a new list of the sets you want, changed as needed:

to_create = []
for s in smith.find_texture_sets_in_folders(["/Game/Foliage"]):
    if s.name == "Bark":
        continue  # skip this one
    if s.name == "Leaf":
        s.blend_mode = unreal.TAMaterialSmithBlendMode.MASKED
        s.two_sided = True
        s.instance_name = "MI_Leaf_Masked"
    to_create.append(s)

options = smith.get_default_options()
options.pack_channels = True
options.assign_to_meshes = False
result = smith.create_material_instances(to_create, options)

Pack channels

request = unreal.TAMaterialSmithPackRequest()

ao = unreal.TAMaterialSmithChannelSource()
ao.texture = unreal.load_asset("/Game/Props/T_Box_AO")
rough = unreal.TAMaterialSmithChannelSource()
rough.texture = unreal.load_asset("/Game/Props/T_Box_R")
metal = unreal.TAMaterialSmithChannelSource()
metal.default_value = 0.0  # no metallic map: constant 0

request.red, request.green, request.blue = ao, rough, metal
request.package_path, request.asset_name = "/Game/Props", "T_Box_ORM"

texture, error = smith.pack_channels(request, True)
if not texture:
    unreal.log_error(error)

Use your own master

studio = unreal.load_asset("/Game/Materials/M_StudioMaster")

profile = smith.get_master_profile(studio)
print(profile.texture_parameters, profile.switches)

# Correct a guess and store the profile in Project Settings
params = profile.texture_parameters
params[unreal.TAMaterialSmithMap.EMISSIVE] = "GlowTexture"
profile.texture_parameters = params
smith.save_master_profile(profile)

options = smith.get_default_options()
options.master = studio
result = smith.create_material_instances(smith.find_texture_sets_in_folders(["/Game/Props"]), options)

Get the Material Smith master

master = smith.get_master_material()            # creates M_Smith_Standard if needed
vt_master = smith.get_master_material(True)     # M_Smith_Standard_VT
existing = smith.get_master_material(False, False)  # None if it doesn't exist yet