Writing a plugin
Como escrever, compilar e instalar um plugin C++/ImGui para o host legado.
Host legado. O Doppio atual em Rust/Iced não carrega plugins C++.
Estas páginas documentam o SDK de plugins C++/ImGui e o seu host no editor C++ arquivado
(doppio-archived/). A engine continua a compilar todos os plugins do
submódulo, para que o SDK se mantenha testado na compilação.
Os plugins são bibliotecas partilhadas que implementam uma C ABI pequena. O host
C++ legado carrega-as com dlopen / LoadLibrary e chama o teu código através dos
ponteiros de função de PluginHostApi. O Doppio atual em Rust não carrega estas
bibliotecas.
Minimal plugin#
#include "caffeine/plugin/PluginAPI.hpp"
class MyPlugin : public Caffeine::Editor::IPlugin {
public:
explicit MyPlugin(const Caffeine::Editor::PluginHostApi* host) : m_host(host) {}
void OnLoad() override {
m_host->registerPanel(m_host->editorContext, GetName(), "My Panel",
&MyPlugin::render, this);
}
void OnUnload() override {}
void OnUpdate(float) override {}
const char* GetName() const override { return "My Plugin"; }
const char* GetVersion() const override { return "1.0.0"; }
private:
static void render(void* self) { /* ImGui here */ }
const Caffeine::Editor::PluginHostApi* m_host;
};
extern "C" Caffeine::Editor::IPlugin* CreatePlugin(
const Caffeine::Editor::PluginHostApi* host) {
return new MyPlugin(host);
}
extern "C" void DestroyPlugin(Caffeine::Editor::IPlugin* p) { delete p; }
Lifecycle#
| Phase | Method | Purpose |
|---|---|---|
| Load | CreatePlugin(host) |
Host constructs your plugin; host->pluginId is set |
| Init | OnLoad() |
Register panels, menus, drawers, services |
| Frame | OnUpdate(dt) |
Optional per-frame logic |
| Unload | OnUnload() |
Release plugin-owned resources |
| Destroy | DestroyPlugin(ptr) |
Host unloads library |
Host API surface#
Defined in include/caffeine/plugin/PluginAPI.hpp:
| Callback | Use |
|---|---|
registerPanel |
Painel ImGui dockable / flutuante |
registerPanelEx |
Painel com metadados de layout PluginPanelInfo (preferido para plugins novos) |
openPanel |
Focar um painel já registado |
registerMenuAction |
Caminho de menu como Tools/My Action |
registerComponentDrawer |
UI de Inspector personalizada para um componente ECS |
registerEntityPresetManifest |
Adicionar presets de entidade ao menu de criação |
registerService |
Expor uma capacidade nomeada a outros plugins |
invokeService |
Chamar um serviço do host ou de um plugin pelo nome |
getActiveWorld |
World ECS atual no editor |
getSelectedEntityId / setSelectedEntityId |
Ler ou alterar a seleção da hierarquia |
getProjectRootPath |
Raiz do projeto aberto (pai de scenes/) |
getCurrentScenePath |
Caminho da cena aberta |
markSceneDirty / markAssetBrowserDirty |
Notificar o host de que o estado mudou |
getComponentTypeId |
Resolver nome de componente → type id para drawers |
getTerrainBrush / setTerrainBrush |
Ler ou editar o pincel de terreno do viewport |
logInfo / logError |
Saída na consola do editor |
Component drawers#
const auto typeId = m_host->getComponentTypeId(m_host->editorContext, "PostProcess");
m_host->registerComponentDrawer(m_host->editorContext, GetName(), typeId,
&drawPostProcess, this);
The draw function receives a pointer to the component's storage in the active archetype.
Services#
Well-known service names live in PluginServices.hpp:
terrain.generateUltraterrain.importHeightmapprocedural.installScriptsprocedural.createStreamingSetupprocedural.loadBenchmark
Plugins can register additional services for aggregators or tooling. See service-registry.md.
Build rules#
- Output name = id do plugin (ex.:
terrain_plugin.so→ idterrain_plugin) - Sem prefixo
libem Unix (PREFIX ""no CMake) - Não ligues
caffeine-corenem ImGui dentro do.so. O host exporta esses símbolos e o SDK é baseado em callbacks; liga apenas bibliotecas de sistema extra (por exemplo${CMAKE_DL_LIBS}) quando o plugin precisar. - Define
CAFFEINE_PLUGIN_EXPORTS=1(eCF_HAS_IMGUI=1) ao compilar o plugin;doppio_add_plugin()define ambos
Use cmake/DoppioPlugin.cmake:
doppio_add_plugin(my_plugin OUTPUT_NAME my_plugin SOURCES src/main.cpp)
SDK-only vs engine-coupled plugins#
| Style | Headers | Best for |
|---|---|---|
| SDK-only | caffeine/plugin/*.hpp + ImGui |
Panels, menus, lightweight tools |
| Engine-coupled | doppio-archived/src/doppio/editor/, src/caffeine/ecs/ |
Terrain, post-process, deep Inspector integration |
Engine-coupled plugins must be rebuilt when Caffeine internals change. Prefer services and the public SDK when possible.