# Plugins

Enable, configure, and troubleshoot Oden plugins.

Last validated: 2026-05-05

Plugins extend Oden with custom entities, global background logic, capture sources, controls, and project-specific GUI. Load plugin files from trusted project or application paths, then add the registered plugin entity or configure the global instance.

## Load a project plugin

Use a project plugin when the plugin belongs to one `.vproj` and should travel with that project.

1.  Put the plugin dynamic library and its runtime dependencies in a project folder, for example `bin`. The plugin file normally ends in `.dll` on Windows and `.so` on Linux.
    
2.  Open the project in Oden.
    
3.  Open `Plugins`.
    
4.  Open `Plugin Paths`.
    
5.  Select `Add`.
    
6.  Set `Plugin Path` to the plugin folder. Use a relative path when the project and plugin folder should move together. The path may contain `%HOME%` for the user’s home directory. Hover the field in the GUI to inspect the expanded path when diagnosing loading problems.
    
7.  Save and reopen the project so Oden scans the path.
    
8.  Open `Plugins` again and confirm that the library appears under `Project Plugins`.
    
9.  Add the plugin entity from the normal entity `Add Child` menu when the plugin registers an entity.
    
10.  Configure the entity options exposed by the plugin, then save the project.
     

If the plugin is in the same folder as the project file, Oden scans that folder even when no explicit plugin path is set.

## Configure global plugin instances

Use a global plugin when the plugin should run without being added to the scene graph. Global plugin instances appear under `Plugins` > `Global Plugin Instances`.

1.  Install the plugin where the application scans program plugins, or set the application-level additional plugin path.
    
2.  Restart Oden.
    
3.  Open `Plugins`.
    
4.  Open `Global Plugin Instances`.
    
5.  Expand the plugin name.
    
6.  Configure the plugin-provided controls.
    
7.  Disable the instance only when the project must load without that global behavior.
    

Global plugin availability depends on the application startup paths, so restart Oden after changing those paths.

## Pass plugin parameters on startup

Use `--plugin-param` for values that should be supplied by launch scripts or deployment tooling instead of the project file.

```bash
oden-streamer --plugin-param tcp_port 4000 --plugin-param mode production
```

Plugins read these key/value pairs through the plugin settings API. The supported keys are plugin-specific.

## Use plugin video capture

Some plugins register a video capture backend. Use it from a video entity when the source is not a built-in camera, file, or network input.

1.  Load the plugin and reopen the project.
    
2.  Open the video entity.
    
3.  Open `Input`.
    
4.  Set `Type` to `Plugin video capture`.
    
5.  Select or confirm the plugin-provided capture type.
    
6.  Configure the plugin-defined options.
    
7.  Start the input and check the texture preview.
    

For the surrounding video input workflow, see [Camera Inputs](camera-inputs.md).

## Troubleshoot plugin loading

1.  Confirm the plugin path is visible in `Plugins` > `Plugin Paths`.
    
2.  Reopen the project after changing `Plugin Path`; reopen Oden after changing application plugin paths.
    
3.  Confirm the plugin file matches the operating system and Oden build architecture.
    
4.  Check that all dynamic-library dependencies are available. Use Dependencies GUI on Windows, or run `ldd -r -d ./plugin.so` on Linux.
    
5.  Confirm the plugin registers a unique entity ID.
    
6.  Check `Project Plugins` for the library and expand it to see registered plugin entities.
    
7.  If `Hot Reloading` is enabled, restart Oden before production testing.
    

> **NOTE**
> `Hot Reloading` is intended for development. Do not rely on it for deployed systems.

## Project-file names

Project plugin folders are stored in `plugin_dll_paths`. The older single `plugin_dll_path` field is deprecated and is patched into `plugin_dll_paths` when old projects load.

```libconfig
plugin_dll_paths : [ "bin" ];

scene_manager : {
    scenes : ( {
        root_entity : {
            children : ( {
                type : "plugin_entity";
                plugin_entity : {
                    type_id : "0b424e19-5f78-4a43-9c75-bd38cb1258b0";
                    type_name : "Inference Plugin";
                    options : ( );
                };
            } );
        };
    } );
};
```

Plugin-defined options are stored with the plugin entity or plugin capture settings. Prefer changing them through the plugin GUI unless the plugin author documents the project-file fields.