Skip to content

Query::get_component should mention that the compenent must be part of the query #9011

@nicopap

Description

@nicopap

How can Bevy's documentation be improved?

Query::get_component doesn't mention that it can only return components that are part of the query itself.

The method itself is very niche, as it's mostly an optimization to avoid accessing several components when only one is necessary.

But the documentation mentions none of this. The only caveat is the following paragraph:

In case of a nonexisting entity or mismatched component, a QueryEntityError is returned instead.

It's not enough!

Code seen in the wild (discord conversation):

fn prepare_player(
    mut commands: Commands,
    players: Query<Entity, With<backend::Player>>,
) {
    for player in &players {      
        let transform = *players.get_component::<Transform>(player).expect("Entity does not contain transform!");
    }
}

This code will always panic! Independently of whether the Entity in question has a Transform component or not. Since players doesn't have access to the Transform component, it cannot return a reference to it.

What should be done

The method should get additional wording saying "can only return components present in the query" (better phrasing pending). This should be slapped at the front of the doc, maybe part of the first paragraph.

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-ECSEntities, components, systems, and eventsC-DocsAn addition or correction to our documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions