Add `inspect` command for debugging entities and their components

[alice-i-cecile]

What problem does this solve or what need does it fill?

Querying for specific components of entity is easy, but finding all of its components is necessarily hard, since it would require an exclusive system. This is particularly challenging for beginners who are attempting to understand the ECS or some specialized feature of it.

What solution would you like?

Add a Command that prints / provides information about the specified entity. Component names would be the MVP, but component contents may also be worth including if a suitable debug method exists for them.

What alternative(s) have you considered?

Implementing Debug for a World or a Query could also work well, and might be a nice complementary solution. See #1130 for this.

Serializing entities into a Scene could also work well, but still requires good introspection capabilities and is somewhat unnatural when you only want to quickly examine the results.

Additional context

This functionality would be very useful in the context of an editor: see bevy-inspector-egui for a wonderful prototype of this in a GUI context.

[cart]

I'm thinking that instead of adding new Commands, we should just directly expose the relevant World metadata (world.entities(), world.components(), and world.archetypes()) as new SystemParams. This should be safe because the Entities, Components, and Archetypes collections are read-only during normal system execution, so they can be read in parallel.

That way users would have access to 100% of the metadata that Bevy ECS has access to.

[cart]

(this is using the terminology / apis from the Bevy ECS rewrite that I am currently wrapping up)

[alice-i-cecile]

I'm thinking that instead of adding new Commands, we should just directly expose the relevant World metadata (world.entities(), world.components(), and world.archetypes()) as new SystemParams. This should be safe because the Entities, Components, and Archetypes collections are read-only during normal system execution, so they can be read in parallel.

That way users would have access to 100% of the metadata that Bevy ECS has access to.

Cool, this would be super helpful and totally solve the issue at hand. I'd wanted runtime access to archetype data when trying to help with #1446 the other day too.

This happened in the 0.5 release right?
So can probably be closed?

[alice-i-cecile]

The required data is now exposed nicely, which is fantastic. But we're still lacking nice helper functions, which are particularly useful for quick debugging.

Entities, Components and Archetypes are exposed to the systems, but you still need to somehow extract the relevant information from them.

After a couple minutes of puzzling, I can't figure out which bits of the bevy_ecs API I need to poke at in order to e.g. get the list of all components on the entity, which points at the need for either a clear example in the docs or a helper function of some sort.

[msklywenn]

@alice-i-cecile Something like this?

fn inspect(
    keyboard: Res<Input<KeyCode>>,
    all_entities: Query<Entity>,
    entities: &Entities,
    archetypes: &Archetypes,
    components: &Components,
) {
    if keyboard.just_pressed(KeyCode::F1) {
        for entity in all_entities.iter() {
            println!("Entity: {:?}", entity);
            if let Some(entity_location) = entities.get(entity) {
                if let Some(archetype) = archetypes.get(entity_location.archetype_id) {
                    for component in archetype.components() {
                        if let Some(info) = components.get_info(component) {
                            println!("\tComponent: {}", info.name());
                        }
                    }
                }
            }
        }
    }
}

(do not press F1 when there are four thousand trees on screen, it takes a while...)

[alice-i-cecile]

@msklywenn yes! Bundling the inner section of that up into an entity command would make for a great debugging tool.

[alice-i-cecile]

We may also want to try printing it's debug value if it exists, but I don't think we have access to the relevant trait data... We'd need a blanket impl for component debugging?