Caffeine

🔧 Tilemap Editor

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

Visão Geral#

O Tilemap Editor é uma ferramenta robusta para o desenho de níveis 2D baseados em grelha (grid). Ele permite que os designers utilizem "tilesets" para pintar cenários complexos de forma eficiente. A ferramenta suporta múltiplas camadas para permitir a separação entre elementos de fundo, elementos interativos e dados de colisão.

Além das ferramentas básicas de pintura, o editor inclui capacidades de "Auto-tiling", que aplicam automaticamente as regras de vizinhança para escolher o tile correto (ex: cantos, bordas de grama/terra). Isto reduz drasticamente o tempo necessário para criar terrenos orgânicos. A integração com o sistema de assets do Caffeine permite a exportação direta para ficheiros .caf otimizados para o runtime.


Implementação#

O editor de tilemaps gere uma estrutura de dados composta por camadas de células, onde cada célula armazena um índice de tile e flags de configuração.

Estrutura de Dados do Tilemap#

cpp
namespace Caffeine::Editor {

struct TileCell {
    int tileID = -1;
    uint32_t flags = 0; // Ex: Inverter X, Inverter Y, Rotação
};

class TileLayer {
public:
    std::string m_name;
    std::vector<TileCell> m_cells;
    int m_width, m_height;
    bool m_isVisible = true;
    bool m_isLocked = false;

    TileCell& GetCell(int x, int y) { return m_cells[y * m_width + x]; }
};

class Tilemap {
public:
    std::vector<TileLayer> m_layers;
    Ref<Tileset> m_activeTileset;
    float m_tileSize = 32.0f;

    void AddLayer(const std::string& name);
    void RemoveLayer(int index);
};

class TilemapEditorPanel : public EditorPanel {
public:
    TilemapEditorPanel();
    void OnImGuiRender() override;
    void OnSceneRender(const SceneView& view);

private:
    void RenderPalette();
    void RenderToolbar();
    void PaintTile(int layerIdx, int x, int y, int tileID);
    void FloodFill(int layerIdx, int x, int y, int targetID, int replacementID);

    Tilemap m_currentMap;
    int m_selectedTileID = 0;
    int m_currentLayer = 0;
    ToolMode m_currentTool = ToolMode::Brush;
};

} // namespace Caffeine::Editor

Algoritmo de Auto-tiling (Pseudo-C++)#

cpp
void TilemapEditorPanel::ApplyAutoTile(int layerIdx, int x, int y) {
    auto& layer = m_currentMap.m_layers[layerIdx];
    
    // Máscara de 8 bits para vizinhos (3x3 à volta do centro)
    uint8_t neighborMask = 0;
    if (HasNeighbor(layer, x, y-1)) neighborMask |= (1 << 0); // Norte
    if (HasNeighbor(layer, x+1, y)) neighborMask |= (1 << 1); // Este
    if (HasNeighbor(layer, x, y+1)) neighborMask |= (1 << 2); // Sul
    if (HasNeighbor(layer, x-1, y)) neighborMask |= (1 << 3); // Oeste
    // ... incluir diagonais se necessário

    // Mapear máscara para o ID do tile correto definido nas regras do Tileset
    int correctTileID = m_currentTileset->GetRuleMatch(neighborMask);
    layer.GetCell(x, y).tileID = correctTileID;
}

Diagrama de Fluxo de Trabalho (ASCII)#

text
┌──────────────────────────────────────────────────────────┐
│ Palette [Tileset: dungeon_v1]                            │
├──────────────────────────────────────────────────────────┤
│ [ 0 ] [ 1 ] [ 2 ] [ 3 ]   Tool: [🎨] [🪣] [🧽] [🧊]        │
│ [ 4 ] [ 5 ] [ 6 ] [ 7 ]   Layer: [Layer 1 (Coll)] [👁️][🔒] │
│ [ 8 ] [ 9 ] [ A ] [ B ]          [Layer 2 (Deco)] [👁️][🔓] │
├──────────────────────────────────────────────────────────┤
│ Viewport (Grid 32x32)                                    │
│  ┌───┬───┬───┬───┬───┐                                   │
│  │ 🧱│ 🧱│ 🧱│ 🧱│ 🧱│                                   │
│  ├───┼───┼───┼───┼───┤                                   │
│  │ 🧱│   │   │   │ 🧱│ <--- Desenho ativo                │
│  ├───┼───┼───┼───┼───┤                                   │
│  │ 🧱│ 🧱│ 🧱│ 🧱│ 🧱│                                   │
│  └───┴───┴───┴───┴───┘                                   │
└──────────────────────────────────────────────────────────┘

Decisões de Design#

Decisão Justificativa
Armazenamento por Camadas Permite profundidade visual e separação lógica (ex: camada de colisão invisível).
Sistema de Auto-tiling Aumenta a produtividade ao automatizar a escolha de tiles de transição.
Ferramenta Bucket Fill Essencial para preencher grandes áreas rapidamente (ex: fundos ou oceanos).
Grid Snapping Forçado Garante que os tiles estão sempre perfeitamente alinhados, evitando erros visuais.

Critério de Aceitação#

  • [ ] Seleção de tiles a partir de uma paleta visual gerada a partir de um Tileset.
  • [ ] Ferramentas funcionais: Pincel, Balde de Tinta (Flood Fill) e Borracha.
  • [ ] Suporte para múltiplas camadas com controlos de visibilidade e bloqueio.
  • [ ] Implementação de regras de Auto-tiling que reagem às mudanças nos vizinhos.
  • [ ] Exportação de ficheiros .caf que mantêm a integridade das camadas e IDs.

Dependências#

  • Upstream: docs/rendering/rhi.md (para renderização eficiente de instâncias de tiles)
  • Downstream: docs/physics/physics-2d.md (para geração de colisores a partir da camada de colisão)

🔗 Tópicos Relacionados#

Tópico Descrição
Tileset Resource Definição da imagem de origem e das regras de auto-tiling.
Scene Viewport Interação direta com o rato para pintura de tiles.
Physics 2D Como o editor de tilemap gera malhas de colisão estáticas.

Referências#

  • Algoritmos de Wang Tiles para geração procedural e auto-tiling.
  • Formato de ficheiro TMX (Tiled Map Editor) como referência de estrutura.
  • Técnicas de renderização por instancing para tilemaps de larga escala.