This module explains how users can write their own plugins for Vortex Studio to add custom objects that can be used to build mechanisms or scenes.

Requirements

Participants must have some basic C/C++ training before taking this training module. To be able to compile and run code, participants must have Visual Studio 2015 (VC14),  Visual Studio 2017 (VC15), or Virtual Studio 2019 (VC16) installed.

Introduction

When using the Vortex Studio Editor, all of the objects that are used to create scenes and mechanisms are actually C++ plugins that CM Labs has created and delivered with the software. Using the Vortex Studio C++ API, users can add their own extensions to Vortex Studio and therefore their own custom functionality in the Editor and in applications deployed in the Player. All Vortex Studio plugins follow a standard structure dictated by Vortex Studio and use a mix of Vortex Studio specific functions and methods, along with standard C++, to implement their functionality. For example, in the case of default extensions like our Joystick input device extension, the plugin makes calls to DirectX and DirectInput functions to read data from a USB control device and make that data available to users.
Possibilities are endless when adding new functionality through extensions:

• Communications Interfaces: If a standard communication protocol like UDP does not suit your environment, a custom C++ plugin could communicate back and forth with other applications using communication protocols such as Serial or Corba.

• Hardware Interfaces: This type of plugin would allow you to have Vortex exchange data with hardware using its custom C++ API. This can include integrating a motion platform, joysticks, pedals, or another kind of hardware that is not supported by Vortex Studio out of the box. Data can be received from the hardware or sent back.

• Custom simulation models: If the models that come out the box with Vortex Studio lack functionality for your use case, plugins can be used to program those models manually. This is especially useful when using the integrated Python interpreter is too slow for the application.

• Additional graphical capabilities: Our Vortex Simulators offer a number of specialized graphical overlays that were developed as internal C++ plugins for Vortex Studio. Specialized graphical layers can be implemented by users using plugins.

Creating custom C++ plugins for Vortex Studio requires a copy of Microsoft Visual Studio.
A good starting point for the development of a C++ plugin for Vortex Studio is the code tutorial that can be found in the C:\CM Labs\Vortex Studio <version>\tutorials\ExUserExtension directory. By default, this extension implements very simple functionality to gather some information from a part and print it to the Vortex Editor debug log, but it could easily be modified to implement any type of functionality. To get more information about the creation of extensions, it is recommended to read  Vortex SDK: Customizing Vortex

Copying a sample and compiling it

1. Copy the C:\CM Labs\Vortex Studio <version>\tutorials\ExUserExtension folder to a new location, outside of the Vortex Studio 2020 file structure.

   
   
   

2. Double-click on the ExUserExtension.vcxproj to open it in Visual Studio. If you have multiple versions of the compiler installed, you may need to select the version to use. Vortex Studio is compatible with Visual Studio 2015, 2017, and 2019.

3. Set the Solution Configuration to Release.
   
   

   Open

   

4. In the Solution Explorer, right-click on the ExUserExtension Project and select Properties.

5. In the General section, change the Output Directory from ..\plugins to plugins. The sample project is configured to create the plugin file one directory above this project. This is likely not desirable.

6. Still in the General section, select a valid Target Platform Version based on the SDK(s) installed on your system.

7. In the C/C++ section, click in the Additional Include Directories field, click on the Drop-down Arrow on the right side and select the <Edit...> menu.

8. Change ..\..\include to C:\CM Labs\Vortex Studio <version>\include and click OK.

9. In the Linker section, click in the Additional Library Directories, click on the Drop-down Arrow on the right side and select the <Edit...> menu.

10. Remove all four entries and add a single one, pointing to C:\CM Labs\Vortex Studio <version>\lib, and click OK.

11. Go to the Linker | Debugging section and change the Generate Program Database File field from ../plugins/ExUserExtension.vxp.pdb to plugins/ExUserExtension.vxp.pdb

12. Go to the Linker | Advanced tab and change the Import Library field from ../plugins/ExUserExtension.vxp.lib to plugins/ExUserExtension.vxp.lib

13. Save the project and solution.

14. Right-click on the project and Build it. The result will be a file called ExUserExtension.vxp located in the plugins sub-directory from the location of your project.

VXP files are really just renamed DLL files that contain the code of your plugin.

Deploying the plugin

Your vxp file can reside anywhere on your file system.

Typically, Vortex searches for vxp in its plugins folder and dll in its bin folder. 

In order to add search locations, the Vortex Editor options, and your application setup file (including the player for example), must be edited to find and load your plugin.

You can put your library files alongside your plugin file, Vortex will find them.

Vortex Studio Editor

• Launch the Vortex Studio Editor

• Go to Options

• Go to the setup section

• Add your Plugin paths using the widget e.g. "C:\CM Labs\Vortex Studio <version>\tutorials\plugins"

• Save, you will be prompted to restart the editor

• Open

  

• Note the editor.vxc does not need to be modified.

Simulator Application

• Launch the Vortex Studio Editor

• Open your setup file

• In the Explorer, select the root of your setup file

• In the Property view, expand the PluginDirectories field

• Use the widget to increase the size

• Click on the ... button and select your folder e.g. "C:\CM Labs\Vortex Studio <version>\tutorials\plugins"

• Save your setup file

• Open

  

Alternate method

After compilation, the VXP file can also be copied to the C:\CM Labs\Vortex Studio <version>\plugins of your Vortex Studio installation. You can also automate this step by editing the Properties of your Visual Studio project once again, going to the Build Events | Post-Build Events, and entering the following text in the Command Line field: copy /Y $(OutDir)$(TargetName)$(TargetExt) "C:\CM Labs\Vortex Studio <version>\plugins". It should be noted that if the editor is running, you will not be able to copy new builds of your plugin to the plugins folder since the file will be in use by Windows.

Using a new module and extension in Vortex Studio

1. Make sure the new plugin file is available in the search paths of Vortex Studio.

2. Start the Vortex Studio Editor.

3. Click on the Options menu in the left sidebar and select the Plugins section.

4. Type "exu" in the Search box at the top right of the window, then expand the Samples section to see the extension we created. If you don't see your plugin listed in this list, it means that it failed to load correctly in the editor. This can happen if the plugin has dependencies on external DLLs and they are not found in the system path.
   

5. Since the ExUserExtension plugin contains both a module and an extension, the module needs to be added to the editor configuration file to be active in the editor. Open the C:\CM Labs\Vortex Studio <version>\resources\config\editor.vxc file in the Vortex Studio Editor.

6. Start typing "MyM" in the Toolbox search bar to narrow down the list of entries to a single one, containing MyModule.
   

7. Double-click on the custom module to add it to the list of active modules in the editor.
   

8. Notice that when the module is selected, the properties related to this module are shown in the Properties window.
   

9. Save the editor.vxc file, then close and restart the Vortex Studio Editor for the change to take effect.

10. Open an existing mechanism.

11. Search for My Extension in the Toolbox and add the resulting extension in the selected mechanism.
    

12. Assign one of the parts of your mechanism to the Part field of the new extension.

13. Save the mechanism.

14. Open a scene that contains this mechanism and Run it.

15. Stop the simulation after running for a few seconds.

16. Open a Windows Explorer window and enter %temp% in the address bar. This will show you the contents of your system's temp directory.

17. Sort files by modified time and look for a file called VortexEditor_computername_99999.log, where the computer name is the name of your computer, and 99999 is the process ID of the editor. You will likely have multiple copies of this file.

18. Open the latest editor log and scroll to the bottom of the log. You will see a bunch of log entries that include the words INFO - My Extension. This is the output that was generated by our plugin.