Caffeine

7.4 — Undo de Geração

Historical Fase: 10 · **Prioridade:** Média · **Esforço:** Baixo Last updated:
> **Depende de:** Fase 4 (`.cterrain`), sistema undo existente no sculpt > **Bloqueia:** 7.3 (brush seguro), experimentação nos presets

Objetivo#

Guardar snapshot do heightmap (e opcionalmente splatmap) antes de operações destrutivas — Generate Terrain, Flatten, import — permitindo Ctrl+Z.


Estado Atual#

Operação Undo
Sculpt (drag) ✅ beginUndo / endUndo no viewport
Splat paint ❌
Generate Terrain ❌
Flatten ❌
Alterar resolution ❌

Design#

Snapshot leve#

cpp
struct TerrainSnapshot {
    u32 resolutionX, resolutionZ;
    std::vector<f32> heights;
    std::vector<Vec4> splatWeights;  // opcional
    u32 dataRevision;
    u32 splatRevision;
};

class TerrainUndoStack {
    static constexpr u32 kMaxSnapshots = 16;
    std::deque<TerrainSnapshot> m_undo;
    std::deque<TerrainSnapshot> m_redo;

    void pushBeforeModify(ECS::Entity entity);
    bool undo(ECS::World& world, ECS::Entity entity);
    bool redo(ECS::World& world, ECS::Entity entity);
};

Quando criar snapshot#

Evento Push undo?
Botão Generate Terrain ✅ antes
Botão Flatten ✅ antes
Import PNG / load .cterrain ✅ antes
Sculpt stroke start ✅ (já existe via editor undo)
Splat stroke start ✅ (adicionar)
Slider resolution ✅ no primeiro change do drag

Não criar snapshot em cada frame de brush — só no início do stroke.


Integração com Editor Undo#

Opção recomendada: undo dedicado ao terreno por entidade, integrado ao EditorContext::undo global.

cpp
// EditorContext
void beginTerrainUndo(ECS::Entity entity);
void endTerrainUndo(ECS::Entity entity);
bool undoTerrain(ECS::Entity entity);

Ou extensão do UndoSystem existente com tipo TerrainHeightmapCommand.


Memória#

Resolução Heights Splat Total/snapshot
65×65 17 KB 68 KB ~85 KB
257×257 264 KB 1 MB ~1.3 MB

16 snapshots × 1.3 MB ≈ 21 MB no pior caso (257²) — aceitável.

Mitigação: limitar stack a 8 entradas em resoluções > 129.


Implementação#

Ficheiros#

text
src/terrain/TerrainUndo.hpp
src/terrain/TerrainUndo.cpp

Fluxo Generate#

cpp
void TerrainCache::generateTerrain(...) {
    TerrainUndo::instance().pushSnapshot(entity, entry);
    TerrainGenerator::generate(...);
    terrain.dataRevision++;
    rebuildMesh(...);
}

Restore#

cpp
bool TerrainUndo::undo(Entity e) {
    auto snap = m_undo.back();
    entry.heightmap.heights() = snap.heights;
    entry.splatmap.weights() = snap.splatWeights;
    terrain.dataRevision = snap.dataRevision;
    rebuildMesh(...);
}

Critérios de Aceitação#

  • [ ] Ctrl+Z restaura heightmap após Generate Terrain
  • [ ] Ctrl+Y redo funciona
  • [ ] Sculpt undo continua a funcionar
  • [ ] Splat paint ganha undo por stroke
  • [ ] Sem leak de snapshots ao remover entidade (removeEntity limpa stack)

Notas#

  • Não serializar undo stack em .caf — só runtime
  • Considerar botão Revert no Inspector como atalho visual