The Interchange Framework is Unreal Engine's import and export framework. It is file format agnostic, asynchronous, customizable, and can be used at runtime.
Interchange import interface
Interchange uses a code base that is extensible and provides a customizable pipeline stack. This gives you the freedom to edit the import pipeline using Blueprint or Python to fit your project's needs.
Important Concepts and Terms
- Pipeline: A collection of operations that process imported data. A pipeline exposes the options used to customize the import process.
- Pipeline Stack: An ordered list of pipelines that process an imported file. Pipelines are combined in the stack and assigned to specific file formats. The pipeline stacks are located in Project Settings > Interchange.
- Factory: An operation that generates the asset from the imported data.
Enable the Interchange Plugins
The Interchange Framework requires the Interchange Editor and Interchange Framework plugins, which are enabled by default. If they are not enabled in your project, enable them in the Project settings for your project. For more information on enabling plugins, see Working with Plugins.
Import an Asset
Assets are imported into Unreal Engine using one of several different methods. Assets can be imported using the Content Drawer or Content Browser, or by selecting File > Import Into Level from the main menu. For more information on importing files, see Importing Assets Directly.
Import Into Level currently works with glTF and MaterialX file formats.
Import Process
These methods trigger the import process.
- Begin the import process by using one of the methods listed above.
- This opens the Interchange Pipeline Configuration window.
- Select the pipeline stack to use from the Choose Pipeline Stack drop down menu.
- Configure your settings and press Import to complete the process.
Use the interface to select your import settings and click Import to continue.
With each method, the engine checks whether the file format is supported by the Interchange Framework. If it is, Interchange uses the appropriate import pipeline stack for your format, and goes through the following process:
- Interchange converts the imported data into an intermediary node structure in Unreal Engine.
- Interchange travels through the pipeline stack, and follows the instructions for the import.
- Uses factories to generate the asset from the result.
If the file format is not supported by Interchange, Unreal Engine uses the legacy framework to import the file.
Reimporting Assets using Interchange
When you reimport an asset that was previously imported using Interchange, Unreal Engine remembers the pipeline stack and options that were used, and displays those options.
Import an Asset Using Blueprint
You can use Blueprint to import assets into Unreal Engine through the Interchange Framework.
The Blueprint example creates an object that imports files at runtime using Interchange.
For example, you can use this feature to import files using Interchange at runtime in an Unreal Engine-based application. The above example creates a function that imports a texture file to a specified file location using the default texture pipeline stack. This method of import currently does not support Skeletal Mesh or Animation data.
Create a new Blueprint Class
To recreate the example, follow the steps below:
- Create a new Actor Blueprint Class in your project to contain the Function. Right click in the Content Browser and select Blueprint Class from the context menu.
-
In the Pick Parent Class window, select Actor and name the new Blueprint class InterchangeActor.
Pick the Parent Class of your new Blueprint.
Add a Function
- Double-click the new Blueprint to open the editor.
-
In the My Blueprint panel, Click the + button in the Functions section and name the new function InterchangeImport.
Create a new Function
Add and Connect the Nodes
- Add a Sequence node and connect it to the output of the function.
- Drag from the Then 0 output and create a Create Source Data node to reference the existing file that will be imported.
- Drag from the In File Name input on Create Source Data and, from the context menu, select Promote to Variable.
- Name the new String variable FilePath. This holds the location of the file that will be imported.
- In the blueprint, select the new variable and select the checkbox for Instance Editable.This makes the variable editable per instance of the Blueprint.
- Promote the output of the Create Source Data node to a new variable named SourceData.
- Drag from the Then 1 output on the Sequence and create a Get Interchange Manager Scripted node. This creates a pointer to the Interchange Manager that is used in the next step.
- Drag from the Get Interchange Manager Scripted output and create an Import Asset node. Connect the Return Value from Get Interchange Manager Scripted to the Target input on Import Asset.
- Drag off from the Content Path input and promote it to a new variable named SavePath. This holds the location of the newly imported file.
- In the blueprint, select the new variable and select the checkbox for Instance Editable.
- Get a reference to the Source Data variable and connect it to the Source Data input on Import Asset.
-
Drag off from the Import Asset Parameters input and create a Make Input Asset Parameters node.
Click image for full size.
Make the Function Available at Runtime
- In the My Blueprints panel, click on the InterchangeImport function and select the checkbox next to Call In Editor in the Details panel. This option makes the function available at runtime in the Details of the InterchangeActor object.
- Save and Compile your Blueprint.
Use Your New Blueprint
- Drag a copy of the InterchangeActor blueprint into the level.
- Click Play.
- Select the InterchangeActor in the Outliner.
- Fill in the FilePath and the SavePath in the Details panel.
- Click the Interchange Import button to import your file.
Adding an Import Scene node with the Blueprint example above spawns the asset directly into the scene.
Using Interchange in a Cooked Application
If you plan to use the Interchange Framework at runtime in a cooked application, add the Interchange folder to the Additional Asset Directories to Cook in the Project - Packaging section of the Project Settings.
Click image for full size.
Import an Asset Using Python
You can use Python script to import assets into Unreal Engine through the Interchange Framework.
import unreal
import_path = "C:/Users/foo/Downloads/Fbx/SkeletalMesh/Animations/Equilibre.fbx"
import_extension = unreal.Paths.get_extension(import_path, False)
is_gltf = import_extension == 'glb' or import_extension == 'gltf'
is_fbx = import_extension == 'fbx'
#if you want to import fbx file make sure interchange fbx import is enable
if is_fbx:
level_editor_subsystem = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
unreal.SystemLibrary.execute_console_command(level_editor_subsystem.get_world(), 'Interchange.FeatureFlags.Import.FBX true')
editor_asset_subsystem = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
transient_path = "/Interchange/Pipelines/Transient/"
transient_pipeline_path = transient_path + "MyAutomationPipeline"
editor_asset_subsystem.delete_directory(transient_path)
#Duplicate the default interchange asset content pipeline, gltf have a special assets
pipeline = editor_asset_subsystem.duplicate_asset("/Interchange/Pipelines/DefaultAssetsPipeline", transient_pipeline_path)
#Set any pipelines properties you need for your asset import here
#force static mesh import
pipeline.get_editor_property("common_meshes_properties").set_editor_property("force_all_mesh_as_type",unreal.InterchangeForceMeshType.IFMT_STATIC_MESH)
#combine static mesh
pipeline.get_editor_property("mesh_pipeline").set_editor_property("combine_static_meshes",True)
#Prevent Material import
pipeline.get_editor_property("material_pipeline").set_editor_property("import_materials",False)
#Prevent Texture import
pipeline.get_editor_property("material_pipeline").get_editor_property("texture_pipeline").set_editor_property("import_textures",False)
#Create a source data from the filename
source_data = unreal.InterchangeManager.create_source_data(import_path)
#create the parameters for the interchange import
import_asset_parameters = unreal.ImportAssetParameters()
#Script is normaly an automated import
import_asset_parameters.is_automated = True
#Add the configured pipeline to the import arguments
eas = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
import_asset_parameters.override_pipelines.append(eas.load_asset(transient_pipeline_path + ".MyAutomationPipeline"))
interchange_manager = unreal.InterchangeManager.get_interchange_manager_scripted()
#import the asset
interchange_manager.import_asset("/game/AA0A/testpython/",source_data,import_asset_parameters)
editor_asset_subsystem.delete_directory(transient_path)
In the above example, a Python script is used to import the Equilibre.fbx file. The script checks to see if the file format is .gltf or .fbx and then assigns the correct pipeline.
Edit the Pipeline Stack
One of the advantages of the Interchange Framework is the ability to select and customize the pipeline stack, a customizable stack of processes through which asset data is processed. You can add pipelines to the default pipeline stack to add behaviors during the import process.
Unreal Engine ships with the following default pipelines:
- Default Assets Pipeline
- Default Material Pipeline
- Default Texture Pipeline
- Default Scene Assets Pipeline
- Default Scene Level Pipeline
- Default Graph Inspector Pipeline
Each default pipeline contains the most common options used for that type of import. You can further customize these pipelines to meet the specific needs of your project.
Edit an Existing Pipeline
Each of the default pipelines is customizable to fit the needs of your project and team.
The following are methods for customizing the import options for your project:
- Add, remove, or reorder the existing pipeline stack in your Project Settings.
- Change which pipelines are used by default.
- Modify the existing default pipelines.
- Create a custom pipeline.
Edit the Project Settings
You can find the pipeline stack in the Project Settings under Engine > Interchange:
The pipeline stack in Project Settings.
The pipeline stack contains the default settings for:
- Import Content
- Import Into Level
- Editor Interface
- Generic
- Editor Generic Pipeline Class
Import Content
Unreal Engine uses these settings to import content into the Content Drawer or Content Browser.
Click image for full size.
You can alter the settings for each type of content listed. You can also add additional headings if needed. For example, the default configuration contains Assets, Materials, and Textures. You could add an additional section to the pipeline stack for Animations and then be able to add one or more custom pipelines to handle incoming animation files.
Import Into Level
The File > Import Into Level option found in the main menu of the Editor window uses these settings when importing content into the engine. By default, this uses two pipelines that work together to import the Actor data from a file and then spawn an Actor in the level:
Click image for full size.
- DefaultSceneAssetPipeline is based on the same class as the DefaultAssetPipeline and is designed for scene import.
- DefaultSceneLevelPipeline generates the Actor in the world after the data passes through the DefaultSceneAssetPipeline.
Modify the Existing Default Pipelines
You can modify the properties of the default Interchange Pipelines to change the following:
- Default Values
- Visibility
- Read-only status
The Interchange Pipeline Details panel.
To change the settings of the default Interchange Pipelines, follow the steps below:
- Locate the default pipelines in the Content Drawer or Content Browser and double click one to open it. The pipelines are located in the Engine > Plugins >Interchange Framework Content > Pipelines folder. If you are unable to see the Engine folder, click on Settings in the top right corner of the Content Drawer or Content Browser and select the checkbox for Show Engine Content.
- Edit the following as needed:
- Visibility during the import and reimport process.
- Default setting.
- Whether the property is read only during the import process.
- Save and close the window.
Create a Custom Pipeline
You can create new Interchange Pipelines to further customize the import process using Blueprints, C++, or Python.
Create a Custom Pipeline Using Blueprints
To create a new Interchange Pipeline using Blueprints, follow the steps below:
Select InterchangePipelineBase as the Parent Class.
- Right click in the Content Drawer or Content Browser and select Create Blueprint Class.
- In the Pick Parent Class window, expand the All Classes category and select InterchangePipelineBase as its Parent Class.
Double click the new Blueprint to open the Blueprint Editor.A custom pipeline created using Blueprints has the following functions that can be overridden to add custom behavior.
Interchange Blueprint Override Functions.
| Override Function | Description |
|---|---|
| Scripted Can Execute on Any Thread | Communicates to the Interchange Manager that this pipeline can be executed in async mode. |
| Scripted Execute Export Pipeline | Executes during the export process (feature is currently nonfunctional). |
| Scripted Execute Pipeline | Executes after file translation. Creates the factory needed to generate Assets. |
| Scripted Execute Post Factory Pipeline | Executes after the factory creates an asset, but before the PostEditChange function is called. |
| Scripted Execute Post Import Pipeline | Executes after the Asset is completely imported and the PostEditChange function is called. |
| Scripted Set Reimport Source Index | Executes and tells the pipeline which source index to reimport. Use this function when reimporting an Asset that can have more than one source. For example, a Skeletal Mesh that has one source file for geometry and another for skinning information. |
Create a Custom Pipeline Using C++
To create a new Interchange pipeline using C++, Create a header file that contains the following:
#pragma once
#include "CoreMinimal.h"
#include "InterchangePipelineBase.h"
#include "InterchangeSourceData.h"
#include "Nodes/InterchangeBaseNodeContainer.h"
#include "InterchangeMyPipeline.generated.h"
UCLASS(BlueprintType)
class INTERCHANGEPIPELINES_API UInterchangeMyPipeline : public UInterchangePipelineBase
{
GENERATED_BODY()
protected:
virtual void ExecutePipeline(UInterchangeBaseNodeContainer* BaseNodeContainer, const TArray<UInterchangeSourceData*>& SourceDatas) override;
virtual bool CanExecuteOnAnyThread(EInterchangePipelineTask PipelineTask) override
{
return true;
}
};
Next, create a source file that contains the following:
#include "InterchangeMyPipeline.h"
void UInterchangeMyPipeline::ExecutePipeline(UInterchangeBaseNodeContainer* NodeContainer, const TArray<UInterchangeSourceData*>& InSourceDatas)
{
Super::ExecutePipeline(NodeContainer, InSourceDatas);
// Put the logic you need on either translated nodes or factory nodes
}
For more information on working with C++ in Unreal Engine, see Programming with C++.
Create a Custom Pipeline Using Python
To create a new Interchange Pipeline using Python script, create a new Python script and use the Project settings to add it to the Startup Scripts. For more information on working with Python scripting in Unreal Engine, see Scripting the Unreal Editor Using Python.
In the example script below, Python script is used to create a basic asset import pipeline.
import unreal
@unreal.uclass()
class PythonPipelineTest(unreal.InterchangePythonPipelineBase):
import_static_meshes = unreal.uproperty(bool,meta=dict(Category="StaticMesh"))
import_skeletal_meshes = unreal.uproperty(bool,meta=dict(Category="SkeletalMesh"))
def cast(self, object_to_cast, object_class):
try:
return object_class.cast(object_to_cast)
except:
return None
def recursive_set_node_properties(self, base_node_container, node_unique_id):
node = base_node_container.get_node(node_unique_id)
# Set the static mesh factory node enable state
static_mesh_node = self.cast(node, unreal.InterchangeStaticMeshFactoryNode)
if static_mesh_node:
static_mesh_node.set_enabled(self.import_static_meshes)
# Set the skeletal mesh factory node enable state
skeletal_mesh_node = self.cast(node, unreal.InterchangeSkeletalMeshFactoryNode)
if skeletal_mesh_node:
skeletal_mesh_node.set_enabled(self.import_static_meshes)
# Iterate children
childrens = base_node_container.get_node_children_uids(node.get_unique_id())
for child_uid in childrens:
self.recursive_set_node_properties(base_node_container, child_uid)
@unreal.ufunction(override=True)
def scripted_execute_pipeline(self, base_node_container, SourceDatas):
root_nodes = base_node_container.get_roots()
for node_unique_id in root_nodes:
self.recursive_set_node_properties(base_node_container, node_unique_id)
return True