Caffeine

🔧 Extension & Plugin System

Planned Milestone: M4 — Advanced Tools & Polish Namespace: `Caffeine::Editor` Arquivos: `doppio-archived/src/doppio/editor/PluginSystem.hpp`, `doppio-archived/src/doppio/editor/PluginSystem.cpp` RF: RF6.8 Last updated:

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#

cpp
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++)#

cpp
// 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)#

text
┌─────────────────────────────────────────────────────────────┐
│ 🔌 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 / .so em 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++).