bevy
bevy copied to clipboard
Have `Single` and `Populated` fail instead of skipping
Objective
Change the behavior of Single and Populated to fail validation instead of skipping systems. Users who want the skipping behavior can recover it by wrapping them in When<T>.
This is a very controversial change, and there has been a lot of discussion about it! See some discussion on https://github.com/bevyengine/bevy/pull/18504#issuecomment-2748338550, which was spun out into #18516, and some later discussion on https://github.com/bevyengine/bevy/pull/18927#issuecomment-2830728114.
I'll try to summarize the arguments here so we don't need to repeat all of them in comments, but let me know if I'm missing or misrepresenting anything and I'll try to update the summary. (And maintainers should feel free to update it!)
Pros
- A failing version of
Singleis useful for asserting invariants about your model, just as the failingResparameter is useful. If we don't change the behavior here, we may need to offer another way to do that. - A consistent story for when systems skip and when they fail is easier to understand.
Currently users need to remember the behavior separately for each kind of system parameter, but with this change they would know that systems skip if and only if they write
When. - Once we do resources-as-entities, consistency between
SingleandReswill be important. I expect users to first learn about resources as a separate concept, and later learn that resources are just a special kind of entity. It will be helpful to be able to teach "Resis just a special kind ofSingle" without needing to qualify "except that it fails instead of skipping". - Making the default behavior be loud helps catch bugs.
Regardless of the failure behavior,
Singleis more convenient thanQuerywhen you know you have exactly one entity, so it will be used when the user expects it never to fail. Most of the uses in the Bevy examples are in this category! If it does fail, then this is something the user didn't expect and we should inform them. If they do want to skip the system at that point, the error message can guide them to addWhen. And global error handlers can be used to ensure that anything missed still won't crash the game. - This is a breaking change, so if we ever want to change it, it's better to change it sooner. Most code that uses Bevy hasn't been written yet!
Cons
- A failing version of
Singleis unnecessary now that we have fallible systems. Users can use an ordinaryQueryparameter and write a simplelet value = query.single()?to get erroring behavior, but there is no concise way to get skipping behavior. - Common cases should be simple. The skipping behavior is much more useful than the failing behavior, and will be needed more often. We don't want Bevy to have a reputation for requiring useless boilerplate for common tasks!
- This is too much churn, part 1
Singleis very new, and we should take time to learn how it's being used in practice before making big changes. - This is too much churn, part 2
Singlewas introduced in 15.0 with the skipping behavior, and was changed to panic in 15.1 with no workaround. This was a major pain for users who had been eager to use the skipping behavior. The skipping behavior was just restored in 16.0, and breaking it again in 17.0 would be really irritating for some of our most enthusiastic users.
Solution
Change the behavior of Single and Populated to fail validation instead of skipping systems.
Wrap them in When where needed to fix tests.