bevy icon indicating copy to clipboard operation
bevy copied to clipboard

Have `Single` and `Populated` fail instead of skipping

Open chescock opened this issue 4 months ago • 1 comments

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 Single is useful for asserting invariants about your model, just as the failing Res parameter 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 Single and Res will 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 "Res is just a special kind of Single" 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, Single is more convenient than Query when 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 add When. 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 Single is unnecessary now that we have fallible systems. Users can use an ordinary Query parameter and write a simple let 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 Single is 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 Single was 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.

chescock avatar Jun 04 '25 16:06 chescock