QuerySingle family of system params

[MiniaczQ]

Objective

Add the following system params:

• QuerySingle<D, F> - Valid if only one matching entity exists,
• Option<QuerySingle<D, F>> - Valid if zero or one matching entity exists.

As @chescock pointed out, we don't need Mut variants.

Fixes: #15264

Solution

Implement the type and both variants of system params.
Also implement ReadOnlySystemParam for readonly queries.

Added a new ECS example fallible_params which showcases SingleQuery usage.
In the future we might want to add NonEmptyQuery, NonEmptyEventReader and Res to it (or maybe just stop at mentioning it).

Testing

Tested with the example.
There is a lot of warning spam so we might want to implement #15391.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[SkiFire13]

I wonder if now that we have validate_param we could use it to write a generic impl<S: SystemParam> SystemParam for Option<S>. This could be tackled in a separate PR though.

[MiniaczQ]

Not every Option<P> makes sense, like Option<Query>

[MiniaczQ]

Also, infinitely nested Options

[SkiFire13]

Right, though maybe this could be solved with a marker trait for those system parameters for which Option can make sense.

[MiniaczQ]

If there is a decent way to derive it I'm down.
There are some cases where Option needs some specialized code, like in QuerySingle

[SkiFire13]

Are we sure this is the change tick that will be used for calling get_param, or an equivalent one for what matters to it? If so could you write a comment explaining why that's the case?

[MiniaczQ]

Practically yes, this happens to be the exact tick that is received by get_param, but there are not validation mechanisms/contract for that.

Currently only executors use validate_param and since the validation and running happens one after another, this is the correct change tick.
For run_systems and observers this also shouldn't be a problem.

While I can make validate_param accept a change_tick, the problem is that the tick used by get_param is generated inside run_unsafe, so we'd still need to uphold this "contract" of calling them back-to-back.

[MiniaczQ]

I'm open for docs/mechanisms on making this better, I'm not sure how to go about it

[chescock]

It won't always be exactly the same tick, because the multi-threaded executor will call validate_param and then spawn a task to run the system and call get_param at some later point. Another system could start in between and increment the current tick.

I think it will be equivalent, though. Any components read by this param can't be written by another system in between the calls, so they can't have an added or changed tick in between the two change_tick values.

[MiniaczQ]

Okay, I'll try to thoroughly document this in validate_param

[alice-i-cecile]

Why isn't this just <D as QueryData>::Item? I think that would improve the ergonomics and complexity quite a bit?

[MiniaczQ]

The ergonomics comment got removed, CI told me to remove unnecessary syntax which made it way better.

<D as WorldQuery>::Item is not a SystemParam so that's one issue with this.
Another would be, if SystemParam returns anything else than itself with changed lifetimes, it won't fit as the system argument.

fn my_system(q: QuerySingle<Entity>) { ... }

// imaginary executor code
let q: <Entity as WorldQuery>::Item = QuerySingle<Entity>::get_param(world);
system(q); // Expected `QuerySingle` got `<Entity as WorldQuery>::Item`

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1701 if you'd like to help out.