🔧 Save/Load Scene
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.
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.
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 > Saveescreve o estado do ECS num ficheiro.caf. - [ ]
File > Openreconstró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
EditorContextapó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#
docs/ecs/scene.md— Conceitos de cena no motor.- JSON for Modern C++ — Caso se decida por um formato de texto no futuro.