Plugins

Plugins can be used to extend functionality. This could be everything from integration with a vehicle to displaying information in the 3D view. Plugin files are dynamic library files that have the file ending .dll on Windows and .so on Linux. Plugins can also extend the sidebar GUI which makes it easier to interact with the plugin as shown in the image below.

plugins overview

To get more information about SDK pricing and how to write plugins, please contact your Voysys representative.

Types of plugins

There are two different kinds of plugins that can be added: Program Plugins and Global Plugins.

Program Plugins

Program Plugins are plugins that is specific to a certain project file, the plugin will only run after it has been added to the project scene graph. The plugin will be visible to the user as an entity and is added to the project in the same way as any other entities.

Global Plugins

Global plugins are different from Program Plugins as Global plugins are not added to the scene graph. All Global Plugins that the software can find will be running regardless of which project that is loaded. A Global Plugin can be used for example to change project depending on an external signal.

Adding plugin to your project

Adding a plugin file to your project is simple, but depending on if it is a Program Plugin or a Global Plugin the steps are different.

Program Plugins

Add a folder next to the project file and put the plugin files into that folder. Set the Project Plugins Path setting to point to the created folder and then save and reload the project. Now when pressing the Add Child button the plugins are visible at the bottom of the list.

Global Plugins

Global plugins are loaded at application startup. The dynamic library file must be located in the same directory as the Player or Streamer executable.

Settings

Program Plugins

The plugins that the software finds in the Project Plugins Path will be shown here. Each dynamic library file can contain multiple plugins and to see which plugins that are available in each file the tab can be opened.

Global Plugin Instances

All global plugins will be visible here. If the global plugin has any GUI elements that can be changed they will be visible here.

Project Plugins Path

This is the path to the folder containing the plugins for the project. When no path is given, the software looks for plugin files in the same folder as the project file. The path can be set as relative and absolute in relation to the project file. There is support for using environmental variables in the path which can be used to have cross-platform projects. To use an environmental variable in your path, put the name of the variable between two percentage signs (e.g. %HOME%). To see the expanded path, hover over the input box.

plugins path
Figure 1. Expanded plugin path.
Hot Reloading

When enabled, the software checks if the plugin has been updated and reloads it without the need to reopen the project.

Use of Hot Reloading in production is strongly discouraged.

Plugin Troubleshoot Guide

In the event that a plugin does not show up in the Entity list, follow these steps:

Windows

  1. Dependencies

    1. Download and run Dependencies GUI

    2. Open your plugin DLL in Dependencies

    3. Look for any unresolved dependencies

  2. If the plugin still doesn’t show up, make sure that the plugin is either in the specified Project Plugins Path under the Settings header, or in the installation directory

  3. Make sure that you use a unique entity ID for your plugin

Linux

  1. Dependencies

    1. Open a terminal window in your plugin directory

    2. Call ldd -r -d ./${PLUGIN_PATH}.so where ${PLUGIN_PATH} is the path to your plugin

    3. Look for any dependencies that are not met and resolve them by installing the appropriate libraries

  2. If the plugin still doesn’t show up, make sure that the plugin is either in the specified Project Plugins Path under the Settings header or in the installation directory.

  3. Make sure that you use a unique entity ID for your plugin