24. Importing a Model

The AGX Dynamics for Unreal import feature is accessible from the AGX menu in the top Menu Bar and the File tab of the AGX Mode.

The import options are accessible from the AGX top menu bar item.

The import options are accessible from the File tab of the AGX Mode.

When importing an AGX Dynamics archive (.agx) or a URDF (.urdf) file into AGX Dynamics for Unreal, the result is a Blueprint containing the imported objects. A key point is that regardless of a model being imported from an AGX Dynamics archive or a URDF file, everything is translated to AGX Dynamics for Unreal Components and Assets and can be used in the same way.

Warning

The resulting Blueprint, called the main Blueprint, derives from a base Blueprint named BP_Base_<GUID>. This base Blueprint should never be manually edited. If edited, the `Model Synchronization feature will not work properly. Any edits should be done on the main Blueprint or instances of it. See Synchronize Model for more details.

24.1. Import settings

When selecting AGX > File > Import Model to Blueprint and then specifying a model to import, the following dialog appears.

Import settings used during the import process.

By selecting Ignore disabled Trimeshes, any agxCollide::Trimesh that has collision disabled will not be imported. Only its RenderData will be imported, if it exists. This can be an efficient way to reduce the number of components imported for large models.

24.2. Synchronize Model

It is possible to synchronize a previously imported Blueprint against the source file it was originally imported from. This is useful for example when changes to the original source file has been made, but a complete, new, Import into AGX Dynamics for Unreal is not desired or appropriate. The Synchronize Model feature will attempt to update the Blueprint according to the selected source file but without removing user changes made in the Blueprint.

Warning

Data loss may occur during model synchronization. The algorithm will attempt to keep user changes untouched but it cannot be guaranteed. It is recommended to use a version control or backup system for your imported models.

There are two main ways to access the Synchronize Model feature from the Unreal Editor:

1. Right click the Blueprint in the Content Browser and select Scripted Asset Actions > AGX Synchronize Model.

Accessing model synchronization from the context menu.

2. From within the Blueprint, select the AGX Model Source Component and klick the Syncronize Model button.

Accessing model synchronization from the details panel of the AGX Model Source Component.

Note

This feature requires the AGX Dynamics objects to have persistent UUID’s between writes to the source file. This works automatically when using models created in e.g. Algoryx Momentum. If the model is created in any other environment, for example a Python or C++ program, consistent UUIDs must be provided by that program.

24.2.1. Limitations

Currently, the following Components are not supported by the Synchronize Model featured and are always ignored:

• Wire

• Track

24.3. Importing AGX Dynamics Archives

The following screenshot shows an example scene with a wheel loader model.

An example scene consisting of a wheel loader model.

When importing the example scene to a Blueprint the following is produced:

A scene with a wheel loader model imported as a Blueprint.

24.3.1. Wire and Track Import Limitation

For Wire and Track, the complete dynamic state of the model is not preserved when imported. For example, the velocities of each lumped node of a Wire will not be preserved during the import process, however the position of the nodes will be. The result of an import of any of these models will replicate the state of the original model as far as possible, but since the information about the dynamic state is not preserved, the resulting imported model can be considered to be at rest.

24.3.2. Models With no Import Support

The following models are not supported when importing from an AGX Dynamics archive (.agx):

• Terrain

• Height Field

24.3.3. What is Imported and What Isn’t

When importing an .agx file, only objects contained within that .agx file are imported, for example Rigid Bodies, Constraints, Materials, Wires etc. Global settings such as gravity, time step or solver settings are not imported and will be ignored.

24.4. Importing URDF Models

When selecting AGX > File > Import Model to Blueprint the following dialog appears.

Import dialog.

If a URDF file is selected and it contains any filename paths, an additional URDF Package section is shown.

Specifying the URDF package directory.

The directory selected here corresponds to the package:// part of any filename path used in the URDF (.urdf) file and must match. This is common when e.g. having mesh files that are used in the URDF model. The figure below shows an example of this.

An example URDF (.urdf) file having package:// as part of a filename path.

Once the import procedure is complete, a Blueprint containing the imported objects will appear and can be used as normal.

After importing a URDF file, the result is a Blueprint containing the imported objects.

24.4.1. Limitations

The URDF import feature in AGX Dynamics for Unreal supports the same features, and have the same limitations, as the Algoryx Dynamics URDF Reader except for a few things:

• URDF’s mimic feature is not supported.
• Textures from mesh files such as e.g. collada (.dae) files are not supported.

24.5. Modifying the Imported Blueprint

During model import two Blueprints are created.

The first Blueprint, placed within the Blueprints sub-folder of the model’s folder in the Content Browser and named with a GUID, is, and should remain, a straight copy of the source model. This means that no changes to this Blueprint should ever be made. This Blueprint is called the base Blueprint. The Components and Properties within the base Blueprint are used for comparison when performing a model synchronization and the synchronization may fail or produce incorrect results if the base Blueprint has been modified.

The second Blueprint, placed in the root of the model’s folder in the Content Browser and named after the imported file, is the Blueprint that may be modified and is used to populate levels. This Blueprint is called the main Blueprint. You may modify properties on Components inherited from the base Blueprint and add new Components, both from the AGX Dynamics for Unreal library of Components and Components provided by Unreal Engine.

Location of the main and base Blueprints after import.

24.5.1. Replacing Render Materials

Some Unreal Editor features make edits to Blueprints automatically. For example, the Replace References feature can be used to replace all usage of a render Material with another Material. If done to replace an imported Material then Unreal Editor will do the replacement on the base Blueprint instead of the main Blueprint, which means that if a Model Synchronization is performed then the new Materials will be overwritten with the Materials from the imported model.

Since replacing render Materials is a common requirement the Model Source Component provides a feature to replace Materials in a way that is compatible with Model Synchronization. From the Details panel for the Model Source Component, within the Material Replacer category, select the current Material that should be replaced and the new Material that should be used instead and click the Replace Materials button.

UI widgets in the Details panel for replacing all usages of a Material with another Material in a Blueprint or Actor.

This will update all Static Meshes within the main Blueprint and instances of that Blueprint that doesn’t already override the Material to use the new Material. This can also be done on a particular instance of the Blueprint to modify that instance only.

24.5.2. Modifying Imported Assets

No assets created during the import may be modified. If you need to tweak the Properties of an imported asset then create a copy of the asset and modify the copy instead.

24.6. Improving Blueprint Editor Performance

For very large models with several hundreds or even thousands of components, the Blueprint editor may be slow to react to user input.

One way to reduce the number of components of a Blueprint is to use the setting Ignore disabled Trimeshes during the import process. See Import settings for more information about import settings.

To improve context menu responstime in the Blueprint Event Graph, it is recommended to de-activate the Context Sensitive setting shown in the image below.

By right-clicking anywhere in the Event Graph the Context Sensitive option can be de-activated.