🔧 Lua VM
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.
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:
+-----------+ +---------------------+ +------------------------+
| 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:
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:
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
LuaVMinicializa sem erros ao arrancar o motor. - [ ] Consegue executar um script simples que imprime uma mensagem na consola.
- [ ] O carregamento de ficheiros
.luaexternos 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. |