Caffeine

🔧 Particle System

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Graphics` Arquivos: `src/caffeine/ecs/ParticleSystem.hpp`, `src/graphics/ParticleComponent.hpp` RF: RF6.7 Last updated:

Visão Geral#

O Sistema de Partículas básico do Caffeine Studio permite a criação de efeitos visuais dinâmicos como fogo, fumo, faíscas e poeira. Este sistema utiliza uma abordagem de simulação por CPU para gerir o ciclo de vida de centenas de partículas individuais, cada uma com propriedades que evoluem ao longo do tempo.

Através do ParticleEmitterComponent, os utilizadores podem definir parâmetros de emissão diretamente no editor. Além disso, uma API Lua dedicada permite que scripts de jogo disparem explosões ou controlem fluxos de partículas em resposta a eventos de gameplay, garantindo um feedback visual rico e dinâmico.


Implementação#

Componente de Emissão (ECS)#

O componente armazena as definições de como as partículas devem ser geradas.

cpp
namespace Caffeine::Graphics {

struct ParticleEmitterComponent {
    // Configurações base
    int maxParticles = 100;
    float emissionRate = 10.0f; // Partículas por segundo
    
    // Propriedades iniciais (com variação aleatória)
    glm::vec2 velocityMin = {-10, 10};
    glm::vec2 velocityMax = {10, 20};
    float lifetime = 2.0f;
    
    // Evolução ao longo do tempo
    glm::vec4 startColor = {1, 1, 1, 1};
    glm::vec4 endColor = {1, 1, 1, 0};
    float startSize = 1.0f;
    float endSize = 0.0f;

    // Estado interno (não serializado)
    std::vector<Particle> activeParticles;
};

} // namespace Caffeine::Graphics

API Lua para Partículas#

Permite controlo programático sobre os efeitos.

lua
-- Exemplo de uso em Lua para uma explosão
local explosion = caffeine.world.create()
local emitter = caffeine.world.addParticleEmitter(explosion, {
    maxParticles = 50,
    startColor = {1, 0.5, 0, 1}, -- Cor de fogo
    endColor = {0.1, 0.1, 0.1, 0}, -- Cinza transparente
    lifetime = 1.5
})

-- Disparar um "burst" de partículas
caffeine.particles.emit(explosion, 30)

Ciclo de Simulação#

O ParticleSystem atualiza cada partícula no frame.

cpp
void ParticleSystem::onUpdate(ECS::World& world, float dt) {
    world.view<ParticleEmitterComponent, TransformComponent>().each([&](auto& emitter, auto& transform) {
        // 1. Simular partículas existentes
        for (auto& p : emitter.activeParticles) {
            p.life -= dt;
            p.position += p.velocity * dt;
            
            // Interpolar cor e tamanho
            float t = 1.0f - (p.life / p.maxLife);
            p.color = lerp(emitter.startColor, emitter.endColor, t);
            p.size = lerp(emitter.startSize, emitter.endSize, t);
        }

        // 2. Remover partículas mortas
        std::erase_if(emitter.activeParticles, [](const Particle& p) { return p.life <= 0; });

        // 3. Emitir novas partículas
        // ... lógica de spawn baseada no emissionRate
    });
}

Decisões de Design#

Decisão Justificativa
Simulação em CPU Mais simples de implementar e depurar na fase inicial (M3) do que shaders de partículas complexos.
Object Pooling Reutilização de estruturas de partículas para evitar alocações constantes de memória.
API Unificada Parâmetros em Lua são os mesmos que no Inspector, garantindo consistência.

Critério de Aceitação#

  • [ ] O componente de emissor pode ser adicionado e configurado no editor.
  • [ ] Partículas são visíveis no SceneViewport durante o "Play Mode".
  • [ ] O ciclo de vida (nascimento, evolução, morte) funciona conforme os parâmetros.
  • [ ] É possível disparar emissão de partículas via script Lua.

Dependências#

  • Upstream: Renderer::Core, ECS::Core, LuaVM
  • Downstream: VisualEffectsAsset

🔗 Tópicos Relacionados#

Tópico Descrição
docs/graphics/renderer.md Detalhes sobre como as partículas são desenhadas.
docs/scripting/scripting.md Lista completa de comandos para partículas em Lua.

Referências#