Caffeine

🔧 Editor Script Integration

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Editor` Arquivos: `src/editor/panels/ScriptInspector.hpp`, `doppio-archived/src/doppio/editor/ConsoleWindow.hpp` RF: RF6.6 Last updated:

Visão Geral#

A integração de scripts no editor permite que os utilizadores do Caffeine Studio façam a gestão da lógica das suas entidades de forma visual e intuitiva. Esta funcionalidade estende o InspectorPanel para suportar o ScriptComponent, permitindo arrastar e soltar ficheiros de script e editar propriedades diretamente.

Além disso, esta integração inclui a captura de erros da LuaVM e a sua exibição na ConsoleWindow, completa com informações de rastreio (stack trace) e números de linha, facilitando a depuração sem sair do ambiente do IDE.


Implementação#

Extensão do Inspector#

O InspectorPanel deve desenhar um campo especial para o ScriptComponent.

cpp
void ScriptInspector::onImGuiRender(ScriptComponent& script) {
    ImGui::Text("Script Resource");
    
    // Campo de drag & drop para ficheiros .lua
    std::string scriptPath = script.script ? script.script->getPath() : "Nenhum script";
    if (ImGui::Button(scriptPath.c_str(), ImVec2(-1, 0))) {
        // Abrir seletor de ficheiros
    }

    if (ImGui::BeginDragDropTarget()) {
        if (const ImGuiPayload* payload = ImGui::AcceptDragDropPayload("ASSET_LUA")) {
            const char* path = (const char*)payload->Data;
            script.script = AssetManager::Load<ScriptAsset>(path);
        }
        ImGui::EndDragDropTarget();
    }

    if (script.script) {
        if (ImGui::Button("Editar Script")) {
            EditorUtils::OpenInSystemEditor(script.script->getPath());
        }
    }
}

Captura e Exibição de Erros#

A ConsoleWindow filtra mensagens específicas da LuaVM.

cpp
// No tratamento de erros da LuaVM
void LuaVM::handleError(sol::error err) {
    std::string message = err.what();
    // Exemplo: "scripts/player.lua:15: attempt to call a nil value"
    
    Editor::Console::LogError(message, Category::Scripting);
}

Layout Visual Sugerido#

text
+------------------------------------------+
| Inspector: PlayerEntity                  |
+------------------------------------------+
| [>] Transform                            |
| [v] Script Component                     |
|     +------------------------------+     |
|     | player_controller.lua     [X]|     |
|     +------------------------------+     |
|     [ Open Editor ]  [ Reload Now ]      |
+------------------------------------------+
| Console                                  |
+------------------------------------------+
| [ERR] player.lua:15: Missing end         |
| [WRN] Deprecated: caffeine.world.old()   |
+------------------------------------------+

Decisões de Design#

Decisão Justificativa
Abrir no Editor Externo Inicialmente, é mais eficiente usar editores especializados (VS Code) do que implementar um editor de texto robusto dentro do motor.
Drag & Drop de Assets Mantém a consistência UX com outros componentes como Sprite ou Audio.
Links nas Mensagens de Erro Clicar num erro na consola deve, idealmente, abrir o ficheiro no editor externo na linha correta.

Critério de Aceitação#

  • [ ] É possível atribuir um script a uma entidade via Inspector.
  • [ ] O botão "Editar Script" abre o ficheiro correto no editor predefinido do SO.
  • [ ] Erros de compilação de Lua aparecem a vermelho na consola do motor.
  • [ ] O componente reflete as alterações após um Hot-Reload.

Dependências#

  • Upstream: ScriptComponent, LuaVM, AssetManager
  • Downstream: SceneEditor

🔗 Tópicos Relacionados#

Tópico Descrição
docs/editor/scene-editor.md Como os painéis do editor são organizados.
docs/debug/debug-tools.md Especificação da janela de consola.

Referências#