# 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](_images/plugins-overview.png)

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: **Project Plugins** and **Global Plugins**. In the GUI, the plugin lists are grouped under three headings: **Program Plugins** (plugins loaded from the application or `additional_plugin_path` directories), **Project Plugins** (plugins loaded from the project’s plugin paths), and **Global Plugin Instances** (running instances of global plugins).

Project Plugins

**Project Plugins** are 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 entity.

Global Plugins

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

## Adding plugin to your project

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

Project Plugins

Add a folder next to the project file and put the plugin files into that folder. Add an entry under the _Plugin Paths_ setting that points to the created folder, 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, or in the directory configured by the application setting `additional_plugin_path`.

## Settings

Program Plugins

The plugins that the software finds in the application directories (next to the executable and in `additional_plugin_path`) are shown here. Each dynamic library file can contain multiple plugins, and to see which plugins are available in each file the tab can be opened.

Project Plugins

The plugins that the software finds in the _Plugin Paths_ are shown here. Each dynamic library file can contain multiple plugins, and to see which plugins 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.

Plugin Paths

A list of paths to folders containing the plugins for the project. Paths can be added or removed. When no path is given, the software looks for plugin files in the same folder as the project file. Paths can be relative or absolute in relation to the project file. There is support for using environment variables, which can be used to have cross-platform projects. To use an environment 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](_images/plugins-path.png)

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. A restart of the application is required for changes to this setting to take effect.

> **NOTE**
> 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](https://github.com/lucasg/Dependencies/releases)
        
    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 _Plugin Paths_ 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 _Plugin Paths_ under the Settings header or in the installation directory.
    
3.  Make sure that you use a unique entity ID for your plugin