Caffeine

🔧 Script Component & System

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Scripting` Arquivos: `src/scripting/ScriptComponent.hpp`, `src/caffeine/script/ScriptSystem.cpp` RF: RF6.2 Last updated:

Visão Geral#

O sistema de componentes de script integra a LuaVM com o sistema ECS (Entity Component System) do Caffeine Studio. O ScriptComponent serve como o elo de ligação, permitindo que qualquer entidade no mundo possua comportamento personalizado definido num ficheiro Lua.

O ScriptSystem é responsável por gerir o ciclo de vida destes scripts dentro do loop principal do motor. Ele garante que as funções de "callback" (como onUpdate e onCreate) sejam invocadas nos momentos corretos, passando o contexto necessário para que o script interaja com a entidade e o mundo ao seu redor.


Implementação#

Componente ECS#

O componente armazena uma referência ao recurso de script (Asset).

cpp
namespace Caffeine::Scripting {

struct ScriptComponent {
    // Referência ao ficheiro .lua gerido pelo AssetManager
    Assets::AssetHandle<ScriptAsset> script;
    
    // Tabela Lua específica para esta instância de componente (para persistência de estado)
    sol::table self;
    bool initialized = false;
};

} // namespace Caffeine::Scripting

Sistema de Scripting#

O ScriptSystem percorre todas as entidades que possuem um ScriptComponent.

cpp
namespace Caffeine::Scripting {

class ScriptSystem : public ECS::ISystem {
    LuaVM* m_vm;

public:
    void onInit(ECS::World& world) override;
    void onUpdate(ECS::World& world, f32 dt) override;
    void onShutdown(ECS::World& world) override;
    
    // Prepara novos scripts que foram adicionados durante o frame
    void initNewScripts(ECS::World& world);

private:
    void executeCallback(ScriptComponent& comp, ECS::Entity entity, const char* name, auto&&... args);
};

} // namespace Caffeine::Scripting

Ciclo de Vida do Script (Lua)#

Cada script pode implementar as seguintes funções:

  • onCreate(entity): Chamado uma vez quando o componente é inicializado.
  • onUpdate(entity, dt): Chamado a cada frame de jogo.
  • onDestroy(entity): Chamado antes do componente ou entidade ser removido.
  • onCollision(entity, other): Invocado pelo sistema de física.

Diagrama de Execução do Sistema#

text
+---------------------+
| ScriptSystem::Update|
+---------+-----------+
          |
          v
+---------+-----------+       +----------------------------+
| Filtro: Entidades   | ----> | Para cada entidade (e):     |
| com ScriptComponent |       +-------------+--------------+
+---------------------+                     |
                                            v
                                +-----------+----------------+
                                | Se !initialized:           |
                                |   - Carregar script        |
                                |   - Invocar onCreate(e)    |
                                |   - initialized = true     |
                                +-----------+----------------+
                                            |
                                            v
                                +-----------+----------------+
                                | Invocar onUpdate(e, dt)    |
                                +----------------------------+

Decisões de Design#

Decisão Justificativa
Instância self por componente Permite que várias entidades usem o mesmo ficheiro de script mas mantenham variáveis locais independentes.
Lazy Initialization Scripts são carregados e inicializados apenas quando necessários, poupando recursos no arranque da cena.
Integração com AssetHandle Permite que o motor faça tracking de dependências e facilite o hot-reloading de scripts.

Critério de Aceitação#

  • [ ] O ScriptComponent pode ser adicionado a qualquer entidade via código ou Inspector.
  • [ ] A função onCreate é chamada exatamente uma vez após a criação.
  • [ ] A função onUpdate é chamada consistentemente todos os frames.
  • [ ] O estado interno do script (variáveis em Lua) é mantido entre frames.

Dependências#

  • Upstream: LuaVM, ECS::Core
  • Downstream: EditorIntegration, PhysicsSystem (para colisões)

🔗 Tópicos Relacionados#

Tópico Descrição
docs/ecs/core.md Documentação do sistema de entidades e componentes.
docs/assets/asset-manager.md Gestão de recursos de scripts.

Referências#