"Apply Material By Rules" Plugin

User Manual

Table of Contents

1. Introduction 2. Getting Started 3. MaterialRules DataTable 3.1 DataTable Fields 3.2 Filter Configuration 3.3 Variable Field 3.4 Creating MaterialRules DataTable 4. Assigning Materials 4.1 From Content Browser 4.2 From Outliner 5. Import Textures 6. Remove Materials 7. Tag Examples 7.1 [FILE_NAME] 7.2 [ASSET_NAME] 7.3 [MATERIAL_NAME] 7.4 [RANDF:min,max] 7.5 [RANDI:min,max] 7.6 [ACTOR_NAME] 7.7 [ACTOR_LAST_INDEX] 7.8 [R0-9:value] 8. Combined Tag Examples 9. Use Cases 10. Creating Rules from Outliner 11. Update Variables from Material Parameters 12. Select By Rules 13. Cheat Sheet UI 14. Conclusion

1. Introduction

"Apply Material By Rules" is a powerful Python plugin for Unreal Engine that allows you to assign materials to different types of objects such as Assets, StaticMesh, Skeleton Mesh, Blueprints, and Components using selection rules. The plugin uses a DataTable called "MaterialRules" to store configuration data, allowing you to assign materials to selected objects with just one click.

2. Getting Started

To begin, install the "Apply Material By Rules" plugin to your Unreal Engine project. Once installed, you can start creating DataTables called "MaterialRules" that store your custom configurations for material assignment.

3. MaterialRules DataTable

3.1 MaterialRules DataTable Fields

  • Active: Enable or disable the rule.
  • Filter: Define the list of objects for material assignment using various selection criteria.
  • Material: Choose any material to assign, along with its parameters.
  • Variable: Customize material parameters using [tags], random values, and rules.

The order of the rows in the DataTable is important, starting with the widest filter and going down to the most restrictive.

3.2 Filter Configuration

The "Filter" field in the "Apply Material By Rules" plugin is used to define search criteria to filter the list of assets, actors, and/or materials to which the rules should be applied. The filter is based on the names or paths of the assets, actors, or materials. You can use the wildcard symbol "*" to make the search more extensive. This allows for more granular control over which objects in the scene the rules will affect.

Filter [Tags]:

  • '': Path of the asset in the Content Browser relative to the location where the DataTable is saved.
  • >: Path of the actor in the Outliner.
  • : Indicates that you want to search for the name of the materials or the slot position (0,1,2,...).

For example, you can use the filter:

  • >*/Spher* to select all objects that have a name starting with "Spher" regardless of their location in the project hierarchy.
  • >*/GreenSphere/Spher* to select only the objects named starting with "Spher" that are located within the "GreenSphere" folder.
  • >*/GreenSphere/Spher*:top to select objects with the name starting with "Spher" that are located within the "GreenSphere" folder and have a material named "top".
  • :top to select all objects with a material named "top".
  • :1 to select all objects with a slot material position 1.
  • myFolder/* selects all objects inside a folder named "myFolder" in the Content Browser.
  • spher* selects all objects with names starting with "Spher" in the current folder of the Content Browser.

By using a combination of filters and variables with different tags, the "Apply Material By Rules" plugin becomes an extremely powerful tool for assigning materials to hundreds of objects at once while maintaining the ability to modify each detail granularly.

3.3 Variable Field

The Variable field uses the following format:

PARAM_NAME=VALUE
  • [PARAM_NAME]: The name of the parameter defined in the material, such as BaseColor, Normal, Roughness, etc.
  • [VALUE]: The value you want to assign to the parameter, which can be an integer, a float, vector3(1,1,1), vector4(1,1,1,1) or a texture.

Examples:

BaseColor=MyTexture_BaseColor
Roughness=0.2
Tint=0.35,0.35,0.35
Tint=0.35,0.35,0.35,1

Variable [Tags]:

  • [FILE_NAME]: Corresponds to the source file name of the object imported into Unreal, without the extension.
  • [ASSET_NAME]: Corresponds to the name of the object registered in the Content Browser.
  • [MATERIAL_NAME]: Corresponds to the name of the object's material.
  • [MATERIAL_SLOT]: Corresponds to the position slot of the object's material. (>UE5.3)
  • [RANDF:min,max]: Creates a random float value between min and max, e.g., "Roughness=[RANDF:0.2,0.5]".
  • [RANDI:min,max]: Creates a random integer value between min and max, e.g., "BaseColor=MyTexture_[RANDI:1,4]_basecolor".
  • [ACTOR_NAME]: Corresponds to the name of the actor in the Outliner.
  • [ACTOR_LAST_INDEX]: Retrieves the number at the end of the actor name in the Outliner, e.g., "Sphere2" -> 2.
  • [R0-9]:value: Special rule that allows up to 10 rules to be written directly on the actor name in the Outliner, e.g., "Sphere[R1:night]" -> "BaseColor=MyTexture_[R1]_basecolor" -> "BaseColor=MyTexture_night_basecolor".

3.4 Creating MaterialRules DataTable

To create a "MaterialRules" DataTable:

  • Right-click in the Content Browser.
  • Navigate to the "Apply Material By Rules" plugin options.
  • Choose from six different options for generating a list of rules based on your existing assets, such as:
    • Object names
    • Material names
    • A combination of both
    • Inclusion of child directories

4. Assigning Materials

There are two ways to assign materials:

4.1 From the Content Browser:

This option will edit the asset and modify the original material of the asset (less recommended).

  • Select the DataTable of rules to execute.
  • Right-click -> Apply Mat By Rules -> Execute Selected Asset Rules, or (Recursive).

Note: Some variables only work if assigned from the Outliner.

Note 2: This is slower because it opens all assets to update the default material.

4.2 From the Outliner:

  • Select the actor to whom you want to assign the material.
  • Select the DataTable.
  • Right-click and "Execute Level Rules For Selected Actor's". This option allows you to select the actors on which you want to assign the material, and this will not change the material in the asset, but it will change the "Material Overwrite".

Once you have executed the command, it will filter and generate the different materials according to the criteria you have defined. The plugin will create a folder called "/MaterialRules/" and store all the newly generated materials inside it.

5. Import Textures

For the textures used with the plugin, simply import them into Unreal and organize them as desired. The tool is powerful enough to search for textures throughout the entire project.

6. Remove Materials

You can remove materials generated by the rules. To do so:

  • Select the actor for which you want to remove the material
  • Right-click, and choose "Remove Material Overwrite".

7. Tag Examples

Here are some examples of how to use the different [tags] in the "Apply Material By Rules" plugin:

7.1 [FILE_NAME]

Suppose you have a set of objects with the file names "Tree_01.fbx", "Tree_02.fbx", and "Tree_03.fbx". You want to assign a texture specific to each object based on the file name.

In the "Variable" column, use the following expression:

BaseColor=tex_[FILE_NAME]_color

This will assign the textures "tex_Tree_01_color", "tex_Tree_02_color", and "tex_Tree_03_color" to the corresponding objects.

7.2 [ASSET_NAME]

Imagine you have three assets named "Car_A", "Car_B", and "Car_C" in the Content Browser. You want to assign a specific normal texture to each asset based on the asset name.

In the "Variable" column, use the following expression:

Normal=tex_[ASSET_NAME]_normal

This will assign the textures "tex_Car_A_normal", "tex_Car_B_normal", and "tex_Car_C_normal" to the corresponding assets.

7.3 [MATERIAL_NAME]

Suppose you have objects with material names such as "Brick", "Concrete", and "Wood". You want to assign a roughness texture based on the material name.

In the "Variable" column, use the following expression:

Roughness=tex_[MATERIAL_NAME]_roughness

This will assign the textures "tex_Brick_roughness", "tex_Concrete_roughness", and "tex_Wood_roughness" to the corresponding materials.

7.4 [RANDF:min,max]

You want to assign a float random value for the Metallic parameter of the materials, ranging from 0.1 to 0.5.

In the "Variable" column, use the following expression:

Metallic=[RANDF:0.1,0.5]

This will assign a random float value between 0.1 and 0.5 to the Metallic parameter for each material.

7.5 [RANDI:min,max]

You want to assign a Integer random value for example to switch between a range of textures.

Imagine you have four variations of a texture named "Grass_1_color", "Grass_2_color", "Grass_3_color", and "Grass_4_color". You want to assign a random variation to the BaseColor of the material.

In the "Variable" column, use the following expression:

BaseColor=tex_Grass_[RANDI:1,4]_color

This will randomly assign one of the four grass textures as the BaseColor for the material.

7.6 [ACTOR_NAME]

You want to use the name of the "Actor" inside the outliner.

Suppose you have actors in the outliner named "Chair_01", "Chair_02", and "Chair_03". You want to assign a specific ambient occlusion texture based on the actor name.

In the "Variable" column, use the following expression:

AO=tex_[ACTOR_NAME]_ao

This will assign the textures "tex_Chair_01_ao", "tex_Chair_02_ao", and "tex_Chair_03_ao" to the corresponding actors.

7.7 [ACTOR_LAST_INDEX]

You want to use the last digit of the name of the "Actor" inside the outliner.

You have actors in the outliner named "Box01", "Box02", and "Box03". You want to assign specific height textures based on the last index in the actor name.

In the "Variable" column, use the following expression:

Height=tex_Box_[ACTOR_LAST_INDEX]_height

This will assign the textures "tex_Box_1_height", "tex_Box_2_height", and "tex_Box_3_height" to the corresponding actors.

7.8 [R0-9:value]

Imagine you have two objects in the outliner named "Wall_1[R1:Day]" and "Wall_2[R1:Night]". You want to assign specific base color textures based on the "Day" or "Night" values embedded in the actor names.

In the "Variable" column, use the following expression:

BaseColor=myTexture_[R1]_BaseColor

This will assign the textures "myTexture_Day_BaseColor" and "myTexture_Night_BaseColor" to the corresponding actors. The R[0-9]:value tag searches for the specified value (e.g., "Day" or "Night") embedded in the actor name and replaces it with the corresponding [R1],[R2]...[R9] tags in the Variable field.

Using the [R0-9:value] tag in combination with other tags further expands the possibilities and flexibility of the "Apply Material By Rules" plugin, making it an even more powerful tool for material assignment in Unreal Engine projects.

8. Combined Tag Examples

Here's an example where we combine multiple [tags] to generate more complex material assignments:

Example 1:

Imagine you have a set of objects in the Content Browser named "Building_A", "Building_B", and "Building_C". Each object has materials with names "Wall", "Roof", and "Window". You want to assign textures for each object based on the object's name, and material name.

In the "Variable" column, use the following expressions:

BaseColor=Tex_[ASSET_NAME]_[MATERIAL_NAME]_color Normal=Tex_[ASSET_NAME]_[MATERIAL_NAME]_normal Roughness=Tex_[ASSET_NAME]_[MATERIAL_NAME]_roughness

This will assign the following textures for the BaseColor, Normal, and Roughness of the materials:

  • Tex_Building_A_Wall_color, Tex_Building_A_Wall_normal, Tex_Building_A_Wall_roughness
  • Tex_Building_A_Roof_color, Tex_Building_A_Roof_normal, Tex_Building_A_Roof_roughness
  • Tex_Building_A_Window_color, Tex_Building_A_Window_normal, Tex_Building_A_Window_roughness
  • ...
  • Tex_Building_C_Wall_color, Tex_Building_C_Wall_normal, Tex_Building_C_Wall_roughness
  • Tex_Building_C_Roof_color, Tex_Building_C_Roof_normal, Tex_Building_C_Roof_roughness
  • Tex_Building_C_Window_color, Tex_Building_C_Window_normal, Tex_Building_C_Window_roughness

This configuration will create unique combinations of textures for each object, and material, allowing for highly customized material assignments.

Example 2:

Imagine you have a set of objects in the Outliner, you have actors named "City_01", "City_02", and "City_03". Each object has materials with names "Wall", "Roof", and "Window". You want to assign textures for each object based on the actor's name, and material name.

In the "Variable" column, use the following expressions:

BaseColor=Tex_[ACTOR_NAME]_[MATERIAL_NAME]_color Normal=Tex_[ACTOR_NAME]_[MATERIAL_NAME]_normal Roughness=Tex_[ACTOR_NAME]_[MATERIAL_NAME]_roughness

This will assign the following textures for the BaseColor, Normal, and Roughness of the materials:

  • Tex_City_01_Wall_color, Tex_City_01_Wall_normal, Tex_City_01_Wall_roughness
  • Tex_City_01_Roof_color, Tex_City_01_Roof_normal, Tex_City_01_Roof_roughness
  • Tex_City_01_Window_color, Tex_City_01_Window_normal, Tex_City_01_Window_roughness
  • ...
  • Tex_City_03_Wall_color, Tex_City_03_Wall_normal, Tex_City_03_Wall_roughness
  • Tex_City_03_Roof_color, Tex_City_03_Roof_normal, Tex_City_03_Roof_roughness
  • Tex_City_03_Window_color, Tex_City_03_Window_normal, Tex_City_03_Window_roughness

This configuration will create unique combinations of textures for each actor and material, allowing for highly customized material assignments.

9. Use Cases

This plugin is extremely powerful for assigning materials to hundreds of objects at once, with the possibility to modify each detail granularly. It's useful for conforming older objects that were not imported correctly or for cases where textures are not correctly linked to materials.

For example, if you have an object library imported as an FBX with only color textures assigned, and the structure is based on:

[OBJECT_NAME]_[MATERIAL_NAME]_color [OBJECT_NAME]_[MATERIAL_NAME]_normal [OBJECT_NAME]_[MATERIAL_NAME]_roughness [OBJECT_NAME]_[MATERIAL_NAME]_ao [OBJECT_NAME]_[MATERIAL_NAME]_height

You only need one line in the rule containing "*" for the filter (for all objects in the scene). Then, choose your "Master Material" and for each variable, simply input:

Color=[FILE_NAME]_[MATERIAL_NAME]_color Normal=[FILE_NAME]_[MATERIAL_NAME]_normal ….

The plugin will automatically generate all the materials for the entire library.

10. Creating Material DataTable Rules from the Outliner

(coming soon)

Overview

This workflow allows users to quickly generate or append material assignment rules for selected actors in the Unreal Editor's Outliner, saving them to a DataTable asset. The system is designed to be user-friendly, robust, and to prevent accidental overwrites.

Step-by-Step Workflow

1. Select Actors in the Outliner

In the Unreal Editor, select one or more actors in the World Outliner that you wish to generate rules for.

2. (Optional) Select a DataTable Asset

If you want to append rules to an existing DataTable, select that DataTable asset in the Content Browser before running the script.

If no DataTable is selected, the system will guide you through creating or choosing one.

3. Run the Script

Execute the script (via right click UI and choose between 3 types):

  • Add Path Rules from Selected Actors
  • Add Material Rules from Selected Actors
  • Add Both Rules from Selected Actors

Script Behavior

A. DataTable Selection Logic

  • If a DataTable is selected in the Content Browser: The script will append new rules to this DataTable.
  • If NO DataTable is selected: The script will check if a default DataTable (named as per your convention, e.g., DataTableMat) exists in the current Content Browser path.
  • If the default DataTable exists:
    You are prompted:
    "The default DataTable "DataTableMat" already exists.
    Do you want to add to it (append) or replace it?
    YES = Add, NO = Replace"
    • YES: The new rules will be appended to the existing DataTable.
    • NO: The existing DataTable will be replaced with a new one containing only the new rules.
  • If the default DataTable does NOT exist:
    You are prompted:
    "No DataTable selected. Do you want to create a new DataTable?"
    • YES: A new DataTable will be created.
    • NO: The operation is cancelled.

B. Rule Generation

The script generates rules for each selected actor based on the chosen mode:

  • Mesh: Uses the outliner path (e.g., >*/ActorLabel) as the rule key.
  • Material: Uses only the material name (e.g., :MaterialName) as the rule key.
  • Both: Generates both types of rules. (e.g., >*/ActorLabel:MaterialName)

Actor labels longer than 12 characters are truncated at the first space, underscore, or dash after the 12th character, with an asterisk (*) appended (e.g., MyLong_ActorName → MyLong*).

The rules are written to the DataTable in CSV format, using the following columns:
---,Active,Filter,Material,Variables

Example User Flows

A. Creating a New DataTable from Outliner Actors

  • Select actors in the Outliner.
  • Do not select any DataTable in the Content Browser.
  • Run the script.
  • When prompted, choose "YES" to create a new DataTable.
  • The DataTable is created in the current Content Browser path, and rules are added for your actors.

B. Appending to an Existing DataTable

  • Select actors in the Outliner.
  • Select an existing DataTable in the Content Browser.
  • Run the script.
  • Rules for the selected actors are appended to the selected DataTable.

C. Handling Existing Default DataTable

  • Select actors in the Outliner.
  • Do not select any DataTable in the Content Browser.
  • Run the script.
  • If the default DataTable exists, choose:
    • "YES" to append rules.
    • "NO" to replace the DataTable with only the new rules.

Error Handling

  • If no actors are selected, you will be prompted to select actors and rerun the script.
  • If you cancel any dialog, the operation is safely aborted with a log message.

Best Practices

  • Always double-check your Content Browser path before running the script to ensure rules are saved where you expect.
  • Use the append/replace prompts to avoid accidental loss of existing DataTable data.
  • For bulk operations, use the "both" mode to generate comprehensive rules.

11. Update Variables from Material Parameters

The "Update Variables from Material Parameters" tool is designed to simplify and speed up the process of filling out the Variables field in the MaterialRules DataTable used by the "Apply Material By Rules" plugin.

When executed, this tool automatically scans the Material Instance assigned in the rule. It extracts all active material parameters and creates corresponding variable entries in the rule. This eliminates the need for manual entry and reduces the risk of errors.

Example

If the assigned material instance contains:

  • A BaseColor texture set to "my_home_texture"
  • A Roughness value of 0.4
  • A Tint color value of (0.5, 0.5, 0.5)

The tool will automatically generate the following variables in the rule:

BaseColor=my_home_texture Roughness=0.4 Tint=0.5,0.5,0.5

How It Helps

  • Saves time by avoiding manual input of variable parameters.
  • Ensures accuracy by directly pulling the values from the material instance.
  • Speeds up the creation of complex rules, especially when working with many parameters or materials.

This functionality is accessible through the context menu (Right-click on asset > Apply Mat By Rules For Assets > Update Variables from Material Parameters).

12. Select By Rules (UE5.3>)

Unreal Engine Advanced Selection Tool

Overview

Select By Rules is a powerful and lightweight Unreal Engine tool designed to streamline actor selection in complex levels using flexible pattern matching. Whether you need to select actors by name patterns, parent hierarchies, or types, Select By Rules provides an efficient and customizable workflow.

This is a lite version — a more advanced edition with additional features will be available soon. The tool is also designed to help you build selection rules for Apply Material By Rules. You can test and refine your selection by using Select By Rules, then copy the rule directly into Apply Material By Rules.

Note: When transferring a rule, don't forget to add the prefix > to specify that the rule refers to an actor path rather than an asset.

Key Features

  • Wildcard-based selection for names and paths.
  • Parent/child hierarchy matching.
  • Actor Type filtering.
  • Live Mode for dynamic updates.
  • MatchCase and Child mode toggles for advanced control.

Actor Selection Logic

Wildcard Rule Matching
Pattern Example Behavior
wall* Matches any actor whose name starts with wall, anywhere in the hierarchy.
/house4/wall* Matches actors under /house4/ whose name starts with wall.
/house/Level*/wall* Matches actors under paths like /house/LevelX/ whose name starts with wall.
* or / or empty Matches all actors (type filter still applies).
  • Single-segment patterns (e.g., wall*) look for name matches at any level.
  • Multi-segment patterns (using /) specify parent paths and name patterns.
Special Symbols
  • * — Wildcard for any string.
  • / — Hierarchical path separator.
Child Selection Mode
Option Behavior
Child=False (default) Only select actors matching the rule directly.
Child=True Select matching actors and all their descendants (children, grandchildren, etc.).

Descendants are identified if their hierarchy path starts with the matched actor's path + /.

Actor Type Filtering

Select By Rules automatically detects all actor types present in the level and generates a clickable list for easy filtering.

Feature Description
Auto-detection Actor types are automatically detected from the level content.
Clickable list Filter by simply clicking on the desired type(s).
Dynamic update If you add or remove actor types in the level, click Clear / Init to refresh the list.
Interface Overview
Control Description
Select Rules Enter the rule pattern for matching actors.
Filter By Types Set type filters to narrow selection.
Select Apply the selection based on the rule and filter.
Clear / Init Reset the current selection.
Live Mode Auto-refresh selection when rules change.
MatchCase Enable case-sensitive matching.
Child Toggle child selection mode.
Example Scenarios
Scenario Rule Type Filter
Select all static meshes starting with wall wall* StaticMeshActor
Select all lights * Light*
Select all props under house level 4 /house4/prop* StaticMeshActor
Select all actors * Actor*
Notes
  • Wildcard support applies to both rule patterns and type filters.
  • Live Mode allows for instant feedback as you modify rules.
  • Complex hierarchies can be handled effortlessly using multi-segment patterns.

13. Cheat Sheet UI — Purpose & Usage

The "Apply Material By Rules — Cheat Sheet" UI is designed to assist users in quickly building variable expressions for the plugin's MaterialRules DataTable, without needing to memorize all available tags and formats.

This small interface provides:

A Quick Reference for Tags

  • [FILE_NAME]
  • [ASSET_NAME]
  • [MATERIAL_NAME]
  • And others available in the plugin documentation.

These tags allow you to dynamically reference object names, materials, and other properties when assigning materials or textures.

Examples of Variable Syntax

For each tag, the UI shows how to write variable expressions. For example:

BaseColor=tex_[FILE_NAME]_color Normal=tex_[ASSET_NAME]_normal

This helps to assign textures automatically based on properties like the file name or asset name.

Live Actor Info Loading

The "Load Selected Actor Info" button lets you pick an actor in the scene and instantly preview tag values. For example, selecting an actor might show:

  • [FILE_NAME] → sphere_v2
  • [ASSET_NAME] → SphereAsset
  • [MATERIAL_NAME] → Emissive,Wood,Metal

This feature helps verify the correct values when writing variables in the MaterialRules DataTable.

How It Helps

  • ✅ Speeds up the creation of rules by providing ready-to-use tag syntax.
  • ✅ Prevents errors by letting you confirm the real tag values from your scene objects.
  • ✅ Simplifies complex setups by showing clear examples for common use cases (BaseColor, Normal, Roughness, etc.).
  • ✅ Reduces time spent switching between the scene and the DataTable by offering immediate feedback.

14. Conclusion

The "Apply Material By Rules" plugin for Unreal Engine is a powerful and efficient tool for automating material assignment for various object types. By using the DataTable "MaterialRules" and leveraging the [tags] system, you can create, modify, and assign materials with a high level of control and customization. This user manual provides a comprehensive guide to using the plugin and its features, enabling you to save time and streamline your material assignment process in Unreal Engine.