From bd353a51c099a8c70fdcc9552aa10fa693e2dae6 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 14:19:17 -0500 Subject: [PATCH 01/26] Create reflexive-world-queries.md --- rfcs/reflexive-world-queries.md | 151 ++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 rfcs/reflexive-world-queries.md diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md new file mode 100644 index 00000000..0c131e05 --- /dev/null +++ b/rfcs/reflexive-world-queries.md @@ -0,0 +1,151 @@ +# Feature Name: `reflexive-world-queries` + +## Summary + +Types created using `#[derive(WorldQuery)]` are now reflexive, +meaning we no longer generate 'Item' structs for each custom WorldQuery. +This makes the API for these types much simpler. + +## Motivation + +You, a humble user, wish to define your own custom `WorldQuery` type. +It should display the name of an entity if it has one, and fall back +to showing the entity's ID if it doesn't. + +```rust +#[derive(WorldQuery)] +struct DebugName { + name: Option<&'static Name>, + id: Entity, +} + +impl Debug for DebugName { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt:Result { + if let Some(name) = self.name { + write!(f, "{name}") + } else { + write!(f, "Entity {:?}", self.id) + } + } +} +``` + +This type is easy define, and should be very useful. +However, you notice a strange error when trying to use it: + +```rust +fn my_system(q: Query) { + for dbg in &q { + println!("{dbg:?}"); + } +} +``` + +``` +error[E0277]: `DebugNameItem<'_>` doesn't implement `Debug` + --> crates\bevy_core\src\name.rs:194:20 + | +194 | println!("{dbg:?}"); + | ^^^ `DebugNameItem<'_>` cannot be formatted using `{:?}` + | + = help: the trait `Debug` is not implemented for `DebugNameItem<'_>` + = note: add `#[derive(Debug)]` to `DebugNameItem<'_>` or manually `impl Debug for DebugNameItem<'_>` + = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) +``` + +"Rustc, what are you talking about?" you ask. You just implemented `Debug`! + +The problem here is that the type returned from the query is *not* the type we just defined +-- it's an hidden macro-generated type with near-identical fields. +Here's what it looks like in the docs: + +```rust +pub struct DebugNameItem<'__w> { + pub name: as WorldQuery>::Item<'__w>, + pub entity: ::Item<'__w>, +} +``` + +In order to fix the error, we need to implement `Debug` for *this* type: + +```rust +impl Debug for DebugNameItem<'_> { ... } +``` + +This successfully avoid the compile error, but it results in an awkward situtation where our documentation, +trait impls, and methods are spread accross two very similar types with a non-obvious distinction between them. +In addition, the `DebugNameItem` struct has necessarily vague documentation due to being generated in a macro. + +## User-facing explanation + +Explain the proposal as if it was already included in the engine and you were teaching it to another Bevy user. That generally means: + +- Introducing new named concepts. +- Explaining the feature, ideally through simple examples of solutions to concrete problems. +- Explaining how Bevy users should *think* about the feature, and how it should impact the way they use Bevy. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, explain how this feature compares to similar existing features, and in what situations the user would use each one. + +## Implementation strategy + +Changing the derive macro to be reflexive should be a trivial change, +and will not be discussed at length in this RFC. + +To support this change, we will need to rework some of our built-in +`WorldQuery` types to be reflexive. + +```rust +// Before: +fn my_system(q: Query>) { + for flag in &q { + ... + } +} + +// After: +fn my_system(q: Query>) { + for Changed(flag) in &q { + ... + } +} +``` + +Since `&mut T` is not reflexive, we will have to implement `WorldQuery` for `Mut`. + +## Drawbacks + +This will add slightly more friction in some cases, non-reflexive `WorldQuery` +types such as `&mut T` are forbidden from being used in the derive macro. +However, these types can still be used in anonymous `WorldQuery`s or types +such as `type MyQuery = (&'static mut A, &'static mut U)`. + +Since the `WorldQuery` derive is only used in cases where the user wishes +to expose a public API, we should prioritize the cleanliness of that API +over the ease of implementing it. + +## Rationale and alternatives + +Do nothing. The current situation is workable, but it's not ideal. +Generated 'Item' structs add signifcant noise to a plugin's API, +and make it more difficult to understand due to having several very similar types. + +## Unresolved questions + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before the feature PR is merged? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? + +## \[Optional\] Future possibilities + +Think about what the natural extension and evolution of your proposal would +be and how it would affect Bevy as a whole in a holistic way. +Try to use this section as a tool to more fully consider other possible +interactions with the engine in your proposal. + +This is also a good place to "dump ideas", if they are out of scope for the +RFC you are writing but otherwise related. + +Note that having something written down in the future-possibilities section +is not a reason to accept the current or a future RFC; such notes should be +in the section on motivation or rationale in this or subsequent RFCs. +If a feature or change has no direct value on its own, expand your RFC to include the first valuable feature that would build on it. From f23f025adc289f929991b6a1b04b1ad5a85c18b2 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:46:01 -0500 Subject: [PATCH 02/26] add future possibilities --- rfcs/reflexive-world-queries.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index 0c131e05..30c003f6 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -137,15 +137,4 @@ and make it more difficult to understand due to having several very similar type ## \[Optional\] Future possibilities -Think about what the natural extension and evolution of your proposal would -be and how it would affect Bevy as a whole in a holistic way. -Try to use this section as a tool to more fully consider other possible -interactions with the engine in your proposal. - -This is also a good place to "dump ideas", if they are out of scope for the -RFC you are writing but otherwise related. - -Note that having something written down in the future-possibilities section -is not a reason to accept the current or a future RFC; such notes should be -in the section on motivation or rationale in this or subsequent RFCs. -If a feature or change has no direct value on its own, expand your RFC to include the first valuable feature that would build on it. +We should explore ways to make the `#[world_query(mutable)]` attribute unnecessary. From 0def33b7c8acf6eb7bf613a9316cd73e2d0d350a Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:48:26 -0500 Subject: [PATCH 03/26] add a user-facing explanation --- rfcs/reflexive-world-queries.md | 34 +++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index 30c003f6..3ac25807 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -76,15 +76,37 @@ This successfully avoid the compile error, but it results in an awkward situtati trait impls, and methods are spread accross two very similar types with a non-obvious distinction between them. In addition, the `DebugNameItem` struct has necessarily vague documentation due to being generated in a macro. +The core of this problem is that derived `WorldQuery` types are not *reflexive*. + ## User-facing explanation -Explain the proposal as if it was already included in the engine and you were teaching it to another Bevy user. That generally means: +### **Reflexive** + +(Adjective) *In reference to oneself.* + +Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, meaning +it returns itself when used in a query. Types such as `&mut T` are not reflexive, +and are forbidden from being used with the derive macro. + +Examples: -- Introducing new named concepts. -- Explaining the feature, ideally through simple examples of solutions to concrete problems. -- Explaining how Bevy users should *think* about the feature, and how it should impact the way they use Bevy. It should explain the impact as concretely as possible. -- If applicable, provide sample error messages, deprecation warnings, or migration guidance. -- If applicable, explain how this feature compares to similar existing features, and in what situations the user would use each one. +```rust +#[derive(WorldQuery)] +struct DebugName<'w> { + name: Option<&'w Name>, + id: Entity, +} + +impl Debug for DebugName<'_> { ... } + +#[derive(WorldQuery)] +#[world_query(mutable)] +struct PhysicsComponents<'w> { + mass: &'w Mass, + transform: Mut<'w, Transform>, + velocity: Mut<'w, Velocity>, +} +``` ## Implementation strategy From 724349007c8aa8e50407f0294425eccea3681e2b Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:49:36 -0500 Subject: [PATCH 04/26] add a minimal unresolved questions section --- rfcs/reflexive-world-queries.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index 3ac25807..ce8fabeb 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -153,9 +153,7 @@ and make it more difficult to understand due to having several very similar type ## Unresolved questions -- What parts of the design do you expect to resolve through the RFC process before this gets merged? -- What parts of the design do you expect to resolve through the implementation of this feature before the feature PR is merged? -- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? +None. ## \[Optional\] Future possibilities From dcbf1a8a73569fee013fdaa03569e5cae2bb825c Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:50:37 -0500 Subject: [PATCH 05/26] remove some things --- rfcs/reflexive-world-queries.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index ce8fabeb..e9826206 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -76,8 +76,6 @@ This successfully avoid the compile error, but it results in an awkward situtati trait impls, and methods are spread accross two very similar types with a non-obvious distinction between them. In addition, the `DebugNameItem` struct has necessarily vague documentation due to being generated in a macro. -The core of this problem is that derived `WorldQuery` types are not *reflexive*. - ## User-facing explanation ### **Reflexive** @@ -155,6 +153,6 @@ and make it more difficult to understand due to having several very similar type None. -## \[Optional\] Future possibilities +## Future possibilities We should explore ways to make the `#[world_query(mutable)]` attribute unnecessary. From c40236205f78459cbdb3e2411029edc6c0a86921 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:02:05 -0500 Subject: [PATCH 06/26] note that most types are reflexive --- rfcs/reflexive-world-queries.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index e9826206..013ce84a 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -83,8 +83,11 @@ In addition, the `DebugNameItem` struct has necessarily vague documentation due (Adjective) *In reference to oneself.* Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, meaning -it returns itself when used in a query. Types such as `&mut T` are not reflexive, -and are forbidden from being used with the derive macro. +it returns itself when used in a query. + +Most `WorldQuery` types are reflexive, and may be used without consideration of this property. +A notable exception is `&mut T`, which is incompatible with the derive macro. +`Mut` must be used instead. Examples: From 496c810af37ba5578333d6e1eda13c57666aeb12 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:02:34 -0500 Subject: [PATCH 07/26] collapse a paragraph --- rfcs/reflexive-world-queries.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index 013ce84a..e6c5291a 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -82,9 +82,8 @@ In addition, the `DebugNameItem` struct has necessarily vague documentation due (Adjective) *In reference to oneself.* -Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, meaning -it returns itself when used in a query. - +Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, +meaning it returns itself when used in a query. Most `WorldQuery` types are reflexive, and may be used without consideration of this property. A notable exception is `&mut T`, which is incompatible with the derive macro. `Mut` must be used instead. From 6083c1a4be9aee617db34c1c9d6fa9cdacd16571 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:05:07 -0500 Subject: [PATCH 08/26] fix an article --- rfcs/reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index e6c5291a..6e54cec5 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -56,7 +56,7 @@ error[E0277]: `DebugNameItem<'_>` doesn't implement `Debug` "Rustc, what are you talking about?" you ask. You just implemented `Debug`! The problem here is that the type returned from the query is *not* the type we just defined --- it's an hidden macro-generated type with near-identical fields. +-- it's a hidden macro-generated type with near-identical fields. Here's what it looks like in the docs: ```rust From 7e9a60ab5bea6aaa1e88efa07a45f8779147b5b2 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:08:23 -0500 Subject: [PATCH 09/26] compare to system params --- rfcs/reflexive-world-queries.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/reflexive-world-queries.md index 6e54cec5..147fb987 100644 --- a/rfcs/reflexive-world-queries.md +++ b/rfcs/reflexive-world-queries.md @@ -110,8 +110,9 @@ struct PhysicsComponents<'w> { ## Implementation strategy -Changing the derive macro to be reflexive should be a trivial change, -and will not be discussed at length in this RFC. +Changing the derive macro to be reflexive should be a trivial change +-- the `SystemParam` derive already works this way, +so the details will not be discussed in this RFC. To support this change, we will need to rework some of our built-in `WorldQuery` types to be reflexive. From 2b0d37bca4c15db34269ecd451f215730f828bac Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:10:38 -0500 Subject: [PATCH 10/26] put the RFC number in the filename --- .../{reflexive-world-queries.md => 67-reflexive-world-queries.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rfcs/{reflexive-world-queries.md => 67-reflexive-world-queries.md} (100%) diff --git a/rfcs/reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md similarity index 100% rename from rfcs/reflexive-world-queries.md rename to rfcs/67-reflexive-world-queries.md From 4449c68f97fbc9b1ffc7f2923534ec66a241721d Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:16:50 -0500 Subject: [PATCH 11/26] make an example pub --- rfcs/67-reflexive-world-queries.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 147fb987..1cf9867f 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -14,9 +14,9 @@ to showing the entity's ID if it doesn't. ```rust #[derive(WorldQuery)] -struct DebugName { - name: Option<&'static Name>, - id: Entity, +pub struct DebugName { + pub name: Option<&'static Name>, + pub id: Entity, } impl Debug for DebugName { From e7780b43c2f4cd635055addc5f4fa999700c4e0f Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:19:08 -0500 Subject: [PATCH 12/26] indent a definition --- rfcs/67-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 1cf9867f..ea08226d 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -80,7 +80,7 @@ In addition, the `DebugNameItem` struct has necessarily vague documentation due ### **Reflexive** -(Adjective) *In reference to oneself.* +1. (Adjective) *In reference to oneself.* Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, meaning it returns itself when used in a query. From 5cb49fb8e8f5f543a5faae552cb534baa9a053fc Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 16:25:37 -0500 Subject: [PATCH 13/26] accidentally a word --- rfcs/67-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index ea08226d..d74fffd6 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -137,7 +137,7 @@ Since `&mut T` is not reflexive, we will have to implement `WorldQuery` for `Mut ## Drawbacks -This will add slightly more friction in some cases, non-reflexive `WorldQuery` +This will add slightly more friction in some cases, since types such as `&mut T` are forbidden from being used in the derive macro. However, these types can still be used in anonymous `WorldQuery`s or types such as `type MyQuery = (&'static mut A, &'static mut U)`. From b34d4c94a0f4e0cdd77a9027d4262fe259a6b403 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 17:09:54 -0500 Subject: [PATCH 14/26] add an example for `AnyOf` --- rfcs/67-reflexive-world-queries.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index d74fffd6..34ed983d 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -133,6 +133,22 @@ fn my_system(q: Query>) { } ``` +```rust +// Before: +fn my_system(q: Query>) { + for (a, b, c) in &q { + ... + } +} + +// After: +fn my_system(q: Query>) { + for AnyOf((a, b, c)) in &q { + ... + } +} +``` + Since `&mut T` is not reflexive, we will have to implement `WorldQuery` for `Mut`. ## Drawbacks From 1a97203bb3a97bf2a70022d395fae73c577942b4 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Thu, 23 Feb 2023 17:15:50 -0500 Subject: [PATCH 15/26] `entity` -> `id` --- rfcs/67-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 34ed983d..8a6eb248 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -62,7 +62,7 @@ Here's what it looks like in the docs: ```rust pub struct DebugNameItem<'__w> { pub name: as WorldQuery>::Item<'__w>, - pub entity: ::Item<'__w>, + pub id: ::Item<'__w>, } ``` From 534dba00094820d21c8b093fe2f7850ec6c63d42 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 10:35:38 -0500 Subject: [PATCH 16/26] complain about more things --- rfcs/67-reflexive-world-queries.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 8a6eb248..dc028dcb 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -72,9 +72,12 @@ In order to fix the error, we need to implement `Debug` for *this* type: impl Debug for DebugNameItem<'_> { ... } ``` -This successfully avoid the compile error, but it results in an awkward situtation where our documentation, -trait impls, and methods are spread accross two very similar types with a non-obvious distinction between them. -In addition, the `DebugNameItem` struct has necessarily vague documentation due to being generated in a macro. +This avoids the compile error, but it results in an awkward situtation where our documentation, +trait impls, and methods are fragmented between two very similar types with a non-obvious distinction between them. + +Since the `DebugNameItem` is generated in a macro, it is very awkard to flesh out its API. +Its documentation is necessarily vague since you can't write it yourself, and deriving traits +requires the special syntax `#[world_query(derive(PartialEq))]`. ## User-facing explanation From d7370df94c10532748b3db01fd326866a213930b Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 10:37:31 -0500 Subject: [PATCH 17/26] emphasize a clause --- rfcs/67-reflexive-world-queries.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index dc028dcb..54654f60 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -72,8 +72,8 @@ In order to fix the error, we need to implement `Debug` for *this* type: impl Debug for DebugNameItem<'_> { ... } ``` -This avoids the compile error, but it results in an awkward situtation where our documentation, -trait impls, and methods are fragmented between two very similar types with a non-obvious distinction between them. +This avoids the compile error, but it results in an awkward situtation where *our documentation, +trait impls, and methods are fragmented between two very similar types* with a non-obvious distinction between them. Since the `DebugNameItem` is generated in a macro, it is very awkard to flesh out its API. Its documentation is necessarily vague since you can't write it yourself, and deriving traits From 0f51714da436869f38b926a6bf033bbfef6f1cf1 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 10:46:20 -0500 Subject: [PATCH 18/26] describe derived types more precisely --- rfcs/67-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 54654f60..329971b0 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -85,7 +85,7 @@ requires the special syntax `#[world_query(derive(PartialEq))]`. 1. (Adjective) *In reference to oneself.* -Any `WorldQuery` type used within `#[derive(WorldQuery)]` must be reflexive, +Any `WorldQuery` type defined with `#[derive(WorldQuery)]` must be reflexive, meaning it returns itself when used in a query. Most `WorldQuery` types are reflexive, and may be used without consideration of this property. A notable exception is `&mut T`, which is incompatible with the derive macro. From f570b1d60ea35eb6336fbdb69a148829bfe0938e Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 18:03:47 -0500 Subject: [PATCH 19/26] remove an example --- rfcs/67-reflexive-world-queries.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 329971b0..76d3d477 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -120,22 +120,6 @@ so the details will not be discussed in this RFC. To support this change, we will need to rework some of our built-in `WorldQuery` types to be reflexive. -```rust -// Before: -fn my_system(q: Query>) { - for flag in &q { - ... - } -} - -// After: -fn my_system(q: Query>) { - for Changed(flag) in &q { - ... - } -} -``` - ```rust // Before: fn my_system(q: Query>) { From 82a5ee57a7588364e699c7f13bc9f1a8b36b5035 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 18:07:33 -0500 Subject: [PATCH 20/26] condense an example --- rfcs/67-reflexive-world-queries.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index 76d3d477..e55c200e 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -121,15 +121,14 @@ To support this change, we will need to rework some of our built-in `WorldQuery` types to be reflexive. ```rust -// Before: fn my_system(q: Query>) { + + // Before: for (a, b, c) in &q { ... } -} - -// After: -fn my_system(q: Query>) { + + // After: for AnyOf((a, b, c)) in &q { ... } From 7d29f57dbfe6c5dcc1c049d26a69e2888db6e03d Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Fri, 24 Feb 2023 18:10:35 -0500 Subject: [PATCH 21/26] lighten --- rfcs/67-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/67-reflexive-world-queries.md index e55c200e..20d1b745 100644 --- a/rfcs/67-reflexive-world-queries.md +++ b/rfcs/67-reflexive-world-queries.md @@ -53,7 +53,7 @@ error[E0277]: `DebugNameItem<'_>` doesn't implement `Debug` = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) ``` -"Rustc, what are you talking about?" you ask. You just implemented `Debug`! +"What do you mean rustc?!" you plead as you bang your head against the wall. You just implemented `Debug`! The problem here is that the type returned from the query is *not* the type we just defined -- it's a hidden macro-generated type with near-identical fields. From 98bddef2027d4a9fe2b37475a3237cbf92f61770 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Tue, 28 Feb 2023 11:28:39 -0500 Subject: [PATCH 22/26] fix RFC number --- ...7-reflexive-world-queries.md => 68-reflexive-world-queries.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rfcs/{67-reflexive-world-queries.md => 68-reflexive-world-queries.md} (100%) diff --git a/rfcs/67-reflexive-world-queries.md b/rfcs/68-reflexive-world-queries.md similarity index 100% rename from rfcs/67-reflexive-world-queries.md rename to rfcs/68-reflexive-world-queries.md From 425dc780033ab31a2138b364291f89dd7a71d179 Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Mon, 6 Mar 2023 22:02:17 -0500 Subject: [PATCH 23/26] Apply suggestions from code review Co-authored-by: Alice Cecile --- rfcs/68-reflexive-world-queries.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/68-reflexive-world-queries.md b/rfcs/68-reflexive-world-queries.md index 20d1b745..e697b7b9 100644 --- a/rfcs/68-reflexive-world-queries.md +++ b/rfcs/68-reflexive-world-queries.md @@ -72,8 +72,8 @@ In order to fix the error, we need to implement `Debug` for *this* type: impl Debug for DebugNameItem<'_> { ... } ``` -This avoids the compile error, but it results in an awkward situtation where *our documentation, -trait impls, and methods are fragmented between two very similar types* with a non-obvious distinction between them. +This avoids the compile error, but it results in an awkward situation where our documentation, +trait impls, and methods are fragmented between two very similar types with a non-obvious distinction between them. Since the `DebugNameItem` is generated in a macro, it is very awkard to flesh out its API. Its documentation is necessarily vague since you can't write it yourself, and deriving traits From 5fcf590e8ac9d71819cf3ed41fd32f2423e33a8e Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Mon, 6 Mar 2023 22:07:06 -0500 Subject: [PATCH 24/26] humble bevy user --- rfcs/68-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/68-reflexive-world-queries.md b/rfcs/68-reflexive-world-queries.md index e697b7b9..4f7168d5 100644 --- a/rfcs/68-reflexive-world-queries.md +++ b/rfcs/68-reflexive-world-queries.md @@ -8,7 +8,7 @@ This makes the API for these types much simpler. ## Motivation -You, a humble user, wish to define your own custom `WorldQuery` type. +You, a Bevy humble user, wish to define your own custom `WorldQuery` type. It should display the name of an entity if it has one, and fall back to showing the entity's ID if it doesn't. From ed2b8dbeebe45c6606d5f48eb5a0d0865e747bbc Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Mon, 6 Mar 2023 22:07:51 -0500 Subject: [PATCH 25/26] i can't type --- rfcs/68-reflexive-world-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/68-reflexive-world-queries.md b/rfcs/68-reflexive-world-queries.md index 4f7168d5..a1cc076a 100644 --- a/rfcs/68-reflexive-world-queries.md +++ b/rfcs/68-reflexive-world-queries.md @@ -8,7 +8,7 @@ This makes the API for these types much simpler. ## Motivation -You, a Bevy humble user, wish to define your own custom `WorldQuery` type. +You, a humble Bevy user, wish to define your own custom `WorldQuery` type. It should display the name of an entity if it has one, and fall back to showing the entity's ID if it doesn't. From 6ca873d2c2fc23ae4107a880219d74ba33ba6d5f Mon Sep 17 00:00:00 2001 From: JoJoJet <21144246+JoJoJet@users.noreply.github.com> Date: Sun, 19 Mar 2023 10:37:00 -0400 Subject: [PATCH 26/26] add another example of reflexive primitive types --- rfcs/68-reflexive-world-queries.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/rfcs/68-reflexive-world-queries.md b/rfcs/68-reflexive-world-queries.md index a1cc076a..3351da90 100644 --- a/rfcs/68-reflexive-world-queries.md +++ b/rfcs/68-reflexive-world-queries.md @@ -121,8 +121,7 @@ To support this change, we will need to rework some of our built-in `WorldQuery` types to be reflexive. ```rust -fn my_system(q: Query>) { - +fn any_system(q: Query>) { // Before: for (a, b, c) in &q { ... @@ -133,6 +132,18 @@ fn my_system(q: Query>) { ... } } + +fn changed_system(q: Query>) { + // Before: + for changed_a in &q { + ... + } + + // After: + for Changed(changed_a) in &q { + ... + } +} ``` Since `&mut T` is not reflexive, we will have to implement `WorldQuery` for `Mut`.