🔧 ECS Lua Bindings
Visão Geral#
Este módulo define a ponte de comunicação entre o ecossistema C++ do Caffeine Studio e o ambiente Lua. Através destes bindings, os scripts conseguem manipular entidades, consultar componentes de transformação, ler inputs do utilizador e responder a eventos do sistema.
A API foi desenhada para ser intuitiva e idiomática para programadores Lua, escondendo a complexidade do sistema de memória e das classes internas do motor. O foco inicial está nos componentes mais críticos: Transform (posicionamento), Input (teclado/rato) e World (gestão de entidades).
Implementação#
API de Manipulação de Mundo#
Os scripts podem criar e destruir entidades dinamicamente.
-- Exemplo de uso em Lua
local e = caffeine.world.create()
caffeine.world.addTransform(e, { x = 100, y = 200, scale = 1.0 })
caffeine.world.addSprite(e, { texture = "assets/hero.caf" })
-- Aceder a componentes existentes
local t = caffeine.world.getTransform(e)
t.x = t.x + 10
caffeine.world.setTransform(e, t)
Implementação de Bindings (C++)#
Utilizamos as funcionalidades de sol::table e sol::usertype para expor as estruturas.
void LuaVM::registerTransformBindings() {
// Definir tipo Transform para Lua
m_lua.new_usertype<TransformComponent>("Transform",
"x", &TransformComponent::position.x,
"y", &TransformComponent::position.y,
"rotation", &TransformComponent::rotation,
"scale", &TransformComponent::scale
);
auto world = m_lua["caffeine"]["world"].get_or_create<sol::table>();
world.set_function("getTransform", [this](ECS::Entity e) {
return m_currentWorld->getComponent<TransformComponent>(e);
});
world.set_function("setTransform", [this](ECS::Entity e, const TransformComponent& t) {
m_currentWorld->replaceComponent<TransformComponent>(e, t);
});
}
API de Input#
Expõe o estado periférico para permitir interatividade.
-- Verificação de teclas
if caffeine.input.isKeyDown("Space") then
jump()
end
-- Posição do rato
local mx, my = caffeine.input.mousePosition()
caffeine.debug.log("Mouse at: " .. mx .. ", " .. my)
Mapeamento de Tipos e Fluxo#
+-------------+ +-------------------+ +-------------+
| Lua Code | <-----> | Sol2 Bindings | <-----> | C++ ECS |
+-------------+ +-------------------+ +-------------+
| e:create() | | set_function(...) | | world.spawn |
| t.x = 10 | | usertype<Trans> | | comp.pos.x |
+-------------+ +-------------------+ +-------------+
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Passagem por valor para structs pequenos | TransformComponent é pequeno o suficiente para evitar a complexidade de gestão de referências (pointers) em scripts simples. |
| Strings para identificação de Input | Usar "Space" em vez de enums numéricos torna o código Lua muito mais legível. |
Prefix caffeine.* |
Garante que a API do motor está isolada e é facilmente descoberta via auto-complete em editores externos. |
Critério de Aceitação#
- [ ] Entidades podem ser criadas via script Lua.
- [ ] O componente de Transformação pode ser lido e modificado via script.
- [ ] Inputs de teclado (isKeyDown) são reportados corretamente ao script.
- [ ] Coordenadas do rato estão acessíveis e corretas.
Dependências#
- Upstream:
LuaVM,ECS::Core,Input::System - Downstream:
ScriptSystem,SampleScripts
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
docs/ecs/core.md |
Detalhes sobre a arquitetura ECS nativa. |
docs/scripting/scripting.md |
Documentação da API de scripting para utilizadores. |