Caffeine

🔧 EditorContext & Undo/Redo

Planned Milestone: M1 — Scene Editor Foundation Namespace: `Caffeine::Editor` Arquivos: `src/caffeine/scene/EditorContext.hpp`, `src/caffeine/scene/EditorContext.cpp` RF: RF6.1 Last updated:

Visão Geral#

O EditorContext funciona como o cérebro central do editor, mantendo o estado global da sessão atual. Ele armazena informações críticas como a entidade selecionada, o estado de modificação da cena (dirty flag) e o caminho do ficheiro aberto. Sem este contexto, os painéis individuais não teriam uma forma unificada de comunicar mudanças entre si.

O sistema de Undo/Redo é integrado diretamente neste contexto para permitir que o utilizador reverta ações destrutivas ou erros de edição. Ele utiliza um sistema de comandos baseado em estados (snapshots) para garantir que a cena possa regressar exatamente ao ponto anterior a qualquer modificação no ECS.


Implementação#

Estrutura do Comando#

Cada comando guarda o estado "antes" e "depois" da modificação para permitir a navegação bidirecional no histórico.

cpp
struct EditorCommand {
    enum Type { 
        AddEntity, 
        RemoveEntity, 
        AddComponent,
        RemoveComponent, 
        SetField, 
        MoveEntity 
    };

    Type type;
    ECS::EntityID targetEntity;
    std::vector<u8> beforeState; // Serialização do componente/entidade antes
    std::vector<u8> afterState;  // Serialização depois da mudança
};

Gestor de Histórico (UndoStack)#

Utiliza um buffer circular para evitar alocações constantes e limitar o uso de memória.

cpp
class UndoStack {
    static constexpr u32 MAX_UNDO = 256;
    EditorCommand m_commands[MAX_UNDO];
    u32 m_head = 0;   // Onde o próximo comando será inserido
    u32 m_tail = 0;   // O comando mais antigo disponível
    u32 m_current = 0; // Posição atual para undo/redo
    u32 m_count = 0;

public:
    void push(const EditorCommand& cmd) {
        m_commands[m_head] = cmd;
        m_head = (m_head + 1) % MAX_UNDO;
        
        if (m_count < MAX_UNDO) {
            m_count++;
        } else {
            m_tail = (m_tail + 1) % MAX_UNDO;
        }
        m_current = m_head;
    }

    bool undo(ECS::World& world) {
        if (m_current == m_tail) return false;
        m_current = (m_current - 1 + MAX_UNDO) % MAX_UNDO;
        applyState(world, m_commands[m_current].beforeState);
        return true;
    }

    bool redo(ECS::World& world) {
        if (m_current == m_head) return false;
        applyState(world, m_commands[m_current].afterState);
        m_current = (m_current + 1) % MAX_UNDO;
        return true;
    }

    void clear() {
        m_head = m_tail = m_current = m_count = 0;
    }

private:
    void applyState(ECS::World& world, const std::vector<u8>& data);
};

EditorContext#

O objeto singleton que orquestra a comunicação entre painéis.

cpp
class EditorContext {
public:
    // Estado da Seleção
    ECS::EntityID selectedEntity = ECS::INVALID_ENTITY;
    ECS::EntityID hoveredEntity = ECS::INVALID_ENTITY;
    ECS::EntityID clipboardEntity = ECS::INVALID_ENTITY;

    // Estado do Gizmo
    enum class GizmoMode { Translation, Rotation, Scale };
    GizmoMode currentGizmoMode = GizmoMode::Translation;

    // Estado da Cena
    std::string currentScenePath = "";
    bool isDirty = false;

    // Sistemas
    UndoStack undoStack;

    void selectEntity(ECS::EntityID id) {
        selectedEntity = id;
    }

    void markDirty() {
        isDirty = true;
    }
};

Fluxo de Dados de Undo#

text
[Utilizador Altera Campo] 
    -> Captura Estado Atual (beforeState)
    -> Aplica Mudança no ECS
    -> Captura Novo Estado (afterState)
    -> EditorContext::undoStack.push(comando)
    -> EditorContext::markDirty()

Decisões de Design#

Decisão Justificativa
Buffer Circular no UndoStack Evita fragmentação de memória e garante um limite previsível de recursos.
Snapshots de Estado Mais simples de implementar para o ECS do que comandos delta complexos, aproveitando a serialização existente.
Dirty Flag no Contexto Centraliza a lógica de aviso de "Guardar Alterações" antes de fechar a aplicação ou mudar de cena.

Critério de Aceitação#

  • [ ] Undo/Redo funciona para a criação de entidades (AddEntity).
  • [ ] Undo/Redo funciona para a remoção de entidades (RemoveEntity).
  • [ ] A Dirty Flag é ativada após qualquer ação no histórico.
  • [ ] Selecionar uma entidade atualiza o selectedEntity globalmente.
  • [ ] O histórico é limpo ao carregar uma nova cena.

Dependências#

  • Upstream: docs/ecs/core.md, docs/ecs/scene.md
  • Downstream: 1.2-hierarchy-panel.md, 1.3-inspector-panel.md, 1.6-scene-editor-orchestrator.md

🔗 Tópicos Relacionados#

Tópico Descrição
Serialização ECS Como transformar componentes em bytes para o UndoStack.
Comandos de Editor Padrão de desenho Command para isolar ações da UI.

Referências#