[Merged by Bors] - Deprecate `ChangeTrackers<T>` in favor of `Ref<T>` by joseph-gio · Pull Request #7306 · bevyengine/bevy

joseph-gio · 2023-01-20T19:22:41Z

Objective

ChangeTrackers<> is a WorldQuery type that lets you access the change ticks for a component. #7097 has added Ref<>, which gives access to a component's value in addition to its change ticks. Since bevy's access model does not separate a component's value from its change ticks, there is no benefit to using ChangeTrackers<T> over Ref<T>.

Solution

Deprecate ChangeTrackers<>.

Changelog

ChangeTrackers<T> has been deprecated. It will be removed in Bevy 0.11.

Migration Guide

ChangeTrackers<T> has been deprecated, and will be removed in the next release. Any usage should be replaced with Ref<T>.

// Before (0.9)
fn my_system(q: Query<(&MyComponent, ChangeTrackers<MyComponent>)>) {
    for (value, trackers) in &q {
        if trackers.is_changed() {
            // Do something with `value`.
        }
    }
}

// After (0.10)
fn my_system(q: Query<Ref<MyComponent>>) {
    for value in &q {
        if value.is_changed() {
            // Do something with `value`.
        }
    }
}

alice-i-cecile · 2023-01-20T20:08:48Z

examples/ecs/component_change_detection.rs

-) {
-    for (entity, component, trackers) in &query {
-        info!("{:?}: {:?} -> {:?}", entity, component, trackers);
+// By using `Ref`, the query is not filtered but the information is available


This comment seems incorrect. I'm not sure that it was ever correct however.

I think the original intended meaning is that the query is not filtered based on change detection, but you can still access the change detection info. I tried to preserve that meaning when rewriting this section of code.

alice-i-cecile · 2023-01-21T16:03:22Z

This is a bit of a controversial decision. I think it's the right one, but there's a possibility that we split change ticks from the data in a meaningful way later. Ping @maniwani @BoxyUwU for a quick second opinion?

james7132 · 2023-01-21T19:59:06Z

A potentially more controversial option is just to have &T return Ref<T> instead. Though that might require some benchmarking to ensure there's no perf regression in doing so.

BoxyUwU · 2023-01-21T22:34:41Z

A nice thing about making &T return Ref<T> is that it would make the ReadOnly assoc type on &mut T have an "obvious answer", with this PR it could realistically be &T or Ref<T>. I think the only downside that Mut<T> has that Ref<T> would also have is the fact that you cant pattern match on it, the other issues (shoving mut everywhere and borrowck annoyances from disjoint borrows) dont apply to Ref<T> which is cool.

alice-i-cecile · 2023-01-22T00:22:52Z

Yeah, I think I'm sold on doing that, but it should be in a new PR. Are you two sold on deprecating ChangeTrackers then?

BoxyUwU · 2023-01-24T02:22:20Z

I was a bit concerned that someone might re-add this WorldQuery in the future as a "perf optimization for if you don't need the component data" but according to james, rust is able to optimize that use case fine as is.

I do think we should avoid actually removing the ChangeTrackers<T> type though, it doesn't have a lifetime like Ref does so it could be more flexible to pass around and store than Ref<'_, T> (for example it is not possible to store a Ref in a component, but you could store ChangeTrackers<T> in a component)

BoxyUwU · 2023-01-24T02:23:29Z

I guess there is also a code clarity question, is Query<ChangeTrackers<T>> clearer than Query<Ref<T>> if semantically all you care about is the change ticks 🤔

alice-i-cecile · 2023-01-24T02:49:01Z

It's a bit clearer, but it also adds yet another concept to learn.

joseph-gio · 2023-02-19T15:13:06Z

I'd like to consider this for 0.10 so we don't miss out on a deprecation cycle. Obviously it's not super important, though.

maniwani · 2023-02-19T16:08:41Z

A more controversial option is just to have &T return Ref<T> instead.

I want this tbh. Better symmetry.

Once we separate !Send resources from World, we have the option to remove Res(Mut)<T> (NonSend(Mut)<T> can go away). Getting resources in a system signature could just use Ref<T> and Mut<T>. Or maybe Res can be like Query.

alice-i-cecile · 2023-02-19T16:19:40Z

That's two SMEs: merging :)

bors r+

# Objective `ChangeTrackers<>` is a `WorldQuery` type that lets you access the change ticks for a component. #7097 has added `Ref<>`, which gives access to a component's value in addition to its change ticks. Since bevy's access model does not separate a component's value from its change ticks, there is no benefit to using `ChangeTrackers<T>` over `Ref<T>`. ## Solution Deprecate `ChangeTrackers<>`. --- ## Changelog * `ChangeTrackers<T>` has been deprecated. It will be removed in Bevy 0.11. ## Migration Guide `ChangeTrackers<T>` has been deprecated, and will be removed in the next release. Any usage should be replaced with `Ref<T>`. ```rust // Before (0.9) fn my_system(q: Query<(&MyComponent, ChangeTrackers<MyComponent>)>) { for (value, trackers) in &q { if trackers.is_changed() { // Do something with `value`. } } } // After (0.10) fn my_system(q: Query<Ref<MyComponent>>) { for value in &q { if value.is_changed() { // Do something with `value`. } } } ```

bors · 2023-02-19T16:35:30Z

Pull request successfully merged into main.

Build succeeded:

`ChangeTrackers<>` is a `WorldQuery` type that lets you access the change ticks for a component. bevyengine#7097 has added `Ref<>`, which gives access to a component's value in addition to its change ticks. Since bevy's access model does not separate a component's value from its change ticks, there is no benefit to using `ChangeTrackers<T>` over `Ref<T>`. Deprecate `ChangeTrackers<>`. --- * `ChangeTrackers<T>` has been deprecated. It will be removed in Bevy 0.11. `ChangeTrackers<T>` has been deprecated, and will be removed in the next release. Any usage should be replaced with `Ref<T>`. ```rust // Before (0.9) fn my_system(q: Query<(&MyComponent, ChangeTrackers<MyComponent>)>) { for (value, trackers) in &q { if trackers.is_changed() { // Do something with `value`. } } } // After (0.10) fn my_system(q: Query<Ref<MyComponent>>) { for value in &q { if value.is_changed() { // Do something with `value`. } } } ```

joseph-gio added 9 commits January 20, 2023 12:32

deprecate ChangeTrackers

9fea77e

update unit tests

c11b2c0

improve deprecation message

dddc755

fix future version

ae04be3

fix bevy_ecs tests

91800ad

tweak formatting

d4216e4

move attributes above docs

5b2798c

update a doc link

f6e5d93

use Ref<> in an example

ad9c655

joseph-gio added A-ECS Entities, components, systems, and events M-Migration-Guide A breaking change to Bevy's public API that needs to be noted in a migration guide labels Jan 20, 2023

alice-i-cecile requested a review from james7132 January 20, 2023 20:07

alice-i-cecile reviewed Jan 20, 2023

View reviewed changes

james7132 approved these changes Jan 21, 2023

View reviewed changes

alice-i-cecile added the X-Needs-SME This type of work requires an SME to approve it. label Jan 21, 2023

alice-i-cecile approved these changes Jan 21, 2023

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Jan 21, 2023

alice-i-cecile mentioned this pull request Jan 22, 2023

Make Query<&T> return Ref<T> #7322

Open

joseph-gio mentioned this pull request Jan 30, 2023

Make ComponentTicks available from ChangeTrackers #7410

Closed

joseph-gio added 3 commits February 4, 2023 22:12

Merge remote-tracking branch 'upstream/main' into no-change-trackers

0e71063

Merge remote-tracking branch 'upstream/main' into no-change-trackers

8ebf600

add #[doc(hidden)] to the prelude re-export

1be031a

joseph-gio added this to the 0.10 milestone Feb 19, 2023

alice-i-cecile requested review from BoxyUwU and maniwani February 19, 2023 15:19

maniwani approved these changes Feb 19, 2023

View reviewed changes

bors bot changed the title ~~Deprecate ChangeTrackers<T> in favor of Ref<T>~~ [Merged by Bors] - Deprecate ChangeTrackers<T> in favor of Ref<T> Feb 19, 2023

bors bot closed this Feb 19, 2023

joseph-gio deleted the no-change-trackers branch February 19, 2023 16:37

joseph-gio mentioned this pull request Feb 25, 2023

[Merged by Bors] - News: Release 0.10.0 bevyengine/bevy-website#546

Closed

Uh oh!

Conversation

joseph-gio commented Jan 20, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Changelog

Migration Guide

Uh oh!

alice-i-cecile Jan 20, 2023

Choose a reason for hiding this comment

Uh oh!

joseph-gio Jan 20, 2023

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile commented Jan 21, 2023

Uh oh!

james7132 commented Jan 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BoxyUwU commented Jan 21, 2023

Uh oh!

alice-i-cecile commented Jan 22, 2023

Uh oh!

BoxyUwU commented Jan 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BoxyUwU commented Jan 24, 2023

Uh oh!

alice-i-cecile commented Jan 24, 2023

Uh oh!

joseph-gio commented Feb 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maniwani commented Feb 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alice-i-cecile commented Feb 19, 2023

Uh oh!

bors bot commented Feb 19, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joseph-gio commented Jan 20, 2023 •

edited

Loading

james7132 commented Jan 21, 2023 •

edited

Loading

BoxyUwU commented Jan 24, 2023 •

edited

Loading

joseph-gio commented Feb 19, 2023 •

edited

Loading

maniwani commented Feb 19, 2023 •

edited

Loading