🔧 Extension & Plugin System
Visão Geral#
O Extension & Plugin System é a arquitetura que permite a extensibilidade do Caffeine Studio, transformando-o numa plataforma modular. Através deste sistema, programadores podem criar novos painéis, ferramentas, comandos de menu e até suportes para novos tipos de assets sem modificar o código-fonte principal do editor. Os plugins são carregados dinamicamente a partir de bibliotecas partilhadas (.dll no Windows, .so no Linux).
Uma característica fundamental deste sistema é o suporte para Hot-Reload. Durante o desenvolvimento de um plugin, o editor consegue detetar alterações na biblioteca, descarregar a versão antiga e carregar a nova versão sem necessidade de reiniciar o IDE. Isto proporciona um fluxo de trabalho extremamente ágil. O sistema também inclui uma API robusta para registar "Component Drawers" personalizados, permitindo que plugins de terceiros definam como os seus componentes aparecem no Inspector.
Implementação#
O sistema de plugins baseia-se num contrato de interface (IPlugin) e num gestor que lida com o carregamento dinâmico de símbolos.
Estrutura da API de Plugins#
namespace Caffeine::Editor {
class IPlugin {
public:
virtual ~IPlugin() = default;
virtual void OnLoad() = 0;
virtual void OnUnload() = 0;
virtual void OnUpdate(float dt) = 0;
// Metadados
virtual const char* GetName() const = 0;
virtual const char* GetVersion() const = 0;
};
struct PluginHandle {
void* libraryHandle;
IPlugin* instance;
std::string path;
std::string name;
};
class PluginManager {
public:
static void Initialize();
static void Shutdown();
static bool LoadPlugin(const std::string& path);
static bool UnloadPlugin(const std::string& name);
static void RefreshPlugins(); // Hot-reload check
// API para Plugins usarem
static void RegisterPanel(const std::string& title, std::function<void()> renderFunc);
static void RegisterMenuAction(const std::string& path, std::function<void()> action);
private:
static std::unordered_map<std::string, PluginHandle> m_loadedPlugins;
};
} // namespace Caffeine::Editor
Exemplo de um Plugin Simples (C++)#
// MyCustomTool.cpp (Compilado como DLL)
#include <Caffeine/Editor/PluginAPI.hpp>
class MyCustomTool : public Caffeine::Editor::IPlugin {
public:
void OnLoad() override {
Caffeine::Editor::PluginManager::RegisterPanel("My Tool", [this]() {
ImGui::Text("Olá do Plugin!");
if (ImGui::Button("Clique aqui")) {
// Ação
}
});
}
void OnUnload() override {
// Limpeza
}
// ...
};
// Exportar função de criação para o PluginManager encontrar
extern "C" CAFFEINE_API IPlugin* CreatePlugin() {
return new MyCustomTool();
}
Diagrama da Interface de Gestão (ASCII)#
┌─────────────────────────────────────────────────────────────┐
│ 🔌 Plugin Manager │
├─────────────────────────────────────────────────────────────┤
│ Available Plugins: │
│ │
│ [X] Caffeine Script Editor v1.2 [Status: Active] [🔄] │
│ - Description: Embedded Lua editor with highlight. │
│ │
│ [X] Discord Rich Presence v1.0 [Status: Active] [🔄] │
│ - Description: Shows current project on Discord. │
│ │
│ [ ] Experimental Terrain Gen v0.1 [Status: Loaded] [▶] │
│ - Description: Procedural 2D terrain tools. │
├─────────────────────────────────────────────────────────────┤
│ [ Install New Plugin ] [ Refresh Directory ] │
└─────────────────────────────────────────────────────────────┘
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Dynamic Linking (DLL/SO) | Permite que o editor seja distribuído como um binário pequeno, com funcionalidades adicionais carregadas sob demanda. |
| Interface C-Style para Exports | Garante compatibilidade entre diferentes compiladores ou versões de ABI ao usar extern "C". |
| Hot-Reload via File Watcher | Automatiza o processo de desenvolvimento de plugins, eliminando tempos de espera de reinicialização. |
| Sandboxing (Limitado) | Embora os plugins tenham acesso à API do editor, o sistema tenta isolar falhas fatais para evitar que um plugin crash o IDE inteiro. |
Critério de Aceitação#
- [ ] Carregamento e descarregamento de ficheiros
.dll/.soem runtime. - [ ] Plugins conseguem registar novos painéis ImGui que aparecem no menu "Window".
- [ ] Plugins conseguem adicionar entradas ao menu principal (File, Edit, etc.).
- [ ] Hot-reload funcional: alterar e recompilar o plugin reflete-se no editor sem fechar.
- [ ] Interface visual para listar, ativar e desativar plugins instalados.
- [ ] API para registar funções de desenho de componentes (Custom Component Inspectors).
Dependências#
- Upstream:
docs/editor/core.md(infraestrutura base do editor) - Downstream: Extensões da comunidade e ferramentas específicas de projeto.
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Editor UI | Como o editor organiza e renderiza painéis. |
| Reflection System | Usado para permitir que plugins inspecionem componentes base. |
| File System | Monitorização da pasta plugins/ para detetar novos ficheiros. |
Referências#
- Padrões de arquitetura de plugins (Unity Editor scripting, VS Code extensions).
- Bibliotecas de carregamento dinâmico (libdl no Linux, WinAPI LoadLibrary).
- Técnicas de hot-reloading de C++ (Runtime Compiled C++).