4.8 Extension & Plugin System

[LyeZinho]

🔧 Extension & Plugin System

Milestone: M4 — Advanced Tools & Polish
Namespace: Caffeine::Editor
Arquivos: src/editor/PluginSystem.hpp, src/editor/PluginSystem.cpp
Status: 📅 Planeado
RF: RF6.8

---

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 / .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++).