Using Datasmith at Runtime

How to use Datasmith functionality from within an Unreal-based application at runtime.

Windows
MacOS
Linux

What is Datasmith Runtime

Datasmith Runtime is a collection of Datasmith features that are available at runtime (as opposed to an in-editor workflow) in an Unreal Engine-based application. You can use these features to create applications that can import .udatasmith files and manipulate them using Blueprints.

Collab Viewer DirectLink

Datasmith DirectLink is accessible in a cooked Unreal Engine-based application using Datasmith Runtime and Blueprints.

With Datasmith Runtime, you can create custom applications that take advantage of Datasmith DirectLink or visualize Datasmith data on demand as part of an iterative 3D workflow.

Enable the following plugins in your project to work with Datasmith Runtime:

  • Datasmith Content

  • Datasmith Importer

  • Datasmith Runtime

Datasmith Runtime is officially supported in Unreal Engine 4 and Unreal Engine 5 using Windows and MacOS. While Datasmith Runtime will work with Linux, this is experimental and you may experience instability and performance issues.

Using Datasmith Runtime with Blueprints

Datasmith Runtime exposes a variety of Datasmith features and import options using several Blueprint nodes. Listed below are the most common:

Runtime Nodes

The most common Datasmith Runtime Blueprint nodes.

Make Datasmith Runtime Import Options

Exposes several import parameters and converts them to a data structure:

Make Datasmith Runtime Import Options

Inputs

Description

Build Hierarchy

Determines whether the hierarchy of Actors is built. Choosing a more detailed hierarchy increases loading and rendering time.

  • None: Imports the source content with the hierarchy stored in the Datasmith Runtime Actor. Your content will not be represented in the World Outliner.

  • Simplified: Imports the source content while minimizing the number of Actors created. Allows exposing objects so the application can modify their properties, while limiting the number of draw calls due to the high number of Actors in the scene.

  • Unfiltered: Imports the source content with full hierarchy.

Build Collision

Determines the type of collision used for components.

  • No Collision: Does not have any representation in the physics engine. Provides the best possible performance.

  • Query Only (No Physical Collision): Uses only spatial queries. Useful for objects that do not need physical simulation such as pawn navigation. Improves performance.

  • Physics Only (No Query Collision): Uses only physics simulation. Useful for objects that do not need spatial queries. Improves performance.

  • Collision Enabled (Query and Physics): Uses both spatial queries and physics simulation.

Collision Type

Determines the type of collision used for Static Meshes.

  • Project Default: Uses the project's physics settings.

  • Simple and Complex: Uses both simple and complex shapes. Simple shapes are used for regular scene queries and collisions. Complex (per-poly) shapes are used for complex scene queries.

  • Use Simple Collision as Complex: Uses only simple shapes for all scene queries and collision tests.

  • Use Complex Collision as Simple: Uses complex (per-poly) shapes for all scene queries and collision tests. Can be used for simulation in static shapes only. Might be necessary if precise collision is needed while navigating a scene.

Import Metadata

Reads and imports metadata for Actors. Increases load time.

The Tesselation Options input is currently not used.

Set Import Options

Sets the value of the selected import options for Datasmith content using a Datasmith Runtime Actor. Uses a Datasmith Runtime Actor as the Target and Datasmith Runtime Import Options as its value.

Set Import Options

Load File

Loads the .udatasmith file located at the specified file path. Requires a File Path and Datasmith Runtime Actor as inputs.

Load File

Load File from Explorer

Opens a File Browser window so you can browse to a location and select a .udatasmith file. Requires a Datasmith Runtime Actor as input. A Default File Path is optional.

Load File from Explorer

Though it works with both Windows and Mac operating systems in Play In Editor (PIE), Load File from Explorer works only with Windows at runtime.

Get Direct Link Proxy

Returns an interface to a DirectLink connection called a Direct Link Proxy. This is the first step in creating a Datasmith DirectLink connection.

Get Direct Link Proxy

Get List of Sources

Gets a list of Datasmith DirectLink Sources. Requires a Direct Link Proxy as input.

DirectLink Get List of Sources

Open Connection with Index

Opens a DirectLink connection with the source located at the specified index value. Requires a Datasmith Runtime Actor and a Source Index as input.

Open Connection with Index

Close Connection

Closes an open DirectLink connection associated with a specified Datasmith Runtime Actor.

Close Connection

Loading Datasmith Content at Runtime

Using Datasmith Runtime, you can load Datasmith content inside a cooked application while having access to the hierarchy and Actor properties.

Click for full image.

To load Datasmith content using Blueprints:

  1. Create a new Actor Blueprint to contain the anchor point for the Datasmith content. You can do this by right-clicking in the Content Browser and selecting Blueprint Class from the context menu. In the Pick Parent Class window, select Actor and name the new Blueprint class DatasmithActor. Double-click the new Blueprint to open the editor.

    Pick Parent Class

    This anchor will serve as the origin point for the imported Datasmith content. If your content is offset from the origin in your source application, then Unreal Engine will maintain that offset from the anchor when the content is imported.

  2. Select the Event Graph tab and remove every event except Event BeginPlay. Drag a connection from Event BeginPlay and add the Spawn Actor From Class node. Open the Class dropdown menu and select DatasmithRuntimeActor. Promote the Return Value to a variable and name it Anchor.

    Runtime Spawn Actor

  3. Spawn Actor requires a Transform to spawn the Anchor. Right-click to the left of Spawn Actor and add a Make Transform node. Connect the output from Make Transform to the Spawn Transform pin on Spawn Actor.

    Make Transform

  4. To finish the Blueprint, click and drag from the execute pin of the Set node and add a Load File from Explorer node. Connect a reference to the Anchor variable to the Datasmith Runtime Actor input.

    Runtime Load Datasmith

  5. Save and Compile the Blueprint. Add a copy of your Anchor Blueprint to the level and press Play to test.

Runtime Load From Explorer

Unreal Engine will open a File Explorer window and ask you to select a file.

Creating a Datasmith DirectLink with Blueprints

You can also open a Datasmith DirectLink between one or more source applications and your Unreal Engine project at runtime using Datasmith Runtime.

  1. Start by creating a new Actor Blueprint to contain the anchor point for your Datasmith content. Double-click the new Blueprint to open the editor.

  2. Similar to the previous example, select the tab for the Event Graph and remove every event except for Event BeginPlay. Drag a connection off Event BeginPlay and add the Spawn Actor From Class node. Open the Class dropdown menu and select DatasmithRuntimeActor.

  3. A Transform is required to spawn the Anchor. Right-click to the left of Spawn Actor and add a Make Transform node. Connect the output from Make Transform to the Spawn Transform pin on Spawn Actor.

    Make Transform

  4. Next, you need a Direct Link Proxy to act as a connection point between your application and your source application. Drag a connection from the Set node and create a Get Direct Link Proxy. Promote the output to a variable and name it Direct Link Sources Proxy. Set it to be Public.

    Load DirectLink Blueprint

  5. Click the + button in the Functions section of the My Blueprints panel to create a new function. Name it DirectLinkUpdate. You will use this new function to trigger the DirectLink connection during runtime.

    Creating a new Blueprint Function

  6. Start by getting a copy of your Direct Link Proxy variable. Drag a line from the variable and create a Get List of Sources node. Promote the output to a variable to hold the list of DirectLink sources and make this variable public.

    Get List of Sources

  7. Drag a line from Set and create a Set Import Options node. Use this node to set some import options before connecting to the DirectLink source. It requires Datasmith Runtime Import Options and an anchor as inputs.

    Set Import Options

  8. Get a copy of your Anchor variable and connect it to the Target input on Set Input Options.

  9. Right-click and create a Make Datasmith Runtime Import Options node, and then drag a connection from the output to the Import Options input.

    Make Import Options

  10. Finish the function by dragging a line from Set Import Options and creating an Open Connection with Index node. This takes in an anchor and a Source Index as input. Connect the reference to the Anchor to the Target input.

    Open Connection with Index

  11. Create a new integer variable to hold your source index. Name it Source Index and connect it to the Source Index input on Open Connection with Index. An index value of 0 will connect to the first source in the list.

    Adding a Source Index

  12. Finally, click on the DirectLinkUpdate function in My Blueprints and enable Call In Editor in the Details panel. This option makes the function available at runtime in the Details of the Anchor object.

    Call In Editor

  13. Save and Compile. The finished Blueprint should look similar to the example below:

Start your source application and run the project by clicking the Play button. Select your Anchor in the World Outliner and click the Direct Link Update button in the Details panel. Then, click the Synchronize with Direct Link button in your source application. You will see your Datasmith content appear in your Level using the import options specified in the Blueprint.

Runtime Direct Link

Disabling the Use Less CPU when in Background option enables the engine to update the 3D viewport when the Unreal Engine window is not focused and when a Pawn in the level is not possessed. This option is found in the Editor Preferences under General > Performance.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss