Plugin migration guide
The move from in-tree plugins to the doppio-plugins submodule and the opt-in loader.
Legacy host. The active Rust/Iced Doppio does not load C++ plugins.
These pages document the C++/ImGui plugin SDK and its host in
caffeine-runtime / doppio-archived. The engine still builds
every plugin from the submodule so the SDK stays compile-tested.
This page documents the move from in-tree Doppio plugins to the standalone
doppio-plugins repository and the opt-in loader.
What changed#
| Before | After |
|---|---|
apps/plugins/<name> inside the engine |
doppio-plugins/plugins/<name> (submodule) |
Engine CMake targets hello_plugin, terrain_plugin, … |
doppio_add_plugin() in the plugin repo |
Every discovered .so loaded at startup |
Only libraries enabled in the Plugin Manager |
| Core referenced plugin identifiers | Core exposes generic host callbacks only |
| Plugin UI used Doppio internals | Plugin UI uses caffeine/plugin/PluginUI.hpp + Caffeine::UIKit |
Migrate a plugin#
-
Move the sources
bashdoppio-plugins/ └── plugins/ └── my-plugin/ ├── CMakeLists.txt ├── README.md └── src/ └── main.cpp -
Build against the SDK
cmakeinclude(DoppioPlugin) doppio_add_plugin(my_plugin OUTPUT_NAME my_plugin SOURCES src/main.cpp)Configure with
-DCAFFEINE_ROOT=/path/to/caffeineand-DIMGUI_DIR=/path/to/caffeine/build/_deps/imgui-src. -
Use the public API
cpp#include "caffeine/plugin/PluginAPI.hpp" #include "caffeine/plugin/PluginUI.hpp"Do not include
editor/…headers. The coupling audit fails on those. -
Register UI with
PluginUI.hppcppCaffeine::Editor::PluginPanelInfo info; info.id = "plugin.my.panel"; info.title = "My Tool"; info.icon = "settings"; info.defaultOpen = false; info.dock = Caffeine::Editor::PluginDockArea::Right; Caffeine::Editor::RegisterPluginPanel(m_host, GetName(), info, &render, this); -
Install and enable
Copy the built library to a
plugins/directory and enable it in Plugins → Plugin Manager. Doppio persists the choice in~/.config/caffeine/plugins.cfg.
Versioning#
Keep the plugin repository and engine in sync. A plugin built against one ABI may fail to load or crash against another. CI should build the plugin matrix against the engine commit it targets.
Validation#
python3 scripts/audit_plugin_coupling.py
# errors: 0, warnings: 0, info: 0