/
Integrating Vortex Studio with Unreal Engine

Integrating Vortex Studio with Unreal Engine

Jan 11, 2023

This information is intended for users of Vortex Studio and Unreal Engine who want to integrate Vortex Studio simulation capabilities with Unreal, within a single process. This integration SDK is useful for single process simulation, VR, and using advanced blueprints logic in Unreal.

 

To use the following guide, you must be familiar with Vortex mechanisms, Vortex Graphics Galleries, and the Unreal Editor.

In the following documentation, you will be able to simulate Vortex mechanisms just like any other assets in an Unreal level.

With the Vortex Studio Plugin for Unreal Engine, the Unreal Editor lets you connect to parameters that you expose in Vortex Studio.

Any Vortex Studio simulation parameter can be sent to a function in an Unreal blueprint (get/set) and included in your Unreal level.

Vortex Studio automatically detects landscape components that you create in Unreal around a Vortex vehicle. A corresponding height field is created and streamed in Vortex Studio at run time. To monitor contacts and collisions during simulation, you can show the height field at the same time using the Vortex Studio Remote Debugger application.

During the simulation, Vortex Studio sends information about the position and orientation of each body to the Unreal Engine. Parameters and outputs can be accessed via the mechanism's interface. To ensure smooth gameplay with accurate synchronization and realistic movements, Vortex Studio sends information about the position and orientation of each body to the Unreal Engine. Parameters and outputs that you expose using a VHL interface let you control the Mechanism in Unreal.

Vortex Studio manages external devices, such as motion platforms and CANopen-compliant devices for controlling vehicles and enriching simulation.

Getting started...

 

 

Tell me about...

Installing the Vortex Studio Plugin

Installing the Vortex Studio Plugin involves downloading the plugin from the Unreal marketplace and configuring basic parameters.

Prerequisites

To use the Vortex Studio for Unreal Engine 4 plugin, you must have Vortex Studio and Unreal Engine 4.26.

Download the plugin from the Unreal Marketplace and install it following these steps:

IMPORTANT

You must have a valid Epic games user account to download the plugin from the Unreal Marketplace.

To install the Plugin with the Epic Games Launcher

  1. Open the Epic Games Launcher and login using your account information.

  2. Click the Marketplace tab.

  3. In the search bar, type Vortex.

    The Vortex Studio plugin appears in the list.

  4. Click Vortex Studio plugin and click on Install to Engine.

    The Vortex Studio plugin now appears in your Unreal projects

To install the Plugin from the 7z File

  1. Open the folder Plugins at the following address <Unreal Engine Installation Folder>\Engine\Plugins\.

  2. If you see a subfolder named VortexPlugin remove it.

  3. Copy the 7z named Vortex_Studio_Unreal_Plugin_[ReleaseNumber].7z into the Plugins folder.

  4. In the 7-zip context menu, select Extract Here.

  5. Delete the 7z file.

How to rebuild the Vortex Studio Plugin to a later version of Vortex Studio

The Vortex Studio Plugin available on the Epic Games Launcher might not match the version of your Vortex Studio installation. It is however possible to update the plugin's version following these steps.

Prerequisites

  • Unreal Engine version 4.26: We cannot guarantee that the plugin will work with a version other than 4.26

  • Microsoft Visual Studio: In order to compile the code, we recommend having Microsoft Visual Studio 2019.

  • Vortex Studio: A Vortex Studio installation is mandatory for the update and for the plugin to work with Unreal Engine.

How to update the plugin step-by-step

  1. Make sure that you currently have the Vortex Studio plugin from the Marketplace. If you don't, install it from the Marketplace page or from the Vault section of your library if it is there:

  2. Open your Windows Explorer and move to the folder where the Vortex Studio plugin was installed. For example, if Epic Games is installed at the default location, the path should be: C:\Program Files\Epic Games\UE_4.26\Engine\Plugins\Marketplace ;

  3. Inside the Marketplace folder, copy the folder VortexPlugin and copy it somewhere else such as in your Documents or on the Desktop. The important part is that it isn't inside the Epic Games repository.

  4. In your new location, open the VortexPlugin folder. There, delete both the Binaries and the Intermediate folders. The end result should look like this:

     

  5. From there, go in the folder named <Work Folder>\VortexPlugin\Source\ThirdParty\VortexStudio\Win64 . This is where we will have to change some files.

  6. Open a new Windows Explorer and open your Vortex Studio installation. The path should be C:\CM Labs\Vortex Studio <vortex version>

  7. The first step will be to copy and replace the library. In <Vortex Studio Installation>\lib, copy VortexIntegration.lib and copy it inside <Work Folder>\VortexPlugin\Source\ThirdParty\VortexStudio\Win64\lib. You will have to replace the existing library.

  8. The second step will be to copy the header files. In <Vortex Studio Installation>\include\VortexIntegration, copy all files and move them to <Work Folder>\VortexPlugin\Source\ThirdParty\VortexStudio\Win64\include\VortexIntegration . This will replace all files except the one named Version.h.

  9. Finally, open the file Version.h in <Work Folder>\VortexPlugin\Source\ThirdParty\VortexStudio\Win64\include\VortexIntegration and open the file VxVersion.h from <Vortex Studio Installation>\include\Vx. Each field of Version.h needs to be replaced to mirror the defined fields of VxVersion.h:

  10. Now that the files are updated, we need to compile the plugin. Open a CMD prompt and move to your Unreal Engine install in the batch file folder C:\Program Files\Epic Games\UE_4.26\Engine\Build\BatchFiles

  11. From here, run this command and replace the path location with your own:

    c:\Users\username\Desktop\vortex>"C:\Program Files\Epic Games\UE_4.26\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin -Plugin="c:\Users\username\Desktop\vortex\VortexPlugin\VortexPlugin.uplugin" -Package "c:\Users\username\Desktop\vortex\output" -CreateSubFolder -VS2019

    Where:

    1. RunUAT.bat is the batch file to run;

    2. BuildPlugin is the action;

    3. -Plugin is the path of the uplugin file from your new plugin folder;

    4. -Package is the output folder where your new plugin will be created. This must be outside the Unreal Engine directory;

    5. -CreateSubFolder is to specify how to create the plugin hierarchy;

    6. -VS2019 is to specify the compiler. This may change depending on your Microsoft Visual Studio installation.

  12. Now go back into your Epic Games application and uninstall the Vortex Studio plugin.

  13. Copy the folder VortexPlugin from your work folder into the plugin repository of Unreal Engine at this location: C:\Program Files\Epic Games\UE_4.26\Engine\Plugins

  14. Close and restart Epic Games. You should now be able to use the Vortex Plugin with your current version.

Running a Sample Project

For convenience, CM Labs offers a sample project that you can use to understand the different features of the Vortex Studio integration with Unreal. You can also use it as a starting point for your own projects.

To download the sample project files do the following:

  1. In a web browser go to https://cm-labs.exavault.com/share/view/1s3xe-amykk3cw

  2. To begin the download, click the filename of the sample project: Vortex_Studio_for_Unreal_Forklift_Sample_[ReleaseNumber].7z and extract the content on your computer.

  3. Open the Unreal Engine 4.26 and click the Launch button.

  4. In the Unreal Project Browser, click Browse and navigate to the extracted sample files.

  5. Open the ForkliftSim_uproject file.

    The project opens in the Unreal Editor.

    NOTE: It can take several minutes for the project and to load for the first time.

  6. To start the simulation, press the Play button.

    You can use a Direct Input game controller to control the forklift.

Organizing Vortex Studio Assets

This section assumes that you already have a good understanding of Vortex Studio Editor Documents.

The Vortex Studio plugin lets you import Vortex mechanisms to an Unreal project.

To create a valid Unreal project using Vortex Studio, you must copy the Vortex assets you want to use in your new Unreal project under the Content directory for the project. Vortex assets include files with the following formats:

  • *.vxmechanism (Mechanism Document)

  • *.vxassembly (Assembly Document)

  • *.vxgraphicgallery (Graphics Gallery Document)

  • *.vxc (Setup Document)

  • *.vxmaterials (Material Table)

Example

In this example, you have the following folder hierarchy for a Vortex forklift mechanism:

  • Forklift

    • Dynamics

      • Forklift.vxmechanism

      • Forklift_Assembly.vxassembly

    • Graphics

      • Forklift2016.vxgraphicgallery

To build a valid Unreal project, you must move the same folder structure to a sub-folder of the Content folder for your Unreal project. The structure of your Unreal project would appear as follows:

  • MyProject

    • MyProject.uproject

    • Config

      • ...

      • ...

    • Content

      • Vortex_Mechanisms

        • Forklift

          • Dynamics

            • Forklift.vxmechanism

            • Forklift_Assembly.vxassembly

          • Graphics

            • Forklift2016.vxgraphicgallery

It is easier to configure packaging settings for the project when all your Vortex assets exist under single directories in the project Content folder, with other assets that the Unreal Editor does not recognize.

Creating Your First Project

Bringing your first Vortex Studio project into Unreal involves verifying that the plugin is enabled, restarting the application, and verifying settings for the project with the plugin.  

About Vortex Studio Project Settings

You can customize several settings for your project in the Unreal Editor from the Project Settings window.

Specifically, you can customize the following settings for your project:

Anytime you change a setting, you must restart the application before they can take effect.

Category

Setting Name

Description

Category

Setting Name

Description

 

Data Provider's Path

This setting is for advanced usage.

Specifies a path (must be under the Content directory for the project) where some simulation data will be stored (for instance, Control Presets).

Default: None.

Application Setup

Use Default

When set to true, the Vortex Studio simulation in the Unreal application uses this default Application Setup Document packaged with Vortex Studio:

C:\CM Labs\Vortex Studio [ReleaseNumber]\resources\config\VortexIntegration.vxc

Default: True.

Custom Application Setup

This setting is only used when Application Setup->Use Default is false. It allows using a custom Application Setup Document for your Unreal project.

It is strongly recommended to use the default Application Setup Document for Vortex integrations as a starting point. The default file is under:

C:\CM Labs\Vortex Studio [ReleaseNumber]\resources\config\VortexIntegration.vxc

Your custom Application Setup Document must reside under the Content folder for the project. It should be under a specific sub-folder since it will be needed to package this Non-Asset folder when packaging your Unreal project.

Default: None (not used)

Material Table

Use Default

When set to true, the Vortex Studio simulation within Unreal will use this default Material Table packaged with Vortex Studio:

C:\CM Labs\Vortex Studio [ReleaseNumber]\resources\DynamicsMaterials\default.vxmaterials

Default: True

Custom Material Table

This setting is only used when Material Table->Use Default is false. It lets you specify a custom Material Table for your Unreal project.

It is strongly recommended that you use the default Material Table for Vortex Studio integrations as a starting point. The default file is under:

C:\CM Labs\Vortex Studio [ReleaseNumber]\resources\DynamicsMaterials\default.vxmaterials

Your custom Material Table must exist under the Content folder for your project. It must exist under a specific sub-folder since the application uses it to package this Non-Asset folder when packaging your Unreal project.

Default: None (not used)

Static Collision


Enable Landscape Collision Detection

If true, Unreal Landscapes will be transferred to Vortex Studio at runtime, using the underlying Vortex terrain paging system, so your mechanisms can collide with them.

For additional parameters that allow tuning the performance of the terrain paging system, please see the Static Collision → Terrain Paging category below.

Default: True

Enable Mesh Simple Collision Detection

If true, Collision On a Simple Shaped Mesh for all Unreal Static Meshes will be transferred to Vortex Studio at runtime, using the underlying Vortex terrain paging system, so your mechanisms can interact with them.

Note that Vortex Studio always uses the colliding geometry (simple or complex) that PhysX would use in Unreal.

For additional parameters that allow tuning the performance of the terrain paging system, please see the Static Collision → Terrain Paging category below.

Default: True

Enable Mesh Complex Collision Detection

If true, Collision On a More Complex Mesh for all Unreal Static Meshes will be transferred to Vortex Studio at runtime, using the underlying Vortex terrain paging system, so your mechanisms can interact with them.

Note that Vortex Studio always uses the colliding geometry (simple or complex) that PhysX would use in Unreal.

For additional parameters that allow tuning the performance of the terrain paging system, please see the Static Collision → Terrain Paging category below.

Default: True

Material Mappings

Allows associating an Unreal Physical Material to a Vortex Contact Material by name. This lets you specify which contact material a Vortex collision uses for computation purposes. The application only uses these associations when at least one of the following settings is enabled:

  • Enable Landscape Collision Detection

  • Enable Mesh Simple Collision Detection

  • Enable Mesh Complex Collision Detection

Default: None.

Static Collision → Terrain Paging Landscape

Tile Size XY

Size in meters, in world X and Y direction, of the square tiles used by the landscape terrain pager for landscape collision queries and caching.
Landscape component will be queried by the terrain pager in tiles of the given size around the dynamically moving Vortex mechanisms.
Tiles will be cached and only queried again if not already present in the cache in order to reduce query time, and in order to produce consistent, non-duplicate collision geometries in the Vortex simulation when multiple moving objects are operating in close proximity.

Use Tile Size XY value around the Landscape Component size for better results.

For more information on this parameter and the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 50 meters

Look Ahead Time

Specifies the time, in simulation seconds, the terrain pager should forecast ahead. All the terrain to be reached within the specified time, at the current velocity, will be requested.

If the terrain paging system experiences slow downs when navigating, consider reducing this parameter.

For more information on this parameter and  the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 1 second

Safety Band Size

Specifies the distance (in meters) to grow the paged region by, as a safety band, in order to account for objects changing direction.

If the terrain paging system experiences slow downs when navigating, consider reducing this parameter.

For more information on this parameter and  the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 1 meter

Static Collision → Terrain Paging Mesh

Tile Size XY

Size in meters, in world X and Y direction, of the square tiles used by the terrain pager for Mesh collision queries and caching.
Terrain will be queried by the terrain pager in tiles of the given size around the dynamically moving Vortex mechanisms.
Tiles will be cached and only queried again if not already present in the cache in order to reduce query time, and in order to produce consistent, non-duplicate collision geometries in the Vortex simulation when multiple moving objects are operating in close proximity.

If the terrain paging system experiences slow downs when navigating on a complex terrain with many obstacles (e.g., trees) consider reducing this parameter.

Note that a too drastic reduction (e.g., a value of 1 meter) can in itself lead to slowdowns. A balance can be found through experimentation.

For more information on this parameter and the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 50 meters

Look Ahead Time

Specifies the time, in simulation seconds, the terrain pager should forecast ahead. All the terrain to be reached within the specified time, at the current velocity, will be requested.

If the terrain paging system experiences slow downs when navigating on a complex terrain with many obstacles (e.g., trees) consider reducing this parameter.

For more information on this parameter and  the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 1 second

Safety Band Size

Specifies the distance (in meters) to grow the paged region by, as a safety band, in order to account for objects changing direction.

If the terrain paging system experiences slow downs when navigating on a complex terrain with many obstacles (e.g., trees) consider reducing this parameter.

For more information on this parameter and  the terrain paging system underlying the Unreal integration, refer to Integrating Vortex Studio using the VortexIntegration API.

Default: 1 meter

To Create a New Unreal Project Using the Vortex Studio Plugin

  1. Open the Unreal Engine 4.26 and click the Launch button.

  2. In the Unreal Editor, follow steps in Unreal documentation to create a new project.

  3. In the upper left, click Edit and then click Plugins.

  4. Confirm that the Vortex Studio plugin is installed.

  5. To enable the plugin, click to select Enabled.

  6. In the lower right, click Restart Now.

    The project re-opens with the Vortex Studio plugin enabled.

  7. Save the project to permanently enable the plugin.

Managing the Frame Rate Between Vortex Studio and the Unreal Editor

By default, new Unreal projects use a variable frame rate. The Vortex Studio integration in Unreal Engine uses a fixed frame rate of 60 Hz. If you do not change the default settings, the simulation will run at unrealistic speeds.

IMPORTANT

To maintain fidelity and realism in the simulation, you must configure project settings so that Unreal Engine and Vortex Studio both use a fixed frame rate.

Example: Setting the Frame Rate in Vortex Studio and the Unreal Engine

In this example, you want a simulation to run at 90 Hz.

To set the Frame Rate in the Unreal Editor, do the following:

  1. In the Unreal Editor, open your project.

  2. Click Edit and then click Project Settings.

  3. In the Project Settings window, under the Engine section, click General Settings.

  4. Scroll down to the Framerate section and do the following:

    1. Click to select the Use Fixed Frame Rate checkbox.

    2. In the Fixed Frame Rate field, specify 90.00.

  5. Save the settings and restart the project.

To set the Frame Rate in the Vortex Studio Editor, do the following:

Prerequisite: You must have a custom Simulator Setup User Guide (not the default one provided with Vortex Studio). For more information, see About Vortex Studio Project Settings.