Vortex Studio SDK Introduction

Vortex® Studio SDK is designed to simulate content created inside the Vortex Studio Editor. It can either run stand-alone or integrate within your existing framework.


Vortex Architecture

Vortex Toolkit is based on the separation between content and application patterns. The application is fixed for a particular simulator, but it can load different content. As a rule of thumb, the application is created by developers and integrators, while content is created by mechanical engineers and level designers.

Content Representation

Content can be created and accessed through the Vortex SDK. All objects and extensions derive from IExtension and other specific interfaces, e.g., IDynamics for dynamics objects, IGraphic for graphics objects.

The scene is the root of the content; it is a container for mechanisms. The scene can have one or more extensions, and can consist of, for example, a digging area with vehicles.

Vortex Content Model

A mechanism is defined by Mechanism and is the main dynamics object with Vortex. It is the representation of such real-life objects as shovel bodies and shovel buckets. It is made up of assemblies, which are an amalgamation of parts, and constraints. Each mechanism can have one or more extensions.

Extensions are additional functionalities attached to a mechanism or scene. They extend the functionalities of their parents.

Relation Between Content and Application

Now that you understand the components that make up the content model and the application model, you can see how they interact with each other and their relationships.

The content model is comprised of the scene and one or more mechanisms, along with the scene's and the mechanism's extensions. VxApplication and the modules are designed for consuming each of the extension types.

Content and Application Models

Vortex Runtime Model

Application Object

The application (class VxApplication) is the central object that makes the simulation run. That is, it is the interface for the different executables connecting with Vortex.

The application contains simulator modules (class ISimulatorModule). At each application update, all modules are updated. Each module powers one aspect of the simulation, e.g., dynamics, graphics, sound, device.

A simulator usually has a fairly fixed set of modules, and they are generally closely related to the hardware.

The application also has extensions that are specific for a particular application, e.g., network, user interface, special graphic display.

An application without content is running empty; content is what populates the simulated world. The main objects in the content are the scene (class VxContent::Scene) and the mechanism (class VxDynamics::Mechanism). Both objects are containers for other objects, and their purpose is defined by the extensions they contain.

There can only be one instance of the VxApplication class per operating system process.
Additionally, in a given process's lifetime, a VxApplication instance should not be destroyed and replaced by a new instance. Proper cleanup of all its internal components and public add-ons is not guaranteed.

Modules and Extensions

The extension/module pattern is a consequence of the separation between application and content. An extension's job is related to a specific aspect of the simulation, e.g., dynamics, graphics, user interface, specific hardware, 3rd party SDK.

Each aspect is managed by a module, and implemented with an instance of ISimulatorModule. When content extensions are put in the application, each ISimulatorModule receives each IExtension and checks whether it should manage it.

For example, the graphics module interfaces with the graphics engine. It takes the information it receives from the IGraphic extensions in the content and sends it to the graphics driver for rendering at runtime.

An extension requires a module to be active in the simulation; it is called 'managed'.
If you are creating a new basic interface for a new feature, you need to create an ISimulatorModule that manages the extensions that will manage those interfaces.

Modern C++

Vortex follows several principles and features of modern C++ and is using C++ 11 as much as possible on the supported platforms.

  • First class objects support smart pointers.
  • nullptr usage is encouraged.
  • Vortex containers follow standard library iterators.
  • Standard library is used as much as possible.

SDK Tutorials

The tutorials are code examples that demonstrate how to work with Vortex Studio.

You can run tutorials from the command line or by double-clicking the tutorial batch file. You can also run the tutorial from the Microsoft Visual Studio Solution file. When the tutorial is a plugin, you can copy the VXP file to the Plugins directory of the Vortex Studio Editor or Vortex Studio Player application. The plugin will be loaded on startup and can be used in editing and simulation.

For information on installing Vortex, see Installation.

Running Tutorials from the Batch File

You can run the tutorials directly from your installation directly using the batch file.

To run a tutorial directly from installation:

  1. Go to the Tutorials > Bin directory of your installed distribution (for example, C:\CM Labs\Vortex Studio [current version]\tutorials\bin).
  2. Find the tutorial you want to run.
  3. Launch the tutorial using one of these methods:
    1. Linux
      • Double-click the runXYZ.sh file, e.g., runExDynamicsExtension.sh
      • From the command line, enter ./runXYZ.sh, e.g., ./runExDynamicsExtension.sh
    2.  Windows
      • Double-click the runXYZ.bat file, e.g., runExDynamicsExtension.bat
      • From the command line, enter runXYZ.bat or runXYZ, e.g., runExDynamicsExtension.bat or runExDynamicsExtension

    Do not run the tutorials by clicking on the executable (*.exe) file. These files are invoked in the scripts, which configure the environment variables needed prior to executing the tutorial.

  4. Press F1 to view the keyboard help for the tutorial you are running. Pressing the F1 cycles through available help for debugging, camera controls, and controls to manipulate the simulation depending on the simulation.

Modifying and Running Tutorials from the Solution

You can use the tutorial solution, Tutorials.sln, in conjunction with Microsoft Visual Studio to modify and run any of the tutorials. This allows you to quickly implement and learn how to work with Vortex before using it in your environment.

This method is available only to Windows users.

To open and run the tutorials with the solution file:

  1. Navigate to the Tutorials folder of your installed distribution (for example, C:\CM Labs\Vortex Studio [current version]\tutorials.
  2. Double-click Tutorials.sln. Microsoft Visual Studio opens with all the tutorials loaded in the Solution Explorer.
  3. Right-click a tutorial in the Solution Explorer and select Build.
    Right-click on the tutorial folder level, not at the file level.
  4. Right-click the tutorial after building and select Set as StartUp Project.
  5. Click Run from Microsoft Visual Studio. Two consoles open: one console displays the graphical view of the tutorial; the other console displays the dynamics information.
All the actions available to you from the right-click menu of each tutorial are also available from the ALL BUILD right-click menu. Clicking ALL BUILD performs the action on all the tutorials in the list. Press F1 to view the keyboard help for the tutorial you are running. Pressing the F1 cycles through available help for debugging, camera controls, and controls to manipulate the simulation depending on the simulation.


Next topic: Customizing Vortex