🔧 Entity Debugger
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).