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 platform and CANopen-compliant devices for controlling vehicles and enrich simulation.

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:

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.

Running a Sample Project

For convenience, CM Labs offers a sample project that you can use to understand 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

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:

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.

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 Integrating Vortex Studio with Unreal Engine#Vortex Studio Plugin Project Settings.

Make sure the custom application setup document is saved in the Content directory of your Unreal project.

1. In the Vortex Studio Editor, open the custom Application Setup Document for this project.
2. In the Explorer panel, click Setup.

   

3. On the right of screen, in the Properties panel, set the Simulation Frame Rate value to 90.00.

   

4. To save your changes, click the Save button.

   

5. When you restart the Unreal Editor, validate that the settings have been correctly configured.

Importing Mechanisms into Unreal

When you import a mechanism from Vortex Studio to the Unreal editor, the application identifies all Graphics Galleries (.vxgraphicgallery) in the mechanism file (.vxmechanism). The application imports all textures, materials, and meshes from the galleries as standard Unreal assets in the directory you specify.

Unreal creates a new Actor blueprint subclass to represent the Vortex Studio mechanism. You can use the new blueprint class to instantiate your Vortex Studio mechanism in an Unreal map. The class accomplishes the following things:

• It replicates the Vortex Studio graphics node hierarchy using the imported graphics galleries and uses it to create a hierarchy of corresponding Unreal Scene and Static Mesh components.

  

• It automatically updates the position and orientation of relevant Unreal Scene and Static Mesh components when Vortex Studio parts are moving.

  When a Vortex Studio part moves, the blueprint analyzes connections between parts and graphics nodes in Vortex Studio (typically under the Skin connection container) to detect which components move.

  The Unreal Editor does not expose the automatic mapping which occurs.
  The Skin connection container and all relevant graphic nodes in Vortex Studio are required for the integration and must not be deleted.

  

Importing a Vortex Studio mechanism into Unreal involves preparing your Vortex Studio project, specifying project settings in the Unreal Editor, and creating a new project blueprint.

Preparing your Vortex Studio Project for Import

When you import a mechanism from Vortex Studio, Unreal creates a version of each material in the Graphics Gallery. Each material that Unreal creates becomes a material instance of "BaseGraphicsMaterial". This material uses a single texture, the first albedo texture defined in the original material, and configures it to use UV set 0. The material instance uses no other textures or material inputs (such as Emission, Occlusion, Specular, or Gloss). Unreal imports every texture currently in the Graphics Gallery.

After you import a mechanism for Vortex Studio to the Unreal Editor, you can modify the graphics gallery contents and the Unreal Editor will automatically update behavior in your project there. Renaming any meshes in Unreal Editor breaks the related Unreal mesh <=> graphics node mapping. If a name changes, you must rename the mesh in Unreal Editor to the name it had when you imported the project.

To Import a Mechanism from Vortex Studio to the Unreal Editor

To add Vortex Studio mechanism to your Unreal project, do the following:

1. Make sure your Vortex Studio assets are 3241001360 in the Content folder for your Unreal project.
2. In the Unreal Editor, select the directory in the Content Browser where you will import your Vortex mechanism, including textures, material instances static meshes, and a VortexMechanism Unreal asset.
3. Option 1:
   1. Drag and drop the .vxmechanism file you want to import from Windows Explorer into the Content Browser.
   2. A pop-up window for selecting a folder appears
   3. After selecting a folder to save the generated blueprint, the application imports the mechanism.
4. Option 2
   1. Right-click on the directory in the Content Browser and then click Import to /Game/...
      
   2. A pop-up window for selecting a folder appears.
   3. Select the .vxmechanism file you want to import and click Open.
   4. The application imports the mechanism and generates a blueprint.
5. Select a folder for the new blueprint class and then click OK.
   
6. Drag-and-drop the generated mechanism blueprint from the Content Browser into the viewport.
   
7. You can open the blueprint to get or set additional values from Vortex Studio. The blueprint appears empty while the application maps the meshes and transforms from Vortex.
   

(Optional) To Take Control of the New Actor

To take control of the new Actor in Unreal, do the following:

1. In the Blueprint Editor for your new Actor, on the toolbar click File and then click Reparent Blueprint.

   

2. In the Reparent Blueprint list, search for Pawn and then click to select it.

   

3. To verify the new parent class for your blueprint, use the mouse to hover over the root element of the Components panel.

   The parent class of the blueprint is now Pawn.

   

4. To add a camera to the blueprint, click the +Add Component button and select the camera you want to add from the menu.

   

5. Click Compile and then click Save.

   

6. In the Components panel, click to select the new camera. Then, switch the center view to Viewport and use manipulators to move your camera to the correct location.

   

7. When the camera is added and in the correct position, in the Components panel, click select the root element (the self element).

   

8. On the right of the screen, in the Details panel, scroll down to the Pawn category and assign Auto Possess Player to a valid player ID. For example, Player 0.

   

9. Compile and save the blueprint.
10. In the main window of the project, click the Save Current button.

    

11. Now, because the Pawn blueprint is automatically possessed when the simulation begins, the 3D view should automatically display what the Blueprint camera sees when you press the Play button.

    

Enabling Vortex Simulation

For simulation with Vortex content to function correctly, your Unreal Level Blueprint must include functions to start and stop Vortex simulation in the context of your Unreal game play.

To add these functions, do the following:

1. Open your Level Blueprint:

   

2. In the Event Graph, find the EventBeginGameplay item.
3. In the EventGameplay item, use the left mouse button to click the Exec icon and drag it to the right and then release the mouse button.

   

   A pop-up window for adding a function appears
4. In the pop-up window, scroll to the Vortex →Application category and click Start Simulation.

   

5. In the Event Graph area, right-click anywhere on the empty space (not on a node).
6. In the search bar of the blueprint actions pop-up window that appears, type end play and then select the search result Event End Play.

   

7. Use the same process to add a Stop Simulation function. Click the Exec icon on the new Event End Play and drag it right before you release the mouse button. Then, add the Stop Simulation function.

   

8. Compile and save the Level Blueprint.
9. To save your map, press the Save Current button in the main Unreal Editor interface.

   

   To make sure that the Vortex simulation can start correctly, always press the Save Current button before you press Play. This of course will also save to disk any changes to your map.

   
   

    You can call the Start Simulation and Stop Simulation functions at any time, but you must make sure the Vortex simulation has completely stopped when you stop the Unreal simulation. All Vortex mechanisms must be loaded when the Vortex simulation is not running.

Get/Set Vortex Studio Mechanism Inputs and Outputs (IO)

After you import Vortex mechanisms to an Unreal project, you must get/set Vortex mechanism inputs and outputs (IO) from the Unreal simulation.

Available IO for mechanisms are defined by the following mechanism interfaces:

• VHL Interfaces
• Control Interfaces

Outputs from these interfaces can be read from Unreal, while inputs can be set with new values from the Unreal simulation.

For this purpose, a set of useful blueprint functions are exposed by the Vortex Studio plugin. To quickly find them, type VHL in the action search bar:

Each function must have a Mechanism Component as a target. This component is automatically created under the blueprint class created when you import a Vortex mechanism (see 3241001360).

The following functions are available to you:

All functions have similar structures:

You must connect the Exec input to the correct Event tick. For example, if the data is get/set every tick, then the Exec of Event Tick must connect to the Exec input for the new function.

Get VHLField as ...

Set VHLField as ...

Earthworks Systems

As a Vortex Studio and Unreal Engine user, you can combine the best of both worlds and use Vortex Studio Earthworks as your soil simulation in Unreal Engine. While an Unreal Engine Landscape can be sculpted and edited in Unreal Editor, it is usually a static and non-deformable object during the simulation. The Vortex Studio Earthwork Systems allows you to make otherwise rigid terrain surfaces deformable within a limited area. Earthmoving operations such as digging, trenching, filling, etc generate particles and respect mass conservation.

To do this, you will want to create one (or many) Deformable Terrains in Vortex Studio, as well as cutting tools or buckets, and import them in Unreal Engine. This guide will help you put it together for the following Earthworks constructs: Soil Bin, Deformable Terrain, Soil Particles. Refer to official Vortex Studio documentation (Earthwork Systems Tutorials) for the remaining Earthworks features: Soil Layer, Soil Emitter, Soil Culling Geometry, Soil Mass Sensor, Soil Materials, Bucket, Blade, Generic Bucket. They work without any specific adaptation needed for Unreal Engine.

Soilbin

As a Vortex Studio and Unreal Engine user, you can see your Vortex Studio Soilbin and interact with it in Unreal Engine. Here are the steps:

	Information	Media
1	How to view an Earthworks Soilbin in Unreal Engine Before you start, make sure that your Soilbin is correctly designed in Vortex Studio. You cannot make changes to the Soilbin extension from the Unreal Editor, and changes to inputs, outputs, and parameters that you make in Vortex Studio can cause problems in Unreal if they affect the mapping to the Procedural Mesh Component in the Unreal blueprint.
2	Expose your Soilbin and its World Transform to VHL using the Vortex Editor. For the proper position of the origin of the Soilbin in Unreal, expose the Outputs. World Transform of the Dynamics Soil Bin. This will be used from the blueprint as a position for the Procedural Mesh Component. To expose it, drag the field onto the VHL Interface's "Outputs" row.
3	To expose a Soilbin's shape so the Unreal object (created later in this guide) can conform to the Soilbin visuals, using Vortex Editor navigate to the VHL editing screen. Add an extension pointer output field by pressing '+' next to the "Outputs" column title. Keeping the VHL editing screen open navigate to your Soilbin in the Explorer tree. Select it and drag it to the "Data" column of the just created extension pointer output on the VHL editing screen. You will need to remember the names of these two outputs when working in Unreal, so it might be helpful for you to rename them.
4	In your Unreal project, open Plugins. Then, enable the 'Procedural Mesh' plugin. It can be found in the  Built-In" pulldown.
5	To prepare Unreal Editor to receive Soilbin data from Vortex, create a 'Procedural Mesh' component in a blueprint relevant to the Soilbin (truck, ground, pile, etc).
6	The 'Procedural Mesh' must be created and updated at runtime from the Vortex data. Here is a breakdown of the Blueprint image shown next to this step: Set the Material on the mesh Set the Transform of the Procedural Mesh based on data from Vortex Create the mesh with the Height Field data from Vortex Recreate the mesh when the Heightfield size changes or Update it if the size didn't change Optional: An empty Soil Bin will likely create graphical artifacts as the bottom face of the container exactly overlaps with the flat height field. To avoid this, you can raise or lower the Transform received from Vortex by a small amount.

Soil particles

When simulating any Earthworks System in Unreal Engine, you will want to see a visual representation of the dug soil (inside or falling from a bucket for example). In Vortex Studio, this dug soil is represented by the Vortex Studio Particle extension. Ensure that your particle system is set up with particle culling and has a reasonable maximum particle count. Refer to official Vortex Studio documentation (Earthwork Systems Tutorials). Once that is set up, here are the steps to use it in Unreal Engine:

Deformable Terrain

As a Vortex Studio and Unreal Engine user, you can see your Vortex Studio Deformable Terrain and interact with it in Unreal Engine. Here are the steps:

For general information about creating a Deformable Terrain in Vortex Studio, refer to Deformable Terrain

Visualizing the Vortex Simulation for Debugging Purposes Using the Vortex Remote Debugger

It can be useful to use the Vortex Studio Remote Debugger tool visualize your simulation. The tool lets you inspect collision geometries, contacts, part origins, and more to identify the source of problems.

The Remote Debugger can be very useful to view the Vortex Studio environment within Unreal. It allows the user to see collision geometries, contacts, part origins, etc.

Supported Colliding Objects in Unreal

The Unreal Engine supports multiple colliding objects in your simulations, including landscape and static meshes.

Landscape

The landscape is the primary tool to create a terrain in the Unreal Engine. This object uses a height map to define elevations of the terrain. It includes several Landscape Components (each with the same number of quads).

The plugin automatically discovers Landscape Components within a 50m x 50m range around any given Vortex Mechanism and creates the corresponding height field in the Vortex world (all this occurs at runtime).

The following image shows an example of a landscape component made of 127 X 127 quads (16129 quads):

You can inspect any generated height fields in the Vortex world using the Vortex Remote Debugger. The following image shows an example of generated height fields in the Vortex Remote Debugger:

Meshes That Do Not Simulate Physics

With the plugin, the application can generate collisions between a Vortex Mechanism and any Unreal mesh that does not simulate physics (static). For example, the system can generate collisions with the following:

• Static meshes
• Instanced static meshes, such as foliage
• Landscape splines

The Unreal Engine supports 2 different types of collisions:

• Simple Collision
• Complex Collision

By default, the application uses simple collisions, since they support better performance. You can override the collision type at different levels in Unreal Engine, in Project Settings or for the individual mesh. For more information about simple and complex collisions in Unreal, see: https://docs.unrealengine.com/en-US/Engine/Physics/SimpleVsComplex/index.html

The plugin always uses the same collision type as the one currently being used by PhysX on the Unreal Engine side. The integration supports the following shapes:

IMPORTANT: To function correctly, the static meshes cannot be in a blueprint containing a Deformable Terrain or a Soil Bin. The statics mesh must exist in a separate actor.

Example of Meshes that Do Not Simulate Physics

The following image shows a default simple collision used by a tree mesh (for foliage).

You can visualize the resulting geometry in the Vortex Remote Debugger:

Mapping Contact Materials

The Vortex Plugin for the Unreal Engine lets you specify which dynamic materials the application uses for a given collision. To configure this, you can map physical materials in Unreal to dynamics materials in Vortex Studio.

The physics properties you define for material in the Unreal Editor do not affect materials in Vortex Studio. The changes you make only apply to PhysX simulation in the Unreal Engine.

Create a Mapping for Contact Materials

To create a mapping for contact materials, do the following:

1. If a Physical Material does not already exist in your Unreal project for the type of material you want to use, create a new one:

   

2. Navigate to Project Settings → Vortex Studio and do one of the following:
   • Click to select the Vortex material table you want to use.
   • Accept the default material setting.
3. Create a Material Mapping. In this new mapping, select the Unreal physical material you want to use and write the Vortex dynamics material that you want to associate it with. You can create a landscape mapping, static Mesh mapping, or static mesh mapping with complex collisions.

   
   

   

   Map Landscape Materials

   The Unreal Editor lets you assign physical materials by Landscape Layer. You can inspect each later here:

   

   To map landscape materials, do the following:

   1. Click to select the layer that you will associate with a physical material.
   2. To automatically select the Landscape Layer Info Object, click on the lens icon next to it.
      
   3. From the Content Browser, double click on the Layer Info Object. The following window appears:

      

   4. Specify the Physical Material that you will associate with the layer and then press the Save.

      

   Map Static Meshes

   To map a static mesh, do the following:

   1. In the Unreal Editor, open a window for the static mesh that you want to associate with a physical material.
   2. Select the Simple Collision Physical Material that you will use for this mesh and save the changes.

      

      The system only applies the physical material if the mesh uses simple collisions

   Map a Static Mesh Using Complex Collisions

   To map a static mesh that uses complex collisions, do the following:

   1. In the Unreal Editor, open a window for the static mesh that you want to associate with a physical material.
   2. Search for graphics materials in the mesh.

      When you use a complex collision, the application uses a graphics material to apply each physical material (a one-to-one relationship). You must pay special attention to the graphics material you select for the static mesh.

      
   3. Double click on the graphics material you want to open an editor for it.

      

   4. From the editor window for the graphics material, select the physical material you will associate with the graphics material.

      

      The application only applies the physical materials if the mesh uses complex collisions.

4. (optional) Use the Vortex Studio Remote Debugger to debug Vortex Studio dynamics material.

   Using the Vortex Studio Remote Debugger tool, you can inspect the dynamics material the Vortex Studio uses for a given contact from the following page:

   

Packaging Your Project

Before you can distribute your simulation to users as an Unreal project, you must package it. Packaging ensures that all code and content is up to date and in the correct format to run on your target platform. For more information about packaging projects in Unreal, see the Packaging Projects topic in Unreal online documentation: https://docs.unrealengine.com/en-US/Engine/Basics/Projects/Packaging/index.html.

When you package an Unreal project that uses the Vortex Studio plugin, you must include all Vortex Studio assets with all the Unreal assets in the packaging process.

To prevent disorganization, CM Labs strongly recommends that you isolate the Vortex Studio assets, including mechanisms, assemblies, graphics galleries, the application setup document, and any material tables, in sub-folders under the Content folder of the Unreal project directory.

IMPORTANT: You can only use the Vortex Studio Plugin for Unreal Engine to package a project for Windows (64-bit)

To Package Your Project

To package a Vortex Mechanisms directory, including all dependent files, do the following:

1. In the Unreal Editor, open the Project Settings for you project.

   

2. Under Project, click to select Packaging.

   

3. At the bottom of the Packaging items, click Show Advanced.

   

4. Scroll down to Additional Non-Asset Directories to Copy.
5. To add a new entry, press the + button and click to select the Vortex_Mechanisms directory under the Content directory

   A packaged version of your Unreal project will now run correctly.

Viewing Vortex Studio Log Files in the Unreal Editor

When you develop a project in the Unreal Editor using Vortex Studio content, you may need to refer to application information about the Vortex Studio simulation for debugging purposes. To facilitate troubleshooting, the Vortex Studio plugin and the Vortex Studio application log messages. To access application logs, follow these steps:

To View Vortex Studio Plugin for Unreal Engine Logs

When you use the plugin, Vortex Studio generates logs in the Output Log window of the Unreal Editor. The application groups log files under the LogVortex category:

You can also find these logs in the Saved/Logs subfolder of your Unreal project.

Logs from the Vortex Application

Logs generated by the Vortex Studio application are output as .log files in the Saved/Logs subfolder of your Unreal project.

Limitations

Physical Interaction Between Unreal and Vortex Studio

The Vortex Studio Plugin for Unreal Engine allows Vortex mechanisms to interact with Unreal static objects only. When enabling this feature, a 50m x 50m detection box is used in the Unreal world around each Vortex Mechanisms to automatically detect all static obstacles. Those obstacles are streamed at runtime to Vortex to create corresponding collision geometries.

Supported Platform

The Vortex Studio Plugin for the Unreal Engine only supports the "Windows (64-bit)" platform.