Hierarchy Panel

[LyeZinho]

🔧 Hierarchy Panel

Milestone: M1 — Scene Editor Foundation
Namespace: Caffeine::Editor
Arquivos: src/editor/HierarchyPanel.hpp, src/editor/HierarchyPanel.cpp
Status: 📅 Planeado
RF: RF6.2

---

Visão Geral

O HierarchyPanel é a janela que apresenta a estrutura organizacional de todas as entidades presentes na cena atual. Ele exibe as entidades em formato de árvore, permitindo visualizar relações de parentesco (transform parenting). Este painel é essencial para a navegação rápida, seleção e organização lógica dos objetos de jogo.

Além da visualização, o painel oferece ferramentas para criação, destruição e reordenação de entidades através de interação direta (drag-and-drop) ou menus de contexto.

---

Implementação

Estrutura da Classe

O painel utiliza o EditorContext para sincronizar a seleção global.

class HierarchyPanel {
    EditorContext* m_context;
    char m_searchFilter[256] = "";

public:
    HierarchyPanel(EditorContext* context) : m_context(context) {}

    void onImGuiRender() {
        ImGui::Begin("Hierarchy");
        
        renderSearchBar();
        renderToolbar();

        if (ImGui::BeginChild("EntityTree")) {
            auto view = m_world->view<ECS::NameComponent>();
            for (auto entity : view) {
                // Apenas renderiza raízes; filhos são processados recursivamente
                if (!m_world->has<ECS::ParentComponent>(entity)) {
                    renderEntityNode(entity);
                }
            }
        }
        ImGui::EndChild();

        renderContextMenu();
        
        ImGui::End();
    }

private:
    void renderEntityNode(ECS::EntityID entity) {
        auto& name = m_world->get<ECS::NameComponent>(entity).name;
        
        ImGuiTreeNodeFlags flags = ((m_context->selectedEntity == entity) ? ImGuiTreeNodeFlags_Selected : 0);
        flags |= ImGuiTreeNodeFlags_OpenOnArrow | ImGuiTreeNodeFlags_SpanAvailWidth;
        
        bool hasChildren = checkHasChildren(entity);
        if (!hasChildren) flags |= ImGuiTreeNodeFlags_Leaf;

        bool opened = ImGui::TreeNodeEx((void*)(uintptr_t)entity, flags, "%s", name.c_str());
        
        if (ImGui::IsItemClicked()) {
            m_context->selectEntity(entity);
        }

        // Context Menu para a entidade específica
        if (ImGui::BeginPopupContextItem()) {
            if (ImGui::MenuItem("Delete")) { m_world->destroy(entity); }
            ImGui::EndPopup();
        }

        // Drag and Drop Logic
        handleDragAndDrop(entity);

        if (opened) {
            if (hasChildren) {
                renderChildren(entity);
            }
            ImGui::TreePop();
        }
    }

    void handleDragAndDrop(ECS::EntityID entity);
    void renderContextMenu(); // Create empty, etc.
};

Lógica de Hierarquia (Parenting)

A hierarquia é mantida através do ParentComponent e ChildrenComponent (ou uma lista de IDs). No M1, focaremos no ParentComponent.

struct ParentComponent {
    ECS::EntityID parentId;
};

Diagrama de Fluxo de Seleção

[HierarchyPanel] Click Node 
    -> EditorContext::selectEntity(ID)
    -> [InspectorPanel] Observa mudança 
    -> [InspectorPanel] Renderiza componentes de ID

---

Decisões de Design

Decisão	Justificativa
ImGuiTreeNodeFlags_Leaf para vazios	Fornece feedback visual imediato sobre quais entidades possuem filhos.
Filtro de Pesquisa	Essencial para cenas com centenas de entidades onde a navegação manual é lenta.
Drag-and-Drop Reparenting	Forma mais intuitiva de organizar objetos em 2D/3D.

---

Critério de Aceitação

• Apresenta todas as entidades da cena em formato de lista/árvore.
• Clicar numa entidade seleciona-a no EditorContext.
• Botão direito no vazio abre menu para "Create Empty Entity".
• Tecla Delete com entidade selecionada remove-a da cena.
• O filtro de pesquisa oculta entidades cujos nomes não coincidem com o texto.
• Entidades com ParentComponent aparecem indentadas sob o pai.

---

Dependências

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

---

🔗 Tópicos Relacionados

Tópico	Descrição
NameComponent	Armazena a string visível no painel.
ECS Parenting	Sistema que sincroniza transformações entre pais e filhos.

---

Referências

• docs/ui/editor-ui.md — Convenções de interface.
• ImGui Demo: Tree Nodes — Referência de implementação.