Use the `#[diagnostic::on_unimplemented]` attribute to improve ECS (system and query) error messages

[alice-i-cecile]

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

Bevy's error messages for invalid inputs for systems and queries that take SystemParam, QueryData or QueryFilter are terrible: users get a terrible error message saying that the trait isn't implemented for the whole tuple and suggesting a bunch of irrelevant tuples with generic types.

For upstream reports of what these errors look like, please see:

• Bevy malformed system errors are extremely unhelpful due to macro-magic rust-lang/rust#89681
• Unhelpful error message for malformed Bevy Query type parameters rust-lang/rust#89680
• No "consider borrowing here" suggestion for method on complex trait bound rust-lang/rust#89679
• Don't treat tuple struct types as functions in diagnostics rust-lang/rust#114247

What solution would you like?

Use the soon-to-be-stabilized diagnostic attribute on our key traits, and manually provide more helpful error messages.

#[diagnostic::on_unimplemented(
    message = "My Message for `ImportantTrait<{A}>` is not implemented for `{Self}`",
    label = "My Label",
    note = "Note 1",
    note = "Note 2"
)]
trait ImportantTrait<A> {}

rust-lang/rust#119888 is the stabilization PR which goes over more details of how this works: this will not be available until Rust 1.78.

What alternative(s) have you considered?

1. Add variadic generics to upstream Rust (one day).
2. Use a macro to determine these things that needs to be added to every system. bevy_check by @jakobhellermann does this, and is essential prior art.

Additional context

This was brought to my attention by George Semmler on Mastodon.

[SpecificProtagonist]

As far as I can tell, the relevant cases are where we use all_tuples!:

• Bundle
• IntoSystemConfigs
• IntoSystemSetConfigs
• ExclusiveSystemParam
• ReadOnlySystemParam
• SystemParamFunction
• WorldQuery
• QueryData
• QueryFilter
• Plugins
• TypePath
• RenderCommand

But we don't necessarily want to do this for all of them: The message is essentially fixed and when I make a mistake in a query, the compiler actually offers more help:

Error message

error[E0277]: the trait bound `Foo: QueryData` is not satisfied
   --> src/main.rs:15:11
    |
15  | fn foo(_: Query<(Entity, Foo, &Bar)>) {}
    |           ^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `QueryData` is not implemented for `Foo`, which is required by `(bevy::prelude::Entity, Foo, &Bar): QueryData`
    |
    = help: the following other types implement trait `QueryData`:
              DebugName
              bevy::prelude::Ref<'__w, T>
              Has<T>
              AnyOf<()>
              AnyOf<(F0,)>
              AnyOf<(F0, F1)>
              AnyOf<(F0, F1, F2)>
              AnyOf<(F0, F1, F2, F3)>
            and 39 others
    = note: required for `(bevy::prelude::Entity, Foo, &Bar)` to implement `QueryData`
note: required by a bound in `bevy::prelude::Query`
   --> /home/vj/workspace/rust/bevy/crates/bevy_ecs/src/system/query.rs:349:37
    |
349 | pub struct Query<'world, 'state, D: QueryData, F: QueryFilter = ()> {
    |                                     ^^^^^^^^^ required by this bound in `Query`

error[E0277]: the trait bound `Bar: bevy::prelude::Component` is not satisfied
   --> src/main.rs:15:11
    |
15  | fn foo(_: Query<(Entity, Foo, &Bar)>) {}
    |           ^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `bevy::prelude::Component` is not implemented for `Bar`, which is required by `(bevy::prelude::Entity, Foo, &Bar): QueryData`
    |
    = help: the following other types implement trait `bevy::prelude::Component`:
              AccessibilityNode
              bevy::prelude::Name
              GlobalTransform
              Transform
              PlaybackSettings
              Children
              SpatialListener
              SceneInstance
            and 166 others
    = note: required for `&Bar` to implement `QueryData`
    = note: 1 redundant requirement hidden
    = note: required for `(bevy::prelude::Entity, Foo, &Bar)` to implement `QueryData`
note: required by a bound in `bevy::prelude::Query`
   --> /home/vj/workspace/rust/bevy/crates/bevy_ecs/src/system/query.rs:349:37
    |
349 | pub struct Query<'world, 'state, D: QueryData, F: QueryFilter = ()> {
    |                                     ^^^^^^^^^ required by this bound in `Query`

Of course this text isn't ideal either, but it correctly identifies which parts of the query are the problems.

Details

[alice-i-cecile]

Really good to see that the error message has improved already.

I think that the main thing I would like to do is change the error message to include some Bevy-specific guidance, and to cull the tuple pyramids from the tips around "the following other types" text.

[SpecificProtagonist]

Just tried it out; I don't think we should overwrite the message or the label, we should only add a note.

We can't remove any parts of the message, so cutting the tuple impls has to wait for do_not_recommend.

[alice-i-cecile]

rust-lang/rust#51992 appears to be the tracking issue for do_not_recommend, which should let us hide the tuple pyramid impls.

[alice-i-cecile]

Previously attempted in #5786

[alice-i-cecile]

https://blog.rust-lang.org/2024/05/02/Rust-1.78.0.html

No longer blocked!