Caffeine

🔧 Lua VM

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Scripting` Arquivos: `src/scripting/LuaVM.hpp`, `src/scripting/LuaVM.cpp` RF: RF6.1 Last updated:

Visão Geral#

A classe LuaVM é o núcleo do sistema de scripting do Caffeine Studio. Ela encapsula o estado da linguagem Lua através da biblioteca sol2, permitindo uma integração fluida entre C++ e scripts de alto nível. Esta máquina virtual é responsável por inicializar o ambiente de execução, registar as APIs nativas do motor e gerir o ciclo de vida dos scripts carregados.

O objetivo principal é oferecer aos utilizadores uma forma rápida e eficiente de definir lógica de jogo sem a necessidade de recompilar o motor. A LuaVM garante que as funções de lógica, input e manipulação de entidades estejam disponíveis num ambiente seguro e isolado, facilitando a iteração rápida durante o desenvolvimento.


Implementação#

Estrutura da Classe C++#

A implementação baseia-se no sol::state para gerir o registo de funções e tipos.

cpp
namespace Caffeine::Scripting {

class LuaVM {
    sol::state m_lua;
    
public:
    bool init();
    void shutdown();
    
    // Gestão de Scripts
    bool loadScript(std::string_view path);
    bool reloadScript(std::string_view path);
    
    // Execução de funções Lua a partir de C++
    template<typename... Args>
    bool call(std::string_view function, Args&&... args) {
        sol::protected_function func = m_lua[function];
        if (!func.valid()) return false;
        
        auto result = func(std::forward<Args>(args)...);
        if (!result.valid()) {
            sol::error err = result;
            // Log de erro centralizado
            return false;
        }
        return true;
    }
    
    sol::state& state() { return m_lua; }
    
private:
    // Registo de módulos específicos
    void registerCaffeineBindings();
    void registerEntityBindings();
    void registerTransformBindings();
    void registerInputBindings();
    void registerEventBindings();
    void registerDebugBindings();
    void registerMathBindings();
};

} // namespace Caffeine::Scripting

Fluxo de Inicialização#

O diagrama abaixo ilustra o processo de arranque da VM:

text
+-----------+       +---------------------+       +------------------------+
| App Start | ----> | LuaVM::init()       | ----> | open_libraries(base)   |
+-----------+       +---------------------+       +------------------------+
                               |
                               v
                    +------------------------+    +------------------------+
                    | registerCaffeineBindings| <| registerMathBindings   |
                    +------------------------+    +------------------------+
                               |
                               v
                    +------------------------+    +------------------------+
                    | registerInputBindings  | <| registerDebugBindings  |
                    +------------------------+    +------------------------+
                               |
                               v
                    +------------------------+
                    | State Ready for Scripts|
                    +------------------------+

Exemplo de Uso Interno#

Para expor uma função de log ao Lua:

cpp
void LuaVM::registerDebugBindings() {
    auto caffeine = m_lua["caffeine"].get_or_create<sol::table>();
    auto debug = caffeine["debug"].get_or_create<sol::table>();
    
    debug.set_function("log", [](const std::string& message) {
        Console::LogInfo(message);
    });
}

No script Lua:

lua
caffeine.debug.log("Sistema LuaVM inicializado com sucesso!")

Decisões de Design#

Decisão Justificativa
Uso de sol2 Biblioteca header-only extremamente eficiente e moderna para bindings C++/Lua.
sol::protected_function Garante que erros em scripts não causem o encerramento do motor (crash).
Namespace caffeine.* Organiza as APIs do motor de forma lógica e evita conflitos com globais do Lua.

Critério de Aceitação#

  • [ ] A LuaVM inicializa sem erros ao arrancar o motor.
  • [ ] Consegue executar um script simples que imprime uma mensagem na consola.
  • [ ] O carregamento de ficheiros .lua externos funciona corretamente.
  • [ ] Funções C++ são chamadas com sucesso a partir de scripts.

Dependências#

  • Upstream: Nenhuma (Core)
  • Downstream: ScriptSystem, ScriptComponent, EditorIntegration

🔗 Tópicos Relacionados#

Tópico Descrição
docs/scripting/scripting.md Guia geral de scripting no motor.
docs/debug/debug-tools.md Ferramentas de depuração e consola.

Referências#