Importing Assets Using Interchange

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 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 Process

These methods trigger the import process.

1. Begin the import process by using one of the methods listed above.

2. This opens the Interchange Pipeline Configuration window.

3. Select the pipeline stack to use from the Choose Pipeline Stack drop down menu.

4. Configure your settings and press Import to complete the process.

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:

1. Interchange converts the imported data into an intermediary node structure in Unreal Engine.

2. Interchange travels through the pipeline stack, and follows the instructions for the import.

3. 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.

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:

1. 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.

2. 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

1. Double-click the new Blueprint to open the editor.

2. 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

1. Add a Sequence node and connect it to the output of the function.

2. Drag from the Then 0 output and create a Create Source Data node to reference the existing file that will be imported.

3. Drag from the In File Name input on Create Source Data and, from the context menu, select Promote to Variable.

4. Name the new String variable FilePath. This holds the location of the file that will be imported.

5. In the blueprint, select the new variable and select the checkbox for Instance Editable.This makes the variable editable per instance of the Blueprint.

6. Promote the output of the Create Source Data node to a new variable named SourceData.

7. 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.

8. 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.

9. 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.

10. In the blueprint, select the new variable and select the checkbox for Instance Editable.

11. Get a reference to the Source Data variable and connect it to the Source Data input on Import Asset.

12. 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

1. 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.

2. Save and Compile your Blueprint.

Use Your New Blueprint

1. Drag a copy of the InterchangeActor blueprint into the level.

2. Click Play.

3. Select the InterchangeActor in the Outliner.

4. Fill in the FilePath and the SavePath in the Details panel.

5. Click the Interchange Import button to import your file.

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.

Import an Asset Using Python

You can use Python script to import assets into Unreal Engine through the Interchange Framework.

import unreal

gltf_path = "D:/projectPS/gltf/sketchfab/ship_in_a_bottle/scene.gltf"

source_data = unreal.InterchangeManager.create_source_data(gltf_path)
import_asset_parameters = unreal.ImportAssetParameters()
import_asset_parameters.is_automated = True

eas = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
import_asset_parameters.override_pipelines.append(eas.load_asset("/Interchange/Pipelines/DefaultSceneAssetsPipeline"))
import_asset_parameters.override_pipelines.append(eas.load_asset("/Interchange/Pipelines/DefaultSceneLevelPipeline"))

ic_mng = unreal.InterchangeManager.get_interchange_manager_scripted()
ic_mng.import_scene("/game/testinterchange/autopython/",source_data,import_asset_parameters)

In the above example, a Python script is used to import the scene.gltf file using a process similar to the Blueprint example.

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 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.

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:

• 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

To change the settings of the default Interchange Pipelines, follow the steps below:

1. 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.

2. Edit the following as needed:

   1. Visibility during the import and reimport process.

   2. Default setting.

   3. Whether the property is read only during the import process.

3. 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:

1. Right click in the Content Drawer or Content Browser and select Create Blueprint Class.

2. 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.

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