Implement WorldQuery and QueryData for Mut

[Themayu]

This is an alternative means of achieving the goals of #12920.

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

Currently, the QueryData derive macro transforms fields of the type &'static mut T to Mut<'w, T> when generating the item type for the query. However, the readonly item type continues to use &'w T as the reference type. This makes it impossible to use change detection on the readonly form of mutable queries.

As an example from my code:

#[derive(QueryData)]
#[query_data(mutable)]
pub struct TextBoxQuery {
    pub data: &'static mut TextBox,
    pub style: &'static mut TextBoxStyle,
    pub text_style: &'static mut TextBoxTextStyle,
}

// derive(QueryData) output
pub struct TextBoxQueryItem<'w> {
    pub data: Mut<'w, TextBox>,
    pub style: Mut<'w, TextBoxStyle>,
    pub text_style: Mut<'w, TextBoxTextStyle>,
}

pub struct TextBoxQueryReadOnlyItem<'w> {
    pub data: &'w TextBox,
    pub style: &'w TextBoxStyle,
    pub text_style: &'w TextBoxTextStyle,
}

What solution would you like?

In #12920, I proposed extending the QueryData derive to add a detect_changes option that would make the derive macro emit Ref<T> instead of Self::ReadOnly when it encounters a &mut T. I've since realised a simpler way of handling the problem: implement WorldQuery and QueryData for Mut<T> directly, setting its ReadOnly type alias to Ref<T>.

I realised this alternate solution during an unstructured discussion in the #ecs_dev Discord channel where some additional questions were brought up.

This would allow for opting into change detection in the readonly form of the query without requiring extension of the derive macro itself, by defining a field as Mut<'_, T> instead of &'_ mut T:

#[derive(QueryData)]
#[query_data(mutable)]
pub struct TextBoxQuery {
    pub data: Mut<'static, TextBox>,
    pub style: &'static mut TextBoxStyle,
    pub text_style: &'static mut TextBoxTextStyle,
}

// derive(QueryData) output
pub struct TextBoxQueryItem<'w> {
    pub data: Mut<'w, TextBox>,
    pub style: Mut<'w, TextBoxStyle>, // this seems confusing, so I was hesitant to bring the idea up at first
    pub text_style: Mut<'w, TextBoxTextStyle>,
}

pub struct TextBoxQueryReadOnlyItem<'w> {
    pub data: Ref<'w, TextBox>,
    pub style: &'w TextBoxStyle,
    pub text_style: &'w TextBoxTextStyle,
}

What alternative(s) have you considered?

Continue with #12920, which has proven difficult to even begin implementing.

[alice-i-cecile]

I prefer this solution to the problem.

[Themayu]

Implementation-wise, would it be sufficient to copy the implementations on &mut T, with a single change to the ReadOnly associated type?

[alice-i-cecile]

I believe that should work. I'd like to see a doc comment on the implementation that explains why this exists, and a doc test that demonstrates the intended use.