4.7 Entity Debugger

[LyeZinho]

🔧 Entity Debugger

Milestone: M4 — Advanced Tools & Polish
Namespace: Caffeine::Editor
Arquivos: src/editor/EntityDebugger.hpp, src/editor/EntityDebugger.cpp
Status: 📅 Planeado
RF: RF6.7

---

Visão Geral

O Entity Debugger é uma ferramenta de introspeção de baixo nível desenhada para programadores que precisam de analisar o estado interno do sistema de entidades (ECS) em tempo real. Enquanto o Inspector padrão foca-se na edição de propriedades amigáveis, o Entity Debugger expõe dados brutos, memória ocupada por componentes e a estrutura dos arquétipos.

Esta ferramenta permite selecionar entidades diretamente no viewport ou via ID e inspecionar que sistemas estão a atuar sobre elas, o tamanho em bytes de cada componente e até visualizar o conteúdo da memória em formato hexadecimal. É essencial para otimização de memória e para debugar comportamentos complexos onde os sistemas do ECS podem estar a entrar em conflito ou a falhar em queries específicas.

---

Implementação

O debugger acede diretamente ao Registry do ECS para extrair metadados e informações de memória.

Estrutura do Debugger

namespace Caffeine::Editor {

struct ComponentInfo {
    std::string name;
    size_t sizeBytes;
    void* rawData;
    std::vector<std::string> matchingSystems;
};

class EntityDebuggerPanel : public EditorPanel {
public:
    EntityDebuggerPanel();
    void OnImGuiRender() override;
    void SetTargetEntity(Entity entity);

private:
    void RenderEntityHeader();
    void RenderArchetypeInfo();
    void RenderComponentList();
    void RenderMemoryHexView(void* data, size_t size);
    void RenderSystemQueries();

    Entity m_selectedEntity;
    std::vector<ComponentInfo> m_cachedComponents;
    bool m_autoRefresh = true;
};

} // namespace Caffeine::Editor

Lógica de Inspeção de Arquétipos (Pseudo-C++)

void EntityDebuggerPanel::UpdateArchetypeInfo(Entity entity) {
    auto& registry = entity.GetScene()->GetRegistry();
    auto archetype = registry.get_archetype(entity.GetID());
    
    m_cachedComponents.clear();
    for (auto typeID : archetype.types()) {
        ComponentInfo info;
        info.name = Reflection::GetTypeName(typeID);
        info.sizeBytes = Reflection::GetTypeSize(typeID);
        info.rawData = registry.get_raw(entity.GetID(), typeID);
        
        // Procurar sistemas que usam este componente
        info.matchingSystems = SystemManager::GetSystemsForComponent(typeID);
        
        m_cachedComponents.push_back(info);
    }
}

Visualização do Debugger (ASCII)

┌────────────────────────────────────────────┐
│  🔬 Entity Debugger                        │
├────────────────────────────────────────────┤
│  Entity: 142 (Hero)                        │
│  Archetype: [Transform, Sprite, RigidBody] │
│                                            │
│  Components:                               │
│  [X] Transform    size: 28 bytes           │
│      └ pos: [120.0, 340.0]                 │
│      └ Hex: 00 00 F0 42 00 00 AA 43 ...    │
│  [ ] Sprite       size: 16 bytes           │
│  [ ] RigidBody2D  size: 32 bytes           │
│                                            │
│  Memory Usage:                             │
│  Total: 76 bytes (Stack-allocated)         │
│                                            │
│  Matching Systems:                         │
│  - RenderSystem (Priority: 100)            │
│  - PhysicsSystem (Priority: 50)            │
│  - PlayerController (Priority: 1)           │
└────────────────────────────────────────────┘

---

Decisões de Design

Decisão	Justificativa
Visualização Hexadecimal	Permite detetar corrupção de memória ou valores desalinhados que não aparecem no Inspector.
Lista de Sistemas Correspondentes	Ajuda a entender por que razão uma entidade está (ou não) a ser processada por um determinado sistema.
Cache de Metadados	O debugger deve ter o menor impacto possível na performance enquanto está aberto.
Integração com Reflexão	Usa o sistema de reflexão do Caffeine para obter nomes de tipos e tamanhos dinamicamente.

---

Critério de Aceitação

• Seleção de entidades via ID manual ou clique no viewport.
• Listagem completa de todos os componentes anexados à entidade.
• Exibição correta do tamanho em bytes de cada estrutura de componente.
• Visualizador de memória hexadecimal para cada componente selecionado.
• Lista de sistemas cujas queries incluem a entidade atual.
• Informação sobre o Arquétipo (ID único do arquétipo no ECS).

---

Dependências

• Upstream: docs/ecs/core.md (conhecimento profundo do sistema de registo e arquétipos)
• Downstream: Otimização de performance e debugging geral de gameplay.

---

🔗 Tópicos Relacionados

Tópico	Descrição
ECS Internals	Detalhes sobre como o motor armazena componentes de forma contígua.
Reflection System	O sistema que permite ao motor conhecer a estrutura das classes C++ em runtime.
Memory Management	Como o motor aloca e gere os buffers de componentes.

---

Referências

• Documentação do EnTT (Entity Component System) sobre inspeção de arquétipos.
• Ferramentas de introspeção de motores comerciais (Unity Entity Debugger).
• Padrões de visualização de memória (Hex editors).