Caffeine

🔧 ECS Lua Bindings

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

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.

lua
-- 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.

cpp
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.

lua
-- 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#

text
+-------------+         +-------------------+         +-------------+
|   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.

Referências#