Exporting an iModel to Unreal Datasmith as a combined mesh

Introduction

This tutorial will guide you through exporting your iTwin into the Datasmith format, and then importing that file directly into Unreal Engine.

Info

Skill level:

Basic

Duration:

20 minutes

Prerequisites

This tutorial assumes that you already have:

  • Unreal Engine 4.26.1 or later installed.
    • It is recommended to install Unreal before the iTwin Exporter for Datasmith app because the app requires some components that Unreal will install for you. If you want to install the exporter first anyway, the application will direct you to manually install the components that Unreal would install.
  • the iTwin Exporter for Datasmith application installed.
    • The installer can be downloaded by clicking “Download now” here, and then running the installer will complete the installation.
  • Visual Studio installed, and the “Game Development with C++” and “.NET desktop development” workloads installed. You must also have the additional Microsoft.NETCore.App, version 3.1.0 component installed, and your Visual Studio build tools must be up to date.
    • If Visual Studio’s build tools are not up to date, the plugin may fail to compile on later Unreal Engine versions. Be sure to open the Visual Studio installer and update.
  • an Unreal project set up, you can follow Epic’s Creating a New Project guide if you don’t have one.
    • We recommend using the Architecture, Engineering & Construction template so the required Datasmith importer plugin is enabled. If you choose not to do this, you will need to enable that plugin yourself in your project’s settings.

Make sure you install both C++ Game Development and .NET desktop development workloads for Visual Studio, and have recently updated Visual Studio.

visual studio required workloads

1. Select your iModel

The iTwin Exporter for Datasmith opens to the sign in page. Hit the Sign In button to be prompted to log in through your default browser. This will bring you to the iModel Select Screen of your most recent project.

To access other projects, select the project dropdown in the header and choose one of the recent projects or click See all my projects to open the Project Select Screen.

Upon entering either of the select screens, the search box in the top-right is focused, so you can immediately type to filter by name and find your iModel or project if you have several.

To see not only your most recent project’s models, click the See all your projects option in the project dropdown

see all projects button placement

2. Export your iModel as a combined-mesh

Once you’ve selected your project and found your iModel, you can perform an export immediately by clicking the Export Button.

quick 'export' button on the tile

This will bring up the Advanced Export Dialog, from which you can toggle on the Combine All Meshes Toggle, and then press the Confirm Export Button at the bottom of the dialog.

the advanced export dialog as it appears after using the quick export button

Simply press the button and use your system’s save file dialog to choose under what name and where to save the resulting datasmith content. Then wait for the export to complete, which is signified by a green success message appearing.

You may also click on your iModel card’s image or its View Button to enter the viewer, and can run a combined-mesh export with the left-most button in the top-left horizontal toolbar.

in-viewer button

Once the export has completed, you should have a file as you named it, like myIModelName.udatasmith and an _Assets folder with the same name as a prefix, for example myIModelName_Assets, in your chosen export location. You should be able to find them in your file browser.

Resulting Datasmith Files

3. Install the iTwin Unreal Datasmith Plugin in your Unreal project

Now we can navigate back to the select screen and use the plugin installer button to install the iTwin Unreal Datasmith Plugin to our Unreal project. Hit the Home Button in the top left, or use the project dropdown and press the See all my projects option to navigate back to the Project Select Screen.

navigate home button placement

From the select screen, you can press the blue Install Plugin Button at the bottom of the application, and in the file dialog find the .uproject file belonging to your Unreal project you created. Just choose that .uproject file and the plugin will be installed to that project.

install plugin button placement

Make sure to close and reopen the Unreal project if it is open. Upon opening the project for the first time since the installation, it may prompt to rebuild the plugin. This is normal, and you should just allow it and wait for it to finish. It may also say that it was designed for a different engine version, but you can ignore this and tell it to continue building, the plugin has been tested in Unreal Engine versions 4.26.0 through 5.0.1 as of writing. If the rebuild fails, make sure you’ve met all of the Prerequisites.

rebuild prompt

4. Import your iModel

In the Unreal Engine editor, use the Datasmith import button to open a file system dialog and select your .udatasmith file to import it into the scene.

unreal editor's datasmith import button placement

Choose a folder to place the content imported from Datasmith into in your content browser, then change any other import settings you need, such as disabling lightmap UV generation if you will only be using dynamic lights to light your scene in Unreal. Then just wait for the import process to finish.

If your scene has a schedule script or other animations, a Level Sequence asset will have been created to control the objects with transform animations. Due to limitations in the Datasmith API, you must manually add the level sequence to the scene. Consult Unreal Engine’s Sequencer Overview for more information on level sequences.

Open the Animations subfolder in the folder where you chose to import. The folder will only exist if you have transformation animations. You can drag and drop the animation asset into the viewport to add it to the scene.

drag-and-drop-level-sequence

Then, in the properties of the newly spawned Level Sequence Actor, toggle the Auto Play checkbox so that it is checked, which matches the default auto play set for the ScheduledActor in your combined-mesh scene that controls the non-transformation animations.

auto play

5. Use a realistic material

Unreal’s starter content comes with a few high-fidelity materials that we can use to test realistic materials on our iModel. For a simple start to applying materials, open StarterContent/Materials in the content browser and drag and drop materials onto your static meshes.

starter content materials from unreal engine

We dragged and dropped some glass, concrete, metal, grass, wood, and cobblestone into our scene to see some high-fidelity materials.

Our sample scene would particularly have benefited from filtering out the tree and grass models and replacing them with more realistic or animated ones, but that is something to explore in your Unreal project.

scene after drag and drop

Materials must opt-in to visibility animation if using the combined-mesh export. You can edit materials attached to your mesh by double clicking the material in the material slots of your static mesh actor’s properties.

material slots of combined mesh

Then select the material result node, if it is not already automatically selected as you open the editor, and set your material’s blend mode in the details panel to “masked”, unless it is already “translucent” in which case leave it as is. For more information on material blend modes in Unreal, see the documentation article Material Blend Modes.

material editor blend mode dropdown

Finally, right click in open space to the left of the result node and use the search to place a MaterialFunctionCall node. In the details panel, you can select a Material Function to use for this node, use MF_SynchroVisibilityAnimate which comes with the plugin. Drag the output pin of the function to the Opacity Mask result pin (or Opacity if the material was translucent).

Now save and apply your material in the top left of the material editor, and your material will animate correctly with the visibility of the scene.

More resources that you may like

Extended functionality and workflow descriptions in iTwin Exporter for Datasmith
Unreal's documentation on importing datasmith content
Create Unreal Dataprep scripts that use your iTwin data