Skip to content

Replace all uses of Query::single with Single #15866

@alice-i-cecile

Description

@alice-i-cecile

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

Query::single and Query::single_mut are convenient lazy helpers with a nasty side effect: they panic unless exactly one matching entity is found!

While this is fine, in theory, for polished, tiny example code, it teaches bad habits to our users.

What solution would you like?

We should swap over all panicking uses over to the shiny new Single system param.

In rare cases, swapping to Query::get_single or even Option<Single<&Component>> might be preferred, to allow for more detailed error handling or to ensure the system runs to do secondary work even if the single entity it's looking for isn't found.

What alternative(s) have you considered?

We could remove these methods entirely, per #14275. This is a much larger and more controversial change. Even if this is chosen, this migration needs to be done anyways, so we might as well do it now.

Additional context

The nascent bevy_cli project introduced a lint to check for this class of error: TheBevyFlock/bevy_cli#95. At some point, we'll want to run that Bevy-specific linter in CI for this project, but it's not ready yet.

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-Cross-CuttingImpacts the entire engineC-Code-QualityA section of code that is hard to understand or changeC-ExamplesAn addition or correction to our examplesD-TrivialNice and easy! A great choice to get started with BevyS-Ready-For-ImplementationThis issue is ready for an implementation PR. Go for it!X-UncontroversialThis work is generally agreed upon

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions