Caffeine

🔧 Save/Load Scene

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

Visão Geral#

A persistência de dados é fundamental para qualquer ferramenta de criação. O sistema de Save/Load Scene permite que o estado atual do mundo ECS seja capturado, transformado num formato binário eficiente (.caf) e restaurado posteriormente. Este processo envolve a serialização recursiva de todas as entidades e seus respetivos componentes.

No editor, este sistema é complementado por uma lógica de "Dirty Flag", que deteta quando a cena em memória diverge da versão guardada no disco, alertando o utilizador para a necessidade de guardar o trabalho antes de fechar o IDE ou mudar de projeto.


Implementação#

Estrutura do Serializador#

O SceneSerializer atua como um wrapper sobre o ECS::World, utilizando um formato de ficheiro estruturado.

cpp
class SceneSerializer {
    ECS::World& m_world;

public:
    SceneSerializer(ECS::World& world) : m_world(world) {}

    bool serialize(const std::string& filepath) {
        std::ofstream fout(filepath, std::ios::binary);
        if (!fout.is_open()) return false;

        // Cabeçalho do Ficheiro
        FileHeader header;
        memcpy(header.signature, "CAFF", 4);
        header.version = 1;
        fout.write((char*)&header, sizeof(FileHeader));

        // Contagem de Entidades
        u32 entityCount = m_world.getEntityCount();
        fout.write((char*)&entityCount, sizeof(u32));

        // Serializar cada Entidade
        m_world.each([&](ECS::EntityID entity) {
            serializeEntity(fout, entity);
        });

        return true;
    }

    bool deserialize(const std::string& filepath) {
        std::ifstream fin(filepath, std::ios::binary);
        if (!fin.is_open()) return false;

        m_world.clear(); // Limpar mundo atual antes de carregar

        FileHeader header;
        fin.read((char*)&header, sizeof(FileHeader));
        if (memcmp(header.signature, "CAFF", 4) != 0) return false;

        u32 entityCount;
        fin.read((char*)&entityCount, sizeof(u32));

        for (u32 i = 0; i < entityCount; i++) {
            deserializeEntity(fin);
        }

        return true;
    }

private:
    void serializeEntity(std::ofstream& out, ECS::EntityID entity);
    void deserializeEntity(std::ifstream& in);
};

Lógica de Dirty Flag e Popups#

Integrada no SceneEditor para garantir a segurança dos dados.

cpp
void saveScene() {
    if (m_context.currentScenePath.empty()) {
        saveSceneAs();
    } else {
        SceneSerializer serializer(*m_world);
        if (serializer.serialize(m_context.currentScenePath)) {
            m_context.isDirty = false;
        }
    }
}

void promptUnsavedChanges(std::function<void()> onProceed) {
    if (m_context.isDirty) {
        ImGui::OpenPopup("Unsaved Changes?");
    } else {
        onProceed();
    }

    if (ImGui::BeginPopupModal("Unsaved Changes?", NULL, ImGuiWindowFlags_AlwaysAutoResize)) {
        ImGui::Text("Existem alterações não guardadas. Deseja guardar antes de continuar?");
        if (ImGui::Button("Sim", ImVec2(120, 0))) { 
            saveScene(); 
            ImGui::CloseCurrentPopup(); 
            onProceed();
        }
        ImGui::SameLine();
        if (ImGui::Button("Não", ImVec2(120, 0))) { 
            ImGui::CloseCurrentPopup(); 
            onProceed();
        }
        ImGui::SameLine();
        if (ImGui::Button("Cancelar", ImVec2(120, 0))) { 
            ImGui::CloseCurrentPopup(); 
        }
        ImGui::EndPopup();
    }
}

Formato do Ficheiro .caf (Binário)#

Secção Conteúdo Tamanho
Signature "CAFF" 4 bytes
Version Version ID 4 bytes
Entity Count Qtd Entidades 4 bytes
Entity Data ID + Component Count Variável
Component Data Component Type ID + Size + Bytes Variável

Decisões de Design#

Decisão Justificativa
Formato Binário vs JSON O binário é mais rápido de ler/escrever e consome menos espaço em disco, crucial para cenas complexas.
m_world.clear() no Load Garante que não existem resíduos de entidades da cena anterior que possam causar bugs de estado.
Popup Modal de Confirmação Evita perda acidental de trabalho, uma das piores experiências para um utilizador de IDE.

Critério de Aceitação#

  • [ ] File > Save escreve o estado do ECS num ficheiro .caf.
  • [ ] File > Open reconstrói todas as entidades e componentes a partir de um .caf.
  • [ ] O indicador de "Dirty" (asterisco no título ou barra de estado) aparece após modificações.
  • [ ] O indicador de "Dirty" desaparece imediatamente após o Save.
  • [ ] Tentar abrir uma nova cena ou fechar o editor com alterações pendentes abre o aviso modal.
  • [ ] O caminho do ficheiro atual é armazenado no EditorContext após o primeiro Save/Load.

Dependências#

  • Upstream: docs/ecs/scene.md, 1.1-editor-context-undo-redo.md
  • Downstream: 1.6-scene-editor-orchestrator.md

🔗 Tópicos Relacionados#

Tópico Descrição
ECS Reflection Sistema necessário para serializar componentes automaticamente.
File System API Abstração para lidar com diferentes sistemas de ficheiros.

Referências#