🔧 Script Component & System
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).
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.
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#
+---------------------+
| 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
ScriptComponentpode 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. |