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.

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.

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.

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.

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.