Caffeine

🔧 Animation Timeline Editor

Planned Milestone: M4 — Advanced Tools & Polish Namespace: `Caffeine::Editor` Arquivos: `doppio-archived/src/doppio/editor/AnimationTimeline.hpp`, `doppio-archived/src/doppio/editor/AnimationTimeline.cpp` RF: RF6.1 Last updated:

Visão Geral#

O Animation Timeline Editor é a ferramenta central para a criação de sequências animadas dentro do Caffeine Studio. Ele permite que os utilizadores manipulem propriedades de entidades ao longo do tempo através de um sistema de keyframes (fotogramas-chave). A interface fornece uma representação visual clara das faixas de animação, permitindo ajustes precisos em transformações, trocas de sprites e disparo de eventos.

Esta ferramenta foi desenhada para ser intuitiva tanto para animadores tradicionais, através do sistema de frames de sprite, como para utilizadores que preferem animação baseada em interpolação de curvas para posições e rotações. A inclusão de Onion Skinning facilita a visualização do movimento, permitindo ver os frames anteriores e posteriores com transparência.


Implementação#

A implementação baseia-se num sistema de faixas (Tracks) e canais de dados. Cada AnimationClip contém múltiplas AnimationTrack.

Estrutura de Classes#

cpp
namespace Caffeine::Editor {

enum class TrackType {
    Sprite,
    Transform,
    Event,
    Audio
};

struct Keyframe {
    float time;
    std::variant<int, glm::vec3, std::string> value;
    EasingType easing = EasingType::Linear;
};

class AnimationTrack {
public:
    virtual ~AnimationTrack() = default;
    virtual void AddKeyframe(float time, const std::variant<int, glm::vec3, std::string>& value) = 0;
    virtual void RemoveKeyframe(int index) = 0;
    virtual TrackType GetType() const = 0;
    
    std::vector<Keyframe> m_keyframes;
    std::string m_targetPropertyName;
};

class AnimationTimelinePanel : public EditorPanel {
public:
    AnimationTimelinePanel();
    void OnImGuiRender() override;
    void SetActiveClip(Ref<AnimationClip> clip);

private:
    void RenderHeader();
    void RenderTimeline();
    void RenderTracks();
    void HandleInput();

    Ref<AnimationClip> m_activeClip;
    float m_currentTime = 0.0f;
    bool m_isPlaying = false;
    bool m_onionSkinningEnabled = true;
};

} // namespace Caffeine::Editor

Diagrama de Interface (ASCII)#

text
┌─────────────────────────────────────────────────────────────┐
│  Animation: "hero_idle"    [▶ Play]  [■ Stop]  [⟳ Loop]   │
│  Duration: 1.2s    FPS: 12                                 │
├─────────────────────────────────────────────────────────────┤
│  Timeline:  |──●──●──●──●──●──●──●──●──●──●──●──●──|      │
│             0s   0.1  0.2  0.3  0.4  0.5  0.6  ...  1.2s   │
├─────────────────────────────────────────────────────────────┤
│  Tracks:                                                     │
│  ▸ Sprite     [hero_1] [hero_2] [hero_3] ...               │
│  ▸ Position   ●─────────────●──────────────●               │
│  ▸ Rotation   ───●─────────────────────●────               │
│  ▸ Events     [play_sfx]        [spawn_particle]            │
└─────────────────────────────────────────────────────────────┘

Exemplo de Lógica de Interpolação#

cpp
glm::vec3 InterpolateTransform(const AnimationTrack& track, float time) {
    if (track.m_keyframes.empty()) return glm::vec3(0.0f);
    
    // Encontrar os dois keyframes entre os quais o 'time' se encontra
    auto it = std::upper_bound(track.m_keyframes.begin(), track.m_keyframes.end(), time, 
        [](float t, const Keyframe& k) { return t < k.time; });

    if (it == track.m_keyframes.begin()) return std::get<glm::vec3>(track.m_keyframes.front().value);
    if (it == track.m_keyframes.end()) return std::get<glm::vec3>(track.m_keyframes.back().value);

    const auto& k1 = *(it - 1);
    const auto& k2 = *it;

    float alpha = (time - k1.time) / (k2.time - k1.time);
    // Aplicar função de easing aqui
    alpha = ApplyEasing(alpha, k1.easing);

    return glm::mix(std::get<glm::vec3>(k1.value), std::get<glm::vec3>(k2.value), alpha);
}

Decisões de Design#

Decisão Justificativa
Sistema de Faixas Polimórfico Permite estender facilmente a animação para novas propriedades de componentes sem alterar o núcleo.
Uso de std::variant para Keyframes Oferece flexibilidade para armazenar diferentes tipos de dados (int para frames, vec3 para posição) numa estrutura comum.
Onion Skinning no Viewport Essencial para dar feedback visual imediato ao animador sobre a fluidez do movimento.
Exportação para .caf binário Garante carregamento rápido pelo motor de jogo durante o runtime.

Critério de Aceitação#

  • [ ] Interface permite criar, mover e remover keyframes em múltiplas faixas.
  • [ ] Reprodução em tempo real no editor com suporte para loop.
  • [ ] Onion skinning funcional, mostrando frames adjacentes com transparência ajustável.
  • [ ] Faixa de eventos permite chamar funções Lua registadas no sistema de scripting.
  • [ ] Exportação e importação correta de ficheiros .caf.

Dependências#

  • Upstream: docs/editor/scene-editor.md, docs/animation/animation-2d.md
  • Downstream: docs/scripting/scripting.md (para faixas de eventos)

🔗 Tópicos Relacionados#

Tópico Descrição
Animation 2D Sistema de runtime que consome as animações criadas.
Scene Viewport Onde o Onion Skinning e a pré-visualização ocorrem.
Asset Browser Gestão de ficheiros de animação .caf.

Referências#

  • Documentação ImGui para implementação de Timelines.
  • Padrões de interpolação Linear e Bezier em motores de jogo.
  • RFC para o formato de asset .caf.