Material Substitution Workflow

When you import or reimport content into Twinmotion using Datasmith, you can use the material substitution feature to replace the materials in your projects with materials from the Twinmotion Library. You can use any material in the Twinmotion Library as a replacement, including the following:

Materials category
Megascans > Surfaces and Adobe Substance 3D libraries
Twinmotion User library

The details of the material substitutions are defined in the material substitution file (a spreadsheet in CSV format), which is automatically installed on your computer when you install Twinmotion. In this spreadsheet, you identify each material you want to replace in your project and match it to the corresponding Twinmotion material you want to use as a replacement.

Once the material substitution feature is enabled and your project is imported into Twinmotion, you can continue to define more substitutions and apply the changes to your project by reimporting it into Twinmotion.

When you select a Twinmotion material for substitution, you can use the default parameters of the material (such as the color, UV scale, or opacity settings) or override them in the material substitution file. When you import or reimport your project into Twinmotion, the new parameters automatically override the default settings.

Textures cannot be specified or overridden in the material substitution workflow. To select or override a texture, you must edit the material directly in Twinmotion.

Prerequisites

Materials in the Twinmotion Library are either local or cloud-based:

Local materials are automatically installed on your computer when you install Twinmotion.
Cloud-based materials are stored on a dedicated server online to reduce local storage requirements on your computer. You must download the materials before you can use them in Twinmotion and as substitutions. For information on how to download cloud assets from the Twinmotion Library, see Accessing Twinmotion Assets on the Cloud.

Using the Material Substitution Workflow

The material substitution workflow uses two files in the CSV format: the material substitution file and the Twinmotion materials ID file. You can open .csv files with spreadsheet programs such as Microsoft Excel or Google Sheets or with any text editor such as Notepad or TextEdit.

To use the material substitution workflow, do as follows:

Create a new Twinmotion scene.
Import the project from your design application into Twinmotion using the Datasmith Direct Link Workflow or the Datasmith File Import Workflow.
During the import process, when you get to the Import window do as follows:
1. In the Collapse dropdown select Collapse by material. This option groups all the objects in your project that use the same material as a single mesh, and displays the names of all the materials used in your project in the Twinmotion Scene graph. This will be helpful later when you need to identify the names of the materials you want to substitute.
2. Select the Enable Substitution checkbox to enable the material substitution feature. When you select this option, the material substitutions defined in the material substitution .csv file are applied when you import and reimport a scene into Twinmotion.
3. Make sure the path in the Substitution table field points to the material substitution file (MaterialsSubstitutionTable_v[file version]_[Twinmotion version].csv) located on your computer.
  This file contains the details of the material substitutions that are applied during the import process. For more information, see About the Material Substitution File.
Generate a Twinmotion materials ID file that contains the names and Globally Unique Identifiers (GUIDs) of all the available materials in Twinmotion you can use as substitutes. To do this, go to File > Export Materials IDs to open the Export library window.
Enter a file name and select a location to store it on your computer, then click Save.
Open the material substitution file, named MaterialsSubstitutionTable_v[file version]_[Twinmotion version].csv, from the following location:
Windows: C:\Users\[username]\Documents\Twinmotion[version]\Twinmotion\Content\Substitution
MacOS: HD:Users:[username]:Documents:Twinmotion[version]:Substitution
In Twinmotion, find the name of the material you want to replace by using the Material picker and selecting the material on an object in the scene.
The name and the properties of the material appear in the Properties panel.
Material to be substituted in the Properties panel.
When you import a scene into Twinmotion, the names of the materials may differ. Spaces or special characters in the names are replaced by underscores. For example, a material named "Cantaria - 12 26" in your design application is changed to "Cantaria_-_12_26" in Twinmotion.
Open the Twinmotion materials ID file you generated and find the GUID of the Twinmotion material you want to use as a replacement. The GUID is the set of alphanumeric characters separated by hyphens. For more information about the contents of this file, see About the Twinmotion Material IDs File.
GUID of a Twinmotion material.
In the material substitution file, enter the details of the substitution in the material substitution table starting at row 12. In the default material substitution file, these rows contain substitution examples for each type of Twinmotion base material. You can modify the rows to specify your own material substitutions.
Details of a material substitution in the material substitution file.
For more information, see Material Subsitution Rules in the About the Material Substitution File section.
To override certain parameters of the Twinmotion materials, enter the information in the Parameter Overrides section starting at column I. For more information about the parameters you can override, see Parameter Overrides.
Once you are done specifying substitutions, if you edited the material substitution file outside of its original location (for example if you uploaded and edited it in Google Sheets), copy the version you edited and overwrite the default material substitution file in the original location.
Depending on whether you imported a .udatasmith file into Twinmotion or created a Direct Link, reimport the .udatasmith file into Twinmotion or update the Direct Link.
For information on how to reimport a .udatasmith file, see Replacing or Updating Datasmith Files in Twinmotion in the Datasmith File Import Workflow documentation.
For information on how to update a Datasmith Direct Link, see Updating A Scene In Twinmotion in the Datasmith Direct Link Workflow documentation.
Once the scene is reimported, the material substitutions are applied to the materials in the scene.

About the Material Substitution File

The material substitution file, named MaterialsSubstitutionTable_v[file version]_[Twinmotion version].csv, contains the table where you specify the details of the material substitutions. When you install Twinmotion, this file is automatically installed on your computer in the following folder:

Windows: C:\Users\[username]\Documents\Twinmotion[version]\Twinmotion\Content\Substitution
MacOS: HD:Users:[username]:Documents:Twinmotion[version]:Substitution

When you import a scene into Twinmotion, by default the path in the Substitution table field in the Import window points to the material substitution file installed on your computer.

Clicking on the ellipsis (…) next to the Substitution table field opens a menu that contains the following commands:

Clear: Clears the Substitution table field.
Copy: Copies the path in the Substitution table field. To locate the material substitution file on your computer, select Copy and then paste the path into the search bar of your Finder window or Windows Explorer.
Paste: Pastes the contents of the clipboard into the Substitution table field. You can copy the path to the material substitution file from your Finder window or Windows Explorer, then select Paste to paste it into the Substitution table field.
Generate default table: Generates a new default material substitution file.

Material Substitution Rules

You must create one material substitution rule for each material you want to replace. The material substitution rules define the details of the substitution, such as which material you want to use as a replacement, and the conditions that Twinmotion uses to determine if a material should be replaced.

The material substitution rules are defined starting in row 12, between columns A (Row ID) to H (Instance Type). You can also define overrides to the default parameters of Twinmotion materials in the Parameter Overrides section starting at column I and in each subsequent column.

The image below shows rows 12 to 22 in the default material substitution file. The contents of these rows are for informational purposes only and aim to provide you with examples of how to define material substitution rules for each type of Twinmotion base material. The information in these rows can be replaced with your own substitution rules.

Substitution file rows 12 to 22 — Material substitution rules in the material substitution file.

Each row contains the substitution rules for one material.
You can define as many substitution rules as you need.
Substitution rules must be entered starting at row 12.
Columns C (Substitution Type) to H (Instance Type) define the basic material substitution rules for each substituted material and must contain a value. For more information, see Basic Material Substitution Rules.
Twinmotion material parameter overrides are defined starting at column I (Parameter Overrides). For more information, see Parameter Overrides.
Substitution rules are applied from top to bottom during the material substitution process. For example, a substitution rule specified in row 12 is applied before the substitution rule in row 13 is applied, and so on.

Basic Material Substitution Rules

The table below describes the contents of columns A to H which define the following material substitution rules: Substitution Type, Filter, Condition, Value, TM Library GUID, and Instance Type.

Column	Name	Description	Possible Values
A	Row ID	In the default material substitution file, this column contains a number and the type of materials that are substituted, for example "01-Standard Stones". The contents of this row can be useful to sort the rows numerically or alphabetically in a spreadsheet program. This row must be present in the table but is not used in the material substitution process. You can leave it empty, or use it to add custom labels.	[any]
B	Row Name	In the default material substitution file, this column identifies the Twinmotion materials by name, for example "Stone Wall 2". This row must be present in the table but is not used in the material substitution process. You can leave it empty, or use it to add custom labels.	[any]
C	Substitution Type	Determines the type of replacement. This value cannot be changed.	Material
D	Filter	The kind of value used, along with the Condition, for finding the materials to replace. Currently, the kind of value cannot be changed and the name of the material in the Value (F) column is used.	Name
E	Condition	The filter criteria to find the materials to replace as specified in the Value (F) column. For example, if the Value (F) column contains the word "Glass", and the condition is "Contains", all materials that contain the word "Glass" are replaced. The asterisk ( * ) and question mark ( ? ) symbols can be used as wildcards.	Contains Equals Starts With Ends With Match Not Contains Not Equals Not Starts With Not Ends With Not Match
F	Value	The name of the material you want to replace. Material names are case-sensitive. For example, the name "Grass" will not match "grass".	[any]
G	TM Library GUID	The GUID (a set of unique numbers that identifies a material) of the Twinmotion material to be used as a replacement. Each Twinmotion local and downloaded cloud-based material is identified by a unique GUID, consisting of a set of grouped alphanumeric characters separated by hyphens. You can find the GUIDs in the exported Twinmotion materials ID file. For more information, see About the Twinmotion Materials IDs File.	[any]
H	Instance Type	If a Twinmotion material replaces more than one material in the imported project, you can specify whether the replacement material is a copy or an instance.	Copy Instance

Parameter Overrides

When you choose a Twinmotion material as a replacement, you can use the default parameters of the material (such as the color, roughness, or scale) or override them. During the material substitution process, the parameter overrides defined in the Parameter Overrides section starting at column I are used instead of the default Twinmotion parameters.

The image below shows the Parameter Overrides section, which starts at column I in the default material substitution file. The contents of this section are for informational purposes only and aim to provide you with examples of how to define parameter overrides. The contents in these columns can be deleted or replaced with your own substitution rules.

Parameter Overrides sections — Parameter Overrides section in the material substitution file.

Each parameter override for a material is entered in a separate column, starting at column I.
You can specify as many overrides as you want.
The parameters and their values must be enclosed within square brackets ( [ ] ) and use the following syntax: [ParameterName Value]. For example: [TintColor 95 128 230].

IMPORTANT: At least one parameter override must be defined for each material substitution. If you do not want to override any parameters, enter one of the default values of an existing parameter for the material. For example, the Clean Brick 01 material has a tint color and the default is 231 134 113. In column I, you would enter [TintColor 231 134 113].

Reference for the Parameter Overrides

Columns A (Color Properties) to F (Example) starting at row 43 contain a reference to the parameter overrides you can define for Twinmotion materials. These rows all start with the number sign ( # ) which means they are for informational purposes only and do not affect the material substitution process.

Parameter Overrides reference — Parameter overrides reference section in the material substitution file.

Column	Name	Description
A	Color Properties	Shows the Property name you must use to identify a parameter in the material substitution table. The Property name can differ from the name of the parameter in the Twinmotion user interface. For example, to specify the "Color" parameter in the material substitution file, you must use "TintColor".
B	Twinmotion UI Name	Shows the name of the parameter as it appears in the Twinmotion user interface.
C	Value Type	Represents how the value of the parameter override should be formatted depending on the type of value. Boolean: A value that can be toggled On or Off; 1 = On and 0 = Off. For example, "[UseMask 1]" means the mask will be On (enabled). Using decimal values (such as 1.2) or any other value creates an error. FLinearColor: A value that represents a color in the RGB model. For example, [LuminanceFilter 95 128 230]. Float: An integer value that represents the minimum and maximum value of a parameter. For example, "Min: 0" and "Max: 2". Options: A value selected from a range of available options. For example, the Glass material type is available in the following options: Translucent, ThinTranslucent, or Basic. TFVector3D: A value type with multiple numbers to enter. They must be listed in the order displayed and can be a decimal value.
D	Range min	Shows the minimum of the value range. For example, "Min: 0.0" means there can be no lower value than 0.0.
E	Range max	Shows the maximum of the value range. For example, "Max: 2.0" means there can be no higher value than 2.0.
F	Example	Shows examples of the syntax to use to enter parameter overrides.

About the Twinmotion Materials IDs file

Each Twinmotion material is identified by a name and a GUID, which is a set of unique numbers that identifies a material. When you specify a Twinmotion material as a replacement, you must use the GUID to identify it in the substitution table. You can find the GUID of all local and downloaded Twinmotion materials by generating a material ID file in CSV format from within Twinmotion.

To generate a Twinmotion materials ID file, go to File > Export Materials IDs. Select a name for the file and save it anywhere on your computer.

The material ID file contains one row for each material in the scene.

Column A shows the location of the material in the Twinmotion Library.
Column B is the name of the material in the Twinmotion Library.
Column C is the GUID of the material. You must use this set of numbers to identify a material as a replacement in the material substitution file.