Choose your operating system:
Windows
macOS
Linux
The Datasmith importer can automatically bring in metadata about the objects it handles: information that you set up for those objects in your 3D design or CAD application. Metadata is most often used to store real-world information about the mechanical part or architectural element that the asset represents, such as the cost of the piece, the material it's made of, physical properties like its weight or insulation efficiency, or usage information like the maximum torque to apply to a part. You can also use metadata to store any other kind of information about an Asset that you might need for your Project.
Having this metadata available in the Unreal Editor and Unreal Engine can help you in two ways:
In your asset pipeline: You can use metadata when you're importing Assets and setting up your Levels to help distinguish different kinds of Assets and Actors that need different processing. For example:
You could use metadata during the Datasmith import process to identify certain kinds of Assets that you won't need in your final scene, so that you can skip importing them.
After import, you could use it to identify Actors in your Level that you want to merge, join, or replace, or whose Materials you want to replace.
At runtime in your game: You can use metadata at runtime to show users selected information about your Actors that comes from your source design tool. For example:
If the objects in your Level have BIM data that contains information about their structural properties, you might want to visualize that information in your interactive experience when the player selects those objects in the scene.
Or, if your project is a product configurator that allows the player to choose between different design options, you might want your gameplay logic to calculate and show a running total of the cost of the player's current choices based on the cost metadata assigned to the visible Assets.
This page describes how to get metadata into Unreal through the Datasmith import process, and how access it in your scripts both in the Editor and at runtime.
Metadata Sources
Datasmith currently imports metadata from the following design tools:
Datasmith currently only handles metadata on geometry, not other kinds of scene objects like lights or cameras.
Autodesk 3ds Max
Add your metadata to your 3ds Max objects on the User Defined tab of the Object Properties window.
To get to this panel for a mesh in 3ds Max:
Select the mesh in the outliner or the viewport.
Right-click and choose either Properties or Object Properties from the context menu, or select Edit > Properties from the main menu.
Enter your metadata into this panel as
key = value
pairs, as shown above.Be certain to leave a space on both sides of the equal (=) sign. If you don't, Datasmith won't recognize your metadata, and won't import it as expected.
You can also set up user-defined properties using MAXScript.
If your model was originally created in Revit and then imported into 3ds Max, the user-defined properties should already be preset by the 3ds Max importer with the model's BIM information.
Autodesk Revit
When you select an element in a Revit view, the Properties palette shows a list of all instance properties that are assigned to that element. You can change these values freely, and add your own custom properties.
For details on setting and using these properties, see the Revit help.
When you use Datasmith to import a Revit scene into the Unreal Editor, Datasmith assigns all instance properties for each Revit element as metadata on the Static Mesh Actor that it creates for that element in the Unreal Engine Level. This metadata also includes any type properties for the object's Revit type that are not empty.
Because Datasmith metadata is always a flat list of key-value pairs, the category headings in the Properties palette (such as Constraints, Structural, Dimensions and Identity Data in the image above) are not included. Only the names and values of the actual properties are preserved.
Dassault Systèmes SolidWorks
When you import a SolidWorks file, Datasmith adds a minimal amount of pre-set metadata to each Static Mesh Actor it creates, to indicate the part name and assembly of that mesh in the original SolidWorks design. However, Datasmith does not currently carry over any custom metadata properties that you add to your parts and assemblies.
Trimble SketchUp Pro
For each component you create in SketchUp, you can set Advanced Attributes such as price, size and status:
Datasmith imports all of these Advanced Attributes, including the Type value if any, into metadata.
The Datasmith metadata may be attached to the Actor that represents your component in the scene hierarchy, not to any of the individual Static Mesh Actors that represent the geometry of that component. If this is the case in your scene, you will need to adjust the Blueprint and Python examples shown below on this page.
Maxon Cinema 4D
In Cinema 4D, you can add User Data to each object in the scene by choosing User Data > Manage User Data in the Attributes panel.
For more information about how to do this, see the Cinema 4D documentation.
A few important notes apply to the data conversion:
In Cinema 4D, you can organize User Data into hierarchical groups, but Datasmith Metadata in Unreal Engine is always a flat list of keys and values. If your User Data contains any groups, as shown above, Datasmith flattens the hierarchy, putting all metadata keys from all groups into a single flat list. The group names themselves are discarded.
For example, in the image below, you can see that the groups are not imported, and the nested properties (IntegerData, VectorData, ColorData, and BooleanData) are moved to be siblings of the StringData and FloatData.
Regardless of the data type you set for your User Data in Cinema 4D, the value stored in the Datasmith Metadata is always a string. Wherever possible, Datasmith converts the original data value into a string that you can parse to extract the relevant information. However, some complex or special-purpose Cinema 4D data types are not supported, such as gradients, links to other scene objects, priority values, splines, and so on.
For example, the image below shows how the ColorData and VertexData items are converted to strings that contain the RGB and XYZ values of the original color and vertex respectively.
Datasmith only allows alphanumeric characters, hyphens, and underscores in the metadata key names. If the name of your User Data contains any other characters, those characters will be converted to underscores automatically.
The following image shows the result of importing the User Data shown above:
IFC 2x3
Datasmith imports all properties assigned to each IFC object and saves them as Datasmith Metadata on the corresponding Unreal Engine Actor.
Left: properties in an IFC file. Right: Datasmith Metadata built from those properties. Click for full image.
Notes about the data conversion:
IFC allows properties to be organized into groups. For example, the image above shows several groups: PSet_Revit_Mechanical, PSet_Revit_Dimensions, PSet_Revit_Identity Data, and so on. However, Datasmith Metadata in Unreal Engine is always a flat list of keys and values. If your IFC properties contain any groups, as shown above, Datasmith flattens the hierarchy, putting all metadata keys from all groups into a single flat list. The group names themselves are discarded.
Datasmith only allows alphanumeric characters, hyphens, and underscores in the metadata key names. If the name of your User Data contains any other characters, those characters will be converted to underscores automatically. For example, in the image above, the Fixture Units property is converted to Fixture_Units in the Datasmith Metadata.
All special characters in the metadata values are preserved.
Viewing Metadata in Unreal Editor
After the Datasmith import process is complete, you can view the metadata for any Static Mesh Actor in your Level in its Details panel, under the Asset User Data section:
Datasmith metadata is currently read-only in the Editor.
Accessing Metadata in Blueprint and Python
There are multiple different ways to access the metadata associated with your scene objects. Which one you should use depends on whether you need to access the metadata during the Datasmith import process, or after the import has finished.
All metadata keys and values are stored as strings in Unreal Engine, regardless of their original type in your design or CAD application. For example, if you set a metadata value in 3ds Max as a Boolean value like true
or as a number like 312
, they will be strings when you read them back in a script within Unreal. If you need the values to be Booleans or numbers, use a Blueprint conversion node like Utilities > String > String to Int or String to Float, or built-in Python string parsing functions like int()
or float()
.
Accessing Metadata During Import
If you need to access your metadata during the Datasmith import process—for example, to identify certain meshes that you want to filter out before generating Unreal Assets for your scene—you can read the metadata from the Datasmith Scene. For background information on how to run a script during the input process, see Customizing the Datasmith Import Process.
You'll find the metadata attached to mesh actor elements in the Datasmith Scene.
Choose your implementation method:
Python
Accessing Metadata After Import
When the import process finalizes your Datasmith Scene into Unreal Assets and Actors, it also applies the metadata from each mesh element in the Datasmith Scene to all the Actors in the Level that represent instances of that Static Mesh Asset. You can then use Blueprint or Python to retrieve the metadata for any or all of the Static Mesh Actors in your Level.
Choose your implementation method:
Python